All visual elements
Visual elements include visual stimuli as well as elements that use other kinds of screen-based functionality like mouse. They all have the properties below setting visual options and transformations.
Input properties all visual elements have
position
depth
Default: position = screen center
Default: depth = 0 (doesn't matter if element won't overlap with other elements)
position is a vector [x y] setting element position on screen (deg). + = right/down (like Western text and matrix indexing), <cd>[0 0]<cd> = screen center. Typically elements center at this point, but see element type documentation for exceptions.
depth is a number setting element layering on screen. + = backward, − = forward. Absolute values don’t matter, only relative. You can ignore depth for element displays that won’t overlap.
To set drift or movement, you can use property vary.
Examples
element.position = [2 0]
→ 2 deg right from screen center
element.position = {[-400 -400], <cdsm>"px"<cdsm>}
→ 400 px left and up from screen center
nn_eyes
Default: show on both eyes
If you turn on stereo display (screen object property stereo) use this property to set whether the element shows on left eye (<cd>1<cd>), right eye (<cd>2<cd>), or both eyes (a vector <cd>[1 2]<cd>). The other position properties above apply as usual within each eye.
rotation
Default: no rotation
Element orientation clockwise (from +x to +y screen axis) about position (deg).
flipHorz
flipVert
Defaults: don't flip
<cd>true<cd>/<cd>false<cd>: flip element horizontally/vertically. Note if you want to flip the whole display for the experiment, use screen object properties flipHorz, flipVert instead.
colorMask
Default: normal color
A 1×3 vector with numbers between 0–1 scaling RGB colors in the element display. e.g. <cd>[1 0 0]<cd> = remove all green and blue color from the display. In the case of a pixel that is pure white (RGB = <cd>[1 1 1]<cd>), colorMask is equivalent to setting its RGB color.
Often you can set color directly in a type-specific property (e.g. color) instead. colorMask is useful for elements where the image(s) are read from a file or data and color can't be set directly, e.g. in picture or movie elements. Another difference is that colorMask is usually adjustable (so you can apply property vary or an adjuster element to it) whereas type-specific color properties often are not.
alpha
Default: no additional transparency
A number between 0–1 applying transparency to the element. 0 = fully transparent (invisible), 1 = no additional transparency.
Note regardless of this property some elements have a fully transparent background and/or specific parts of their display that have some level of transparency. In general alpha applies an additional multiplication of transparency at the level of the whole element. If the element has any visible background and you want to change the transparency of that specifically, use property backColor below instead. Some elements also allow setting transparency for other parts of their display with type-specific properties—see element type documentation.
intensity
Default: normal
A number ≥ 0 multiplying the RGB intensity of the element. < 1 = decrease brightness, 1 = normal, > 1 = increase brightness. Note often you can set brightness more directly through type-specific properties setting color.
contrastMult
Default: normal
A number ≥ 0 multiplying the contrast of the element, assuming a mean intensity of 0.5 (50%). < 1 = decrease contrast, 1 = normal, > 1 = increase contrast.
Or a vector [mult mean] if you want to use a different mean intensity value. Currently PsychBench cannot automatically detect actual mean intensity values for use with this property.
The transformation at each pixel is:
<cd>rgb = (rgb-mean)*mult+mean<cd>
convolution
Default: no convolution
You can apply various types of blur or any other convolution filter using this property. convolution is a further struct that can have the following fields. You can omit fields (or leave them = <cd>[]<cd>) to leave them at default.
Note if you use convolution, PsychBench needs to fill any transparent parts of the element background with a solid color to blend with. Even if the element doesn’t have any transparent background, this still affects pixels near its edges since PsychBench pads the element display with this color. By default fill color is the same as trial background color. If you want to use a different color, you can set property backColor below (must be opaque).
type
size
sigma
Default: no generated kernel
type is a string <cdsm>"average"<cdsm>, <cdsm>"disk"<cdsm>, or <cdsm>"gaussian"<cdsm> to tell PsychBench to use a symmetric convolution kernel of that type. You then need to set size and other parameters in further fields below:
size is width of the symmetric kernel. Convolution is applied at the resolution the element shows at on screen. As such, kernel size is a distance on screen, so by default it’s in deg units as usual. The resulting size will round up to an odd integer number of px on screen. Note if you want to set size in px units, you can use <cdm>{value, <cdm><cdsm>"unit"<cdsm><cdm>}<cdm> form directly in the field, e.g. convolution.size = <cdm>{value, <cdm><cdsm>"px"<cdsm><cdm>}<cdm>.
sigma (type = <cdsm>"gaussian"<cdsm> only): This is standard deviation of the Gaussian. Again this is a distance on screen, by default in deg but you can specify other units like px directly in the field if you want.
For type = <cdsm>"gaussian"<cdsm> only, you can set either size or sigma and the other will default to size = 4 × sigma. You can also set both if you want a different ratio.
Note if you use filterResolutionMult below to apply the convolution at a resolution lower than screen resolution, PsychBench will automatically scale size and sigma down. So, always set them assuming convolution at screen resolution.
type requires the MATLAB Image Processing Toolbox.
kernel
Default: no custom kernel
If you don’t have the Image Processing Toolbox or want to use a different kernel than one of the above, you can directly specify any kernel as a 2D matrix in kernel instead. Specifically this is a correlation kernel like those generated by fspecial (it will be rotated 180 deg at application to implement convolution). Pixels in the kernel correspond to pixels at screen resolution. Like a MATLAB image matrix, rows correspond to height and columns to width. The kernel must be an odd integer number of px wide and high (not necessarily symmetric). If the kernel is separable, you can use a 1×2 cell array containing x and y kernels for greater efficiency.
Note if you use filterResolutionMult below to apply the convolution at a resolution lower than screen resolution, PsychBench does not scale your custom kernel down. You must set it assuming convolution at the lower resolution.
shader
Default: no custom shaders
You can apply custom visual transformations using one or more GLSL shaders. shader is a further struct that can have the following fields. You can omit fields (or leave them = <cd>[]<cd>) to leave them at default. You can apply multiple shaders separately by making shader a struct array, e.g. <cd>shader(1).fileName = <cd> ..., <cd>shader(2).fileName = <cd>... , to run in that order.
fileName
A string or array of strings that are text files containing GLSL shader code, one file per shader. If multiple files then the shaders will be linked into a single program in that order.
setupCode
setupVars
Defaults: no additional setup code
PsychBench automatically loads and links the shader(s) in fileName using Psychtoolbox LoadGLSLProgramFromFiles and adds them to a GL operator using AddToGLOperator. However, typically the shader(s) need some setup code between loading/linking and adding, e.g. setting uniforms, making auxiliary textures, etc. You can set setupCode to a string that is the name of a MATLAB script containing this code. The script can reference the variable n_shader which will contain the pointer to the loaded/linked shader program. It can optionally make variables blitterConfig and n_lutTexture which will go to inputs of AddToGLOperator, and nn_glTextures which is a row vector containing OpenGL texture numbers for any auxiliary textures the setup code opens so PsychBench can close them later.
setupVars: You can provide further inputs to the setup code in this field. This is a further struct containing any number of fields with any names containing anything you want. This will struct be available to the setup code in a variable called vars.
Example
An example of a shader and some setup code for it which reproduces property contrastMult above is in <><PsychBench folder><>/docs/demos. Other open source shader files can also be found in <><PsychBench folder><>/core/elementWithScreen. Many more can be found in folders in Psychtoolbox.
filterOrder
filterGrayscale
filterResolutionMult
filterGamma
Default: filterOrder = intensity → contrastMult → convolution → custom shaders in shader
Default: filterGrayscale = don't assume grayscale element display
Default: filterResolutionMult = filter at screen resolution
Default: filterGamma = apply filters to standard gamma-encoded RGB
Properties intensity, contrastMult, convolution, shader, above are implemented as GLSL shaders that run on your graphics hardware. The properties below affect all of them.
filterOrder: If you enable more than one of these filters, the default order they apply in is listed above. You can set filterOrder if you want to use a different order. This is an array of strings that can include any of <cds>"intensity"<cds>, <cds>"contrastMult"<cds>, <cds>"convolution"<cds>, <cds>"shader"<cds>, <cds>"shader(1)"<cds>, <cds>"shader(2)"<cds>, ... in any order.
filterGrayscale: <cd>true<cd>/<cd>false<cd>: assume grayscale element display. If the element is grayscale, setting this = <cd>true<cd> makes the filter operation(s) faster since then they only need to be calculated once for each pixel, not recalculated for each RGB pixel component. This can help avoid dropped frames if you have a dynamic stimulus where PsychBench needs to re-filter at each frame of animation and you have some combination of computationally intensive filter / large stimulus / high screen resolution / slow system. Note if the element is not grayscale and you set filterGrayscale = <cd>true<cd>, it will appear grayscale but with distorted brightness, so don't do that. filterGrayscale doesn't apply to custom shaders you set in shader above—for these you can implement any grayscale treatment directly in your shader code.
filterResolutionMult lets you apply these filters at a lower resolution than the element shows at on screen. This is a number between 0–1 that is fraction of screen resolution to use, e.g. 0.5 = half screen resolution, 1 = screen resolution. The filter result is then scaled up to screen resolution for display. filterResolutionMult < 1 makes the filter operation(s) faster, similar to filterGrayscale above. However it may come at a cost of reduced image quality.
filterGamma applies a gamma decoding before any intensity, contrastMult, convolution, shader and then its inverse (re-encoding) after them and before display. You can use this to apply these filters to a representation that models the physical luminance the element will produce as opposed to its standard gamma-encoded RGB, assuming the filterGamma you set correctly models the total mapping from gamma-encoded RGB → luminance for your display (note this total mapping is generally not just your graphics card's gamma table—see screen object gamma for more information). For example, you could use filterGamma with a blur convolution to simulate reduced visual acuity at the eye. filterGamma is ignored if no convolution filters are applied.
filterGamma can be one number for simple power law gamma decoding/re-encoding (e.g. the standard 2.2). Or it can be an n×3 matrix with columns corresponding to RGB color channels, rows corresponding to input intensities (e.g. for 1024 rows: 0, 1/1024, 2/1024, ... 1), and numbers = output intensities between 0–1.
filterGamma doesn't change the gamma decoding that is actually applied element displays—for that add a screen object and set its property gamma. You can also mix using filterGamma with screen gamma.
channelResolution
Default: 8 bits
Intensity resolution of each pixel channel (R, G, B, A) for the element display before being drawn to the experiment window (bits). Typically you can leave this at default 8 bits (256 levels) since final displayed channel resolution is limited by your graphics hardware. However, if needed you can set this to 16 or 32 bits for higher precision in pre-window processing.
Not all graphics hardware supports even pre-window channel resolutions > 8 bits, more specifically that and alpha blending at the same time. If yours doesn't, you will see warnings from Psychtoolbox in the MATLAB command window and you would need to upgrade your graphics hardware.
Example
If an element display has low dynamic range at low levels (e.g. levels 15–20 out of 256 at 8 bits) and you apply a filter like intensity that scales it up, e.g. ×10 to 150–200, the quantization would become easily visible since it would be distributed across much more of the dynamic range of the screen. To avoid this you could set the element's channel resolution = 16 or 32 bits such that the same initial range would be quantized into 6,144 or 100,663,296 levels, which would still look smooth when scaled up.
backColor
Default: transparent RGBA <cd>[0 0 0 0]<cd>
Color of the background area of the element display. This only affects elements that have empty space in their display. Generally leave it at default transparent, which allows elements with empty space to layer on top of other elements without occluding them.
In unusual cases you might want to specify an opaque background. For example, the default transparent background can cause artifacts in some element displays with antialiased edges or other transparency (see the element type documentation). You can set backColor = a string <cds>"opaque"<cds> to make it opaque matching trial background color. You can also use any custom opaque color by setting a 1×3 RGB vector with numbers between 0–1.
addDisplay
Default: <cd>false><cd> → display occludes or blends with whatever is behind it
<cd>true<cd>/<cd>false<cd>: If = <cd>true<cd> then instead of the usual occluding or blending, the element display's pixel values will add to pixel values behind it on screen (including negative pixel values subtract). For most elements this doesn't make sense to do. However, some elements support it—see element type documentation. For example, if you set addDisplay = <cd>true<cd> for a noise element then instead of simply showing a noise patch, it will add noise to whatever is behind it on screen, typically another element.
Notes: Use property depth above to put the element above the other element(s) you want to add to.
Not all graphics hardware supports this, more specifically this and alpha blending at the same time. If yours doesn't, all element displays will occlude and you will see warnings from Psychtoolbox in the MATLAB command window. On some systems making a screen object and setting its property bufferChannelResolution to <cds>"16i"<cds> will work in this case. Otherwise you would need to upgrade your graphics hardware.
Technical
If you enable this property, PsychBench enables a signed experiment window frame buffer (default 16 bit floating point) and unclamps pre-display pixel values. These can also be set independently in screen object properties bufferChannelResolution and clampChannels, but if you set addDisplay for any element in the experiment then PsychBench does it automatically so you don't need to. However, you can additionally set screen bufferChannelResolution if you want to change the type of signed frame buffer it uses.
Input properties all objects have
Record properties all visual elements have
PsychBench uses record properties to record information during experiments. You can't set record properties but you can see them in experiment results using input property report.