BlinnPhongMaterial¶
|
Class representing a material using the Blinn-Phong lighting model. |
Class representing a material using the Blinn-Phong lighting model. This is a lazy-imported class, therefore import using full path from psychopy.visual.stim3d import BlinnPhongMaterial when inheriting from it.
This class stores material information to modify the appearance of drawn primitives with respect to lighting, such as color (diffuse, specular, ambient, and emission), shininess, and textures. Simple materials are intended to work with features supported by the fixed-function OpenGL pipeline. However, one may use shaders that implement the Blinn-Phong shading model for per-pixel lighting.
If shaders are enabled, the colors of objects will appear different than without. This is due to the lighting/material colors being computed on a per-pixel basis, and the formulation of the lighting model. The Phong shader determines the ambient color/intensity by adding up both the scene and light ambient colors, then multiplies them by the diffuse color of the material, as the ambient light’s color should be a product of the surface reflectance (albedo) and the light color (the ambient light needs to reflect off something to be visible). Diffuse reflectance is Lambertian, where the cosine angle between the incident light ray and surface normal determines color. The size of specular highlights are related to the shininess factor which ranges from 1.0 to 128.0. The greater this number, the tighter the specular highlight making the surface appear smoother. If shaders are not being used, specular highlights will be computed using the Phong lighting model. The emission color is optional, it simply adds to the color of every pixel much like ambient lighting does. Usually, you would not really want this, but it can be used to add bias to the overall color of the shape.
If there are no lights in the scene, the diffuse color is simply multiplied by the scene and material ambient color to give the final color.
Lights are attenuated (fall-off with distance) using the formula:
attenuationFactor = 1.0 / (k0 + k1 * distance + k2 * pow(distance, 2))
The coefficients for attenuation can be specified by setting attenuation in the lighting object. Values k0=1.0, k1=0.0, and k2=0.0 results in a light that does not fall-off with distance.
win (~psychopy.visual.Window or None) – Window this material is associated with, required for shaders and some color space conversions.
diffuseColor (array_like) – Diffuse material color (r, g, b) with values between -1.0 and 1.0.
specularColor (array_like) – Specular material color (r, g, b) with values between -1.0 and 1.0.
ambientColor (array_like) – Ambient material color (r, g, b) with values between -1.0 and 1.0.
emissionColor (array_like) – Emission material color (r, g, b) with values between -1.0 and 1.0.
shininess (float) – Material shininess, usually ranges from 0.0 to 128.0.
colorSpace (str) – Color space for diffuseColor, specularColor, ambientColor, and emissionColor. This is no longer used.
opacity (float) – Opacity of the material. Ranges from 0.0 to 1.0 where 1.0 is fully opaque.
contrast (float) – Contrast of the material colors.
diffuseTexture (TexImage2D) – Optional 2D texture to apply to the material. Color values from the texture are blended with the diffuseColor of the material. The target primitives must have texture coordinates to specify how texels are mapped to the surface.
face (str) – Face to apply material to. Values are front, back or both.
Warning
This class is experimental and may result in undefined behavior.
Ambient color (r, g, b) of the material (psychopy.color.Color, ArrayLike or None).
RGB values of the ambient color of the material (numpy.ndarray).
Use this material for successive rendering calls.
useTextures (bool) – Enable textures.
The name of the color space currently being used (str or None).
For strings and hex values this is not needed. If None the default colorSpace for the stimulus is used (defined during initialisation).
Please note that changing colorSpace does not change stimulus parameters. Thus, you usually want to specify colorSpace before setting the color.
A value that is simply multiplied by the color (float).
This may be used to adjust the lightness of the material. This is applied to all material color components.
Examples
Basic usage:
stim.contrast = 1.0 # unchanged contrast
stim.contrast = 0.5 # decrease contrast
stim.contrast = 0.0 # uniform, no contrast
stim.contrast = -0.5 # slightly inverted
stim.contrast = -1.0 # totally inverted
Setting contrast outside range -1 to 1 is permitted, but may produce strange results if color values exceeds the monitor limits.:
stim.contrast = 1.2 # increases contrast
stim.contrast = -1.2 # inverts with increased contrast
Diffuse color (r, g, b) for the material (psychopy.color.Color, ArrayLike or None).
RGB values of the diffuse color of the material (numpy.ndarray).
Diffuse texture of the material (psychopy.tools.gltools.TexImage2D or None).
Emission color (r, g, b) of the material (psychopy.color.Color, ArrayLike or None).
RGB values of the emission color of the material (numpy.ndarray).
Stop using this material.
Must be called after begin before using another material or else later drawing operations may have undefined behavior.
Upon returning, GL_COLOR_MATERIAL is enabled so material colors will track the current glColor.
clear (bool) – Overwrite material state settings with default values. This ensures material colors are set to OpenGL defaults. You can forgo clearing if successive materials are used which overwrite glMaterialfv values for GL_DIFFUSE, GL_SPECULAR, GL_AMBIENT, GL_EMISSION, and GL_SHININESS. This reduces a bit of overhead if there is no need to return to default values intermittently between successive material begin and end calls. Textures and shaders previously enabled will still be disabled.
Face to apply the material to (str). Possible values are one of ‘front’, ‘back’ or ‘both’.
Set the ambient color for the material.
Use this function if you wish to supress logging or apply operations on the color component.
color (ArrayLike or ~psychopy.colors.Color) – Color to set as the ambient component of the light source.
colorSpace (str or None) – Colorspace to use. This is only used to set the color, the value of ambientColor after setting uses the color space of the object.
operation (str) – Operation string.
log (bool or None) – Enable logging.
Set the diffuse color for the material.
Use this method if you wish to supress logging or apply operations on the color component.
color (ArrayLike or ~psychopy.colors.Color) – Color to set as the diffuse component of the material.
colorSpace (str or None) – Colorspace to use. This is only used to set the color, the value of diffuseColor after setting uses the color space of the object.
operation (str) – Operation string.
log (bool or None) – Enable logging.
Set the emission color for the material.
Use this function if you wish to supress logging or apply operations on the color component.
color (ArrayLike or ~psychopy.colors.Color) – Color to set as the ambient component of the light source.
colorSpace (str or None) – Colorspace to use. This is only used to set the color, the value of ambientColor after setting uses the color space of the object.
operation (str) – Operation string.
log (bool or None) – Enable logging.
Set the diffuse color for the material. Use this function if you wish to supress logging or apply operations on the color component.
color (ArrayLike or ~psychopy.colors.Color) – Color to set as the specular component of the light source.
colorSpace (str or None) – Colorspace to use. This is only used to set the color, the value of diffuseColor after setting uses the color space of the object.
operation (str) – Operation string.
log (bool or None) – Enable logging.
Material shininess coefficient (float).
This is used to specify the ‘tightness’ of the specular highlights. Values usually range between 0 and 128, but the range depends on the specular highlight formula used by the shader.
Specular color (r, g, b) of the material (psychopy.color.Color, ArrayLike or None).
RGB values of the specular color of the material (numpy.ndarray).