[clinton/guile-figl.git] / upstream-doc / man2 / glGetMaterial.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="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>
Commit	Line	Data
7faf1d71 AW	1	<?xml version="1.0" encoding="UTF-8"?>
	2	<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
	3	"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
	4	<refentry id="glGetMaterial">
	5	<refmeta>
	6	<refmetainfo>
	7	<copyright>
	8	<year>1991-2006</year>
	9	<holder>Silicon Graphics, Inc.</holder>
	10	</copyright>
	11	</refmetainfo>
	12	<refentrytitle>glGetMaterial</refentrytitle>
	13	<manvolnum>3G</manvolnum>
	14	</refmeta>
	15	<refnamediv>
	16	<refname>glGetMaterial</refname>
	17	<refpurpose>return material parameters</refpurpose>
	18	</refnamediv>
	19	<refsynopsisdiv><title>C Specification</title>
	20	<funcsynopsis>
	21	<funcprototype>
	22	<funcdef>void <function>glGetMaterialfv</function></funcdef>
	23	<paramdef>GLenum <parameter>face</parameter></paramdef>
	24	<paramdef>GLenum <parameter>pname</parameter></paramdef>
	25	<paramdef>GLfloat * <parameter>params</parameter></paramdef>
	26	</funcprototype>
	27	</funcsynopsis>
	28	<funcsynopsis>
	29	<funcprototype>
	30	<funcdef>void <function>glGetMaterialiv</function></funcdef>
	31	<paramdef>GLenum <parameter>face</parameter></paramdef>
	32	<paramdef>GLenum <parameter>pname</parameter></paramdef>
	33	<paramdef>GLint * <parameter>params</parameter></paramdef>
	34	</funcprototype>
	35	</funcsynopsis>
	36	</refsynopsisdiv>
	37	<!-- eqn: ignoring delim $$ -->
	38	<refsect1 id="parameters"><title>Parameters</title>
	39	<variablelist>
	40	<varlistentry>
	41	<term><parameter>face</parameter></term>
	42	<listitem>
	43	<para>
	44	Specifies which of the two materials is being queried.
	45	<constant>GL_FRONT</constant> or <constant>GL_BACK</constant> are accepted,
	46	representing the front and back materials,
	47	respectively.
	48	</para>
	49	</listitem>
	50	</varlistentry>
	51	<varlistentry>
	52	<term><parameter>pname</parameter></term>
	53	<listitem>
	54	<para>
	55	Specifies the material parameter to return.
	56	<constant>GL_AMBIENT</constant>,
	57	<constant>GL_DIFFUSE</constant>,
	58	<constant>GL_SPECULAR</constant>,
	59	<constant>GL_EMISSION</constant>,
	60	<constant>GL_SHININESS</constant>, and
	61	<constant>GL_COLOR_INDEXES</constant>
	62	are accepted.
	63	</para>
	64	</listitem>
