Sending Triggers with Pixel Mode

In Pixel Mode, your VPixx hardware sends automated digital signals based on the colour of the top left pixel of the display. This guide explains the principles of how Pixel Mode works and how to use it in your research.

Looking for a brief overview? Check out our short video below:

Introduction to digital signalling

Researchers often have to align recorded data and events in their experiment timeline. For instance, researchers might ask the following questions:

• Where in our MEG trace did our stimulus first appear onscreen?

• When did the fixation cross appear in our eye-tracking data?

• Where in our EEG data did the response phase begin?

To address these questions, researchers send carefully timed digital signals from their experiment to their recording system, to act as event ‘markers' in the data stream. These markers help parse and interpret a continuous stream of recorded data. Ideally, event markers should be fast, precise, automatic, and informative. They should reliably tell the researcher when something happened and should be able to carry unique information about what happened.

To send event markers from VPixx hardware to your recording system, we use a type of digital signalling called transistor-transistor logic (TTL). This widely accepted protocol uses rapid, simple voltage changes to communicate between physical pins connected to either system. The pins can either have a voltage (in which case we call the pin high) or no voltage (low).

VPixx has invested considerable research and development into ensuring digital signals sent from our hardware are microsecond precise. They reflect the timing of (visual) events in your experiment in an extremely consistent and reliable way. This directly translates to more precision in analyzing your collected data.

Setting up your hardware for digital signalling

To pass digital signals from your VPixx hardware to your recording system, you need to physically connect the digital output port on your device to your recording system’s receiver. VPixx offers standard and custom cabling solutions for various receivers. You can find out more about what we offer here:https://vpixx.com/products/cabling-solutions/.

The digital output port on your VPixx hardware supports up to 24 pins or “channels” for TTL signalling. Your receiver will have a set number of channels for inputs, typically between 8-24 channels. By signalling events on multiple channels, we can communicate different unique patterns to indicate unique events in our experiment.

Principles of Pixel Mode

For any given frame of video, the video data passes from your experiment PC’s graphics card to VPixx hardware before being shown on the display. If the hardware is operating in Pixel Mode, the voltages on the digital out port are automatically set based on the colour of the top left-most pixel in that video frame.

The animation below shows an exaggerated top left pixel and the resulting digital output.

Each of our digital output channels is associated with a unique bit plane of the R, G or B colour values of the pixel. In other words, in a standard display with 2^24 unique colours available, we can generate 2^24 unique digital signals on our digital output port. That’s over 16 million unique event markers!

Pixel Mode is designed to be program-agnostic. If the mode is enabled on your hardware, you can use any software you like to run your experiment, from PsychoPy to Powerpoint. As long as you can control the colour value of the top left pixel of the experiment display, you can send Pixel Mode digital signals.

Pixel Mode updates on every video frame. If you maintain the same pixel value across multiple frames, the digital output will also remain the same. The state of each digital output channel will only change when the pixel value does. Here’s an example of what the changing channel values look like, on a PROPixx. Note the transition from black on frame 1 (all channels low) to white on frame 2 (all channels high) to black for two frames, and then full red on frame 5 (first 8 channels high).

Pixel Mode timing vs. display behaviour

Pixel Mode values are detected in the video signal before being passed to the display. This causes a short, consistent temporal offset between digital signal onset and physical screen illumination.

This happens because when our Pixel Mode value is detected, the video data for the frame is still in the process of being transmitted. We need additional time to collect enough video data to start physically illuminating the display.

VPixx displays have deterministic, or fully characterized, timing properties. Therefore we can say the exact temporal offset between the timing of the digital signals and physical pixel illumination, for any of our displays. The table below shows a summary of temporal offsets for different displays:

Pixel Mode value calculator

We now know how Pixel Mode works, how communication between devices operates, and what kind of temporal offsets to expect from our event markers. Next, we have to decide how to determine our Pixel Mode values!

The easiest method is to simply use our calculator. Select the digital output channels you want to be ‘high’ on a given frame, and the calculator will tell you what RGB value you need to draw in the top left corner of the display.

It’s important to remember that your receiver may not label the digital input channels in the same manner. You can refer to your cable wiring diagram to see how the digital output channels map to your receiver channels, to help you interpret the incoming signal.

