Screen device object

A screen object is optional. You only need to make one if you want to change a property from default. Often the easiest way to set screen object properties is to change their default values using pb_prefs.

An object of type screen represents the screen and window the experiment shows in. This let you set general options like window size and position, timing precision / compatibility tradeoffs, color/luminance calibration, etc. Currently there can only be one screen object for an experiment (in some cases it can represent multiple screens, e.g. a window spanning screens). In an experiment script you can make one outside trials with the command screenObject and add it with addToExperiment.

Input properties


Default: highest attached screen number (secondary screen)

Psychtoolbox screen number to run the experiment on. 0, 1, 2, ... .  What screen number means depends on your operating system—you can type Screen('Screens') to get available screen numbers for currently attached screens, and Screen Screens? for general information. <cd>inf<cd> = highest screen number currently attached, which is typically the second screen in a multi-screen setup. Note on Linux you probably need to use Psychtoolbox XOrgConfCreator at least once before you can use a second screen.


Default: prompt for screen measurements at experiment startup

By default PsychBench prompts you to enter/confirm screen height and distance from subject to screen at experiment startup so it can interpret visual angle degree units. If you prefer to set them in the experiment script, you can make a screen object and set these properties. Then PsychBench doesn’t prompt when the experiment runs.

height_cm is screen height not including bezel (cm).

distance_cm is distance from subject to screen (cm).


Default: full-screen window

By default the experiment window is full screen. Optionally you can set openRect for a smaller window. This is a vector <cd>[x_tl y_tl x_br y_br]<cd> setting top left and bottom right coordinates of the window. Coordinates are relative to screen top left (not center) and units are fraction of respective screen dimension.

<cd>[0    0    1/2  1/2  ] <cd> – top left quarter of screen
<cd>[0.25 0.25 0.75 0.75 ] <cd> – half screen size centered on screen
<cd>[0    0    1    1    ] <cd> – full screen

If you use a partial screen window, PsychBench scales down all visual stimuli proportionate to the window height. For example, if you use a half-height window then 10 deg visual angle will appear as 5 deg. Also according to Psychtoolbox documentation, using any partial screen window can reduce timing precision. So, only use openRect for developing experiments. Usually the easiest way to change this property is using pb_prefs → screen tab.


Defaults: current Psychtoolbox settings (prioritize timing precision)

These properties set tradeoffs between visual timing precision and compatibility. Timing precision includes stimulus start/end and measured times, as well as avoiding tearing and other artifacts. On systems where high precision settings cause problems in opening or closing the experiment window, you can switch to compatibility. If you do, you should not run experiments where precise timing is important (you can still develop and test them, and run other experiments). Most commonly this is on Macs, which is okay because according to Psychtoolbox you shouldn’t run precise timing experiments on Mac anyway. Usually the easiest way to change these properties is using pb_prefs → screen tab.

doSyncTests sets whether and how Psychtoolbox does its screen synchronization tests before opening the experiment window. If your system often fails sync tests, you can disable or change them by default (− precision, + compatibility). For more information from Psychtoolbox see SyncTrouble a doSyncTests is a number which determines Psychtoolbox Screen('Preference', 'SkipSyncTests'):

<cd> 1 <cd> – sync tests on and error if fail (SkipSyncTests = <cd>0<cd>)
<cd> 0 <cd> – sync tests partially on and continue if fail (SkipSyncTests = <cd>1<cd>)
<cd>-1 <cd> – sync tests off (SkipSyncTests = <cd>2<cd>)
syncTestParams: You can also retain sync tests but change their thresholds to make them easier to pass (− precision, + compatibility). This is a 1×4 vector of parameters that go to inputs of Psychtoolbox Screen('Preference', 'SyncTestSettings'): (1) maxStddev (sec), (2) minSamples, (3) maxDeviation (sec), (4) maxDuration (sec). See the Psychtoolbox SyncTrouble page link above for documentation.

useCompositor = <cd>true<cd>/<cd>false<cd>: use your system’s window compositor, if there is one, to run the experiment window (− precision, + compatibility). <cd>true<cd> sets Psychtoolbox 
Screen('Preference', 'ConserveVRAM', <cd>16384<cd>). This can avoid hangs at experiment window close on Intel Macs, and may be necessary to run Psychtoolbox on M chips at all. For more information from Psychtoolbox see

For all these properties <cd>[]<cd> = current Psychtoolbox setting in case you want to use the Psychtoolbox command directly. Psychtoolbox defaults are to prioritize timing precision.


Default: no multisampling

