glColorMaterial function

Article
12/11/2020

The glColorMaterial function causes a material color to track the current color.

Syntax

void WINAPI glColorMaterial(
   GLenum face,
   GLenum mode
);

Parameters

face: Specifies whether front, back, or both front and back material parameters should track the current color. Accepted values are GL_FRONT, GL_BACK, and GL_FRONT_AND_BACK. The default value is GL_FRONT_AND_BACK.
mode: Specifies which of several material parameters track the current color. Accepted values are GL_EMISSION, GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, and GL_AMBIENT_AND_DIFFUSE. The default value is GL_AMBIENT_AND_DIFFUSE.

Return value

This function does not return a value.

Error codes

The following error codes can be retrieved by the glGetError function.

Name	Meaning
GL_INVALID_ENUM	face or mode was not an accepted value.
GL_INVALID_OPERATION	The function was called between a call to glBegin and the corresponding call to glEnd.

Remarks

The glColorMaterial function specifies which material parameters track the current color. When you enable GL_COLOR_MATERIAL, for each of the material or materials specified by face, the material parameter or parameters specified by mode track the current color at all times. Enable and disable GL_COLOR_MATERIAL with the functions glEnable and glDisable, which you call with GL_COLOR_MATERIAL as their argument. By default, GL_COLOR_MATERIAL is disabled.

With glColorMaterial, you can change a subset of material parameters for each vertex using only the glColor function, without calling glMaterial. If you are going to specify only such a subset of parameters for each vertex, it is better to do so with glColorMaterial than with glMaterial.

The following functions retrieve information related to glColorMaterial:

glGet with argument GL_COLOR_MATERIAL_PARAMETER

glGet with argument GL_COLOR_MATERIAL_FACE

glIsEnabled with argument GL_COLOR_MATERIAL

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	Gl.h
Library	Opengl32.lib
DLL	Opengl32.dll