Mask Stimulus

Description

Masks are useful only in conjuction with layers.

A mask can truncate, obscure, or erase stimuli in its layer that lie below it. The “masked out” regions become transparent or semi-transparent “windows”, through which any stimuli below the layer are visible. If the mask is inverted, it will make a “hole” through the stimuli under it, allowing the stimuli beneath the layer to show through.

For example, the following layer will produce a red ring with inner radius 5 and outer radius 10:

layer the_layer {
    circle (
        color = 1,0,0
        x_size = 20
        )
    mask (
        mask = ellipse
        inverted = true
        x_size = 10
        )
}

Signature

stimulus/mask

Required Parameters

mask

Options
rectangle
ellipse
gaussian
raised_cosine

Mask type

Optional Parameters

inverted

Default

NO

If YES, the effect of the mask is inverted: Areas of the display that normally would be visible through the mask are hidden, and areas that normally would be hidden are visible.

std_dev

Default

1.0

Standard deviation of Gaussian mask.

The Gaussian mask is computed on a 2x2 square, centered at the origin, using the equation:

exp(-1.0 * (dist - mean) * (dist - mean) / (2.0 * std_dev * std_dev))

where dist is distance from the center. The mask is then stretched to cover a rectangle of x_size by y_size degrees. If the x and y sizes are equal, then the mask is scaled by size/2 in both directions, so std_dev has units of size/2 degrees.

mean

Default

0.0

Mean of Gaussian mask.

This value determines the radial offset of the Gaussian peak from the center of the mask. If non-zero, the peak will be a circle, rather than a point, and luminance will decrease both inside and outside the circle, producing a toroidal mask.

normalized

Default

NO

If YES, the Gaussian mask includes a multiplicative normalization term (1/(std_dev*sqrt(2*pi))). If NO, this term is omitted.

edge_width

Default

0.125

Edge width of raised cosine mask.

This value specifies the width of the sinusoidal edge as a fraction of the total width (i.e. diameter) of the mask. It should be greater than zero and less than or equal to 0.5.

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)

fullscreen

Default

NO

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.

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.