Screen device object

A screen object is optional. You only need to make one if you want to change a property from default. Note for some properties you can also change the defaults themselves using pb_prefs, which is often more convenient.

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 at experiment startup so it can interpret visual angle degree units. However, if you prefer to set them in the experiment script, you can make a screen object and set these properties. In that case PsychBench won’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, using a partial screen window can reduce timing precision, so generally only use openRect for developing experiments. Usually the easiest way to change this property is with pb_prefs.


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 the high precision defaults cause problems in opening or closing the experiment window (especially on Mac, sometimes on Windows), you can switch to compatibility instead. Note Psychtoolbox recommends not running precise timing experiments on such systems. You can still develop precise timing experiments and/or run experiments that don’t need precise timing. Usually the easiest way to change these properties is with pb_prefs.

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 (less precision, more 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 (less precision, more 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 to run the experiment window (less precision, more compatibility). <cd>true<cd> sets Psychtoolbox Screen('Preference', 'ConserveVRAM', <cd>16384<cd>). Note on some Windows setups this is forced by the operating system anyway—you can check the command window text from Psychtoolbox when opening an experiment window for if this is the case. For more information from Psychtoolbox see and other threads on Psychtoolbox + system 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: bufferChannelResolution = 8 bit unsigned integer
Default: clampChannels = clamped

bufferChannelResolution sets intensity resolution of each pixel channel (R, G, B) for the experiment window frame buffer. Final displayed channel resolution is still limited by your graphics hardware, so typically at least for an SDR screen you can leave this at default 8 bit unsigned integer (256 levels). However, if needed you can set this to a string for higher precision at the frame buffer:

<cds>"8"  <cds> – 8 bit unsigned integer
<cds>"16" <cds> – 16 bit floating point
<cds>"16i"<cds> – 16 bit integer (signed if supported, else unsigned)
<cds>"32" <cds> – 32 bit floating point

See Psychtoolbox PsychImaging'FloatingPoint16Bit', 'FixedPoint16Bit', etc. for more information. Note this property is independent of element channelResolution. i.e. if you set this property, each element display pre-window still defaults to 8 bits/channel and you must set the ones you want higher there.

clampChannels = <cd>true<cd>/<cd>false<cd>: clamp all pre-display pixel channel values to 0–1. Clamped is most compatible with older graphics hardware. See Psychtoolbox Screen('ColorRange') and PsychImaging'NormalizedHighresColorRange' for more information.


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.)

<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 for stereo display, set to a number > 0 specifying a stereo mode provided by Psychtoolbox. Type Screen OpenWindow? and read under input stereomode for more information on stereo modes, 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

If you set stereo > 0, you can use element property nn_eyes to set whether an 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.
See the stereo tutorial in <PsychBench folder>/docs/tutorials.


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 n_window 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 by listing them 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 frameRates, frameIntervals for actual frame rate and intervals achieved in each trial. For more information on frames and timing precision see Timing precision.