Blame |
Last modification |
View Log
| RSS feed
<?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="glGetMaterial">
<refmeta>
<refmetainfo>
<copyright>
<year>1991-2006</year>
<holder>Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
<refentrytitle>glGetMaterial</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glGetMaterial</refname>
<refpurpose>return material parameters</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glGetMaterialfv</function></funcdef>
<paramdef>GLenum <parameter>face</parameter></paramdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>GLfloat * <parameter>params</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glGetMaterialiv</function></funcdef>
<paramdef>GLenum <parameter>face</parameter></paramdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>GLint * <parameter>params</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- eqn: ignoring delim $$ -->
<refsect1 id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>face</parameter></term>
<listitem>
<para>
Specifies which of the two materials is being queried.
<constant>GL_FRONT</constant> or <constant>GL_BACK</constant> are accepted,
representing the front and back materials,
respectively.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pname</parameter></term>
<listitem>
<para>
Specifies the material parameter to return.
<constant>GL_AMBIENT</constant>,
<constant>GL_DIFFUSE</constant>,
<constant>GL_SPECULAR</constant>,
<constant>GL_EMISSION</constant>,
<constant>GL_SHININESS</constant>, and
<constant>GL_COLOR_INDEXES</constant>
are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>params</parameter></term>
<listitem>
<para>
Returns the requested data.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="description"><title>Description</title>
<para>
<function>glGetMaterial</function> returns in <parameter>params</parameter> the value or values of parameter <parameter>pname</parameter>
of material <parameter>face</parameter>. Six parameters are defined:
</para>
<variablelist>
<varlistentry>
<term><constant>GL_AMBIENT</constant></term>
<listitem>
<para>
<parameter>params</parameter> returns four integer or floating-point values representing the
ambient reflectance of the material.
Integer values,
when requested,
are linearly mapped from the internal floating-point representation
such that 1.0 maps to the most positive representable integer value,
and
<inlineequation><mml:math>
<!-- eqn: -1.0:-->
<mml:mn>-1.0</mml:mn>
</mml:math></inlineequation>
maps to the most negative representable integer value.
If the internal value is outside the range
<inlineequation><mml:math>
<!-- eqn: [-1,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>-1</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>,
the corresponding integer return value is undefined. The initial value is
(0.2, 0.2, 0.2, 1.0)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_DIFFUSE</constant></term>
<listitem>
<para>
<parameter>params</parameter> returns four integer or floating-point values representing the
diffuse reflectance of the material.
Integer values,
when requested,
are linearly mapped from the internal floating-point representation
such that 1.0 maps to the most positive representable integer value,
and
<inlineequation><mml:math>
<!-- eqn: -1.0:-->
<mml:mn>-1.0</mml:mn>
</mml:math></inlineequation>
maps to the most negative representable integer value.
If the internal value is outside the range
<inlineequation><mml:math>
<!-- eqn: [-1,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>-1</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>,
the corresponding integer return value is undefined. The initial value is
(0.8, 0.8, 0.8, 1.0).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_SPECULAR</constant></term>
<listitem>
<para>
<parameter>params</parameter> returns four integer or floating-point values representing the
specular reflectance of the material.
Integer values,
when requested,
are linearly mapped from the internal floating-point representation
such that 1.0 maps to the most positive representable integer value,
and
<inlineequation><mml:math>
<!-- eqn: -1.0:-->
<mml:mn>-1.0</mml:mn>
</mml:math></inlineequation>
maps to the most negative representable integer value.
If the internal value is outside the range
<inlineequation><mml:math>
<!-- eqn: [-1,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>-1</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>,
the corresponding integer return value is undefined. The initial value is
(0, 0, 0, 1).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_EMISSION</constant></term>
<listitem>
<para>
<parameter>params</parameter> returns four integer or floating-point values representing the
emitted light intensity of the material.
Integer values,
when requested,
are linearly mapped from the internal floating-point representation
such that 1.0 maps to the most positive representable integer value,
and
<inlineequation><mml:math>
<!-- eqn: -1.0:-->
<mml:mn>-1.0</mml:mn>
</mml:math></inlineequation>
maps to the most negative representable integer value.
If the internal value is outside the range
<inlineequation><mml:math>
<!-- eqn: [-1,1]:-->
<mml:mfenced open="[" close="]">
<mml:mn>-1</mml:mn>
<mml:mn>1</mml:mn>
</mml:mfenced>
</mml:math></inlineequation>,
the corresponding integer return value is undefined. The initial value is
(0, 0, 0, 1).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_SHININESS</constant></term>
<listitem>
<para>
<parameter>params</parameter> returns one integer or floating-point value representing the
specular exponent of the material.
Integer values,
when requested,
are computed by rounding the internal floating-point value to the
nearest integer value. The initial value is 0.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>GL_COLOR_INDEXES</constant></term>
<listitem>
<para>
<parameter>params</parameter> returns three integer or floating-point values representing the
ambient, diffuse, and specular indices of the material.
These indices are used only for color index lighting.
(All the other parameters are used only for RGBA lighting.)
Integer values,
when requested,
are computed by rounding the internal floating-point values to the
nearest integer values.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="notes"><title>Notes</title>
<para>
If an error is generated,
no change is made to the contents of <parameter>params</parameter>.
</para>
</refsect1>
<refsect1 id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated if <parameter>face</parameter> or <parameter>pname</parameter> is not an
accepted value.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetMaterial</function>
is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
</para>
</refsect1>
<refsect1 id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glMaterial</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>