Number of color samples per pixel for the graphics hardware to compute to apply multisample antialiasing, e.g. 0, 4, 8, etc. This goes to input multiplesample of Psychtoolbox Screen('OpenWindow'). Higher numbers give better quality but use more resources, which can affect video memory and frame rate. See for more information from Psychtoolbox.


Default: current Psychtoolbox setting (current gamma table)

An n×3 (intensity × RGB) matrix with normalized gamma values between 0–1. Typically n = 256 intensity levels. You can use this to calibrate luminance at each intensity × color channel based on data acquired from a photometer. This goes to Psychtoolbox Screen('LoadNormalizedGammaTable').

<cd>[]<cd> = current Psychtoolbox setting in case you want to use the Psychtoolbox command directly. Psychtoolbox default is the current gamma table, which you can get with Screen('ReadNormalizedGammaTable').


Default: only show mouse cursor when needed

<cd>true<cd>/<cd>false<cd>: show the mouse cursor all the time during the experiment. Regardless of what you set this to, the cursor shows when an element needs it. This just sets whether it shows the rest of the time too. If you use a partial screen window (openRect above) or have multiple screens attached, PsychBench ignores this property and the cursor stays on.


Default: don't flip display

<cd>true<cd>/<cd>false<cd>: flip the display horizontally/vertically. Useful if you’re running through a mirror. Note this flips the display for the whole experiment. If you want to flip just one element, use element properties flipHorz, flipVert instead.


Default: stereo = monoscopic display
Default: stereoOptions = none

0 = regular monoscopic display. Or set to a number > 0 specifying a stereo mode available in Psychtoolbox. Type Screen OpenWindow? for more information on stereo modes from Psychtoolbox, but as of July 2021:

<cd> 0 <cd> – none

<cd> 1 <cd> – OpenGL native stereo
<cd>11 <cd> – Psychtoolbox’s frame-sequential stereo

<cd> 2 <cd> – left → top half of screen / right → bottom half
<cd> 3 <cd> – like 2 except opposite

<cd> 4 <cd> – left → left half of screen / right → right half
<cd> 5 <cd> – like 4 except opposite

<cd> 6 <cd> – left = red / right = green anaglyph
<cd> 7 <cd> – like 6 except opposite

<cd> 8 <cd> – left = red / right = blue anaglyph
<cd> 9 <cd> – like 8 except opposite

<cd>12 <cd> – hardware-specific method, e.g. virtual reality head-mounted display.

If you set stereo > 0, you can use element property nn_eyes to set whether each element shows on left/right/both eyes. Some elements also have specialized stereo display options—see the element type documentation.

Additional stereo modes, parameters, and options are available in Psychtoolbox functions (e.g. SetStereoSideBySideParameters, SetAnaglyphStereoParameters, etc.) and imaging tasks in Psychtoolbox PsychImaging. Use properties beforeOpenCode/afterOpenCode below if needed.

stereoOptions: For any stereo mode (stereo > 0), this goes to Psychtoolbox Screen('SelectStereoDrawBuffer') input param1. Type Screen SelectStereoDrawBuffer? for more information.


Default: no custom code

You can access many screen-related options by writing custom code using Psychtoolbox functions and telling PsychBench to run it in these properties. Set any of these properties to a string containing code to run or the name of a script containing code.

beforeOpenCode runs before the experiment window opens but after the imaging pipeline opens. For example, you can write code calling PsychImaging('AddTask') to add imaging tasks. (For code to run before the imaging pipeline, just put it directly in your experiment script before runExperiment.)

openCode replaces PsychBench opening the experiment window. It must contain a call to Psychtoolbox PsychImaging('OpenWindow') and make a variable called ans containing the 
on-screen window number (pointer/handle). You can use this for options that need to be input to this command. <cd>[]<cd> = PsychBench opens the experiment window automatically.

afterOpenCode runs after the experiment window opens. For afterOpenCode only, your code can use the following variables containing information about the window:

n_window    – Psychtoolbox on-screen window number (pointer/handle)
windowSize    – window size [width height] (px)
windowCenter    – window center [x y] relative to its top left (px)
refreshRate    – see record property below
refreshInterval    – see record property below

Input properties all objects have


Record properties

PsychBench uses record properties to record information during experiments. You can't set record properties but you can see them in experiment results using input property report.


Nominal screen refresh rate (refreshes/sec) and interval (sec) measured by Psychtoolbox at experiment startup. In addition to being the rate visual displays animate at, this sets timing resolution (frame rate) for element start/end and many other processes in the experiment. See trial property frameIntervals for actual frame intervals achieved within each trial. For more information on frames and timing precision see Timing precision.