function DetectionRTInVideoDemo(moviename, timeOfEvent, trials)
%
% DetectionRTInVideoDemo(moviename, timeOfEvent, trials)
%
% A demo implementation of how to collect reaction time for detection of a
% specific time-locked event in a movie file.
%
% Parameters:
% moviename - Filename of moviefile to use. If none is provided, then the
% simple DualDiscs collision movie is used which is part of PTB.
%
% timeOfEvent - Time (in seconds) when the timelocked event happens which
% should be detected by the subject. Default is time of contact of the
% DualDiscs collision.
%
% trials - Number of trials to run. Defaults to 10 or ESC key press.
%
% How the demo works: Read the source code - its well documented ;-)
% This demo demonstrates the optimal way if you have movies with sound
% (that needs to be played in sync with the video) or long movies that
% don't fit into memory or that you don't want to load into memory.
%
% It uses automatic synchronized audio-video playback. The central
% while-loop checks for arrival of new frames for display and displays them
% when their time has come. It also registers subjects keypress responses
% and does all the bookkeeping and sanity checking.
%
% An alternative approach would be to preload the whole movie into textures:
% The whole movie gets read into PTB textures before start of trial. Then
% you show the textures in quick succession like in MovieDemo. The
% advantage of that approach is exact control over display timing and
% display order: You can show frames in any order you like at any rate you
% like (and that your hardware likes). Disadvantage would be: Longer trial
% setup time for loading the whole movie, higher memory consumption (keep
% all n frames in memory instead of only the current one) and the inability
% to play sound in sync with video.
%
% History:
% 12/19/05 mk Wrote it.
% 02/03/06 mk Adapted for use on Windows.
% 03/11/12 mk Cleanup.
% 06/17/13 mk Cleanup.
if nargin < 1
% Default movie is our own disc collision movie:
moviename = [ PsychtoolboxRoot 'PsychDemos/MovieDemos/DualDiscs.mov' ];
end;
if nargin < 2
timeOfEvent = 1.16;
end;
if nargin < 3
trials = 10;
end;
fprintf('Loading probe movie %s ...\n', moviename);
fprintf('Time locked probe event will happen at time %f secs after start of movie.\n', timeOfEvent);
fprintf('Will run %i trials or until ESCape key is pressed.\n', trials);
% Switch KbName into unified mode: It will use the names of the OS-X
% platform on all platforms in order to make this script portable:
KbName('UnifyKeyNames');
% Query keycodes for ESCAPE key and Space key:
esc=KbName('ESCAPE');
space=KbName('space');
try
% Child protection: Make sure we run on the OSX / OpenGL Psychtoolbox.
% Abort if we don't:
AssertOpenGL;
% Background color will be a grey one:
background=[128, 128, 128];
% Open onscreen window. We use the display with the highest number on
% multi-display setups:
screen=max(Screen('Screens'));
% This will open a screen with background color 'background':
win = Screen('OpenWindow', screen, background);
% Hide the mouse cursor:
HideCursor;
% Show instructions...
tsize=30;
Screen('TextSize', win, tsize);
[x, y]=Screen('DrawText', win, 'Collision detection fake experiment.',40, 100); %#ok<*ASGLU>
[x, y]=Screen('DrawText', win, 'Press ESC-ape key to abort anytime.', 40, y + 10 + tsize);
[x, y]=Screen('DrawText', win, 'Press SPACE key when you see the discs colliding', 40, y + 10 + tsize);
Screen('DrawText', win, 'Press any key to start the experiment...', 40, y + 10 + tsize);
% Flip to show the grey screen:
Screen('Flip',win);
% Wait for keypress + release...
KbStrokeWait;
% Show cleared screen...
Screen('Flip',win);
% Wait a second...
WaitSecs(1);
% Main trial loop: Do 'trials' trials...
for i=1:trials
% Open the moviefile and query some infos like duration, framerate,
% width and height of video frames. We could also query the total count of frames in
% the movie, but computing 'framecount' takes long, so avoid to query
% this property if you don't need it!
[movie movieduration fps] = Screen('OpenMovie', win, moviename);
% We estimate framecount instead of querying it - faster:
framecount = movieduration * fps;
% Start playback of the movie:
% Play 'movie', at a playbackrate = 1 (normal speed forward),
% play it once, aka with loopflag = 0,
% play audio track at volume 1.0 = 100% audio volume.
Screen('PlayMovie', movie, 1, 0, 1.0);
% Video playback and key response RT collection loop:
% This loop repeats until either the subject responded with a
% keypress to indicate s(he) detected the event in the vido, or
% until the end of the movie is reached.
movietexture=0; % Texture handle for the current movie frame.
reactiontime=-1; % Variable to store reaction time.
lastpts=0; % Presentation timestamp of last frame.
onsettime=-1; % Realtime at which the event was shown to the subject.
rejecttrial=0; % Flag which is set to 1 to reject an invalid trial.
while(movietexture>=0 && reactiontime==-1)
% Check if a new movie video frame is ready for visual
% presentation: This call polls for arrival of a new frame. If
% a new frame is ready, it converts the video frame into a
% Psychtoolbox texture image and returns a handle in
% 'movietexture'. 'pts' contains a so called presentation
% timestamp. That is the time (in seconds since start of movie)
% at which this video frame should be shown on the screen.
% Arrival of textures is automatically synchronized to the
% audio track and to real-world time. If the video display loop
% can't keep up with the flow of time and the soundtrack,
% the engine will automatically skip/drop frames to keep video
% in sync with audio as good as possible. If the pts of a new
% texture is greater than the 'timeOfEvent' then you'll know
% that this texture will show the visual target event as soon
% as you draw and 'Flip' it.
% In case that no new video texture is available yet for
% presentation, this function will return a zero texture handle
% to indicate this. If no new texture will become available
% anymore, because the end of the movie is reached, it will
% return a handle of -1 to indicate end of playback.
% The 0 - flag means: Don't wait for arrival of new frame, just
% return a zero or -1 'movietexture' if none is ready.
[movietexture pts] = Screen('GetMovieImage', win, movie, 0);
% Is it a valid texture?
if (movietexture>0)
% Yes. Draw the texture into backbuffer:
Screen('DrawTexture', win, movietexture);
% Flip the display to show the image at next retrace:
% vbl will contain the exact system time of image onset on
% screen: This should be accurate in the sub-millisecond
% range.
vbl=Screen('Flip', win);
% Is this the event video frame we've been waiting for?
if (onsettime==-1 && pts >= timeOfEvent)
% Yes: This is the first frame with a pts timestamp that is
% equal or greater than the timeOfEvent, so 'vbl' is
% the exact time when the event was presented to the
% subject. Define it as onsettime:
onsettime = vbl;
% Compare current pts to last one to see if the movie
% decoder skipped a frame at this crucial point in
% time. That would invalidate this trial.
if (pts - lastpts > 1.5*(1/fps))
% Difference to last frame is more than 1.5 times
% the expected difference under assumption 'no
% skip'. We skipped in the wrong moment!
rejecttrial=1;
end;
end;
% Keep track of the frames pts in order to check for skipped frames:
lastpts=pts;
% Delete the texture. We don't need it anymore:
Screen('Close', movietexture);
movietexture=0;
end;
% Done with drawing. Check the keyboard for subjects response:
[keyIsDown, secs, keyCode]=KbCheck;
if (keyIsDown==1)
% Abort requested?
if keyCode(esc)
% This signals abortion:
rejecttrial=-1;
% Break out of display loop:
break;
end;
% Space key pressed to indicate detection of event?
if keyCode(space)
% Response too early (before event happened?)
if (onsettime==-1)
% Reject this trial:
rejecttrial=2;
else
% Valid response: Difference between 'secs' and
% 'onsettime' is the reaction time:
reactiontime=secs - onsettime;
end;
end;
end;
end; % ...of display loop...
% Stop movie playback, in case it isn't already stopped. We do this
% by selection of a playback rate of zero: This will also return
% the number of frames that had to be dropped to keep audio, video
% and realtime in sync.
droppedcount = Screen('PlayMovie', movie, 0, 0, 0);
if (droppedcount > 0.2*framecount)
% Over 20% of all frames skipped?!? Playback problems! We
% reject this trial...
rejecttrial=4;
end;
% Close the moviefile.
Screen('CloseMovie', movie);
% Check if aborted.
if (rejecttrial==-1)
% Break out of trial loop
break;
end;
if (reactiontime==-1 && rejecttrial==0)
rejecttrial=3;
end;
% Print out trials result if it was a valid trial:
if (rejecttrial==0)
fprintf('Trial %i valid: Reaction time was %f msecs.\n', i, 1000 * reactiontime);
end;
if (rejecttrial==1)
fprintf('Trial %i rejected due to skip in video playback at time of event.\n', i);
end;
if (rejecttrial==2)
fprintf('Trial %i rejected. False detection by subject.\n', i);
end;
if (rejecttrial==3)
fprintf('Trial %i rejected. No detection by subject. Asleep?!?\n', i);
end;
if (rejecttrial==4)
fprintf('Trial %i rejected. Way too many skips in movie playback!!!\n', i);
end;
% Wait for subject to release keys:
KbReleaseWait;
end; % Trial done. Next trial...
% Done with the experiment. Close onscreen window and finish.
ShowCursor;
sca;
fprintf('Done. Bye!\n');
return;
catch %#ok<CTCH>
% Error handling: Close all windows and movies, release all ressources.
sca;
psychrethrow(psychlasterror);
end;