Drifting Grating Stimulus¶

Description¶

A drifting grating stimulus

Signature¶

stimulus/drifting_grating

Required Parameters¶

spatial_frequency¶

Example: 1

Spatial frequency (cycles per degree)

speed¶

Example: 1

Drift speed (degrees per second)

grating_type¶

Options: sinusoid

square

triangle

sawtooth

Grating type

Optional Parameters¶

direction¶

Default: 0.0

Direction of drift (degrees)

central_starting_phase¶

Starting phase at the grating’s center (degrees).

Only one of central_starting_phase and starting_phase may be specified. If both are omitted, the grating will behave as if starting_phase were set to zero. Because the interpretation of starting_phase is often unintuitive and generally unhelpful, it is recommended that grating definitions always include central_starting_phase.

compute_phase_incrementally¶

Default: NO

If NO, the current phase of the grating is computed from central_starting_phase/starting_phase, spatial_frequency, speed, and the total time elapsed since the stimulus started playing.

If YES, the current phase is computed from the previous phase (i.e. the phase when the stimulus was last drawn), spatial_frequency, speed, and the time elapsed since the previous phase was computed.

This parameter is relevant only when the stimulus is live queued and the values of central_starting_phase/starting_phase, spatial_frequency, and/or speed are changed while the stimulus is playing. Most notably, if the parameter’s value is NO, then changes to speed will cause a discontinuous jump in phase. If the value is YES, then changes to speed will be smooth, with no phase jump.

mask¶

Default: NO

If YES, the grating will function as a mask (similar to a Mask Stimulus). When used as part of a layer, “high” regions of the grating (where the value is close to one) will allow stimuli beneath it in the layer to show through, while “low” regions (where the value is near zero) will partially or fully erase such stimuli, exposing any stimuli beneath the layer.

When the value of this parameter is YES, color, alpha_multiplier, source_blend_factor, dest_blend_factor source_alpha_blend_factor, and dest_alpha_blend_factor are ignored.

Note: For compatibility with existing experiments, the value of this parameter can also be one of rectangle, ellipse, or gaussian, in which case it specifies the type of mask to apply to the grating. However, this usage is deprecated, and new experiments should use a Mask Stimulus instead.

inverted¶

Default: NO

If YES, all grating values are inverted, e.g. high values become low, and low values become high

color¶

Default: 1.0,1.0,1.0

The color of the stimulus, 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).

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)

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.

autoplay¶

Default: NO

If YES, the stimulus will start playing automatically (as if by an implicit Play Dynamic Stimulus action) after it has been queued and Update Stimulus Display has been invoked. It will also stop playing automatically (as if by an implicit Stop Dynamic Stimulus action) after it has been dequeued and Update Stimulus Display is invoked.

Deprecated Parameters¶

starting_phase¶

Starting phase (degrees) at the “starting” edge of the grating. Exactly what constitutes the starting edge depends on direction, x_size, and y_size in a manner that is often unintuitive and generally unhelpful. Please use central_starting_phase instead.

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 grating. 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 stimulus.

normalized¶

Default: YES

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

Placement¶

Allowed at top level:	Yes
Allowed parent:	Folder, Frame List Stimulus, Layer Stimulus, List Replicator, Movie Stimulus, Range Replicator, Stimulus Group