If you prefer to calculate triggers directly in your code, you can use the following formulae:

% Define what dout channels we want to be high on this frame
doutChannelsHigh = [0, 2, 4];

% Determine the decimal value associated with this unique pattern
desiredTriggerValue = sum(2.^doutChannelsHigh);

% Convert to RGB255 value
% MATLAB uses uint8 for 8-bit values
pixelColor = [mod(desiredTriggerValue, 256), ...
              bitshift(desiredTriggerValue, -8), ...
              bitshift(desiredTriggerValue, -16) ];

#Define what doutchannels we want to be high on this frame
doutChannelsHigh = [0,2,4]

#Determine the decimal value associated with this unique pattern
desiredTriggerValue = sum(2**i for i in doutChannelsHigh)

#Convert to RGB255 value
pixelColor = [ triggerValue%256, (triggerValue>>8)%256, (triggerValue>>16)%256]

Pixel Mode variants

There are three different variants of Pixel Mode, which control all or a subset of the digital output channels available. If channels are “ignored” it means other systems can use those channels, and Pixel Mode signals will not overwrite them. See below for each variant and description:

*Pixel Mode B was introduced in release 1.8.1 (September 2024) and is only available for the DATAPixx3 with firmware revision 27 or higher.

Enabling Pixel Mode on VPixx hardware

Below is a list of VPixx hardware that supports Pixel Mode, and how to enable the mode on that particular device:

VIEWPixx and VIEWPixx /3D

Pixel Mode B is currently only available for the DATAPixx3. It cannot be used with a VIEWPixx display.

• In LabMaestro:

  • Double-click on the VIEWPixx monitor in the Environment section of the Project panel

  • In Digital IO, select the desired Pixel Mode variant from the Output Mode dropdown menu

  • Optional: Save as Power-On settings to remain in this mode after restarting the device

• In MATLAB:

  • Set the mode using the following commands

    MATLAB

    %Set preferred mode:
    %0 is Pixel Mode RGB
    %1 is Pixel Mode GB
    mode = 0;
    
    Datapixx('Open');
    Datapixx('EnablePixelMode', mode);
    Datapixx('RegWr');
    
    %To disable:
    Datapixx('DisablePixelMode');
    Datapixx('RegWr');

• In Python

  • Set the desired mode using one of the following commands

    PY

    from pypixxlib import _libdpx as dp
    
    #Connect to hardware
    dp.DPxOpen()
    
    #Ensure pixel mode enabled-- uncomment the desired variant
    #dp.DPxEnableDoutPixelMode()
    #dp.DPxEnableDoutPixelModeGB()
    dp.DPxWriteRegCache()
    
    #To disable:
    #dp.DPxDisableDoutPixelMode()
    #dp.DPxDisableDoutPixelModeGB()
    dp.DPxWriteRegCache()

DATAPixx and DATAPixx3

Pixel Mode B is currently only available for the DATAPixx3. It cannot be used with a DATAPixx.

• In LabMaestro:

  • Double-click on the DATAPixx device in the Environment section of the Project panel

  • In Digital IO, select the desired Pixel Mode variant from the Output Mode dropdown menu

  • Optional: Save as Power-On settings to remain in this mode after restarting the device

• In MATLAB:

  • Set the mode using the following commands

    MATLAB

    %Set preferred mode:
    %0 is Pixel Mode RGB
    %1 is Pixel Mode GB
    %2 is Pixel Mode B
    mode = 0;
    
    Datapixx('Open');
    Datapixx('EnablePixelMode', mode);
    Datapixx('RegWr');
    
    %To disable:
    Datapixx('DisablePixelMode');
    Datapixx('RegWr');

• In Python

  • Set the desired mode using one of the following commands

    PY

    from pypixxlib import _libdpx as dp
    
    #Connect to hardware
    dp.DPxOpen()
    
    #Ensure pixel mode enabled-- uncomment the desired variant
    #dp.DPxEnableDoutPixelMode()
    #dp.DPxEnableDoutPixelModeGB()
    #dp.DPxEnableDoutPixelModeB()
    dp.DPxWriteRegCache()
    
    #To disable:
    #dp.DPxDisableDoutPixelMode()
    #dp.DPxDisableDoutPixelModeGB()
    #dp.DPxDisableDoutPixelModeB()
    dp.DPxWriteRegCache()

