function GazeContingentTutorial(mode, ms, myimgfile)
%
% ___________________________________________________________________
%
% Demo implementation of a generic gaze-contingent display.
% We take one input image and create - via image processing - two images
% out of it: An image to show at the screen location were the subject
% fixates (According to the eye-tracker). A second image to show in the
% peripery of the subjects field of view. These two images are blended into
% each other via a gaussian weight mask (an aperture). The mask is centered
% at the center of gaze and allows for a smooth transition between the two
% images.
%
% This illustrates an application of OpenGL Alpha blending by compositing
% two images based on a spatial gaussian weight mask. Compositing is done
% by the graphics hardware.
%
% See also: PsychDemos, MovieDemo, DriftDemo
% HISTORY
%
% mm/dd/yy
%
% 7/23/05 mk Derived it from Frans Cornelissens AlphaImageDemoOSX.
% 11/19/06 dhb Remove OSX from name.
% 11/11/14 mk Clean up, modernize, use 0-1 color range.
% Use new-style color specifications in normalized range 0.0 - 1.0:
PsychDefaultSetup(2);
% Setup default mode to color vs. gray.
if nargin < 1
mode = 1;
end
% Setup default aperture size to 2*200 x 2*200 pixels.
if nargin < 2
ms=200;
end
basepath = [ PsychtoolboxRoot 'PsychDemos' filesep ];
% Use default demo images, if no special image was provided.
if nargin < 3
myimgfile= [basepath 'konijntjes1024x768.jpg'];
end
myblurimgfile= [basepath 'konijntjes1024x768blur.jpg'];
mygrayimgfile= [basepath 'konijntjes1024x768gray.jpg'];
try
fprintf('GazeContingentDemo (%s)\n', datestr(now));
fprintf('Press a key or click on mouse to stop demo.\n');
% Set background color to black aka zero intensity:
backgroundcolor = 0.0;
% Get the list of screens and choose the one with the highest screen number.
screenNumber=max(Screen('Screens'));
% Open a double buffered fullscreen window. Use PsychImaging(), so the
% normalized 0.0 - 1.0 color format is used for drawing, instead of the
% old 0 - 255 range:
[w, wRect] = PsychImaging('OpenWindow', screenNumber, backgroundcolor);
% Load image file:
fprintf('Using image ''%s''\n', myimgfile);
imdata=imread(myimgfile);
imdatablur=imread(myblurimgfile);
imdatagray=imread(mygrayimgfile);
% Crop image if it is larger then screen size. There's no image scaling
% in maketexture:
[iy, ix, id]=size(imdata);
[wW, wH]=WindowSize(w);
if ix>wW || iy>wH
disp('Image size exceeds screen size');
disp('Image will be cropped');
end
if ix>wW
cl=round((ix-wW)/2);
cr=(ix-wW)-cl;
else
cl=0;
cr=0;
end
if iy>wH
ct=round((iy-wH)/2);
cb=(iy-wH)-ct;
else
ct=0;
cb=0;
end
% imdataXXX is the cropped version of the images.
imdata=imdata(1+ct:iy-cb, 1+cl:ix-cr,:);
imdatablur=imdatablur(1+ct:iy-cb, 1+cl:ix-cr,:);
imdatagray=imdatagray(1+ct:iy-cb, 1+cl:ix-cr,:);
% Compute image for foveated region and periphery:
switch (mode)
case 1
% Mode 1:
% Fovea contains original image data:
foveaimdata = imdata;
% Periphery contains grayscale-version:
peripheryimdata = imdatagray;
case 2
% Fovea contains original image data:
foveaimdata = imdata;
% Periphery contains blurred-version:
peripheryimdata = imdatablur;
case 3
% Fovea contains color-inverted image data:
foveaimdata(:,:,:) = 255 - imdata(:,:,:);
% Periphery contains original data:
peripheryimdata = imdata;
case 4
% Test-case: One shouldn't see any foveated region on the
% screen - this is a basic correctness test for blending.
foveaimdata = imdata;
peripheryimdata = imdata;
otherwise
% Unknown mode! We force abortion:
fprintf('Invalid mode provided!');
abortthisbeast
end
% Build texture for foveated region:
foveatex=Screen('MakeTexture', w, foveaimdata);
tRect=Screen('Rect', foveatex);
% Build texture for peripheral (non-foveated) region:
nonfoveatex=Screen('MakeTexture', w, peripheryimdata);
[ctRect, dx, dy]=CenterRect(tRect, wRect);
% We create a two layers Luminance + Alpha matrix for use as transparency
% (or mixing weights) mask: Layer 1 (Luminance) is filled with luminance
% value 1.0 aka white - the ones() function does this nicely for us, by
% first filling both layers with 1.0:
[x,y] = meshgrid(-ms:ms, -ms:ms);
maskblob = ones(2*ms+1, 2*ms+1, 2);
% Layer 2 (Transparency aka Alpha) is now filled/overwritten with a gaussian
% transparency/mixing mask.
xsd = ms / 2.2;
ysd = ms / 2.2;
maskblob(:,:,2) = 1 - exp(-((x / xsd).^2) - ((y / ysd).^2));
% Build a single transparency mask texture:
masktex = Screen('MakeTexture', w, maskblob);
mRect = Screen('Rect', masktex);
fprintf('Size image texture: %d x %d\n', RectWidth(tRect), RectHeight(tRect));
fprintf('Size mask texture: %d x %d\n', RectWidth(mRect), RectHeight(mRect));
% Do initial flip to show blank screen:
Screen('Flip', w);
% The mouse-cursor position will define gaze-position (center of
% fixation) to simulate (x,y) input from an eyetracker. Set cursor
% initially to center of screen, but do hide it from view:
[a,b] = RectCenter(wRect);
SetMouse(a,b,screenNumber);
HideCursor;
buttons = 0;
priorityLevel=MaxPriority(w);
Priority(priorityLevel);
% Wait until all keys on keyboard are released:
KbReleaseWait;
mxold=0;
myold=0;
% Show periphery image:
Screen('DrawTexture', w, nonfoveatex);
Screen('TextSize', w, 24);
DrawFormattedText(w, 'Step1: Create Non-foveated (periphery) texture:\nPress mouse button to continue\n', 0, 40, 1, 50);
Screen('Flip', w);
% Wait for mouseclick:
GetClicks;
% Show fovea image:
Screen('DrawTexture', w, foveatex);
Screen('TextSize', w, 24);
DrawFormattedText(w, 'Step2: Create Fovea texture:\nPress mouse button to continue\n', 0, 40, 1, 50);
Screen('Flip', w);
GetClicks;
mode = 0;
% Infinite display loop: Whenever "gaze position" changes, we update
% the display accordingly. Loop aborts on keyboard press or mouse
% click:
while 1
% Query current mouse cursor position (our "pseudo-eyetracker") -
% (mx,my) is our gaze position.
[mx, my, buttons]=GetMouse;
if any(buttons)
while any(buttons)
[mx, my, buttons]=GetMouse; %(w);
end
mode = mode + 1;
mxold = -1;
if mode == 4
break;
end
end
% We only redraw if gazepos. has changed:
if (mx~=mxold || my~=myold)
% Compute position and size of source- and destinationrect and clip them:
myrect=[mx-ms my-ms mx+ms+1 my+ms+1];
dRect = ClipRect(myrect,ctRect);
sRect=OffsetRect(dRect, -dx, -dy);
% Valid destination rectangle?
if ~IsEmptyRect(dRect)
% Yes! Draw image for current frame:
% Step 1: Draw the alpha-mask into the backbuffer. It
% defines the aperture for foveation: The center of gaze
% has zero alpha value. Alpha values increase with distance from
% center of gaze according to a gaussian function and
% approach 1.0 at the border of the aperture...
if mode > 0
% Actual use of masktex to define transitions/mix:
% First clear framebuffer to backgroundcolor, not using
% alpha blending (== GL_ONE, GL_ZERO), enable all channels
% for writing [1 1 1 1], so everything gets cleared to good
% starting values:
Screen('BlendFunction', w, GL_ONE, GL_ZERO, [1 1 1 1]);
Screen('FillRect', w, backgroundcolor);
% Then keep alpha blending disabled and draw the mask
% texture, but *only* into the alpha channel. Don't touch
% the RGB color channels but use the channel mask
% [R G B A] = [0 0 0 1] to only enable the alpha-channel
% for drawing into it:
Screen('BlendFunction', w, GL_ONE, GL_ZERO, [0 0 0 1]);
Screen('DrawTexture', w, masktex, [], myrect);
else
% Visualize the alpha/mask channel of the
% framebuffer and the new masktex itself to explain
% the concept - alpha values of 1 will show as white,
% values of zero as black, intermediates as gray levels:
Screen('BlendFunction', w, GL_SRC_ALPHA, GL_ZERO);
Screen('FillRect', w, 1);
Screen('DrawTexture', w, masktex, [], myrect);
end
% Step 2: Draw peripheral image. It is only/increasingly drawn where
% the alpha-value in the backbuffer is 1.0 or close, leaving
% the foveated area (low or zero alpha values) alone:
% This is done by weighting each color value of each pixel
% with the corresponding alpha-value in the backbuffer
% (GL_DST_ALPHA). Disable alpha channel writes via [1 1 1 0], so
% alpha mask stays untouched and only RGB color channels are
% affected:
if mode == 1 || mode == 3
Screen('BlendFunction', w, GL_DST_ALPHA, GL_ZERO, [1 1 1 0]);
Screen('DrawTexture', w, nonfoveatex, [], ctRect);
end
% Step 3: Draw foveated image, but only/increasingly where the
% alpha-value in the backbuffer is zero or low: This is
% done by weighting each color value with one minus the
% corresponding alpha-value in the backbuffer
% (GL_ONE_MINUS_DST_ALPHA).
if mode == 2 || mode == 3
Screen('BlendFunction', w, GL_ONE_MINUS_DST_ALPHA, GL_ONE, [1 1 1 0]);
Screen('DrawTexture', w, foveatex, sRect, dRect);
end
% Draw some text with explanation of the different steps:
switch(mode)
case 0,
txt = 'Draw gaussian aperture mask texture around center of fixation (aka mouse position):\nThis shows the alpha mask channel of the framebuffer used for mixing of the images (white = 1.0 alpha weight, black = 0.0 alpha weight)';
case 1,
txt = 'Draw periphery texture, but weight each incoming source color pixel by the alpha value stored in the framebuffers alpha channel';
case 2,
txt = 'Draw fovea texture, but weight each incoming source color pixel by 1 minus the alpha value stored in the framebuffers alpha channel';
case 3,
txt = 'Perform alpha weighted compositing (all previous steps together):\n1. Draw alpha weight mask according to mouse position,\n2. Overdraw with alpha-weighted periphery texture,\n3. Overdraw with 1-alpha weighted fovea texture.';
end
txt = [txt '\nMouse click for next step.'];
DrawFormattedText(w, txt, 0, 40, [1 0 0], 60);
% Show final result on screen. The 'Flip' also clears the drawing
% surface back to black background color and a zero alpha value:
Screen('Flip', w);
end
end
% Keep track of last gaze position:
mxold=mx;
myold=my;
% We wait 1 ms each loop-iteration so that we
% don't overload the system in realtime-priority:
WaitSecs('YieldSecs', 0.001);
% Abort demo on keypress our mouse-click:
if KbCheck || any(buttons)
break;
end
end
% Display full image a last time, just for fun...
Screen('BlendFunction', w, GL_ONE, GL_ZERO);
Screen('DrawTexture', w, foveatex);
Screen('Flip', w);
% The same command which closes onscreen and offscreen windows also
% closes textures.
sca;
ShowCursor;
Priority(0);
fprintf('End of GazeContingentDemo. Bye!\n\n');
return;
catch
%this "catch" section executes in case of an error in the "try" section
%above. Importantly, it closes the onscreen window if its open.
sca;
ShowCursor;
Priority(0);
psychrethrow(psychlasterror);
end %try..catch..