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 lets 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 using function screenObject and add it using 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 (at least that use deg and other standard distance units) based on window height. For example, if you use a half-height window then 10 deg will appear as 5 deg. Note 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 (highest timing precision, lowest compatibility)

These properties set tradeoffs between visual timing precision and compatibility. Timing precision includes both accuracy in stimulus start/end times and measured time values, and potentially avoiding visual artifacts like tearing. On systems where high precision causes problems in opening or closing the experiment window, you can switch to compatibility. This generally comes at a cost of reduced timing precision. Most commonly you need this is on Macs, which may be okay since Psychtoolbox recommends not running 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. 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 desktop 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. On some Windows 8+ setups this may be forced by the operating system anyway. For more information from Psychtoolbox see and other threads on Psychtoolbox + desktop compositor.

For all these properties <cd>[]<cd> = current Psychtoolbox setting. Psychtoolbox defaults in turn are to prioritize timing precision. If you leave any of these properties at default, you can also use the corresponding Psychtoolbox command directly before the experiment.


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 graphics card gamma table)

Set gamma decoding (correction) applied by the graphics card during the experiment. This is an n×3 matrix which goes to Psychtoolbox Screen('LoadNormalizedGammaTable'). Columns corresponding to RGB color channels. Rows corresponding to input intensities, e.g. for 1024 rows: 0, 1/1024, 2/1024, ... 1. Numbers in the matrix are output intensities between 0–1. A common use for gamma is calibrating display luminance based on data acquired from a photometer.

You can also use one number for simple power law gamma, i.e. output = input^gamma. (At least for LCD screens this is generally not appropriate.)

You can also control gamma decoding for specific elements using element property gamma. For example, you would do this if you wanted different elements in an experiment to use different gamma. See also element property filterGamma.

<cd>[]<cd> = current Psychtoolbox setting. Psychtoolbox default in turn is your graphics card's current gamma table for the screen, which you can get with Screen('ReadNormalizedGammaTable'). If you leave gamma at default, you can also use the Psychtoolbox command directly before the experiment.

Note graphics card gamma is generally only part of the gamma decoding of a display. The screen may add its own gamma, then the screen's physical RGB → luminance response is equivalent to further gamma, etc. However, graphics card gamma can be used to calibrate total display gamma based on luminance measurements.


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.


Screen refresh rate (refreshes/sec) and interval (sec) measured by Psychtoolbox at experiment startup. In addition to being the nominal rate that dynamic displays can animate at, this sets the nominal timing resolution for element start/end and many other processes. Note actual frame rate achieved in the experiment can be lower when frames are dropped due to processing load. See trial record properties frameRate, frameIntervals for actual frame rate and intervals achieved in each trial. For more information on frames and timing precision see Timing precision.