[clinton/guile-figl.git] / upstream-doc / man2 / glGetMap.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="glGetMap">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glGetMap</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glGetMap</refname>
        <refpurpose>return evaluator parameters</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glGetMapdv</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLenum <parameter>query</parameter></paramdef>
                <paramdef>GLdouble * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glGetMapfv</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLenum <parameter>query</parameter></paramdef>
                <paramdef>GLfloat * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glGetMapiv</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLenum <parameter>query</parameter></paramdef>
                <paramdef>GLint * <parameter>v</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <!-- eqn: ignoring delim $$ -->
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>target</parameter></term>
            <listitem>
                <para>
                    Specifies the symbolic name of a map.
                    Accepted values are
                    <constant>GL_MAP1_COLOR_4</constant>,
                    <constant>GL_MAP1_INDEX</constant>,
                    <constant>GL_MAP1_NORMAL</constant>,
                    <constant>GL_MAP1_TEXTURE_COORD_1</constant>,
                    <constant>GL_MAP1_TEXTURE_COORD_2</constant>,
                    <constant>GL_MAP1_TEXTURE_COORD_3</constant>,
                    <constant>GL_MAP1_TEXTURE_COORD_4</constant>,
                    <constant>GL_MAP1_VERTEX_3</constant>,
                    <constant>GL_MAP1_VERTEX_4</constant>,
                    <constant>GL_MAP2_COLOR_4</constant>,
                    <constant>GL_MAP2_INDEX</constant>,
                    <constant>GL_MAP2_NORMAL</constant>,
                    <constant>GL_MAP2_TEXTURE_COORD_1</constant>,
                    <constant>GL_MAP2_TEXTURE_COORD_2</constant>,
                    <constant>GL_MAP2_TEXTURE_COORD_3</constant>,
                    <constant>GL_MAP2_TEXTURE_COORD_4</constant>,
                    <constant>GL_MAP2_VERTEX_3</constant>, and
                    <constant>GL_MAP2_VERTEX_4</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>query</parameter></term>
            <listitem>
                <para>
                    Specifies which parameter to return.
                    Symbolic names
                    <constant>GL_COEFF</constant>,
                    <constant>GL_ORDER</constant>, and
                    <constant>GL_DOMAIN</constant> are accepted.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>v</parameter></term>
            <listitem>
                <para>
                    Returns the requested data.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry> define evaluators.
            <function>glGetMap</function> returns evaluator parameters.
            <parameter>target</parameter> chooses a map,
            <parameter>query</parameter> selects a specific parameter,
            and <parameter>v</parameter> points to storage where the values will be returned.
        </para>
        <para>
            The acceptable values for the <parameter>target</parameter> parameter are described
            in the <citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry> reference pages.
        </para>
        <para>
            <parameter>query</parameter> can assume the following values:
        </para>
        <variablelist>
            <varlistentry>
                <term><constant>GL_COEFF</constant></term>
                <listitem>
                    <para>
                        <parameter>v</parameter> returns the control points for the evaluator function.
                        One-dimensional evaluators return 
                        <inlineequation><mml:math><mml:mi mathvariant="italic">order</mml:mi></mml:math></inlineequation>
                        control points,
                        and two-dimensional evaluators return 
                        <inlineequation><mml:math>
                            <!-- eqn: uorder  times  vorder:-->
                            <mml:mrow>
                                <mml:mi mathvariant="italic">uorder</mml:mi>
                                <mml:mo>&times;</mml:mo>
                                <mml:mi mathvariant="italic">vorder</mml:mi>
                            </mml:mrow>
                        </mml:math></inlineequation>
                        control points.
                        Each control point consists of one, two, three, or four integer,
                        single-precision floating-point,
                        or double-precision floating-point values,
                        depending on the type of the evaluator.
                        The GL returns two-dimensional control points in row-major order,
                        incrementing the 
                        <inlineequation><mml:math><mml:mi mathvariant="italic">uorder</mml:mi></mml:math></inlineequation>
                        index quickly
                        and the 
                        <inlineequation><mml:math><mml:mi mathvariant="italic">vorder</mml:mi></mml:math></inlineequation>
                        index after each row.
                        Integer values,
                        when requested,
                        are computed by rounding the internal floating-point values to the
                        nearest integer values.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GL_ORDER</constant></term>
                <listitem>
                    <para>
                        <parameter>v</parameter> returns the order of the evaluator function.
                        One-dimensional evaluators return a single value,
                        <inlineequation><mml:math><mml:mi mathvariant="italic">order</mml:mi></mml:math></inlineequation>.
                        The initial value is 1.
                        Two-dimensional evaluators return two values,
                        <inlineequation><mml:math><mml:mi mathvariant="italic">uorder</mml:mi></mml:math></inlineequation>
                        and 
                        <inlineequation><mml:math><mml:mi mathvariant="italic">vorder</mml:mi></mml:math></inlineequation>.
                        The initial value is 1,1.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GL_DOMAIN</constant></term>
                <listitem>
                    <para>
                        <parameter>v</parameter> returns the linear 
                        <inlineequation><mml:math><mml:mi mathvariant="italic">u</mml:mi></mml:math></inlineequation>
                        and 
                        <inlineequation><mml:math><mml:mi mathvariant="italic">v</mml:mi></mml:math></inlineequation>
                        mapping parameters.
                        One-dimensional evaluators return two values,
                        <inlineequation><mml:math><mml:mi mathvariant="italic">u1</mml:mi></mml:math></inlineequation>
                        and 
                        <inlineequation><mml:math><mml:mi mathvariant="italic">u2</mml:mi></mml:math></inlineequation>,
                        as specified by <citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry>.
                        Two-dimensional evaluators return four values
                        (<inlineequation><mml:math><mml:mi mathvariant="italic">u1</mml:mi></mml:math></inlineequation>, 
                        <inlineequation><mml:math><mml:mi mathvariant="italic">u2</mml:mi></mml:math></inlineequation>, 
                        <inlineequation><mml:math><mml:mi mathvariant="italic">v1</mml:mi></mml:math></inlineequation>,
                        and 
                        <inlineequation><mml:math><mml:mi mathvariant="italic">v2</mml:mi></mml:math></inlineequation>)
                        as specified by <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry>.
                        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>v</parameter>.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if either <parameter>target</parameter> or <parameter>query</parameter> is not
            an accepted value.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetMap</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>glEvalCoord</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glMap2</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="glGetMap">
	5	<refmeta>
	6	<refmetainfo>
	7	<copyright>
	8	<year>1991-2006</year>
	9	<holder>Silicon Graphics, Inc.</holder>
	10	</copyright>
	11	</refmetainfo>
	12	<refentrytitle>glGetMap</refentrytitle>
	13	<manvolnum>3G</manvolnum>
	14	</refmeta>
	15	<refnamediv>
	16	<refname>glGetMap</refname>
	17	<refpurpose>return evaluator parameters</refpurpose>
	18	</refnamediv>
	19	<refsynopsisdiv><title>C Specification</title>
	20	<funcsynopsis>
	21	<funcprototype>
	22	<funcdef>void <function>glGetMapdv</function></funcdef>
	23	<paramdef>GLenum <parameter>target</parameter></paramdef>
	24	<paramdef>GLenum <parameter>query</parameter></paramdef>
	25	<paramdef>GLdouble * <parameter>v</parameter></paramdef>
	26	</funcprototype>
	27	</funcsynopsis>
	28	<funcsynopsis>
	29	<funcprototype>
	30	<funcdef>void <function>glGetMapfv</function></funcdef>
	31	<paramdef>GLenum <parameter>target</parameter></paramdef>
	32	<paramdef>GLenum <parameter>query</parameter></paramdef>
	33	<paramdef>GLfloat * <parameter>v</parameter></paramdef>
	34	</funcprototype>
	35	</funcsynopsis>
	36	<funcsynopsis>
	37	<funcprototype>
	38	<funcdef>void <function>glGetMapiv</function></funcdef>
	39	<paramdef>GLenum <parameter>target</parameter></paramdef>
	40	<paramdef>GLenum <parameter>query</parameter></paramdef>
	41	<paramdef>GLint * <parameter>v</parameter></paramdef>
	42	</funcprototype>
	43	</funcsynopsis>
	44	</refsynopsisdiv>
	45	<!-- eqn: ignoring delim $$ -->
	46	<refsect1 id="parameters"><title>Parameters</title>
	47	<variablelist>
	48	<varlistentry>
	49	<term><parameter>target</parameter></term>
	50	<listitem>
	51	<para>
	52	Specifies the symbolic name of a map.
	53	Accepted values are
	54	<constant>GL_MAP1_COLOR_4</constant>,
	55	<constant>GL_MAP1_INDEX</constant>,
	56	<constant>GL_MAP1_NORMAL</constant>,
	57	<constant>GL_MAP1_TEXTURE_COORD_1</constant>,
	58	<constant>GL_MAP1_TEXTURE_COORD_2</constant>,
	59	<constant>GL_MAP1_TEXTURE_COORD_3</constant>,
	60	<constant>GL_MAP1_TEXTURE_COORD_4</constant>,
	61	<constant>GL_MAP1_VERTEX_3</constant>,
	62	<constant>GL_MAP1_VERTEX_4</constant>,
	63	<constant>GL_MAP2_COLOR_4</constant>,
	64	<constant>GL_MAP2_INDEX</constant>,
