Stimulus Display¶

Description¶

A stimulus display device.

By including a stimulus display device definition in your experiment file, you can configure the default display or create one or more non-default displays. (See below for more information.)

Note: Start IO Device, Stop IO Device, and autostart have no effect on this device.

Default Display

If an experiment requires a stimulus display (e.g. because it includes one or more stimuli) but does not define a stimulus display device, it will create a display automatically. This display is called the default stimulus display.

If you want to configure the default display (e.g. change its background color or enable frame capture), add a stimulus display device with no display_info parameter to your experiment, and set its other parameters as desired. Note that only one stimulus display device can configure the default display.

Non-Default Displays

If your experiment defines one or more stimulus display devices with non-empty display_info parameters, it will not create a default stimulus display. Instead, each stimulus display definition will create and configure a non-default display.

Because the default display is not available, all stimulus definitions and display-related actions (e.g. Update Stimulus Display) must specify explicitly which display to use. If not, the experiment will fail to load.

Note that if an experiment that defines non-default displays includes a stimulus display device with no display_info parameter, that device will not configure the default display (which does not exist). Instead, it will create another non-default display that takes its configuration information from #mainScreenInfo.

Signature¶

iodevice/stimulus_display

Optional Parameters¶

display_info¶

Example:: {'display_to_use': 1, 'width': 400, 'height': 300, 'distance': 200}

Dictionary containing configuration information for the display. The keys and values are the same as those used with #mainScreenInfo.

If omitted, the value of #mainScreenInfo is used.

background_color¶

Default:: 0.5,0.5,0.5

The background color, expressed as a comma-separated list of red, green, and blue components. Each component may be described by any valid expression, but the expression must result in a value between 0 and 1 (inclusive).

background_alpha_multiplier¶

Default:: 1.0

Controls the transparency of the background. 1.0 is fully opaque, while 0.0 is fully tranparent.

Note: To enable background transparency, you must set display_info’s make_window_opaque key to false. To make the stimulus display window fully transparent, set this parameter and all components of background_color to 0.

redraw_on_every_refresh¶

Default:: NO

If YES, the display will be redrawn during every refresh cycle. If NO, the display will be redrawn only when needed or when explicitly requested via Update Stimulus Display.

announce_stimuli_on_implicit_updates¶

Default:: YES

Controls the announcement of stimuli during “implicit” display updates (i.e. updates requested by running dynamic stimuli and not triggered by an explicit Update Stimulus Display action). If set to NO, values assigned to update_variable for implicit updates will contain only the number of stimuli displayed (in place of the usual list of stimulus parameters).

update_variable¶

Variable in which to store update announcements for the display. The announcements have the same format as those assigned to #stimDisplayUpdate.

If omitted, #stimDisplayUpdate is used.

capture_format¶

Options:: none

JPEG

PNG
Default:: none

Format in which to capture display frames.

If none, display frames will not be captured. Otherwise, for every display redraw for which capture_enabled evaluates to true, the contents of the display will be captured in the specified format, at the resolution determined by capture_height_pixels, and stored (as binary data) in the variable specified by capture_variable.

capture_height_pixels¶

Default:: 0

Height (in pixels) of captured display frames.

If the value of this parameter is less than or equal to zero, frames will be captured at the full height and width of the display. Otherwise, each frame will be scaled down to the specified height, with the width chosen to match the aspect ratio of the display.

Note: The cost of frame capture, in terms of both CPU usage and required storage space, depends almost entirely on the size of the captured frames. If you experience performance issues with capture enabled, try reducing the value of this parameter.

capture_enabled¶

Default:: YES

If capture_format is not none, every time the display redraws, it will test the value of this parameter. If the parameter evaluates to a true value (e.g. 1, true), the current frame will be captured.

By setting this parameter to the name of a variable, your experiment can dynamically enable or disable frame capture by assigning a true or false value, respectively, to the variable. This allows you to capture frames only when needed.

capture_variable¶

Variable in which to store captured display frames. If omitted, #stimDisplayCapture is used.

autostart¶

Default:: NO

If YES, the device will start I/O automatically (as if by an implicit Start IO Device action) when the experiment starts running.

Note: Device I/O will always stop automatically when the experiment stops running, irrespective of this setting.

alt¶

Alternative device to use if this one fails to initialize (e.g. because the required hardware is not available). If #allowAltFailover is set to 0 or false, this parameter is ignored.

Placement¶

Allowed at top level:	Yes
Allowed parent:	Folder