GLMATERIAL() MachTen Programmer’s Manual GLMATERIAL()

NAME
glMaterialf, glMateriali, glMaterialfv, glMaterialiv -
specify material parameters for the lighting model

C SPECIFICATION
void glMaterialf( GLenum face,
GLenum pname,
GLfloat param )
void glMateriali( GLenum face,
GLenum pname,
GLint param )

PARAMETERS
face Specifies which face or faces are being updated.
Must be one of GL_FRONT, GL_BACK, or
GL_FRONT_AND_BACK.

pname Specifies the single-valued material parameter of
the face or faces that is being updated. Must be
GL_SHININESS.

param Specifies the value that parameter GL_SHININESS
will be set to.

C SPECIFICATION
void glMaterialfv( GLenum face,
GLenum pname,
const GLfloat *params )
void glMaterialiv( GLenum face,
GLenum pname,
const GLint *params )

PARAMETERS
face Specifies which face or faces are being updated.
Must be one of GL_FRONT, GL_BACK, or
GL_FRONT_AND_BACK.

pname Specifies the material parameter of the face or
faces that is being updated. Must be one of
GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, GL_EMISSION,
GL_SHININESS, GL_AMBIENT_AND_DIFFUSE, or
GL_COLOR_INDEXES.

params Specifies a pointer to the value or values that
pname will be set to.

DESCRIPTION
glMaterial assigns values to material parameters. There
are two matched sets of material parameters. One, the
front-facing set, is used to shade points, lines, bitmaps,
and all polygons (when two-sided lighting is disabled), or
just front-facing polygons (when two-sided lighting is
enabled). The other set, back-facing, is used to shade
back-facing polygons only when two-sided lighting is
enabled. Refer to the glLightModel reference page for
details concerning one- and two-sided lighting calcula-
tions.

glMaterial takes three arguments. The first, face, speci-
fies whether the GL_FRONT materials, the GL_BACK materi-
als, or both GL_FRONT_AND_BACK materials will be modified.
The second, pname, specifies which of several parameters
in one or both sets will be modified. The third, params,
specifies what value or values will be assigned to the
specified parameter.

Material parameters are used in the lighting equation that
is optionally applied to each vertex. The equation is
discussed in the glLightModel reference page. The parame-
ters that can be specified using glMaterial, and their
interpretations by the lighting equation, are as follows:

GL_AMBIENT params contains four integer or float-
ing-point values that specify the
ambient RGBA reflectance of the mate-
rial. Integer values are mapped lin-
early such that the most positive rep-
resentable value maps to 1.0, and the
most negative representable value maps
to -1.0. Floating-point values are
mapped directly. Neither integer nor
floating-point values are clamped.
The initial ambient reflectance for
both front- and back-facing materials
is (0.2, 0.2, 0.2, 1.0).

GL_DIFFUSE params contains four integer or float-
ing-point values that specify the dif-
fuse RGBA reflectance of the material.
Integer values are mapped linearly
such that the most positive repre-
sentable value maps to 1.0, and the
most negative representable value maps
to -1.0. Floating-point values are
mapped directly. Neither integer nor
floating-point values are clamped.
The initial diffuse reflectance for
both front- and back-facing materials
is (0.8, 0.8, 0.8, 1.0).

GL_SPECULAR params contains four integer or float-
ing-point values that specify the
specular RGBA reflectance of the mate-
rial. Integer values are mapped lin-
early such that the most positive rep-
resentable value maps to 1.0, and the
most negative representable value maps
to -1.0. Floating-point values are
mapped directly. Neither integer nor
floating-point values are clamped.
The initial specular reflectance for
both front- and back-facing materials
is (0, 0, 0, 1).

GL_EMISSION params contains four integer or float-
ing-point values that specify the RGBA
emitted light intensity of the mate-
rial. Integer values are mapped lin-
early such that the most positive rep-
resentable value maps to 1.0, and the
most negative representable value maps
to -1.0. Floating-point values are
mapped directly. Neither integer nor
floating-point values are clamped.
The initial emission intensity for
both front- and back-facing materials
is (0, 0, 0, 1).

GL_SHININESS params is a single integer or float-
ing-point value that specifies the
RGBA specular exponent of the mate-
rial. Integer and floating-point val-
ues are mapped directly. Only values
in the range [0,128] are accepted.
The initial specular exponent for both
front- and back-facing materials is 0.

GL_AMBIENT_AND_DIFFUSE
Equivalent to calling glMaterial twice
with the same parameter values, once
with GL_AMBIENT and once with
GL_DIFFUSE.

GL_COLOR_INDEXES params contains three integer or
floating-point values specifying the
color indices for ambient, diffuse,
and specular lighting. These three
values, and GL_SHININESS, are the only
material values used by the color
index mode lighting equation. Refer
to the glLightModel reference page for
a discussion of color index lighting.

NOTES
The material parameters can be updated at any time. In
particular, glMaterial can be called between a call to
glBegin and the corresponding call to glEnd. If only a
single material parameter is to be changed per vertex,
however, glColorMaterial is preferred over glMaterial (see
glColorMaterial).

ERRORS
GL_INVALID_ENUM is generated if either face or pname is
not an accepted value.

GL_INVALID_VALUE is generated if a specular exponent out-
side the range [0,128] is specified.

ASSOCIATED GETS
glGetMaterial

SEE ALSO
glColorMaterial, glLight, glLightModel

MachTen 3