65	<constant>GL_MAP2_NORMAL</constant>,
66	<constant>GL_MAP2_TEXTURE_COORD_1</constant>,
67	<constant>GL_MAP2_TEXTURE_COORD_2</constant>,
68	<constant>GL_MAP2_TEXTURE_COORD_3</constant>,
69	<constant>GL_MAP2_TEXTURE_COORD_4</constant>,
70	<constant>GL_MAP2_VERTEX_3</constant>, and
71	<constant>GL_MAP2_VERTEX_4</constant>.
72	</para>
73	</listitem>
74	</varlistentry>
75	<varlistentry>
76	<term><parameter>query</parameter></term>
77	<listitem>
78	<para>
79	Specifies which parameter to return.
80	Symbolic names
81	<constant>GL_COEFF</constant>,
82	<constant>GL_ORDER</constant>, and
83	<constant>GL_DOMAIN</constant> are accepted.
84	</para>
85	</listitem>
86	</varlistentry>
87	<varlistentry>
88	<term><parameter>v</parameter></term>
89	<listitem>
90	<para>
91	Returns the requested data.
92	</para>
93	</listitem>
94	</varlistentry>
95	</variablelist>
96	</refsect1>
97	<refsect1 id="description"><title>Description</title>
98	<para>
99	<citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry> define evaluators.
100	<function>glGetMap</function> returns evaluator parameters.
101	<parameter>target</parameter> chooses a map,
102	<parameter>query</parameter> selects a specific parameter,
103	and <parameter>v</parameter> points to storage where the values will be returned.
104	</para>
105	<para>
106	The acceptable values for the <parameter>target</parameter> parameter are described
107	in the <citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry> reference pages.
108	</para>
109	<para>
110	<parameter>query</parameter> can assume the following values:
111	</para>
112	<variablelist>
113	<varlistentry>
114	<term><constant>GL_COEFF</constant></term>
115	<listitem>
116	<para>
117	<parameter>v</parameter> returns the control points for the evaluator function.
118	One-dimensional evaluators return
119	<inlineequation><mml:math><mml:mi mathvariant="italic">order</mml:mi></mml:math></inlineequation>
120	control points,
121	and two-dimensional evaluators return
122	<inlineequation><mml:math>
123	<!-- eqn: uorder times vorder:-->
124	<mml:mrow>
125	<mml:mi mathvariant="italic">uorder</mml:mi>
126	<mml:mo>×</mml:mo>
127	<mml:mi mathvariant="italic">vorder</mml:mi>
128	</mml:mrow>
129	</mml:math></inlineequation>
130	control points.
131	Each control point consists of one, two, three, or four integer,
132	single-precision floating-point,
133	or double-precision floating-point values,
134	depending on the type of the evaluator.
135	The GL returns two-dimensional control points in row-major order,
136	incrementing the
137	<inlineequation><mml:math><mml:mi mathvariant="italic">uorder</mml:mi></mml:math></inlineequation>
138	index quickly
139	and the
140	<inlineequation><mml:math><mml:mi mathvariant="italic">vorder</mml:mi></mml:math></inlineequation>
141	index after each row.
142	Integer values,
143	when requested,
144	are computed by rounding the internal floating-point values to the
145	nearest integer values.
146	</para>
147	</listitem>
148	</varlistentry>
149	<varlistentry>
150	<term><constant>GL_ORDER</constant></term>
151	<listitem>
152	<para>
153	<parameter>v</parameter> returns the order of the evaluator function.
154	One-dimensional evaluators return a single value,
155	<inlineequation><mml:math><mml:mi mathvariant="italic">order</mml:mi></mml:math></inlineequation>.
156	The initial value is 1.
157	Two-dimensional evaluators return two values,
158	<inlineequation><mml:math><mml:mi mathvariant="italic">uorder</mml:mi></mml:math></inlineequation>
159	and
160	<inlineequation><mml:math><mml:mi mathvariant="italic">vorder</mml:mi></mml:math></inlineequation>.
161	The initial value is 1,1.
162	</para>
163	</listitem>
164	</varlistentry>
165	<varlistentry>
166	<term><constant>GL_DOMAIN</constant></term>
167	<listitem>
168	<para>
169	<parameter>v</parameter> returns the linear
170	<inlineequation><mml:math><mml:mi mathvariant="italic">u</mml:mi></mml:math></inlineequation>
171	and
172	<inlineequation><mml:math><mml:mi mathvariant="italic">v</mml:mi></mml:math></inlineequation>
173	mapping parameters.
174	One-dimensional evaluators return two values,
175	<inlineequation><mml:math><mml:mi mathvariant="italic">u1</mml:mi></mml:math></inlineequation>
176	and
177	<inlineequation><mml:math><mml:mi mathvariant="italic">u2</mml:mi></mml:math></inlineequation>,
178	as specified by <citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry>.
179	Two-dimensional evaluators return four values
180	(<inlineequation><mml:math><mml:mi mathvariant="italic">u1</mml:mi></mml:math></inlineequation>,
181	<inlineequation><mml:math><mml:mi mathvariant="italic">u2</mml:mi></mml:math></inlineequation>,
182	<inlineequation><mml:math><mml:mi mathvariant="italic">v1</mml:mi></mml:math></inlineequation>,
183	and
184	<inlineequation><mml:math><mml:mi mathvariant="italic">v2</mml:mi></mml:math></inlineequation>)
185	as specified by <citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry>.
186	Integer values,
187	when requested,
188	are computed by rounding the internal floating-point values to the
189	nearest integer values.
190	</para>
191	</listitem>
192	</varlistentry>
193	</variablelist>
194	</refsect1>
195	<refsect1 id="notes"><title>Notes</title>
196	<para>
197	If an error is generated,
198	no change is made to the contents of <parameter>v</parameter>.
199	</para>
200	</refsect1>
201	<refsect1 id="errors"><title>Errors</title>
202	<para>
203	<constant>GL_INVALID_ENUM</constant> is generated if either <parameter>target</parameter> or <parameter>query</parameter> is not
204	an accepted value.
205	</para>
206	<para>
207	<constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetMap</function>
208	is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
209	and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
210	</para>
211	</refsect1>
212	<refsect1 id="seealso"><title>See Also</title>
213	<para>
214	<citerefentry><refentrytitle>glEvalCoord</refentrytitle></citerefentry>,
215	<citerefentry><refentrytitle>glMap1</refentrytitle></citerefentry>,
216	<citerefentry><refentrytitle>glMap2</refentrytitle></citerefentry>
217	</para>
218	</refsect1>
219	<refsect1 id="Copyright"><title>Copyright</title>
220	<para>
221	Copyright <trademark class="copyright"></trademark> 1991-2006
222	Silicon Graphics, Inc. This document is licensed under the SGI
223	Free Software B License. For details, see
224	<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
225	</para>
226	</refsect1>
227	</refentry>