65	</varlistentry>
66	<varlistentry>
67	<term><parameter>params</parameter></term>
68	<listitem>
69	<para>
70	Returns the requested data.
71	</para>
72	</listitem>
73	</varlistentry>
74	</variablelist>
75	</refsect1>
76	<refsect1 id="description"><title>Description</title>
77	<para>
78	<function>glGetMaterial</function> returns in <parameter>params</parameter> the value or values of parameter <parameter>pname</parameter>
79	of material <parameter>face</parameter>. Six parameters are defined:
80	</para>
81	<variablelist>
82	<varlistentry>
83	<term><constant>GL_AMBIENT</constant></term>
84	<listitem>
85	<para>
86	<parameter>params</parameter> returns four integer or floating-point values representing the
87	ambient reflectance of the material.
88	Integer values,
89	when requested,
90	are linearly mapped from the internal floating-point representation
91	such that 1.0 maps to the most positive representable integer value,
92	and
93	<inlineequation><mml:math>
94	<!-- eqn: -1.0:-->
95	<mml:mn>-1.0</mml:mn>
96	</mml:math></inlineequation>
97	maps to the most negative representable integer value.
98	If the internal value is outside the range
99	<inlineequation><mml:math>
100	<!-- eqn: [-1,1]:-->
101	<mml:mfenced open="[" close="]">
102	<mml:mn>-1</mml:mn>
103	<mml:mn>1</mml:mn>
104	</mml:mfenced>
105	</mml:math></inlineequation>,
106	the corresponding integer return value is undefined. The initial value is
107	(0.2, 0.2, 0.2, 1.0)
108	</para>
109	</listitem>
110	</varlistentry>
111	<varlistentry>
112	<term><constant>GL_DIFFUSE</constant></term>
113	<listitem>
114	<para>
115	<parameter>params</parameter> returns four integer or floating-point values representing the
116	diffuse reflectance of the material.
117	Integer values,
118	when requested,
119	are linearly mapped from the internal floating-point representation
120	such that 1.0 maps to the most positive representable integer value,
121	and
122	<inlineequation><mml:math>
123	<!-- eqn: -1.0:-->
124	<mml:mn>-1.0</mml:mn>
125	</mml:math></inlineequation>
126	maps to the most negative representable integer value.
127	If the internal value is outside the range
128	<inlineequation><mml:math>
129	<!-- eqn: [-1,1]:-->
130	<mml:mfenced open="[" close="]">
131	<mml:mn>-1</mml:mn>
132	<mml:mn>1</mml:mn>
133	</mml:mfenced>
134	</mml:math></inlineequation>,
135	the corresponding integer return value is undefined. The initial value is
136	(0.8, 0.8, 0.8, 1.0).
137	</para>
138	</listitem>
139	</varlistentry>
140	<varlistentry>
141	<term><constant>GL_SPECULAR</constant></term>
142	<listitem>
143	<para>
144	<parameter>params</parameter> returns four integer or floating-point values representing the
145	specular reflectance of the material.
146	Integer values,
147	when requested,
148	are linearly mapped from the internal floating-point representation
149	such that 1.0 maps to the most positive representable integer value,
150	and
151	<inlineequation><mml:math>
152	<!-- eqn: -1.0:-->
153	<mml:mn>-1.0</mml:mn>
154	</mml:math></inlineequation>
155	maps to the most negative representable integer value.
156	If the internal value is outside the range
157	<inlineequation><mml:math>
158	<!-- eqn: [-1,1]:-->
159	<mml:mfenced open="[" close="]">
160	<mml:mn>-1</mml:mn>
161	<mml:mn>1</mml:mn>
162	</mml:mfenced>
163	</mml:math></inlineequation>,
164	the corresponding integer return value is undefined. The initial value is
165	(0, 0, 0, 1).
166	</para>
167	</listitem>
168	</varlistentry>
169	<varlistentry>
170	<term><constant>GL_EMISSION</constant></term>
171	<listitem>
172	<para>
173	<parameter>params</parameter> returns four integer or floating-point values representing the
174	emitted light intensity of the material.
175	Integer values,
176	when requested,
177	are linearly mapped from the internal floating-point representation
178	such that 1.0 maps to the most positive representable integer value,
179	and
180	<inlineequation><mml:math>
181	<!-- eqn: -1.0:-->
182	<mml:mn>-1.0</mml:mn>
183	</mml:math></inlineequation>
184	maps to the most negative representable integer value.
185	If the internal value is outside the range
186	<inlineequation><mml:math>
187	<!-- eqn: [-1,1]:-->
188	<mml:mfenced open="[" close="]">
189	<mml:mn>-1</mml:mn>
190	<mml:mn>1</mml:mn>
191	</mml:mfenced>
192	</mml:math></inlineequation>,
193	the corresponding integer return value is undefined. The initial value is
194	(0, 0, 0, 1).
195	</para>
196	</listitem>
197	</varlistentry>
198	<varlistentry>
199	<term><constant>GL_SHININESS</constant></term>
200	<listitem>
201	<para>
202	<parameter>params</parameter> returns one integer or floating-point value representing the
203	specular exponent of the material.
204	Integer values,
205	when requested,
206	are computed by rounding the internal floating-point value to the
207	nearest integer value. The initial value is 0.
208	</para>
209	</listitem>
210	</varlistentry>
211	<varlistentry>
212	<term><constant>GL_COLOR_INDEXES</constant></term>
213	<listitem>
214	<para>
215	<parameter>params</parameter> returns three integer or floating-point values representing the
216	ambient, diffuse, and specular indices of the material.
217	These indices are used only for color index lighting.
218	(All the other parameters are used only for RGBA lighting.)
219	Integer values,
220	when requested,
221	are computed by rounding the internal floating-point values to the
222	nearest integer values.
223	</para>
224	</listitem>
225	</varlistentry>
226	</variablelist>
227	</refsect1>
228	<refsect1 id="notes"><title>Notes</title>
229	<para>
230	If an error is generated,
231	no change is made to the contents of <parameter>params</parameter>.
232	</para>
233	</refsect1>
234	<refsect1 id="errors"><title>Errors</title>
235	<para>
236	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>face</parameter> or <parameter>pname</parameter> is not an
237	accepted value.
238	</para>
239	<para>
240	<constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetMaterial</function>
241	is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
242	and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
243	</para>
244	</refsect1>
245	<refsect1 id="seealso"><title>See Also</title>
246	<para>
247	<citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>
248	</para>
249	</refsect1>
250	<refsect1 id="Copyright"><title>Copyright</title>
251	<para>
252	Copyright <trademark class="copyright"></trademark> 1991-2006
253	Silicon Graphics, Inc. This document is licensed under the SGI
254	Free Software B License. For details, see
255	<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
256	</para>
257	</refsect1>
258	</refentry>