BlinnPhongMaterial([win, diffuseColor, ...])

Class representing a material using the Blinn-Phong lighting model.


class psychopy.visual.BlinnPhongMaterial(win=None, diffuseColor=(0.5, 0.5, 0.5), specularColor=(-1.0, -1.0, -1.0), ambientColor=(-1.0, -1.0, -1.0), emissionColor=(-1.0, -1.0, -1.0), shininess=10.0, colorSpace='rgb', diffuseTexture=None, opacity=1.0, contrast=1.0, face='front')[source]

Class representing a material using the Blinn-Phong lighting model.

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.

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.


This class is experimental and may result in undefined behavior.

  • 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, a) with values between 0.0 and 1.0.

  • specularColor (array_like) – Specular material color (r, g, b, a) with values between 0.0 and 1.0.

  • ambientColor (array_like) – Ambient material color (r, g, b, a) with values between 0.0 and 1.0.

  • emissionColor (array_like) – Emission material color (r, g, b, a) with values between 0.0 and 1.0.

  • shininess (float) – Material shininess, usually ranges from 0.0 to 128.0.

  • colorSpace (float) – Color space for diffuseColor, specularColor, ambientColor, and emissionColor.

  • diffuseTexture (TexImage2D) –

  • 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.

  • face (str) – Face to apply material to. Values are front, back or both.

  • textures (dict, optional) – Texture maps associated with this material. Textures are specified as a list. The index of textures in the list will be used to set the corresponding texture unit they are bound to.

property ambientColor

Ambient color of the material.

property ambientRGB

Diffuse color of the material.


Use this material for successive rendering calls.


useTextures (bool) – Enable textures.

property diffuseColor

Diffuse color of the material.

property diffuseRGB

Diffuse color of the material.

property diffuseTexture

Diffuse color of the material.

property emissionColor

Emission color of the material.

property emissionRGB

Diffuse color of the material.


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.

property shininess
property specularColor

Specular color of the material.

property specularRGB

Diffuse color of the material.

Back to top