353 lines
17 KiB
XML
353 lines
17 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
|
|
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
|
|
<refentry id="glMaterial">
|
|
<refmeta>
|
|
<refmetainfo>
|
|
<copyright>
|
|
<year>1991-2006</year>
|
|
<holder>Silicon Graphics, Inc.</holder>
|
|
</copyright>
|
|
</refmetainfo>
|
|
<refentrytitle>glMaterial</refentrytitle>
|
|
<manvolnum>3G</manvolnum>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname>glMaterial</refname>
|
|
<refpurpose>specify material parameters for the lighting model</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv><title>C Specification</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>glMaterialf</function></funcdef>
|
|
<paramdef>GLenum <parameter>face</parameter></paramdef>
|
|
<paramdef>GLenum <parameter>pname</parameter></paramdef>
|
|
<paramdef>GLfloat <parameter>param</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>glMateriali</function></funcdef>
|
|
<paramdef>GLenum <parameter>face</parameter></paramdef>
|
|
<paramdef>GLenum <parameter>pname</parameter></paramdef>
|
|
<paramdef>GLint <parameter>param</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsect1 id="parameters"><title>Parameters</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>face</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies which face or faces are being updated.
|
|
Must be one of
|
|
<constant>GL_FRONT</constant>,
|
|
<constant>GL_BACK</constant>, or
|
|
<constant>GL_FRONT_AND_BACK</constant>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>pname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the single-valued material parameter of the face or faces
|
|
that is being updated.
|
|
Must be <constant>GL_SHININESS</constant>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>param</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the value that parameter <constant>GL_SHININESS</constant> will be set to.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsynopsisdiv><title>C Specification</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>glMaterialfv</function></funcdef>
|
|
<paramdef>GLenum <parameter>face</parameter></paramdef>
|
|
<paramdef>GLenum <parameter>pname</parameter></paramdef>
|
|
<paramdef>const GLfloat * <parameter>params</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>glMaterialiv</function></funcdef>
|
|
<paramdef>GLenum <parameter>face</parameter></paramdef>
|
|
<paramdef>GLenum <parameter>pname</parameter></paramdef>
|
|
<paramdef>const GLint * <parameter>params</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsect1 id="parameters2"><title>Parameters</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>face</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies which face or faces are being updated.
|
|
Must be one of
|
|
<constant>GL_FRONT</constant>,
|
|
<constant>GL_BACK</constant>, or
|
|
<constant>GL_FRONT_AND_BACK</constant>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>pname</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the material parameter of the face or faces that is being updated.
|
|
Must be one of
|
|
<constant>GL_AMBIENT</constant>,
|
|
<constant>GL_DIFFUSE</constant>,
|
|
<constant>GL_SPECULAR</constant>,
|
|
<constant>GL_EMISSION</constant>,
|
|
<constant>GL_SHININESS</constant>,
|
|
<constant>GL_AMBIENT_AND_DIFFUSE</constant>, or
|
|
<constant>GL_COLOR_INDEXES</constant>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>params</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a pointer to the value or values that <parameter>pname</parameter> will be set to.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1 id="description"><title>Description</title>
|
|
<para>
|
|
<function>glMaterial</function> assigns values to material parameters.
|
|
There are two matched sets of material parameters.
|
|
One,
|
|
the <emphasis>front-facing</emphasis> 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,
|
|
<emphasis>back-facing</emphasis>,
|
|
is used to shade back-facing polygons only when two-sided lighting is enabled.
|
|
Refer to the <citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry> reference page for details concerning one- and
|
|
two-sided lighting calculations.
|
|
</para>
|
|
<para>
|
|
<function>glMaterial</function> takes three arguments.
|
|
The first,
|
|
<parameter>face</parameter>,
|
|
specifies whether the
|
|
<constant>GL_FRONT</constant> materials, the
|
|
<constant>GL_BACK</constant> materials, or both
|
|
<constant>GL_FRONT_AND_BACK</constant> materials will be modified.
|
|
The second,
|
|
<parameter>pname</parameter>,
|
|
specifies which of several parameters in one or both sets will be modified.
|
|
The third,
|
|
<parameter>params</parameter>,
|
|
specifies what value or values will be assigned to the specified parameter.
|
|
</para>
|
|
<para>
|
|
Material parameters are used in the lighting equation that is optionally
|
|
applied to each vertex.
|
|
The equation is discussed in the <citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry> reference page.
|
|
The parameters that can be specified using <function>glMaterial</function>,
|
|
and their interpretations by the lighting equation, are as follows:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><constant>GL_AMBIENT</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> 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
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: -1.0:-->
|
|
<mml:mn>-1.0</mml:mn>
|
|
</mml:math></inlineequation>.
|
|
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).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_DIFFUSE</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> 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
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: -1.0:-->
|
|
<mml:mn>-1.0</mml:mn>
|
|
</mml:math></inlineequation>.
|
|
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).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_SPECULAR</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> 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
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: -1.0:-->
|
|
<mml:mn>-1.0</mml:mn>
|
|
</mml:math></inlineequation>.
|
|
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).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_EMISSION</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> 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
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: -1.0:-->
|
|
<mml:mn>-1.0</mml:mn>
|
|
</mml:math></inlineequation>.
|
|
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).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_SHININESS</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> 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
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: [0,128]:-->
|
|
<mml:mfenced open="[" close="]">
|
|
<mml:mn>0</mml:mn>
|
|
<mml:mn>128</mml:mn>
|
|
</mml:mfenced>
|
|
</mml:math></inlineequation>
|
|
are accepted.
|
|
The initial specular exponent for both front- and back-facing materials
|
|
is 0.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_AMBIENT_AND_DIFFUSE</constant></term>
|
|
<listitem>
|
|
<para>
|
|
Equivalent to calling <function>glMaterial</function> twice with the same parameter values,
|
|
once with <constant>GL_AMBIENT</constant> and once with <constant>GL_DIFFUSE</constant>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><constant>GL_COLOR_INDEXES</constant></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>params</parameter> contains three integer or floating-point values specifying
|
|
the color indices for ambient,
|
|
diffuse,
|
|
and specular lighting.
|
|
These three values,
|
|
and <constant>GL_SHININESS</constant>,
|
|
are the only material values used by the color index mode lighting equation.
|
|
Refer to the <citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry> reference page for a discussion
|
|
of color index lighting.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1 id="notes"><title>Notes</title>
|
|
<para>
|
|
The material parameters can be updated at any time.
|
|
In particular,
|
|
<function>glMaterial</function> can be called between a call to <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
|
|
call to <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
|
|
If only a single material parameter is to be changed per vertex,
|
|
however,
|
|
<citerefentry><refentrytitle>glColorMaterial</refentrytitle></citerefentry> is preferred over <function>glMaterial</function>
|
|
(see <citerefentry><refentrytitle>glColorMaterial</refentrytitle></citerefentry>).
|
|
</para>
|
|
<para>
|
|
While the ambient, diffuse, specular and emission material parameters
|
|
all have alpha components, only the diffuse alpha component is used in
|
|
the lighting computation.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="errors"><title>Errors</title>
|
|
<para>
|
|
<constant>GL_INVALID_ENUM</constant> is generated if either <parameter>face</parameter> or <parameter>pname</parameter> is not
|
|
an accepted value.
|
|
</para>
|
|
<para>
|
|
<constant>GL_INVALID_VALUE</constant> is generated if a specular exponent outside the range
|
|
<inlineequation><mml:math>
|
|
<!-- eqn: [0,128]:-->
|
|
<mml:mfenced open="[" close="]">
|
|
<mml:mn>0</mml:mn>
|
|
<mml:mn>128</mml:mn>
|
|
</mml:mfenced>
|
|
</mml:math></inlineequation>
|
|
is specified.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="associatedgets"><title>Associated Gets</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>glGetMaterial</refentrytitle></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="seealso"><title>See Also</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>glColorMaterial</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glLight</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="Copyright"><title>Copyright</title>
|
|
<para>
|
|
Copyright <trademark class="copyright"></trademark> 1991-2006
|
|
Silicon Graphics, Inc. This document is licensed under the SGI
|
|
Free Software B License. For details, see
|
|
<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|