screen device object

An object of type screen represents the screen and window the experiment shows in. This lets you set options like window size and position, timing precision / compatibility tradeoffs, color/luminance calibration, etc. An experiment can only have one screen object. You can add columns setting properties for it in the optional table for objects not specific to trial (experiment, device, staircase objects). [Or in the coding method: Make a screen object outside trials using function screenObject, set properties, and input it to addToExperiment.]

n_screen

Default, changeable in pb_prefs: highest attached screen number (a 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.

height_cm
distance_cm

Default: prompt to enter/confirm saved measurements at experiment startup

By default PsychBench asks you to enter/confirm saved display panel height and distance when you run an experiment so it can use visual angle degree units. If you prefer to set them directly in the experiment, you can add a screen object and set these properties. Then PsychBench won’t ask.

height_cm is display panel height (dimension) (cm).

distance_cm is distance from eye to panel (cm).

openRect

Default, changeable in pb_prefs: 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), + = right/down, units are fraction of respective screen dimension.

e.g.
<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. 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.

doSyncTests
syncTestParams
useCompositor

Defaults, changeable in pb_prefs: current Psychtoolbox settings (Psychtoolbox default: 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 set 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 http://psychtoolbox.org/docs/ConserveVRAMSettings and other threads on Psychtoolbox + system compositor.

For all these properties <cd>[]<cd> (default) = 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.

multisample

Default, changeable in pb_prefs: 0 = 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 http://psychtoolbox.org/docs/AntiAliasing for more information from Psychtoolbox.

bufferChannelResolution
clampChannels

Default, changeable in pb_prefs: bufferChannelResolution = 8 bit unsigned integer
Default, changeable in pb_prefs: clampChannels = clamp

bufferChannelResolution sets intensity resolution per 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.

gamma

Default, changeable in pb_prefs: current Psychtoolbox setting (Psychtoolbox default: 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> (default) = 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.

showMouseCursor

Default, changeable in pb_prefs: 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 always shows.

flipHorz
flipVert

Default, changeable in pb_prefs: 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.

stereo
stereoOptions

Default, changeable in pb_prefs: stereo = monoscopic display
Default, changeable in pb_prefs: stereoOptions = none

0 = regular mono 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> – mono display

<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, for any visual element you can use property nn_eyes to set whether it 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.

beforeOpenCode
openCode
afterOpenCode

Default, changeable in pb_prefs: 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 MATLAB 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 run it directly before calling 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.

afterOpenCode runs after the experiment window opens. For afterOpenCode only, your code can reference 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

refreshRate
refreshInterval

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.