Additions:
%%(matlab;Usage)[VBLTimestamp StimulusOnsetTime FlipTimestamp Missed Beampos] = Screen('AsyncFlipBegin', windowPtr [, when] [, dontclear] [, dontsync] [, multiflip]);%%
If this command is called while a previously scheduled asynchronous flip is
still in progress, it will wait for that pending async flip to finish and return
its results (timestamps etc.). If no such operation is in progress, it will
return results of the most recently finished async or sync flip. Waiting for
previous flips to complete and returning their results is a convenience
function. In most cases, in order to have more control over the execution of
your script and your flip timing, you will rather want to use one of the
finalizer commands [[Screen]]('AsyncFlipCheckEnd') or [[Screen]]('AsyncFlipEnd')
asynchronous flip operation.
windows while their parent-onscreen window is in async flip state. You can
only access onscreen windows which are not participating in an async flip
operation.
- If you enable the Psychtoolbox image processing pipeline, most restrictions
on drawing during async flips are relaxed: You can draw into any windows while
async flips are pending, even the window for which the flip is pending. Only
use of the [[Screen]]('GetImage') command is forbidden on async flipping onscreen
windows and potentially problematic on offscreen windows while an async flip
is in progress. However, this is somewhat theoretical. In practice many
operating systems, graphics drivers and graphics cards can't really handle the
load of parallel drawing and async flipping, due to system bugs or design
constraints. On such systems you may observe inconsistent timing, degraded
performance, and on some systems even visual stimulus corruption, malfunctions
or hard system crashes [e.g., Apple MacOS/X 10.4.11 with ATI Radeon X1600]!
- Even the restricted set of allowed reliably working [[Screen]]/OpenGL commands
should be avoided, because some graphics hardware and drivers may not be
- Parallel processing of flips puts additional burden onto your CPU,
- Code with async flips - as any piece of parallely executing code - is harder
to implement correctly and more challenging to debug for you.
- Asynchronous updates of gamma tables will likely not work reliably.
- Stereo stimulus display in stereomode 10 (two separate onscreen windows) will
likely not work with reliable timing or have possible tearing artifacts.
async flips, so this feature is provided for the few demanding special cases
where this is not the case and the benefits outweight the costs.
Deletions:
%%(matlab;Usage)Screen('AsyncFlipBegin', windowPtr [, when] [, dontclear] [, dontsync] [, multiflip]);%%
This command doesn't return anything, you'll need to use the finalizer commands
flip operation.
windows while any onscreen window is in async flip state. You can only
access onscreen windows which are not participating in an async flip
operation. Even the restricted set of allowed [[Screen]]/OpenGL commands should
be avoided if possible, because some graphics hardware and drivers may not be
- Parallel processing of flips puts additional burden and load onto your CPU,
- Code with async flips - as any piece of parallel code - is harder to
get right and more challenging to debug for you.
- Asynchronous updates of gamma tables may not work reliably.
async flips, so this feature is here for the few cases where this is not the
case and the benefits outweight the costs.
Additions:
%%(matlab;Usage)Screen('AsyncFlipBegin', windowPtr [, when] [, dontclear] [, dontsync] [, multiflip]);%%
Schedule an asynchronous flip of front and back display surfaces for given
onscreen window. "windowPtr" is the id of the onscreen window whose content
should be shown at flip time. "when" is the requested stimulus onset time, a
value of zero or no argument asks for flip at next possible vertical retrace.
For the meaning and explanation of all other parameters, see the help for
'[[Screen]] [[Flip]]?'.
This command doesn't return anything, you'll need to use the finalizer commands
mentioned below to collect information about the final result and timing of the
flip operation.
The difference between [[Screen]]('AsyncFlipBegin',...); and the more commonly used
[[Screen]]('[[Flip]]', ...); is that [[Screen]]('[[Flip]]') operates synchronously: Execution of
your code is paused until the flip operation has finished, ie. at least until
the requested onset deadline 'when' has passed.
[[Screen]]('AsyncFlipBegin') will prepare everything for a flip at the requested
time 'when' - or at next vertical retrace if 'when' is omitted - but then
immediately return control to your code. Your code can continue to execute and
do other things, e.g., schedule flips for other onscreen windows, perform
keyboard or mouse queries, etc.
You can check the progress state of asynchronous flips or wait for them to
finish and collect timing information for the finalized flip by use of the
commands [[Screen]]('AsyncFlipCheckEnd') and [[Screen]]('AsyncFlipEnd');
In general you should avoid using asynchronous flips and instead use
conventional '[[Flip]]' unless you have a good reason to do otherwise, because async
flips come with a couple of strings attached:
- You are restricted in what you can do with [[Screen]]() or OpenGL while async
flips are in progress: You can not do anything with textures or offscreen
windows while any onscreen window is in async flip state. You can only
access onscreen windows which are not participating in an async flip
operation. Even the restricted set of allowed [[Screen]]/OpenGL commands should
be avoided if possible, because some graphics hardware and drivers may not be
able to handle such concurrent graphics operations without degraded stimulus
onset timing accuracy, ie. you may experience more missed stimulus deadlines
and timing glitches -- or inconsistent behaviour accross different computers
and graphics cards or operating system releases. In the end it allows you to
do non-[[Screen]] related things like sound, I/O, keyboard checks...
- Parallel processing of flips puts additional burden and load onto your CPU,
GPU and operating system, so it incurs additional overhead and may degrade
absolute drawing performance and cause more timing issues and glitches if
your system is not reliably able to handle the concurrent load.
- Code with async flips - as any piece of parallel code - is harder to
get right and more challenging to debug for you.
- Using a non-zero "multiflip" argument is not allowed.
- Asynchronous updates of gamma tables may not work reliably.
- Use of the 'UserspaceBufferDrawingPrepare' hook-chain of the imaging
pipeline is not allowed.
Our general stance is that most code can be written efficiently without need for
async flips, so this feature is here for the few cases where this is not the
case and the benefits outweight the costs.
Deletions:
%%(matlab;Usage)[VBLTimestamp StimulusOnsetTime FlipTimestamp Missed Beampos] = Screen('Flip', windowPtr [, when] [, dontclear] [, dontsync] [, multiflip]);%%
[[Flip]] front and back display surfaces in sync with vertical retrace and return
timestamps. "windowPtr" is the id of the onscreen window whose content should be
shown at flip time. "when" specifies when to flip: If set to zero (default), it
will flip on the next possible retrace.If set to a value when > 0, it will flip
at the first retrace after system time 'when' has been reached."dontclear" If
set to 1, flip will not clear the framebuffer after [[Flip]] - this allows
incremental drawing of stimuli. The default is zero, which will clear the
framebuffer to background color after each flip. A value of 2 will prevent [[Flip]]
from doing anything to the framebuffer after flip. This leaves the job of
setting up the buffer to you - the framebuffer is in an undefined state after
flip. "dontsync" If set to zero (default), [[Flip]] will sync to the vertical
retrace and will pause Matlabs executionuntil the [[Flip]] has happened. If set to
1, [[Flip]] will still synchronize stimulus onset to the vertical retrace, butwill
*not* wait for the flip to happen: [[Flip]] returns immediately and all returned
timestamps are invalid. A value of 2will cause [[Flip]] to show the stimulus
*immediately* without waiting/syncing to the vertical retrace. "multiflip"
defaults to zero: If set to a value greater than zero, [[Flip]] will flip *all*
onscreen windows instead of just the specified one. This allows to synchronize
stimulus onset on multiple displays, e.g., for multidisplay stereo setups or
haploscopes. You need to (somehow) synchronize all attached displays for this to
operate tear-free. [[Flip]] (optionally) returns a high-precision estimate of the
system time (in seconds) when the actual flip has happened in the return
argument 'VBLTimestamp'. An estimate of Stimulus-onset time is returned in
'StimulusOnsetTime'. Beampos is the position of the monitor scanning beam when
the time measurement was taken (useful for correctness tests). FlipTimestamp is
a timestamp taken at the end of [[Flip]]'s execution. Use the difference between
FlipTimestamp and VBLTimestamp to get an estimate of how long Flips execution
takes. This is useful to get a feeling for the timing error if you try to sync
Matlabs execution to the retrace, e.g., for triggering acquisition devices like
EEG, fMRI, or for starting playback of a sound. "Missed" indicates if the
requested presentation deadline for your stimulus has been missed. A negative
value means that dead- lines have been satisfied. Positive values indicate a
deadline-miss. The automatic detection of deadline-miss is not fool-proof - it
can report false positives and also false negatives, although it should work
fairly well with most experimental setups. If you are picky about timing, please
use the provided timestamps or additional methods to exercise your own tests.
Additions:
""<div class="subfct" id="Screen">""===[[AsyncFlipBegin Screen('AsyncFlipBegin')]]===
Deletions:
""<div class="subfct" id="Screen" style="background-color:#eee; padding:1em; border-width:1px; border-style:solid; border-color:#ddd; margin-bottom: 2em;border-top: 5px solid #999999;">""===[[AsyncFlipBegin Screen('AsyncFlipBegin')]]===
Additions:
""<div class="subfct" id="Screen" style="background-color:#eee; padding:1em; border-width:1px; border-style:solid; border-color:#ddd; margin-bottom: 2em;border-top: 5px solid #999999;">""===[[AsyncFlipBegin Screen('AsyncFlipBegin')]]===
DrawingFinished WaitUntilAsyncFlipCertain AsyncFlipBegin AsyncFlipCheckEnd AsyncFlipEnd Flip<<""</div>""
Deletions:
===[[AsyncFlipBegin Screen('AsyncFlipBegin')]]===
DrawingFinished WaitUntilAsyncFlipCertain AsyncFlipBegin AsyncFlipCheckEnd AsyncFlipEnd Flip<<
Additions:
===[[AsyncFlipBegin Screen('AsyncFlipBegin')]]===
==[[Psychtoolbox]] › [[Screen]].{mex*,dll} subfunction==
%%(matlab;Usage)[VBLTimestamp StimulusOnsetTime FlipTimestamp Missed Beampos] = Screen('Flip', windowPtr [, when] [, dontclear] [, dontsync] [, multiflip]);%%
[[Flip]] front and back display surfaces in sync with vertical retrace and return
timestamps. "windowPtr" is the id of the onscreen window whose content should be
shown at flip time. "when" specifies when to flip: If set to zero (default), it
will flip on the next possible retrace.If set to a value when > 0, it will flip
at the first retrace after system time 'when' has been reached."dontclear" If
set to 1, flip will not clear the framebuffer after [[Flip]] - this allows
incremental drawing of stimuli. The default is zero, which will clear the
framebuffer to background color after each flip. A value of 2 will prevent [[Flip]]
from doing anything to the framebuffer after flip. This leaves the job of
setting up the buffer to you - the framebuffer is in an undefined state after
flip. "dontsync" If set to zero (default), [[Flip]] will sync to the vertical
retrace and will pause Matlabs executionuntil the [[Flip]] has happened. If set to
1, [[Flip]] will still synchronize stimulus onset to the vertical retrace, butwill
*not* wait for the flip to happen: [[Flip]] returns immediately and all returned
timestamps are invalid. A value of 2will cause [[Flip]] to show the stimulus
*immediately* without waiting/syncing to the vertical retrace. "multiflip"
defaults to zero: If set to a value greater than zero, [[Flip]] will flip *all*
onscreen windows instead of just the specified one. This allows to synchronize
stimulus onset on multiple displays, e.g., for multidisplay stereo setups or
haploscopes. You need to (somehow) synchronize all attached displays for this to
operate tear-free. [[Flip]] (optionally) returns a high-precision estimate of the
system time (in seconds) when the actual flip has happened in the return
argument 'VBLTimestamp'. An estimate of Stimulus-onset time is returned in
'StimulusOnsetTime'. Beampos is the position of the monitor scanning beam when
the time measurement was taken (useful for correctness tests). FlipTimestamp is
a timestamp taken at the end of [[Flip]]'s execution. Use the difference between
FlipTimestamp and VBLTimestamp to get an estimate of how long Flips execution
takes. This is useful to get a feeling for the timing error if you try to sync
Matlabs execution to the retrace, e.g., for triggering acquisition devices like
EEG, fMRI, or for starting playback of a sound. "Missed" indicates if the
requested presentation deadline for your stimulus has been missed. A negative
value means that dead- lines have been satisfied. Positive values indicate a
deadline-miss. The automatic detection of deadline-miss is not fool-proof - it
can report false positives and also false negatives, although it should work
fairly well with most experimental setups. If you are picky about timing, please
use the provided timestamps or additional methods to exercise your own tests.
<<=====See also:=====
DrawingFinished WaitUntilAsyncFlipCertain AsyncFlipBegin AsyncFlipCheckEnd AsyncFlipEnd Flip<<
Deletions:
===[[AsyncFlipBegin]]===
==ScreenFunctions==
Usage:
Screen('AsyncFlipBegin', windowPtr [, when] [, dontclear] [, dontsync] [, multiflip]);
Schedule an asynchronous flip of front and back display surfaces for given
onscreen window. "windowPtr" is the id of the onscreen window whose content
should be shown at flip time. "when" is the requested stimulus onset time, a
value of zero or no argument asks for flip at next possible vertical retrace.
For the meaning and explanation of all other parameters, see the help for
'Screen Flip?'.
This command doesn't return anything, you'll need to use the finalizer commands
mentioned below to collect information about the final result and timing of the
flip operation.
The difference between Screen('AsyncFlipBegin',...); and the more commonly used
Screen('Flip', ...); is that Screen('Flip') operates synchronously: Execution of
your code is paused until the flip operation has finished, ie. at least until
the requested onset deadline 'when' has passed.
Screen('AsyncFlipBegin') will prepare everything for a flip at the requested
time 'when' - or at next vertical retrace if 'when' is omitted - but then
immediately return control to your code. Your code can continue to execute and
do other things, e.g., schedule flips for other onscreen windows, perform
keyboard or mouse queries, etc.
You can check the progress state of asynchronous flips or wait for them to
finish and collect timing information for the finalized flip by use of the
commands Screen('AsyncFlipCheckEnd') and Screen('AsyncFlipEnd');
In general you should avoid using asynchronous flips and instead use
conventional 'Flip' unless you have a good reason to do otherwise, because async
flips come with a couple of strings attached:
- They are not portable to MS-Windows: Code written with async flip will only
work on Apple OS/X and GNU/Linux. There are no plans to ever support this
feature on MS-Windows, we don't want to beat that shaky beast to death...
- You are restricted in what you can do with Screen() or OpenGL while async
flips are in progress: You can not do anything with textures or offscreen
windows while any onscreen window is in async flip state. You can only
access onscreen windows which are not participating in an async flip
operation. Even the restricted set of allowed Screen/OpenGL commands should
be avoided if possible, because some graphics hardware and drivers may not be
able to handle such concurrent graphics operations without degraded stimulus
onset timing accuracy, ie. you may experience more missed stimulus deadlines
and timing glitches -- or inconsistent behaviour accross different computers
and graphics cards or operating system releases. In the end it allows you to
do non-Screen related things like sound, I/O, keyboard checks...
- Parallel processing of flips puts additional burden and load onto your CPU,
GPU and operating system, so it incurs additional overhead and may degrade
absolute drawing performance and cause more timing issues and glitches if
your system is not reliably able to handle the concurrent load.
- Code with async flips - as any piece of parallel code - is harder to
get right and more challenging to debug for you.
- Using a non-zero "multiflip" argument is not allowed.
- Asynchronous updates of gamma tables may not work reliably.
- Use of the 'UserspaceBufferDrawingPrepare' hook-chain of the imaging
pipeline is not allowed.
Our general stance is that most code can be written efficiently without need for
async flips, so this feature is here for the few cases where this is not the
case and the benefits outweight the costs.
ScreenFunctions