A screen object is optional. You only need to add one if you want to change a property from default. Note for some properties you can also change the default values themselves using pb_prefs at the MATLAB command line, which may be more convenient.
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.]
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
height_cm is display panel height (dimension) (cm).
distance_cm is distance from eye to panel (cm).
Default: full-screen window
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. Usually the easiest way to set this property is with pb_prefs.
Defaults: current Psychtoolbox settings (highest timing precision, lowest compatibility)
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'):
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> = 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 http://psychtoolbox.org/docs/AntiAliasing for more information from Psychtoolbox.
Default: bufferChannelResolution = 8 bit unsigned integer
Default: clampChannels = clamped
<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.
Default: current Psychtoolbox setting (current graphics card gamma table)
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
<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
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.
Default: no custom 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. <cd>[]<cd> = PsychBench opens the experiment window automatically.
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
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 frameRates, frameIntervals for actual frame rate and intervals achieved in each trial. For more information on frames and timing precision see Timing precision.