This driver provides common high-level functionality for interaction with
the VPixx Technologies DataPixx device. The driver provides high-level
functions for basic device operations and for timestamping of visual
stimulus onset. It also provides functionality needed for the
PsychImaging() command and the Screen() image processing pipeline to
properly setup the high-precision video display modes and stereo display
modes of the DataPixx.
The driver is dependend on the low-level MEX file Datapixx() driver to be
present. It will fail if that MEX file is missing or dysfunctional.
Normally you will have a DataPixx connected when using this driver, but
for basic code development and testing you can call
PsychDataPixx(‘SetDummyMode’, 1); and then run without a connected
Commands and their syntax
oldmode = PsychDataPixx(‘SetDummyMode’ [, mode]);
- Switch driver into dummy mode if ‘mode’ is set to 1. In dummy mode, the
code mostly operates without a DataPixx device connected. This is useful
for basic debugging of code without access to the device. The simulated
device returns more or less meaningful values, good enough for initial
A ‘mode’ setting of zero enabled normal mode of operation.
You must call this command before any other command for proper operation!
- Open a connection to the device, with default settings. If the device
is already open then this will do almost nothing, otherwise the
connection is opened.
You must call this function before all other remaining commands!
- Close a connection to the device. Multiple virtual connections can be
simultaneously open. If this function call closes the last virtual
connection, then the real physical connection to the device is closed and
the driver is reset.
If you used PsychImaging() to make use of Datapixx graphics mode, it will
automatically close that connection once the corresponding onscreen
window is closed. As a simple rule, you only need to call the ‘Close’
function if you also called the ‘Open’ function before.
status = PsychDataPixx(‘GetStatus’ [,newstatus]);
- Retrieve a struct ‘status’ with the complete driver internal state.
Optionally assign new state ‘newstatus’ to driver. Only assign a new
state if you *really* know what you’re doing!
oldmode = PsychDataPixx(‘LogOnsetTimestamps’, mode);
- Return current timestamp acquisition mode as optional return argument
‘oldmode’. Set a new mode, according to argument ‘mode’. ‘mode’ can
be one of:
0 = Disable all timestamp acquisition and logging.
1 = Log a visual stimulus onset timestamp for the next Screen(‘Flip’) or
Screen(‘AsyncFlipBegin’) command after this function call, then stop
logging again. This is a one-shot timestamp function.
2 = Log all Screen(‘Flip’) and Screen(‘AsyncFlipBegin’) visual stimulus
onset timestamps until this function is called again with a ‘mode’
setting of 1 or 0.
Timestamping is disabled by default (mode == 0), as it incurs a bit of
computational overhead to acquire and log timestamps, typically up to 2-3
msecs of extra time per ‘Flip’ command.
The driver will log all timestamps in a buffer, which can be read out via
the following timestamp related commands.
[boxTime, getsecsTime, flipCount, currentFlipcount] = PsychDataPixx(‘GetLastOnsetTimestamp’);
- Retrieve visual stimulus onset timestamps related to last logged
“Flip”. This call will only return valid values after a Flip command is
finished, ie., after a successfull call to Screen(‘Flip’) or
Screen(‘AsyncFlipCheckEnd’) or Screen(‘AsyncFlipEnd’), and only if
logging of timestamps was enabled by setting the ‘LogOnsetTimestamps’
mode (see above) to a non-zero value. It always returns the most recently
‘boxTime’ is the time in seconds of stimulus onset as measured by the
DataPixx internal clock.
‘getsecsTime’ is the time in seconds of stimulus onset as measured by the
Psychtoolbox GetSecs() clock.
‘flipCount’ is the “serial number” of the Screen flip command to which
the returned timestamps refer.
‘currentFlipcount’ is the “serial number” of the most recent Screen flip
Computation of ‘getsecsTime’ will become inaccurate if you don’t
frequently call PsychDataPixx(‘GetPreciseTime’) to resynchronize the
clocks! A more accurate approach to retrieve GetSecs() style timestamps
is to use the PsychDataPixx(‘GetTimestampLog’, 1) function to retrieve
all logged timestamps at the end of a session and apply some
high-precision remapping of timestamps.
[getsecs, boxsecs, confidence] = PsychDataPixx(‘GetPreciseTime’);
- Query both the DataPixx clock and GetSecs clock and compute which GetSecs
time ‘getsecs’ corresponds to which Datapixx time ‘boxsecs’ and how
reliable this correspondence is in ‘confidence’. ‘confidence’ is the
margin of error between both timestamps.
This function implicitely synchronizes both clocks to get more precise
values for ‘getsecstime’ from calls to PsychDataPixx(‘GetLastOnsetTimestamp’);
The function is automatically called once at device open time.
log = PsychDataPixx(‘GetTimestampLog’ [, remapPrecise = 0]);
- Fetch the full log of all acquired visual stimulus onset timestamps
into the variable ‘log’. ‘log’ is a 3-by-n matrix for the n timestamps,
one column encodes one stimulus onset, aka one logged invocation of
Screen(‘Flip’) et al.
If the optional parameter ‘remapPrecise’ is set to 1, then an expensive
calibration procedure is used to compute very precise GetSecs()
timestamps for row 2 of the returned matrix, otherwise a cheap but
inaccurate remapping is performed. The expensive procedure can take up to
1 second, but is highly recommended for precise timestamps. See
explanation of ‘BoxsecsToGetsecs’ function below for more details. You’ll
typically call this function only at the end of an experiment session.
- Clear the log with all currently acquired timestamps.
tgetsecs = PsychDataPixx(‘FastBoxsecsToGetsecs’, t);
- Map given timestamp ‘t’ in Datapixx clock time to Psychtoolbox GetSecs
time and return it in ‘tgetsecs’. This mapping is only precise if you
call PsychDataPixx(‘GetPreciseTime’); frequently. For a more accurate
remapping use the following PsychDataPixx(‘BoxsecsToGetsecs’, t);
instead, which is more time consuming to execute though.
[tgetsecs, sd, ratio] = PsychDataPixx(‘BoxsecsToGetsecs’, t);
- Perform remapping of a vector of Datapixx timestamps ‘t’, ie.,
timestamps expressed in Datapixx clock time, into Psychtoolbox GetSecs
timestamps ‘tgetsecs’. Return measures of accuracy of remapping.
This must be called while the device is still open! It performs the same
calibration procedure as PsychDataPixx(‘GetTimestampLog’, 1); and can
easily take up to 1 second of time.
The remapping is performed by fitting a mapping function to the set of
acquired timestamp samples from both the Psychtoolbox GetSecs clock and
the DataPixx clock. The best fit function is used for mapping DataPixx
timestamps in ‘t’ to PTB timestamps in ‘tgetsecs’. ‘sd’ is the standard
deviation of the best-fit function wrt. to fitting error. ‘ratio’ is an
estimate of the clock speed difference between the host clock and the
- Request an update of the DataPixx register block in sync with the next
visual stimulus onset as triggered by Screen(‘Flip’) or
Screen(‘AsyncFlipBegin’). This will emit the neccessary PSYNC pixel
sequence at next flip and tell the device to apply all pending settings
on reception of that PSYNC token.
count = PsychDataPixx(‘FlipCount’);
- Return “serial number” of the last executed visual stimulus update via
one of the Screen “Flip” commands.
PsychDataPixx(‘ExecuteAtFlipCount’, targetFlipCount, commandString);
- Request execution of ‘commandString’ via eval() function in sync with
the Screen(‘Flip’) or Screen(‘AsyncFlipBegin’) command which will
cause the stimulus onset with “serial number” ‘targetFlipCount’. You can
ask for the current “serial number” by calling current = PsychDataPixx(‘FlipCount’);
Providing an empty ‘targetFlipCount’ means to execute at next flip.
Datapixx related commands in ‘commandString’ will be scheduled for
execution on the device at next visual stimulus onset by use of the psync
Not all commands are allowed inside ‘commandString’! Any call to Screen()
or any OpenGL command is forbidden. Datapixx commands which could block
execution to wait for the Datapixx , e.g., Datapixx(‘RegWrRd’) are
problematic, and the calls Datapixx(‘RegWrPixelSync’) and
Datapixx(‘RegWrRdPixelSync’) are strictly forbidden!
This function is mostly used by other higher-level DataPixxToolbox
functions, e.g., for I/O (sound, digital or analog), in order to
synchronize their operation and schedules to visual stimulus updates.
- Load an identity CLUT into the device at next stimulus onset, ie., next
‘Flip’ command for window ‘win’. This is a pure convenience function for
that common case. Normally you’d use Screen(‘LoadNormalizedGammaTable’, win, clut, 2);
to upload a new ‘clut’ table at next ‘Flip’ command execution.
oldverbosity = PsychDataPixx(‘Verbosity’ [,verbosity]);
- Retrieve and optionally set a new level of ‘verbosity’ for driver debug
output. verbosity can be 0 for no output, 1 for only errors, 2 for
additionally warnings, 3 for additional info, 4 for very verbose output.
oldtimeout = PsychDataPixx(‘PsyncTimeoutFrames’ [, timeoutFrames]);
– Query and/or set timeout (in video refresh cycles) for recognition of
PSYNC codes by the device. By default, the timeout is set to the
equivalent of 5 minutes, which means: If the device is instructed to wait
for a PSYNC marker token in the video stream, but doesn’t receive the
expected token within 5 minutes, it will continue processing as if the
token was received. This is used to prevent device-hangs on programming
errors or other malfunctions. The default setting of 5 minutes is very
generous. You can override this default and set an arbitrary timeout
between 1 and 65535 video refresh cycles with this function.
Normally you won’t call the following functions yourself, as Psychtoolbox
automatically performs neccessary setup during calls to PsychImaging()
that are related to the DataPixx device (“help PsychImaging” for
– Switch DPixx device immediately into video processing mode ‘mode’.
Type “Datapixx SetVideoMode?” for a list of available ‘mode’ settings and
explanation of their purpose and behaviour.
– Switch DPixx device immediately into video split mode ‘mode’.
Type “Datapixx SetVideoHorizontalSplit?” for a list of available ‘mode’
settings and explanation of their purpose and behaviour.
– Switch DPixx device immediately into vertical stereo video mode ‘mode’.
Type “Datapixx SetVideoVerticalStereo?” for a list of available ‘mode’
settings and explanation of their purpose and behaviour.
Internal commands: NOT FOR USE BY PURE MORTALS!
rc = PsychDataPixx(‘CheckGPUSanity’, window, xoffset);
– Perform online-test of GPU identity gamma tables and DVI-D display
encoders. Try to correct problems with wrong identity gamma tables and at
least detect problems with (spatio-)temporal display dithering. Returns
rc == 0 on full success, rc > 0 on failure.
– PTB callback at ‘Flip’ time: Do whatever DPixx related work is
pending for next ‘Flip’, e.g., DPixx clut updates, writing of PSYNC pixel
sequences, preparation of logging of timestamps etc.
– Callback for PTB imaging pipeline: Ultrafast upload of given ‘clut’
into the device at next bufferswap.
– Callback for PTB imaging pipeline after successfull finish of a
bufferswap. Do whatever needs to be done, e.g., incrementing the
swapcounter and logging of timestamps.
– Callback at time of closing the DataPixx onscreen window: Perform
whatever actions are needed at shutdown, e.g., restoring identity clut on
device, restoring default video mode and settings, closing device
connection, cleanup of data structures etc.