Layer Stimulus

Description

A layer is a container for other stimuli. When displayed, it first renders its child stimuli into a single scene, against a transparent background. It then draws this composite scene on the stimulus display.

The position and rotation specified by stimuli within a layer are interpreted as relative to the position and rotation of the layer itself. Hence, by changing a layer’s x_position, y_position, and/or rotation parameters, you can move a layer and its contents without needing to change the parameters of any child stimuli.

If one of a layer’s children is a mask, the “masked out” regions become transparent or semi-transparent “windows”, through which any stimuli below the layer are visible. For example, when displayed together, the following stimuli produce a red circle inside a green square:

rectangle the_background (
    color = 0,1,0
    x_size = 10
    )

layer the_layer {
    rectangle (
        color = 1,0,0
        x_size = 10
        )
    mask (
        mask = ellipse
        x_size = 10
        )
}

Signature

stimulus/layer

Optional Parameters

fullscreen

Default:

YES

If YES, the stimulus is sized to fill the display. In this mode, x_size, y_size, x_position, y_position, and rotation are ignored.

Note: Fullscreen layers consume a large amount of texture memory on the graphics hardware. Use them only when necessary.

max_size_x

Maximum horizontal size (degrees).

If omitted, the maximum horizontal size is set to the value of x_size when the stimulus is loaded.

max_size_y

Maximum vertical size (degrees).

If omitted, the maximum vertical size is set to the value of y_size when the stimulus is loaded.

alpha_multiplier

Default:

1.0

By default, the alpha multiplier controls the transparency of the stimulus. 1.0 is fully opaque, while 0.0 is fully tranparent.

Changes to the parameters source_blend_factor and dest_blend_factor can alter how (or if) the alpha multiplier is used.

source_blend_factor

Options:
zero
one
source_color
one_minus_source_color
dest_color
one_minus_dest_color
source_alpha
one_minus_source_alpha
dest_alpha
one_minus_dest_alpha
Default:

source_alpha

Source blending factor.

The parameters source_blend_factor, dest_blend_factor, source_alpha_blend_factor, and dest_alpha_blend_factor provide detailed control over how the color components and alpha multiplier of each fragment of the stimulus (the “source”) are combined with the color and alpha values already present in the framebuffer (the “destination”), which in turn result from blending the stimulus display background with any stimuli drawn beneath the source stimulus. These parameters correspond directly to the four arguments of the OpenGL function glBlendFuncSeparate. Please refer to that function’s reference page for explanations of the different blend factor options.

Note: Irrespective of the blend factors used, the blend equation is always GL_FUNC_ADD.

dest_blend_factor

Default:

one_minus_source_alpha

Destination blending factor. Accepts the same values as source_blend_factor.

source_alpha_blend_factor

Source alpha blending factor. Accepts the same values as source_blend_factor.

If omitted, the value of source_blend_factor is used.

dest_alpha_blend_factor

Destination alpha blending factor. Accepts the same values as source_blend_factor.

If omitted, the value of dest_blend_factor is used.

x_size

Example:

5.0

Horizontal size (degrees).

If omitted, the value of y_size is used. It is an error to omit both x_size and y_size (unless fullscreen is YES).

y_size

Example:

5.0

Vertical size (degrees).

If omitted, the value of x_size is used. It is an error to omit both x_size and y_size (unless fullscreen is YES).

x_position

Default:

0.0

Horizontal center position (degrees)

y_position

Default:

0.0

Vertical center position (degrees)

rotation

Default:

0.0

Rotation (degrees)

deferred

Options:
no
yes
explicit
Default:

no

Controls when the stimulus is loaded. If no, the stimulus is loaded at experiment load time. If yes, the stimulus is loaded the first time it is queued. If explicit, the stimulus must be loaded explictly with Load Stimulus.

display

Name of the display on which the stimulus will be presented. If omitted, the default display (if available) will be used.

Placement

Allowed at top level:

Yes

Allowed parent:

Compound Stimulus, Folder, Frame List Stimulus, Layer Stimulus, List Replicator, Movie Stimulus, Range Replicator, Stimulus Group

Allowed children:

Stimulus