Get an image from a window or texture and add it as a new video frame to a
movie.
Calling this function on an onscreen window while an asynchronous flip is
pending on the window due to
Screen('
AsyncFlipBegin') is not allowed! Finalize
such flips first. Readback of other onscreen or offscreen windows or textures is
possible during async flip, but discouraged because it will have a significant
impact on performance.
"windowPtr" is the handle of the onscreen window, offscreen window or texture
whose image should be added.
"rect" is the rectangular subregion to get, and its default is the whole window.
The function will only honor the top-left corner of the 'rect' argument, but
ignore the bottom-right corner and thereby the width and height as defined by
the 'rect'. The size of added video frames is fully defined as the fixed size of
movie frames as specified at movie creation time via the
Screen('
CreateMovie')
call.
"bufferName" is a string specifying the buffer from which to copy the image: The
'bufferName' argument is meaningless for offscreen windows and textures and will
be silently ignored. For onscreen windows, it defaults to 'frontBuffer', i.e.,
it returns the image that your subject would see at that moment. If
frame-sequential stereo mode is enabled, 'frontLeftBuffer' returns what your
subject would see in its left eye, 'frontRightBuffer' returns the subjects
right-eye view. If double-buffering is enabled, you can also return the
'backBuffer', i.e. what your subject will see after the next
Screen('
Flip')
command, and for frame-sequential stereo also 'backLeftBuffer' and
'backRightBuffer' respectively. 'aux0Buffer' - 'aux3Buffer' returns the content
of
OpenGL AUX buffers 0 to 3. Only query the AUX buffers if you know what you
are doing, otherwise your script will crash. This is mostly meant for internal
debugging of PTB. If the imaging pipeline is enabled you can also return the
content of the unprocessed backbuffer, ie. before processing by the pipeline, by
requesting 'drawBuffer'.
"moviePtr" is the optional handle to the movie to which the video frame should
be added. You can get this handle from the
Screen('
CreateMovie') function when
creating the movie. By default frames are added to the first movie created with
Screen('
CreateMovie').
"frameduration" optionally defines the display duration of the added video frame
in units of movie frame intervals. See the help for '
CreateMovie' for further
explanation of "frameduration".
Movie images are always stored as uint8 images with 8 bits resolution per pixel
color component. Images are always stored as four channel RGBA frames.
See
Screen('
CreateMovie?') for help on movie creation.