Video Stimulus

Description

A stimulus that plays a video stored in any video file format supported by the operating system.

Note: To preserve the video’s aspect ratio on screen, x_size and y_size must be equal. When drawn, the larger dimension spans the full specified size, while the smaller dimension is scaled to maintain the aspect ratio.

Note: If the video contains an alpha channel, the embedded alpha value for each pixel is multiplied by the value of alpha_multiplier.

Signature

stimulus/video

Required Parameters

path

Filesystem path to the video file

Optional Parameters

volume

Default

0.0

Output audio volume (floating-point value between 0 and 1, where 0 is muted and 1 is full system volume)

loop

Default

NO

If YES, the video will repeat indefinitely (or until Stop Dynamic Stimulus is invoked)

repeats

Default

0

Number of times to repeat the video. Note that the video will always play at least once, even if this value is less than one.

If loop is YES, this parameter is ignored.

ended

Variable that will be set to true after the video ends. If repeats is greater than 1, the variable will be set only once, after all repetitions are complete. If loop is YES, the variable will never be set.

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.