<?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>
