function DriftingMaskedGratingTutorial(angle, cyclespersecond, f, drawmask)
% function DriftDemo2(angle, cyclespersecond, f, drawmask)
% ___________________________________________________________________
%
% Display an animated grating using the new Screen('DrawTexture') command.
% In the OS X Psychtoolbox Screen('DrawTexture') replaces
% Screen('CopyWindow'). The demo will stop after roughly 20 seconds have
% passed or after the user hits a key.
%
% This demo illustrates how to draw an animated grating online by use of
% only one grating texture. We create one texture with a static sine
% grating. In each successive frame we only draw a rectangular subregion of
% the sine-texture onto the screen, basically showing the texture through
% an aperture. The subregion - and therefore our "aperture" is shifted each
% frame, so we create the impression of a moving grating.
%
% The demo also shows how to use alpha-blending for masking the grating
% with a gaussian transparency mask (a texture with transparency layer).
%
% And finally, we demonstrate rotated drawing, as well as how to emulate
% the old OS-9 'WaitBlanking' command with the new 'Flip' command.
%
% Parameters:
%
% angle = Angle of the grating with respect to the vertical direction.
% cyclespersecond = Speed of grating in cycles per second.
% f = Frequency of grating in cycles per pixel.
% drawmask = If set to 1, then a gaussian aperture is drawn over the grating
%
% CopyWindow vs. DrawTexture:
%
% In the OS 9 Psychtoolbox, Screen ('CopyWindow") was used for all
% time-critical display of images, in particular for display of the movie
% frames in animated stimuli. In contrast, Screen('DrawTexture') should not
% be used for display of all graphic elements,  but only for  display of
% MATLAB matrices.  For all other graphical elements, such as lines,  rectangles,
% and ovals we recommend that these be drawn directly to the  display
% window during the animation rather than rendered to offscreen  windows
% prior to the animation.
%
% _________________________________________________________________________
% 
% see also: PsychDemos, MovieDemo

% HISTORY
%  6/7/05    mk     Adapted from Allen Ingling's DriftDemoOSX.m 

if nargin<4
    % By default, we mask the grating by a gaussian transparency mask:
    drawmask=1;
end

if nargin<3
    % Grating cycles/pixel
    f=0.05;
end

if nargin<2
    % Speed of grating in cycles per second:
    cyclespersecond=1;
end

if nargin<1
    % Angle of the grating: We default to 30 degrees.
    angle=30;
end

movieDurationSecs=20;   % Abort demo after 20 seconds.
texsize=100;            % Half-Size of the grating image.

% Screen('Preference', 'SkipSyncTests', 1);

try
	% This script calls Psychtoolbox commands available only in OpenGL-based 
	% versions of the Psychtoolbox. (So far, the OS X Psychtoolbox is the
	% only OpenGL-base Psychtoolbox.)  The Psychtoolbox command AssertPsychOpenGL will issue
	% an error message if someone tries to execute this script on a computer without
	% an OpenGL Psychtoolbox
	AssertOpenGL;
	
	% Get the list of screens and choose the one with the highest screen number.
	% Screen 0 is, by definition, the display with the menu bar. Often when 
	% two monitors are connected the one without the menu bar is used as 
	% the stimulus display.  Chosing the display with the highest dislay number is 
	% a best guess about where you want the stimulus displayed.  
	screens=Screen('Screens');
	screenNumber=max(screens);
	
    % Find the color values which correspond to white and black.  Though on OS
	% X we currently only support true color and thus, for scalar color
	% arguments,
	% black is always 0 and white 255, this rule is not true on other platforms will
	% not remain true on OS X after we add other color depth modes.  
	white=WhiteIndex(screenNumber);
	black=BlackIndex(screenNumber);
	gray=(white+black)/2;
	if round(gray)==white
		gray=black;
	end
	inc=white-gray;
	
	% Open a double buffered fullscreen window and draw a gray background 
	% to front and back buffers:
	[w screenRect]=Screen('OpenWindow',screenNumber, gray);

    % Enable alpha-blending:
    Screen('BlendFunction', w, GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);

    % Show initial gray screen:
    Screen('Flip', w);

    % Calculate parameters of the grating:
    p=ceil(1/f);  % pixels/cycle    
    fr=f*2*pi;
    visiblesize=2*texsize+1;

    % Create one single static grating image:
    [x,y]=meshgrid(-2*texsize:2*texsize + p, -texsize:texsize);
    grating=gray + inc*cos(fr*x);

    % Store grating in texture:
    gratingtex=Screen('MakeTexture', w, grating);

    % Create a single gaussian transparency mask and store it to a texture:
    mask=ones(2*texsize+1, 2*texsize+1, 2) * gray;
    [x,y]=meshgrid(-1*texsize:1*texsize,-1*texsize:1*texsize);
    mask(:, :, 2)=white * (1 - exp(-((x/45).^2)-((y/45).^2)));
    masktex=Screen('MakeTexture', w, mask);
    
    % Query duration of monitor refresh interval:
    ifi=Screen('GetFlipInterval', w);
    
    waitframes = 1;
    waitduration = waitframes * ifi;
    
    % Translate requested speed of the grating (in cycles per second)
    % into a shift value in "pixels per frame", assuming given
    % waitduration: This is the amount of pixels to shift our "aperture" at
    % each redraw:
    shiftperframe= cyclespersecond * p * waitduration;
    
    Screen('TextSize', w, 24);
    
    % Slide 1: The static grating texture:
    [xp yp] = DrawFormattedText(w, 'Step 1: Generate a single static texture which shows the periodic grating pattern: The texture must contain at least two full periods of the pattern.\nPress a key to continue.\n\n', 0, 20, 0, 50);
    cmd = 'gratingtex = Screen(''MakeTexture'', w, gratingmatrix);\nScreen(''DrawTexture'', w, gratingtex);';
    [xp yp] = DrawFormattedText(w, cmd, xp, yp, 255);
    Screen('DrawTexture', w, gratingtex);
    Screen('Flip', w);

    GetClicks(w);
    
    % Slide 2: Cut out an aperture from the texture, and render it to a
    % dstRect of same size:

    autodrift = 0;
    xoffset = 0;
    angle = 0;
    i=0;

    while (1)
        [x y buttons] = GetMouse(w);

        if buttons(1) && ~autodrift
            xoffset = x - 100;
            xoffset = max(xoffset, 0);
            xoffset = min(xoffset, 2*texsize);
        end
              
        if buttons(2)
            autodrift = mod(autodrift+1, 3);
            while buttons(2)
                [x y buttons] = GetMouse(w);
            end
        end
        
        if autodrift >= 1
            % Shift the grating by "shiftperframe" pixels per frame:
            xoffset = mod(i*shiftperframe,p);
            i=i+1;
            
            if buttons(1)
                angle = x / RectWidth(screenRect) * 360.0;
            end
        end
                
        if autodrift == 0
            [xp yp] = DrawFormattedText(w, 'Step 2: Cut out a rectangular subregion ''srcRect'' from the texture and draw it to the screen area ''dstRect'' of same size. The texture is shown through an aperture.\nMoving the aperture creates apparent smooth motion. - Try it with the mouse!\nPress a key to continue.\n\n', 0, 20, 0, 50);
        else
            if autodrift >= 1
                [xp yp] = DrawFormattedText(w, 'Step 3: Horizontal shifting of the cut-out aperture region ''srcRect'' creates a nice drifting pattern. Subpixel accurate movements are possible due to hardware bilinear texture interpolation.\nPress a key to continue.\n\n', 0, 20, 0, 50);
                if angle~=0
                    [xp yp] = DrawFormattedText(w, '\nIt is also possible to rotate the ''dstRect'' destination region by some angle to create a rotated grating.\n', 0, yp, 0, 50);
                end
            end
            if autodrift == 2
                [xp yp] = DrawFormattedText(w, '\nOne can mask the ''dstRect'' destination region with a ''transparency mask'' texture by use of alpha-blending.\n', 0, yp, 0, 50);                
            end
        end
        
        cmd = 'Screen(''DrawTexture'', w, gratingtex, ';
        yp=yp+20;
        [xp] = DrawFormattedText(w, cmd, 0, yp, 255);
        cmd = 'srcRect, ';
        [xp] = DrawFormattedText(w, cmd, xp, yp, [255 0 0]);
        cmd = 'dstRect';
        [xp] = DrawFormattedText(w, cmd, xp, yp, [255 255 0]);
        if angle==0
            cmd = ');\n';
        else
            cmd = [', ' num2str(angle) ');\n'];
        end
        [xp yp] = DrawFormattedText(w, cmd, xp, yp, 255);
        
        % Draw static grating texture:
        dstRect = OffsetRect(Screen('Rect', gratingtex), 100, yp + 50);
        Screen('DrawTexture', w, gratingtex, [], dstRect);

        % Define shifted srcRect that cuts out the properly shifted rectangular
        % area from the texture:
        srcRect=[xoffset 0 xoffset + visiblesize visiblesize];
        apertRect = OffsetRect(srcRect, 100, yp + 50);
        Screen('FrameRect', w, [255 0 0], apertRect, 4);
        % Definition of the drawn rectangle on the screen:
        dstRect=[0 0 visiblesize visiblesize];
        dstRect=OffsetRect(dstRect, 600, yp + 150);
        Screen('DrawLine', w, [255 0 0 128], apertRect(1), apertRect(2), dstRect(1), dstRect(2), 4);
        Screen('DrawLine', w, [255 0 0 128], apertRect(3), apertRect(2), dstRect(3), dstRect(2), 4);
        Screen('DrawLine', w, [255 0 0 128], apertRect(1), apertRect(4), dstRect(1), dstRect(4), 4);
        Screen('DrawLine', w, [255 0 0 128], apertRect(3), apertRect(4), dstRect(3), dstRect(4), 4);
        % Draw grating texture:
        Screen('DrawTexture', w, gratingtex, srcRect, dstRect, angle);
        Screen('FrameRect', w, [255 255 0], dstRect, 4);
        
        if autodrift == 2
            maskRect = CenterRectOnPoint(dstRect, x, y);
            xp = 0;
            cmd = sprintf('Screen(''DrawTexture'', w, masktex, [], [%i %i %i %i], %f);\n', maskRect(1), maskRect(2), maskRect(3), maskRect(4), angle);
            [xp] = DrawFormattedText(w, cmd, xp, yp, 255);
            Screen('DrawTexture', w, masktex, [], maskRect, angle);
        end
        
        if KbCheck
            break;
        end
        
        Screen('Flip', w);
    end
        
    KbReleaseWait;
        
    % Perform initial Flip to sync us to the VBL and for getting an initial
    % VBL-Timestamp for our "WaitBlanking" emulation:
    vbl=Screen('Flip', w);

    i=0;
    dstRect = CenterRect(dstRect, screenRect);
    
    % Animationloop:
    while(1)
        % Shift the grating by "shiftperframe" pixels per frame:
        xoffset = mod(i*shiftperframe,p);
        i=i+1;
        
        % Define shifted srcRect that cuts out the properly shifted rectangular
        % area from the texture:
        srcRect=[xoffset 0 xoffset + visiblesize visiblesize];
        
        % Draw grating texture, rotated by "angle":
        Screen('DrawTexture', w, gratingtex, srcRect, dstRect, angle);

        if drawmask==1
            % Draw gaussian mask over grating: We need to subtract 0.5 from
            % the real size to avoid interpolation artifacts that are
            % created by the gfx-hardware due to internal numerical
            % roundoff errors when drawing rotated images:
            Screen('DrawTexture', w, masktex, [0 0 visiblesize visiblesize], dstRect, angle);
        end

        angle = angle + 0.1;
        
        % Flip 'waitframes' monitor refresh intervals after last redraw.
        vbl = Screen('Flip', w, vbl + (waitframes - 0.5) * ifi);

        % Abort demo if any key is pressed:
        if KbCheck
            break;
        end
    end

    %The same commands wich close onscreen and offscreen windows also close
	%textures.
	sca;

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;
    psychrethrow(psychlasterror);
end %try..catch..