Screen('OpenVideoCapture')

Psychtoolbox › Screen.{mex*,dll} subfunction

Try to open the video source 'deviceIndex' for video capture into onscreen
window 'windowPtr' and return a handle 'videoPtr' on success. If 'deviceIndex'
is left out, it defaults to zero - use the first capture device attached to your
machine. 'roirectangle' if specified, defines the requested size for captured
images. The default is to return the maximum size image provided by the capture
device. A 'roirectangle' setting of [0 0 width height] will not define a region
of interest, but instead request a video capture resolution of width x height
pixels, instead of the default maximum resolution. Settings of [left top right
bottom] will leave video capture at maximum resolution, but crop the images to
the rectangular subregion as defined by the given left, right, top and bottom
borders. Such ROI's are only applied to returned video images, not to recorded
video by default. See the 'recordingflags' settings below on how to adjust this
behaviour to your needs.
The real ROI (region of interest) may differ from the requested one, depending
on the capabilities of your capture device. 'pixeldepth' if provided, asks for
the number of layers that captured textures should have: 1=Luminance image,
2=Luminance+Alpha image, 3=RGB image, 4=RGB+Alpha, 5=YCBCR image. Default is to
take whatever the capture device provides by default. Different devices support
different formats so some of these settings may be ignored. Some combinations of
video capture devices and graphics cards may support a setting of 5=YCBCR
encoding. If they do, then this is an especially efficient way to handle color
images, which may result in lower cpu load and higher framerates.
'numbuffers' if provided, specifies the number of internal video buffers to use.
It defaults to a value that is optimal for your specific hardware for common
use. 'allowfallback' if set to 1, will allow Psychtoolbox to use a less
efficient mode of operation for video capture if your specific hardware or
operating system setup doesn't allow to use the high-performance mode.
'allowfallback' defaults to 1 = Allow fallback path.
'targetmoviename' If you provide a filename for this argument, PTB will record
the captured video to the specified movie file on your filesystem. PTB will use
a default video codec for encoding the video stream. If you want to use a
specific codec, you can extend the targetmoviename by a string of format
:CodecType=xxx , where xxx is the numeric type id or name of the codec. You can
get a list of codecs supported by your system by running PTB's recording engine
at a verbosity level of 4 or higher.
However, please read 'help VideoRecording' for many more options for tweaking
the video recording process via the 'targetmoviename' parameter.
'recordingflags' specify the behaviour of harddisc- recording: 0 (default) =
Only record video. 2 = Record audio track as well. The value 1 (or 1+2) asks PTB
to first record into system memory, and only write the movie file after capture
has been stopped. This allows for higher capture framerates, but is limited in
recording time by installed memory. Also, this mode currently can sometimes
cause hangs and crashes of PTB for unknown reasons, so better avoid!
A setting of 4 will only enable recording, but no return of captured data, i.e.,
just record to disk. A setting of 8 will avoid some calls that are supposed to
provide better realtime behaviour, but may cause some problems with some video
codecs when recording to disk. A setting of 16 will perform most of the heavy
work on a separate parallel background thread, utilizing multi-core machines
better.
A setting of 32 will try to select the highest quality codec for texture
creation from captured video, instead of the normal quality codec. A setting of
64 will return capture timestamps in the time base of the video engine (e.g.,
elapsed time since start of capture, or recording time in movie), instead of the
default time base, which is regular GetSecs() time.
A setting of 128 will force use of a videorate converter in pure live capture
mode. By default the videorate converter is only used if video recording is
active. The converter makes sure that video is recorded (or delivered) at
exactly the requested capture framerate, even if the system isn't really capable
of maintaining that framerate: If the video source (camera) delivers frames at a
too low framerate, the converter will insert duplicated frames to boost up
effective framerate. If the source delivers more frames than the engine can
handle (e.g., system overload or video encoding too slow) the converter will
drop frames to reduce effective framerate. Slight fluctuations are compensated
by adjusting the capture timestamps. This mechanism guarantees a constant
framerate in recorded video as well as the best possible audio-video sync and
smoothness of video, given system constraints. The downside may be that the
recorded content and returned timestamps don't reflect the true timing of
capture, but a beautified version. In pure live capture, rate conversion is off
by default to avoid such potential confounds in the timestamps. Choose this
options carefully.
A setting of 256 in combined video live capture and video recording mode will
restrict video framerate conversion to the recorded videostream, but provide
mostly untampered true timing to the live capture. By default, framerate
conversion applies to recording and live feedback if video recording is enabled.
A setting of 512 requests that ROI's as defined by the 'roirectangle' parameter
get also applied to recorded video. Without this setting, ROI's only apply to
live video as returned by Screen('GetCapturedImage',...);
A setting of 1024 disables application of ROI's to live video as returned by
Screen('GetCapturedImage',...);
'captureEngineType' This optional parameter allows selection of the video
capture engine to use for this video source. Allowable values are currently 0, 1
and 3. Zero selects Apples Quicktime Sequence-Grabber API as capture engine,
which is supported on MacOS/X and MS-Windows (for Windows you'll need to install
a Quicktime Video digitizer component VDIG). The Quicktime engine allows movie
recording and sound recording as well (see above). A value of 1 selects Firewire
video capture via the free software library libdc1394-V2. That engine only
supports high performance machine vision cameras that are compliant with the
IIDC-1.x standard and that are connected via a Firewire (IEEE1394) bus system.
Use of the engine with such cams allows for much higher flexibility and
performance than use of video capture via Quicktime, however, video recording to
harddisk or sound recording isn't yet supported with firewire capture, ie., the
'targetmoviename' is simply ignored. The firewire capture engine is supported on
Linux, MacOS/X and - maybe in the future, with quite a few limitations and bugs
- on Windows.
A value of 3 selects the GStreamer video capture engine. This engine will be
supported on all operating systems and will allow for video and sound recording
of captured video and audio streams. Currently it is not yet implemented on Mac
OS/X. Type 'help GStreamer' for installation and setup instructions for the
required GStreamer runtime libraries.
If you don't specify 'captureEngineType', the global setting from
Screen('Preference', 'DefaultVideoCaptureEngine') will be used. If you don't
specify that either then engine selection will default to Quicktime for MacOS/X
and GStreamer on Linux and MS-Windows.
To summarize:
Quicktime engine: Supports all cameras/video sources supported by your operating
system, allows for video- and audio recording as well. On many setups, only one
camera can be used at a time and the 'deviceIndex' parameter is ignored -- the
default source is always chosen. Latency, max framerate and reliability is ok,
but not stellar.
GStreamer: Is the engine of choice for all operating systems and most
applications.
Firewire engine: Supports only Firewire machine vision cameras, but allows free
selection among all connected cameras, simultaneous operation of many cameras,
low latency, high framerates and reliability, precise timestamping and low level
access to many special features of such cameras, e.g., gain-, shutter-,
exposure-, trigger controls etc.