214 lines
6.6 KiB
Plaintext
214 lines
6.6 KiB
Plaintext
'\" e
|
|
'\"! eqn | mmdoc
|
|
'\"macro stdmacro
|
|
.ds Vn Version 1.2
|
|
.ds Dt 24 September 1999
|
|
.ds Re Release 1.2.1
|
|
.ds Dp Jan 14 18:30
|
|
.ds Dm 01 material.
|
|
.ds Xs 18013 8 material.gl
|
|
.TH GLMATERIAL 3G
|
|
.SH NAME
|
|
.B "glMaterialf, glMateriali, glMaterialfv, glMaterialiv
|
|
\- specify material parameters for the lighting model
|
|
|
|
.SH C SPECIFICATION
|
|
void \f3glMaterialf\fP(
|
|
GLenum \fIface\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglMaterialf( 'u
|
|
GLenum \fIpname\fP,
|
|
GLfloat \fIparam\fP )
|
|
.fi
|
|
void \f3glMateriali\fP(
|
|
GLenum \fIface\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglMateriali( 'u
|
|
GLenum \fIpname\fP,
|
|
GLint \fIparam\fP )
|
|
.fi
|
|
|
|
.SH PARAMETERS
|
|
.TP \w'\fIparams\fP\ \ 'u
|
|
\f2face\fP
|
|
Specifies which face or faces are being updated.
|
|
Must be one of
|
|
\%\f3GL_FRONT\fP,
|
|
\%\f3GL_BACK\fP, or
|
|
\%\f3GL_FRONT_AND_BACK\fP.
|
|
.TP
|
|
\f2pname\fP
|
|
Specifies the single-valued material parameter of the face or faces
|
|
that is being updated.
|
|
Must be \%\f3GL_SHININESS\fP.
|
|
.TP
|
|
\f2param\fP
|
|
Specifies the value that parameter \%\f3GL_SHININESS\fP will be set to.
|
|
.SH C SPECIFICATION
|
|
void \f3glMaterialfv\fP(
|
|
GLenum \fIface\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglMaterialfv( 'u
|
|
GLenum \fIpname\fP,
|
|
const GLfloat \fI*params\fP )
|
|
.fi
|
|
void \f3glMaterialiv\fP(
|
|
GLenum \fIface\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglMaterialiv( 'u
|
|
GLenum \fIpname\fP,
|
|
const GLint \fI*params\fP )
|
|
.fi
|
|
|
|
.SH PARAMETERS
|
|
.TP
|
|
\f2face\fP
|
|
Specifies which face or faces are being updated.
|
|
Must be one of
|
|
\%\f3GL_FRONT\fP,
|
|
\%\f3GL_BACK\fP, or
|
|
\%\f3GL_FRONT_AND_BACK\fP.
|
|
.TP
|
|
\f2pname\fP
|
|
Specifies the material parameter of the face or faces that is being updated.
|
|
Must be one of
|
|
\%\f3GL_AMBIENT\fP,
|
|
\%\f3GL_DIFFUSE\fP,
|
|
\%\f3GL_SPECULAR\fP,
|
|
\%\f3GL_EMISSION\fP,
|
|
\%\f3GL_SHININESS\fP,
|
|
\%\f3GL_AMBIENT_AND_DIFFUSE\fP, or
|
|
\%\f3GL_COLOR_INDEXES\fP.
|
|
.TP
|
|
\f2params\fP
|
|
Specifies a pointer to the value or values that \f2pname\fP will be set to.
|
|
.SH DESCRIPTION
|
|
\%\f3glMaterial\fP assigns values to material parameters.
|
|
There are two matched sets of material parameters.
|
|
One,
|
|
the \f2front-facing\fP 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,
|
|
\f2back-facing\fP,
|
|
is used to shade back-facing polygons only when two-sided lighting is enabled.
|
|
Refer to the \%\f3glLightModel\fP reference page for details concerning one- and
|
|
two-sided lighting calculations.
|
|
.P
|
|
\%\f3glMaterial\fP takes three arguments.
|
|
The first,
|
|
\f2face\fP,
|
|
specifies whether the
|
|
\%\f3GL_FRONT\fP materials, the
|
|
\%\f3GL_BACK\fP materials, or both
|
|
\%\f3GL_FRONT_AND_BACK\fP materials will be modified.
|
|
The second,
|
|
\f2pname\fP,
|
|
specifies which of several parameters in one or both sets will be modified.
|
|
The third,
|
|
\f2params\fP,
|
|
specifies what value or values will be assigned to the specified parameter.
|
|
.P
|
|
Material parameters are used in the lighting equation that is optionally
|
|
applied to each vertex.
|
|
The equation is discussed in the \%\f3glLightModel\fP reference page.
|
|
The parameters that can be specified using \%\f3glMaterial\fP,
|
|
and their interpretations by the lighting equation, are as follows:
|
|
.TP 20
|
|
\%\f3GL_AMBIENT\fP
|
|
\f2params\fP contains four integer or floating-point values that specify
|
|
the ambient RGBA reflectance of the material.
|
|
Integer values are mapped linearly such that the most positive representable
|
|
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).
|
|
.TP
|
|
\%\f3GL_DIFFUSE\fP
|
|
\f2params\fP contains four integer or floating-point values that specify
|
|
the diffuse RGBA reflectance of the material.
|
|
Integer values are mapped linearly such that the most positive representable
|
|
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).
|
|
.TP
|
|
\%\f3GL_SPECULAR\fP
|
|
\f2params\fP contains four integer or floating-point values that specify
|
|
the specular RGBA reflectance of the material.
|
|
Integer values are mapped linearly such that the most positive representable
|
|
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).
|
|
.TP
|
|
\%\f3GL_EMISSION\fP
|
|
\f2params\fP contains four integer or floating-point values that specify
|
|
the RGBA emitted light intensity of the material.
|
|
Integer values are mapped linearly such that the most positive representable
|
|
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).
|
|
.TP
|
|
\%\f3GL_SHININESS\fP
|
|
\f2params\fP is a single integer or floating-point value that specifies
|
|
the RGBA specular exponent of the material.
|
|
Integer and floating-point values 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.
|
|
.TP
|
|
\%\f3GL_AMBIENT_AND_DIFFUSE\fP
|
|
Equivalent to calling \%\f3glMaterial\fP twice with the same parameter values,
|
|
once with \%\f3GL_AMBIENT\fP and once with \%\f3GL_DIFFUSE\fP.
|
|
.TP
|
|
\%\f3GL_COLOR_INDEXES\fP
|
|
\f2params\fP contains three integer or floating-point values specifying
|
|
the color indices for ambient,
|
|
diffuse,
|
|
and specular lighting.
|
|
These three values,
|
|
and \%\f3GL_SHININESS\fP,
|
|
are the only material values used by the color index mode lighting equation.
|
|
Refer to the \%\f3glLightModel\fP reference page for a discussion
|
|
of color index lighting.
|
|
.SH NOTES
|
|
The material parameters can be updated at any time.
|
|
In particular,
|
|
\%\f3glMaterial\fP can be called between a call to \%\f3glBegin\fP and the corresponding
|
|
call to \%\f3glEnd\fP.
|
|
If only a single material parameter is to be changed per vertex,
|
|
however,
|
|
\%\f3glColorMaterial\fP is preferred over \%\f3glMaterial\fP
|
|
(see \%\f3glColorMaterial\fP).
|
|
.P
|
|
While the ambient, diffuse, specular and emission material parameters
|
|
all have alpha components, only the diffuse alpha component is used in
|
|
the lighting computation.
|
|
.SH ERRORS
|
|
\%\f3GL_INVALID_ENUM\fP is generated if either \f2face\fP or \f2pname\fP is not
|
|
an accepted value.
|
|
.P
|
|
\%\f3GL_INVALID_VALUE\fP is generated if a specular exponent outside the range
|
|
[0,128] is specified.
|
|
.SH ASSOCIATED GETS
|
|
\%\f3glGetMaterial\fP
|
|
.SH SEE ALSO
|
|
\%\f3glColorMaterial(3G)\fP,
|
|
\%\f3glLight(3G)\fP,
|
|
\%\f3glLightModel(3G)\fP
|