Psychtoolbox>Screen.{mex*} subfunction

oldvalue = Screen(‘SetVideoCaptureParameter’, capturePtr, ‘parameterName’ [, value]);

Set video capture parameter ‘parameterName’ on video capture device
If ‘value’ is provided, then the parameter is set to ‘value’ and the parameter
is switched to manual control mode. If ‘value’ is left out, then the current
setting of ‘parameterName’ is queried and returned. If ‘parameterName’ starts
with the word ‘Auto’ then the parameter is switched to automatic control, if
supported. In any case, the old value is returned. Type and range of supported
capture parameters varies between different capture devices and operating
systems. Your specific device may only support a subset (or none) of the
available parameters. If you specify an unsupported ‘parameterName’, your
request will be silently ignored, except that the return value is set to DBL_MAX

  • a very high number. The following settings are currently available on devices
    that support them: ‘Brightness’, ‘Gain’, ‘Exposure’, ‘Shutter’, ‘Sharpness’,
    ‘Hue’, ‘Saturation’, ‘Gamma’, ‘Iris’, ‘Focus’, ‘Zoom’, ‘Pan’, ‘Tilt’,
    ‘OpticalFilter’, ‘CaptureSize’, ‘CaptureQuality’, ‘FrameRate’, ‘TriggerDelay’.
    The special setting ‘PrintParameters’ prints all features to the command window.
    ‘GetVendorname’ and ‘GetModelname’ return the name of the device vendor, resp.
    the device model name. ‘GetROI’ returns the capture region of interest (ROI),
    which can deviate from the ROI requested in Screen(‘OpenVideoCapture’),
    depending on the capabilities of the capture device. ‘SetNextCaptureBinSpec=xxx’
    Will set the gst-launch line which describes the video capture source to be used
    during the next call to Screen(‘OpenVideoCapture’, -9, …); or the name or path
    of a video capture device to be used during the next call to
    Screen(‘OpenVideoCapture’) with a deviceIndex between -1 and -8.
    Opening a video capture device with the special deviceIndex -9 means to create a
    [GStreamer](GStreamer) bin and use it as video source. The bin is created by parsing the
    string passed here. Use the special ‘capturePtr’ value -1 when setting this bin
    description, as this call may need to be made while a capture device is not yet
    opened, so no valid ‘capturePtr’ exists. This setting is only honored on the
    [GStreamer](GStreamer) video capture engine.
    ‘GetFramerate’ Returns the nominal capture rate of the capture device.
    ‘GetBandwidthUsage’ Returns firewire bandwidth used by camera at current
    settings in so called bandwidth units. The 1394 bus has 4915 bandwidth units
    available per cycle. Each unit corresponds to the time it takes to send one
    quadlet at ISO speed S1600. The bandwidth usage at S400 is thus four times the
    number of quadlets per packet. In other words, it is complicated. This returns
    normalized bus bandwidth usage between 0.0 for 0% and 1.0 for 100%, assuming
    4915 units correspond to 100% bus utilization.
    ‘SetNewMoviename=xxx’ Will change the name of the videofile used for video
    recording to xxx. This allows you to change target files for video recordings
    without the need to close and reopen the capture device. You must stop capture
    though and then restart it after assigning a new filename.
    ‘SetGStreamerProcessingPipeline=xxx’ This assigns a [GStreamer](GStreamer) gst-launch style
    pipeline for use during post-processing of captured video on a libdc1394 capture
    device. This is only supported if multi-threaded video capture or recording is
    active via recordingflags & 16 and video capture was started with the
    ‘dropframes’ = 0 setting, so that all captured video is processed by a realtime
    thread and pushed through a [GStreamer](GStreamer) processing pipeline. You can build a
    processing pipeline of standard [GStreamer](GStreamer) plugins to do something to the video
    frames after they’ve been captured but before they are returned via
    Screen(‘GetCapturedImage’). The processing does not have any effect on recorded
    video footage.
    ‘StopAtFramecount’ Set or retrieve the framecounter value at which the camera
    should stop its capture operation. By default the camera will empty its queue of
    captured images before stopping in free-running mode. In synchronized mode it
    will stop at the same framecounter value as the master camera, so all cams
    capture the same number of frames. You can override these defaults and specify
    an arbitrary value with this setting. However, be careful in synchronized mode
    to not specify a target stop count which can’t be reached by a slave camera once
    capture stops synchronously on all cameras, otherwise stopping that camera will
    be impossible and result in a hard hang of your script!
    ‘GetCorruptFramecount’ Retrieve current count of corrupted frames received from
    a camera. Not all cameras and operating systems can detect and report corrupt
    frames. Currently only implemented on libdc1394 capture engine.
    ‘GetCurrentFramecount’ Retrieve current count of captured frames on a camera.
    ‘GetFutureMaxFramecount’ Retrieve current maximum count which could be reached
    if you’d try to stop capture right now.
    ‘GetFetchedFramecount’ Retrieve framecount of last frame fetched via
    Screen(‘GetCapturedImage’). This is the running counter value at the time the
    video frame was captured, essentially a copy of ‘GetCurrentFramecount’ stamped
    onto the retrieved video frame.
    ‘PreferFormat7Modes’ If set to 1, prefer Format-7 video capture modes over other
    modes, even if given capture settings for fps and resolution and ROI would allow
    otherwise. Format-7 modes are only supported by more high-end cams, but using
    them sometimes allows to save bus-bandwidth in addition to the higher
    flexibility. If you find yourself starving for bandwidth it may be worth a try
    to set this preference. The default setting 0 will use non-Format-7 by default
    and only choose Format-7 if this is needed to satisfy given ROI, framerate and
    resolution settings.
    ‘DataConversionMode’ What kind of image data should be requested from the camera
    and how should it be postprocessed? This controls the tradeoff between required
    bus-bandwidth on Firewire/USB busses and processing load on the cpu or gpu of
    the host computer, allowing to prioritize one over the other. Possible settings:
    0 = Don’t care (Default setting), 1 = Request raw data and return it
    unprocessed. 2 = Request raw data but post-process it into a standard format
    (Luminance for 1 layer, RGB for 3 layer images), 3 = Request mono/rgb filtered
    data from camera and return it unprocessed (as processing should not be needed),
    4 = Request mono data but post-process it as if it were raw data (convert to
    mono or rgb). Option 1 minimizes bus bandwidth, memory consumption and cpu load
    but requires manual post processing by you at some time. Option 2 minimizes bus
    bandwidth but not memory consumption and it significantly increases cpu load.
    Option 3 minimizes cpu load but maximizes bus bandwidth consumption. The default
    option 0 will do whatever is convenient for the attached camera. Option 1 only
    makes sense if you request 1 layer data. Option 4 is like option 2, but for
    broken cameras which deliver raw data in mono format instead of the
    spec-compliant raw format. Option 3 in combination with 1 layer image format can
    be used to get raw data from broken cameras which deliver raw data mislabeled as
    mono data.
    ‘DebayerMethod’ Select method of bayer filtering for conversion of raw sensor
    data to RGB images. Different methods represent different tradeoffs between
    quality and computation time. Method 0 (the Default) is the fastest and lowest
    quality method, whereas higher numbers select higher quality and more cpu load.
    Currently values 0 to 7 may be valid for your system. This can be also used with
    a ‘capturePtr’ of -1 to set the method used during movie playback.
    ‘OverrideBayerPattern’ If you choose color image output from raw sensor input,
    via one of the ‘DataConversionMode’ settings, then a bayer filter operation must
    be performed to convert raw sensor data to RGB data. The filter operation must
    know the bayer filter layout of your cameras sensor, but this layout can’t get
    auto-detected on all cameras in all modes of operation. If the bayer conversion
    aborts due to this, you may need to manually specify the bayer filter pattern to
    use with the ‘OverrideBayerPattern’ setting: 0 = RGGB, 1 = GBRG, 2 = GRBG, 3 =
    BGGR. This can be also used with a ‘capturePtr’ of -1 to set the method used
    during movie playback.
    ‘SyncMode’ Query or set mode flags for synchronization of the video capture
    operation of multiple cameras. This setting is currently only supported with the
    dedicated libdc1394 video capture engine (engine id 1), and only for some types
    of cameras on some operating systems, specifically as of Nov 2013 it only works
    on Linux with firewire cameras. The default setting for ‘SyncMode’ is zero,
    which means the camera is free-running, independent of any other camera.
    Non-zero values allow to synchronize the capture operation of the camera with
    other cameras. Each camera can be either a sync-master, which means it controls
    all capture operations (start, stop and timing of capture), or a sync-slave,
    which means its timing is controlled by the master camera. There can be at most
    one master for synchronized operation. If hardware sync is selected and an
    external trigger signal source is used, no master camera is needed. For the
    master camera, set the ‘SyncMode’ to 1, for a slave camera set it to 2. There
    are three different sync strategies. Select exactly one by adding the value 4, 8
    or 16 to the ‘SyncMode’ value of 1 or 2, e.g., 1+4 to select soft-sync mode and
    define a soft-sync master:
    4 = Soft-Sync: Synchronisation happens purely in software. Works always but less
    8 = Bus-Sync: All cameras on a given firewire bus are synchronized down to ~125
    usecs. This only works with some cameras which support bus-sync, and usually
    only if they are identical camera models with identical settings. Also it only
    works for cameras on the same firewire bus, e.g., multiple cams connected to the
    same port on the computer via a common firewire hub or via daisy-chaining. Bus
    sync is elegant if it works, with no need for extra cabling and electronics.
    16 = Hw-Sync: All slave cameras are connected via some dedicated trigger signal
    distribution cables to a master camera or to an external trigger signal source.
    The master camera or external source drives capture operations and timing of all
    connected slave cameras. This is most reliable and accurate, but requires extra
    cabling and hardware. If you use this option, also use the trigger configuration
    commmands below to configure each camera individually as a master or slave, the
    trigger source port, and the type and polarity of the external trigger signal to
    In any case, for synchronized operation you must always first start capture on
    all participating slave cameras, then finally on the designated master - which
    will actually truly start capture of the whole pack. For stopping capture you
    first stop the master, which will actually stop capture of the whole setup, then
    all slaves to disengage them. If you need cameras to start and perform capture
    and recording in sync, but you don’t need them to stop in exact synchrony, you
    can add the flag 32 = No lock-step. This allows for some slack and inaccuracy in
    stopping capture and recording, but may allow for reduced latency for realtime
    applications of video capture.
    The way trigger signals are used if ‘SyncMode’ is selected as mode 16 aka
    hardware sync, can be controlled via the following settings:
    ‘TriggerMode’ The way a trigger signal controls camera capture operation: 0 =
    Start of exposure is triggered by falling edge of trigger signal, duration of
    exposure is controlled by shutter setting. 1 = Exposure starts with falling edge
    and stops with rising edge. Modes 2, 3, 4 and 5 are multiple exposure modes.
    Modes 6 and 7 are vendor specific modes.
    ‘TriggerPolarity’ 0 = Active low / falling edge. 1 = Active high / rising edge =
    Inverted polarity.
    ‘TriggerSource’ Which source input port to use: Sources 0 to 3 are available,
    corresponding to ports 0 - 3.
    ‘GetTriggerSources’ Returns a list of supported source ports for given camera.
    ‘PIO’ Set or get general purpose programmable IO pins on camera. Accepts/returns
    a 32-Bit integer value to control up to 32 pins. The value is provided and
    expected as a double, ie. a uint32 cast from/to a double.
    ‘1394BModeActive’ Set or get if Firewire-800 mode aka 1394B mode is active: 1 =
    Activate, 0 = Use default classic mode.
    ‘ISOSpeed’ Get/Set Firewire ISO bus speed: Valid values are 100, 200, 400, 800,
    1600, 3200 MBit/s. Default is 400 MBit, higher values require ‘1394BModeActive’
    to be set to 1 - and a camera and firewire controller which support 1394B mode
    and higher speeds than 400 MBit/s.
    ‘GetCycleTimer’ Returns the current decoded 32-Bit firewire bus cycle count in
    return argument 1 and the GetSecs() time at which that count was queried in the
    second return argument: [firewireSeconds, GetSecsSeconds, busSeconds,
    busIsoCycles, busTicks]. A busIsoCycles takes 125 usecs, busTicks are 1/24.576
    Mhz on top of that. The combination of busSeconds, busIsoCycles and busTicks is
    decoded into firewireSeconds for your convenience. Firewire bus time wraps to
    zero every 128 seconds.
    ‘ResetBus’ Resets the firewire or USB bus to which a camera is attached.
    ‘ResetCamera’ Resets the camera.
    ‘Temperature’ Retrieves and/or sets the target temperature (returned in 1st
    argument). Returns current temperature in 2nd return argument.
    ‘WhiteBalance’ Get/Set white balance settings: 1st argument is U (in YUV mode)
    or Blue value (in RGB mode). 2nd argument is V (in YUV mode) or Red (in RGB
    mode). E.g., [u, v] = Screen(‘…’, camera, ‘WhiteBalance’ [, newU, newV]);
    ‘WhiteShading’ Sets or gets white shading correction point: In/Out values 1, 2
    and 3 correspond to Red, Green and Blue, e.g., [r,g,b] = Screen(‘…’, camera,
    ‘WhiteShading’ [, newR, newG, newB]);
    ‘BaslerChecksumEnable’ Enable extra CRC checksumming on Basler cameras, to
    detect corrupt video frames. Compute intense!
    ‘BaslerFrameTimestampEnable’ Use Basler cameras builtin timestamping of start of
    image exposure to compute extra precise capture timestamps. By default, the time
    of reception of a frame in the host computer is timestamped. Doesn’t work on
    many Basler cameras though.
    ‘BaslerFrameCounterEnable’ Retrieve framecounter values from Basler camera
    itself instead of using our own software frame counter. Theoretically extra
    robust. In practice only useful if your Basler camera allows software controlled
    power-cycling, which some Basler cameras do not allow. If the camera doesn’t
    allow power-cycling then use of this feature will cause a hard hang of
    ‘LoadMarkerTrackingPlugin=’ Specify the name of a special markertracker plugin
    to load and use during video capture. The name must be the path and filename of
    a shared library which implements this plugin. EXPERIMENTAL and subject to
    change without notice!
    ‘SendCommandToMarkerTrackingPlugin=’ Send an ASCII string containing commands to
    a loaded markertracker plugin. EXPERIMENTAL!

###See also: OpenVideoCapture CloseVideoCapture StartVideoCapture StopVideoCapture GetCapturedImage