PROPixx projector

Pixel Mode B is currently only available for the DATAPixx3. It cannot be used with a PROPixx Controller.

• In LabMaestro:

  • Double-click on the DATAPixx3 or PROPixx Controller driving the projector. This is found in the Environment section of the Project panel

  • In Digital IO, select the desired Pixel Mode variant from the Output Mode dropdown menu

  • Optional: Save as Power-On settings to remain in this mode after restarting the device

• In MATLAB:

  • Set the mode using the following commands

    MATLAB

    %Set preferred mode:
    %0 is Pixel Mode RGB
    %1 is Pixel Mode GB
    %2 is Pixel Mode B
    mode = 0;
    
    Datapixx('Open');
    Datapixx('EnablePixelMode', mode);
    Datapixx('RegWr');
    
    %To disable:
    Datapixx('DisablePixelMode');
    Datapixx('RegWr');

• In Python

  • Set the desired mode using one of the following commands

    PY

    from pypixxlib import _libdpx as dp
    
    #Connect to hardware
    dp.DPxOpen()
    
    #Ensure pixel mode enabled-- uncomment the desired variant
    #dp.DPxEnableDoutPixelMode()
    #dp.DPxEnableDoutPixelModeGB()
    #dp.DPxEnableDoutPixelModeB()
    dp.DPxWriteRegCache()
    
    #To disable:
    #dp.DPxDisableDoutPixelMode()
    #dp.DPxDisableDoutPixelModeGB()
    #dp.DPxDisableDoutPixelModeB()
    dp.DPxWriteRegCache()

Troubleshooting Pixel Mode

Pixel Mode requires something called 1-1 pixel identity passthrough. Put simply, the pixel values you draw in your software must match the pixel values read by the display.

If your pixels become altered in some way, Pixel Mode will pass the wrong triggers to your hardware.

To learn more about Pixel Identity Passthrough and how to verify it on your system, see our troubleshooting guide: What is Pixel Identity Passthrough?

A note about sub-frame timing of pixel illumination

Pixel Mode provides microsecond-precise triggering based on when the video signal reaches our hardware.

On the PROPixx projector, the entire screen illuminates simultaneously. Digital signals are thus in lockstep with every pixel on the display.

Our VIEWPixx monitors use a scanning backlight that moves down the screen throughout a video frame. Thus, the exact timing of pixel illumination on a VIEWPixx is location-specific. Of course, this delay is always less than the screen refresh rate (8.33 ms/frame at 120Hz).

If you want to characterize the exact offset between your trigger (based on the start of the video frame), and the illumination of the specific patch of pixels where your stimulus appears on a VIEWPixx, you will need to perform a one-time measurement using a photodiode placed over that stimulus’ position on the screen. This will give you the precise sub-frame offset between the trigger and the spatially-dependent onset of your stimulus. 

Example: Using Pixel Mode to send an event marker indicating the stimulus onset

% Open a fullscreen window
screenid = max(Screen('Screens'));
[window, windowRect]=PsychImaging('OpenWindow', screenid, 0);

%Enable Pixel Mode
Datapixx('Open');
Datapixx('EnablePixelMode', 0);
Datapixx('RegWr');

% Pixel Mode pixel properties
pixelPos = [0, 0];
pixelCol = [19,0,0]; %channels 0,1,4 to high

% Define stimulus
textString = 'Hello World';
textColor = [255, 255, 255];

% Draw the text "Hello World" in the middle of the display
DrawFormattedText(window, textString, 'center', 'center', textColor);

% Draw the single pixel in the top-left corner
Screen('DrawDots', window, pixelPos, 1, pixelCol, [], 1);

% Flip to the screen
Screen('Flip', window);

% Wait for a spacebar press to exit
KbName('UnifyKeyNames');
exitKey = KbName('space');

while true
    % Check the keyboard for a key press
    [keyIsDown, ~, keyCode] = KbCheck;
    
    % Exit on spacebar press
    if keyIsDown && keyCode(exitKey)
        break;
    end
end

% Close the Psychtoolbox window
sca;

%Shut down
Datapixx('DisablePixelMode');
Datapixx('RegWr');
Datapixx('Close');