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">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glMap1
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glMap1
</refname>
17 <refpurpose>define a one-dimensional evaluator
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glMap1f
</function></funcdef>
23 <paramdef>GLenum
<parameter>target
</parameter></paramdef>
24 <paramdef>GLfloat
<parameter>u1
</parameter></paramdef>
25 <paramdef>GLfloat
<parameter>u2
</parameter></paramdef>
26 <paramdef>GLint
<parameter>stride
</parameter></paramdef>
27 <paramdef>GLint
<parameter>order
</parameter></paramdef>
28 <paramdef>const GLfloat *
<parameter>points
</parameter></paramdef>
33 <funcdef>void
<function>glMap1d
</function></funcdef>
34 <paramdef>GLenum
<parameter>target
</parameter></paramdef>
35 <paramdef>GLdouble
<parameter>u1
</parameter></paramdef>
36 <paramdef>GLdouble
<parameter>u2
</parameter></paramdef>
37 <paramdef>GLint
<parameter>stride
</parameter></paramdef>
38 <paramdef>GLint
<parameter>order
</parameter></paramdef>
39 <paramdef>const GLdouble *
<parameter>points
</parameter></paramdef>
43 <!-- eqn: ignoring delim $$ -->
44 <refsect1 id=
"parameters"><title>Parameters
</title>
47 <term><parameter>target
</parameter></term>
50 Specifies the kind of values that are generated by the evaluator.
52 <constant>GL_MAP1_VERTEX_3
</constant>,
53 <constant>GL_MAP1_VERTEX_4
</constant>,
54 <constant>GL_MAP1_INDEX
</constant>,
55 <constant>GL_MAP1_COLOR_4
</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>, and
60 <constant>GL_MAP1_TEXTURE_COORD_4
</constant> are accepted.
65 <term><parameter>u1
</parameter></term>
66 <term><parameter>u2
</parameter></term>
69 Specify a linear mapping of
70 <inlineequation><mml:math><mml:mi mathvariant=
"italic">u
</mml:mi></mml:math></inlineequation>,
71 as presented to
<citerefentry><refentrytitle>glEvalCoord1
</refentrytitle></citerefentry>,
73 <inlineequation><mml:math>
75 <mml:mover><mml:mi mathvariant=
"italic">u
</mml:mi><mml:mo>^</mml:mo></mml:mover>
76 </mml:math></inlineequation>,
77 the variable that is evaluated by the equations specified by this command.
82 <term><parameter>stride
</parameter></term>
85 Specifies the number of floats or doubles between
86 the beginning of one control point and the beginning of the next one
87 in the data structure referenced in
<parameter>points
</parameter>.
88 This allows control points to be embedded in arbitrary data structures.
89 The only constraint is that the values for a particular control point
90 must occupy contiguous memory locations.
95 <term><parameter>order
</parameter></term>
98 Specifies the number of control points.
104 <term><parameter>points
</parameter></term>
107 Specifies a pointer to the array of control points.
113 <refsect1 id=
"description"><title>Description
</title>
115 Evaluators provide a way to use polynomial or rational polynomial mapping
120 The values produced by an evaluator are sent to further stages
121 of GL processing just as if they had been presented using
122 <citerefentry><refentrytitle>glVertex
</refentrytitle></citerefentry>,
123 <citerefentry><refentrytitle>glNormal
</refentrytitle></citerefentry>,
124 <citerefentry><refentrytitle>glTexCoord
</refentrytitle></citerefentry>, and
125 <citerefentry><refentrytitle>glColor
</refentrytitle></citerefentry> commands,
126 except that the generated values do not update the current normal,
131 All polynomial or rational polynomial splines of any degree
132 (up to the maximum degree supported by the GL implementation)
133 can be described using evaluators.
134 These include almost all splines used in computer graphics: B-splines,
135 Bezier curves, Hermite splines, and so on.
138 Evaluators define curves based on Bernstein polynomials.
140 <inlineequation><mml:math>
141 <!-- eqn: p ( u hat):-->
143 <mml:mi mathvariant=
"italic">p
</mml:mi>
144 <mml:mo>⁡</mml:mo>
145 <mml:mfenced open=
"(" close=
")">
146 <mml:mover><mml:mi mathvariant=
"italic">u
</mml:mi><mml:mo>^</mml:mo></mml:mover>
149 </mml:math></inlineequation>
153 <informalequation><mml:math>
154 <!-- eqn: p ( u hat) = sum from {i = 0} to {n} { {B sub i} sup n ( u hat ) R sub i }:-->
157 <mml:mi mathvariant=
"italic">p
</mml:mi>
158 <mml:mo>⁡</mml:mo>
159 <mml:mfenced open=
"(" close=
")">
160 <mml:mover><mml:mi mathvariant=
"italic">u
</mml:mi><mml:mo>^</mml:mo></mml:mover>
166 <mml:mo>Σ</mml:mo>
168 <mml:mi mathvariant=
"italic">i
</mml:mi>
172 <mml:mi mathvariant=
"italic">n
</mml:mi>
176 <mml:msup><mml:mfenced open=
"" close=
"">
177 <mml:msub><mml:mi mathvariant=
"italic">B
</mml:mi>
178 <mml:mi mathvariant=
"italic">i
</mml:mi>
181 <mml:mi mathvariant=
"italic">n
</mml:mi>
183 <mml:mo>⁡</mml:mo>
184 <mml:mfenced open=
"(" close=
")">
185 <mml:mover><mml:mi mathvariant=
"italic">u
</mml:mi><mml:mo>^</mml:mo></mml:mover>
188 <mml:mo>⁢</mml:mo>
189 <mml:msub><mml:mi mathvariant=
"italic">R
</mml:mi>
190 <mml:mi mathvariant=
"italic">i
</mml:mi>
195 </mml:math></informalequation>
201 <inlineequation><mml:math>
202 <!-- eqn: R sub i:-->
203 <mml:msub><mml:mi mathvariant=
"italic">R
</mml:mi>
204 <mml:mi mathvariant=
"italic">i
</mml:mi>
206 </mml:math></inlineequation>
207 is a control point and
208 <inlineequation><mml:math>
209 <!-- eqn: {B sub i} sup n ( u hat):-->
211 <mml:msup><mml:mfenced open=
"" close=
"">
212 <mml:msub><mml:mi mathvariant=
"italic">B
</mml:mi>
213 <mml:mi mathvariant=
"italic">i
</mml:mi>
216 <mml:mi mathvariant=
"italic">n
</mml:mi>
218 <mml:mo>⁡</mml:mo>
219 <mml:mfenced open=
"(" close=
")">
220 <mml:mover><mml:mi mathvariant=
"italic">u
</mml:mi><mml:mo>^</mml:mo></mml:mover>
223 </mml:math></inlineequation>
225 <inlineequation><mml:math><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math></inlineequation>th
226 Bernstein polynomial of degree
227 <inlineequation><mml:math><mml:mi mathvariant=
"italic">n
</mml:mi></mml:math></inlineequation>
228 (
<parameter>order
</parameter> =
229 <inlineequation><mml:math>
232 <mml:mi mathvariant=
"italic">n
</mml:mi>
236 </mml:math></inlineequation>):
239 <inlineequation><mml:math>
240 <!-- eqn: {B sub i} sup n ( u hat) = left ( {cpile { n above i }} right ) {u hat} sup i { ( 1 - u hat) sup { n - i } }:-->
243 <mml:msup><mml:mfenced open=
"" close=
"">
244 <mml:msub><mml:mi mathvariant=
"italic">B
</mml:mi>
245 <mml:mi mathvariant=
"italic">i
</mml:mi>
248 <mml:mi mathvariant=
"italic">n
</mml:mi>
250 <mml:mo>⁡</mml:mo>
251 <mml:mfenced open=
"(" close=
")">
252 <mml:mover><mml:mi mathvariant=
"italic">u
</mml:mi><mml:mo>^</mml:mo></mml:mover>
257 <mml:mfenced open=
"(" close=
")">
258 <mml:mfenced open=
"" close=
"">
261 <mml:mi mathvariant=
"italic">n
</mml:mi>
264 <mml:mi mathvariant=
"italic">i
</mml:mi>
269 <mml:mo>⁢</mml:mo>
270 <mml:msup><mml:mfenced open=
"" close=
"">
271 <mml:mover><mml:mi mathvariant=
"italic">u
</mml:mi><mml:mo>^</mml:mo></mml:mover>
273 <mml:mi mathvariant=
"italic">i
</mml:mi>
275 <mml:mo>⁢</mml:mo>
276 <mml:mfenced open=
"" close=
"">
277 <mml:msup><mml:mfenced open=
"(" close=
")">
281 <mml:mover><mml:mi mathvariant=
"italic">u
</mml:mi><mml:mo>^</mml:mo></mml:mover>
284 <mml:mfenced open=
"" close=
"">
286 <mml:mi mathvariant=
"italic">n
</mml:mi>
288 <mml:mi mathvariant=
"italic">i
</mml:mi>
295 </mml:math></inlineequation>
301 <inlineequation><mml:math>
302 <!-- eqn: 0 sup 0 == 1:-->
304 <mml:msup><mml:mn>0</mml:mn>
310 </mml:math></inlineequation>
312 <inlineequation><mml:math>
313 <!-- eqn: left ( {cpile { n above 0 }} right ) == 1:-->
315 <mml:mfenced open=
"(" close=
")">
316 <mml:mfenced open=
"" close=
"">
319 <mml:mi mathvariant=
"italic">n
</mml:mi>
330 </mml:math></inlineequation>
333 <function>glMap1
</function> is used to define the basis and to specify what kind of values
336 a map can be enabled and disabled by calling
<citerefentry><refentrytitle>glEnable
</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glDisable
</refentrytitle></citerefentry>
337 with the map name, one of the nine predefined values for
<parameter>target
</parameter>
339 <citerefentry><refentrytitle>glEvalCoord1
</refentrytitle></citerefentry> evaluates the one-dimensional maps that are enabled.
341 <citerefentry><refentrytitle>glEvalCoord1
</refentrytitle></citerefentry> presents a value
342 <inlineequation><mml:math><mml:mi mathvariant=
"italic">u
</mml:mi></mml:math></inlineequation>,
343 the Bernstein functions are evaluated using
344 <inlineequation><mml:math>
346 <mml:mover><mml:mi mathvariant=
"italic">u
</mml:mi><mml:mo>^</mml:mo></mml:mover>
347 </mml:math></inlineequation>,
349 <inlineequation><mml:math>
350 <!-- eqn: u hat = {u - u1} over {u2 - u1}:-->
352 <mml:mover><mml:mi mathvariant=
"italic">u
</mml:mi><mml:mo>^</mml:mo></mml:mover>
355 <mml:mfenced open=
"" close=
"">
357 <mml:mi mathvariant=
"italic">u
</mml:mi>
359 <mml:mi mathvariant=
"italic">u1
</mml:mi>
362 <mml:mfenced open=
"" close=
"">
364 <mml:mi mathvariant=
"italic">u2
</mml:mi>
366 <mml:mi mathvariant=
"italic">u1
</mml:mi>
371 </mml:math></inlineequation>
374 <parameter>target
</parameter> is a symbolic constant that indicates what kind of control points
375 are provided in
<parameter>points
</parameter>,
376 and what output is generated when the map is evaluated.
377 It can assume one of nine predefined values:
381 <term><constant>GL_MAP1_VERTEX_3
</constant></term>
384 Each control point is three floating-point values representing
385 <inlineequation><mml:math><mml:mi mathvariant=
"italic">x
</mml:mi></mml:math></inlineequation>,
386 <inlineequation><mml:math><mml:mi mathvariant=
"italic">y
</mml:mi></mml:math></inlineequation>,
388 <inlineequation><mml:math><mml:mi mathvariant=
"italic">z
</mml:mi></mml:math></inlineequation>.
389 Internal
<citerefentry><refentrytitle>glVertex3
</refentrytitle></citerefentry> commands are generated when the map is evaluated.
394 <term><constant>GL_MAP1_VERTEX_4
</constant></term>
397 Each control point is four floating-point values representing
398 <inlineequation><mml:math><mml:mi mathvariant=
"italic">x
</mml:mi></mml:math></inlineequation>,
399 <inlineequation><mml:math><mml:mi mathvariant=
"italic">y
</mml:mi></mml:math></inlineequation>,
400 <inlineequation><mml:math><mml:mi mathvariant=
"italic">z
</mml:mi></mml:math></inlineequation>,
402 <inlineequation><mml:math><mml:mi mathvariant=
"italic">w
</mml:mi></mml:math></inlineequation>.
403 Internal
<citerefentry><refentrytitle>glVertex4
</refentrytitle></citerefentry> commands are generated when the map is evaluated.
408 <term><constant>GL_MAP1_INDEX
</constant></term>
411 Each control point is a single floating-point value representing a color index.
412 Internal
<citerefentry><refentrytitle>glIndex
</refentrytitle></citerefentry> commands are generated when the map is evaluated
413 but the current index is not updated with the value of these
<citerefentry><refentrytitle>glIndex
</refentrytitle></citerefentry>
419 <term><constant>GL_MAP1_COLOR_4
</constant></term>
422 Each control point is four floating-point values representing
423 red, green, blue, and alpha.
424 Internal
<citerefentry><refentrytitle>glColor4
</refentrytitle></citerefentry> commands are generated when the map is
425 evaluated but the current color is not updated with the value of these
426 <citerefentry><refentrytitle>glColor4
</refentrytitle></citerefentry> commands.
431 <term><constant>GL_MAP1_NORMAL
</constant></term>
434 Each control point is three floating-point values representing
436 <inlineequation><mml:math><mml:mi mathvariant=
"italic">x
</mml:mi></mml:math></inlineequation>,
437 <inlineequation><mml:math><mml:mi mathvariant=
"italic">y
</mml:mi></mml:math></inlineequation>,
439 <inlineequation><mml:math><mml:mi mathvariant=
"italic">z
</mml:mi></mml:math></inlineequation>
440 components of a normal vector.
441 Internal
<citerefentry><refentrytitle>glNormal
</refentrytitle></citerefentry> commands are generated when the map is
442 evaluated but the current normal is not updated with the value of
443 these
<citerefentry><refentrytitle>glNormal
</refentrytitle></citerefentry> commands.
448 <term><constant>GL_MAP1_TEXTURE_COORD_1
</constant></term>
451 Each control point is a single floating-point value representing
453 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>
456 <citerefentry><refentrytitle>glTexCoord1
</refentrytitle></citerefentry> commands are generated when the map is
457 evaluated but the current texture coordinates are not updated with the value
458 of these
<citerefentry><refentrytitle>glTexCoord
</refentrytitle></citerefentry> commands.
463 <term><constant>GL_MAP1_TEXTURE_COORD_2
</constant></term>
466 Each control point is two floating-point values representing
468 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>
470 <inlineequation><mml:math><mml:mi mathvariant=
"italic">t
</mml:mi></mml:math></inlineequation>
473 <citerefentry><refentrytitle>glTexCoord2
</refentrytitle></citerefentry> commands are generated when the map is
474 evaluated but the current texture coordinates are not updated with the value
475 of these
<citerefentry><refentrytitle>glTexCoord
</refentrytitle></citerefentry> commands.
480 <term><constant>GL_MAP1_TEXTURE_COORD_3
</constant></term>
483 Each control point is three floating-point values representing
485 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>,
486 <inlineequation><mml:math><mml:mi mathvariant=
"italic">t
</mml:mi></mml:math></inlineequation>,
488 <inlineequation><mml:math><mml:mi mathvariant=
"italic">r
</mml:mi></mml:math></inlineequation>
490 Internal
<citerefentry><refentrytitle>glTexCoord3
</refentrytitle></citerefentry> commands are generated when the map is
491 evaluated but the current texture coordinates are not updated with the value
492 of these
<citerefentry><refentrytitle>glTexCoord
</refentrytitle></citerefentry> commands.
497 <term><constant>GL_MAP1_TEXTURE_COORD_4
</constant></term>
500 Each control point is four floating-point values representing
502 <inlineequation><mml:math><mml:mi mathvariant=
"italic">s
</mml:mi></mml:math></inlineequation>,
503 <inlineequation><mml:math><mml:mi mathvariant=
"italic">t
</mml:mi></mml:math></inlineequation>,
504 <inlineequation><mml:math><mml:mi mathvariant=
"italic">r
</mml:mi></mml:math></inlineequation>,
506 <inlineequation><mml:math><mml:mi mathvariant=
"italic">q
</mml:mi></mml:math></inlineequation>
509 <citerefentry><refentrytitle>glTexCoord4
</refentrytitle></citerefentry> commands are generated when the map is evaluated but
510 the current texture coordinates are not updated with the value
511 of these
<citerefentry><refentrytitle>glTexCoord
</refentrytitle></citerefentry> commands.
517 <parameter>stride
</parameter>,
518 <parameter>order
</parameter>, and
519 <parameter>points
</parameter> define the array addressing for accessing the control points.
520 <parameter>points
</parameter> is the location of the first control point,
521 which occupies one, two, three, or four contiguous memory locations,
522 depending on which map is being defined.
523 <parameter>order
</parameter> is the number of control points in the array.
524 <parameter>stride
</parameter> specifies how many float or double locations to advance the internal
525 memory pointer to reach the next control point.
528 <refsect1 id=
"notes"><title>Notes
</title>
530 As is the case with all GL commands that accept pointers to data,
531 it is as if the contents of
<parameter>points
</parameter> were copied by
<function>glMap1
</function> before
<function>glMap1
</function>
533 Changes to the contents of
<parameter>points
</parameter> have no effect after
<function>glMap1
</function> is called.
536 <refsect1 id=
"errors"><title>Errors
</title>
538 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>target
</parameter> is not an accepted value.
541 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>u1
</parameter> is equal to
<parameter>u2
</parameter>.
544 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>stride
</parameter> is less than the number
545 of values in a control point.
548 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>order
</parameter> is less than
1 or
549 greater than the return value of
<constant>GL_MAX_EVAL_ORDER
</constant>.
552 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glMap1
</function>
553 is executed between the execution of
554 <citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry>
555 and the corresponding execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
558 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glMap1
</function> is called and the value
559 of
<constant>GL_ACTIVE_TEXTURE
</constant> is not
<constant>GL_TEXTURE0
</constant>.
562 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
564 <citerefentry><refentrytitle>glGetMap
</refentrytitle></citerefentry>
567 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_MAX_EVAL_ORDER
</constant>
570 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_MAP1_VERTEX_3
</constant>
573 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_MAP1_VERTEX_4
</constant>
576 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_MAP1_INDEX
</constant>
579 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_MAP1_COLOR_4
</constant>
582 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_MAP1_NORMAL
</constant>
585 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_MAP1_TEXTURE_COORD_1
</constant>
588 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_MAP1_TEXTURE_COORD_2
</constant>
591 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_MAP1_TEXTURE_COORD_3
</constant>
594 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_MAP1_TEXTURE_COORD_4
</constant>
597 <refsect1 id=
"seealso"><title>See Also
</title>
599 <citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry>,
600 <citerefentry><refentrytitle>glColor
</refentrytitle></citerefentry>,
601 <citerefentry><refentrytitle>glEnable
</refentrytitle></citerefentry>,
602 <citerefentry><refentrytitle>glEvalCoord
</refentrytitle></citerefentry>,
603 <citerefentry><refentrytitle>glEvalMesh
</refentrytitle></citerefentry>,
604 <citerefentry><refentrytitle>glEvalPoint
</refentrytitle></citerefentry>,
605 <citerefentry><refentrytitle>glMap2
</refentrytitle></citerefentry>,
606 <citerefentry><refentrytitle>glMapGrid
</refentrytitle></citerefentry>,
607 <citerefentry><refentrytitle>glNormal
</refentrytitle></citerefentry>,
608 <citerefentry><refentrytitle>glTexCoord
</refentrytitle></citerefentry>,
609 <citerefentry><refentrytitle>glVertex
</refentrytitle></citerefentry>
612 <refsect1 id=
"Copyright"><title>Copyright
</title>
614 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
615 Silicon Graphics, Inc. This document is licensed under the SGI
616 Free Software B License. For details, see
617 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.