Diagnosing dithering in your graphics pipeline

There are several ways to diagnose dithering in your graphics pipeline. Below are some different methods you can try:

Using the PyPixx Graphics Card Test

PyPixx is a standalone software tool included in our software tools package. PyPixx includes a graphics card test that checks for dithering and provides a summary of the test results. To run the test, open PyPixx with your VPixx device connected and powered on. Navigate to System -> Hardware -> Graphics Card Test:

Graphics card test available through PyPixx

The test will allow you to select a VPixx display and check for dithering. Deviations from expected output will be recorded and reported.

Results of a graphics card test with no dithering detected

Please note, for this test to work:

– Your display must be set to 1920 x 1080 resolution
– The video must be passed through a VPixx device
– The widget must cover the top line of the display
– The widget must be 1920 pixels wide (i.e., full screen)

Using the built-in tools in Psychtoolbox

The creators of Psychtoolbox have created a low level test for dithering, which is included in the toolbox download. Simply open MATLAB with your VPixx device connected and powered on, and enter the following:

MATLAB

DatapixxGPUDitherpatternTest

The test will output its assessment to the command window. The documentation for this function can be found here.

Using the vline command

Our software API includes a command called “vline,” which returns the RGB values of the top line of pixels on the display. Vline will show the output values as they are received by the screen; if there is a mismatch between your expected output and the values returned by vline, this is evidence of dithering.

Our MATLAB/Psychtoolbox and Python APIs both include a vline command, as does our command-line program VPutil. Use the tabs below to see code example for how to run a vline test using one of these tools and a simple grayscale ramp. You may wish to alter the tested RGB values for further diagnostics.

We strongly recommend running this code several times in a row, as dithering is inconsistent across frames and may require a few runs to detect.

MATLAB/Psychtoolbox

MATLAB

function VlineDitherTest()

%Connect to device
Datapixx('Open');

%Open an onscreen window on secondary display
Screen('Preference', 'SkipSyncTests', 1);
screenId=max(Screen('Screens'));
[windowPtr, rect] = Screen('OpenWindow', screenId, [0,0,0]); 
finalDitherCount = 0;

%create a ramp of greyscale values to check for dithered output. It will be most obvious for
%intermediate values.
for value=0:255
    
    %draw grayscale rectangle that crosses entire top row 
    Screen('FillRect', windowPtr, value, [0,0, rect(3), 20]);
    Screen('Flip', windowPtr);
    
    %register update to collect most recent state from hardware, followed by vline
    Datapixx('RegWrRd'); 
    vline = Datapixx('GetVideoLine', rect(3));
    
    %compare expected and measured output from entire top row of pixels 
    expected = repmat(value,3, rect(3));        
    dither = sum(expected~=vline, 'all');
    fprintf('nTest %i: %i discrepancies', value, dither);
    
    %keep track of total discrepancies across tests
    finalDitherCount= finalDitherCount + dither;

end

fprintf('nTest complete. 256 grey levels tested, %i discrepancies detected.', finalDitherCount);
fprintf('nIf discrepancies > 0 you may need to disable dithering on your graphics card.n');

%Shut down
Screen('Closeall');
Datapixx('Close');
end

Python (libdpx wrapper)

PY

from pypixxlib._libdpx import DPxOpen, DPxClose, DPxGetVidLine, DPxUpdateRegCache
from psychopy import visual
import numpy as np

#connect to our hardware
DPxOpen()

#draw an onscreen window
win = visual.Window([1920, 200], pos=[0,0], color=[0,0,0], units='pixels', colorSpace='rgb255')
finalDitherCount = 0;
for value in range(256):
 
    #draw a rectangle that occupies the top row of pixels
    line = visual.Line(win, start=(-960,100), end=(960,100), lineWidth=20, lineColor=(value, value, value), lineColorSpace='rgb255')
    line.draw()
    win.update()
 
    #register update to get most recent device status, followed by a vline
    DPxUpdateRegCache()
    vline = DPxGetVidLine()
 
    #compare vline against expected results
    vlineArray = np.array(vline)
    compare = (vlineArray==value)
    dither = np.size(compare) - np.sum(compare)
    print('Test ', value,': ', dither, ' discrepancies')
 
    #keep track of total
    finalDitherCount = finalDitherCount+dither

print('Test complete, ', finalDitherCount,' discrepancies detected. If this value is >0, you may need to adjust graphics card settings')
win.close()
DPxClose()

Python (object oriented)

PY

from pypixxlib.viewpixx import VIEWPixx #substitute device being used
from psychopy import visual
import numpy as np

#connect to our hardware
vpx = VIEWPixx()

#draw an onscreen window
win = visual.Window([1920, 200], pos=[0,0], color=[0,0,0], units='pixels', colorSpace='rgb255')
finalDitherCount = 0;
for value in range(256):

    #draw a rectangle that occupies the top row of pixels
    line = visual.Line(win, start=(-960,100), end=(960,100), lineWidth=20, lineColor=(value, value, value), lineColorSpace='rgb255')
    line.draw()
    win.update()

    #register update to get most recent device status, followed by a vline
    vpx.updateRegisterCache()
    vline = vpx.getVideoLine()

    #compare vline against expected results
    vlineArray = np.array(vline)
    compare = (vlineArray==value)
    dither = np.size(compare) - np.sum(compare)
    print('Test ', value,': ', dither, ' discrepancies')

    #keep track of total
    finalDitherCount = finalDitherCount+dither

print('Test complete, ', finalDitherCount,' discrepancies detected. If this value is >0, you may need to adjust graphics card settings')
win.close()
vpx.close()

VPutil

Use software of your choice (e.g., Microsoft Paint, Powerpoint) to display a window with no border across the top of the display.
Open VPutil with the device connected and powered on.
Type ‘vline ‘ where is a value between 1 and maximum horizontal resolution, and hit enter.