272 lines
8.6 KiB
Plaintext
272 lines
8.6 KiB
Plaintext
|
'\" te
|
||
|
|
'\"! tbl|eqn | mmdoc
|
||
|
|
'\"macro stdmacro
|
||
|
|
.ds Vn Version 1.2
|
||
|
|
.ds Dt 24 September 1999
|
||
|
|
.ds Re Release 1.2.1
|
||
|
|
.ds Dp Jan 14 18:30
|
||
|
|
.ds Dm 01 map1.gl -
|
||
|
|
.ds Xs 15186 10 map1.gl
|
||
|
|
.TH GLMAP1 3G
|
||
|
|
.SH NAME
|
||
|
|
.B "glMap1d, glMap1f
|
||
|
|
\- define a one-dimensional evaluator
|
||
|
|
|
||
|
|
.SH C SPECIFICATION
|
||
|
|
void \f3glMap1d\fP(
|
||
|
|
GLenum \fItarget\fP,
|
||
|
|
.nf
|
||
|
|
.ta \w'\f3void \fPglMap1d( 'u
|
||
|
|
GLdouble \fIu1\fP,
|
||
|
|
GLdouble \fIu2\fP,
|
||
|
|
GLint \fIstride\fP,
|
||
|
|
GLint \fIorder\fP,
|
||
|
|
const GLdouble \fI*points\fP )
|
||
|
|
.fi
|
||
|
|
void \f3glMap1f\fP(
|
||
|
|
GLenum \fItarget\fP,
|
||
|
|
.nf
|
||
|
|
.ta \w'\f3void \fPglMap1f( 'u
|
||
|
|
GLfloat \fIu1\fP,
|
||
|
|
GLfloat \fIu2\fP,
|
||
|
|
GLint \fIstride\fP,
|
||
|
|
GLint \fIorder\fP,
|
||
|
|
const GLfloat \fI*points\fP )
|
||
|
|
.fi
|
||
|
|
|
||
|
|
.EQ
|
||
|
|
delim $$
|
||
|
|
.EN
|
||
|
|
.SH PARAMETERS
|
||
|
|
.TP \w'\f2target\fP\ \ 'u
|
||
|
|
\f2target\fP
|
||
|
|
Specifies the kind of values that are generated by the evaluator.
|
||
|
|
Symbolic constants
|
||
|
|
\%\f3GL_MAP1_VERTEX_3\fP,
|
||
|
|
\%\f3GL_MAP1_VERTEX_4\fP,
|
||
|
|
\%\f3GL_MAP1_INDEX\fP,
|
||
|
|
\%\f3GL_MAP1_COLOR_4\fP,
|
||
|
|
\%\f3GL_MAP1_NORMAL\fP,
|
||
|
|
\%\f3GL_MAP1_TEXTURE_COORD_1\fP,
|
||
|
|
\%\f3GL_MAP1_TEXTURE_COORD_2\fP,
|
||
|
|
\%\f3GL_MAP1_TEXTURE_COORD_3\fP, and
|
||
|
|
\%\f3GL_MAP1_TEXTURE_COORD_4\fP are accepted.
|
||
|
|
.TP
|
||
|
|
\f2u1\fP, \f2u2\fP
|
||
|
|
Specify a linear mapping of $u$,
|
||
|
|
as presented to \%\f3glEvalCoord1\fP,
|
||
|
|
to $u hat$,
|
||
|
|
the variable that is evaluated by the equations specified by this command.
|
||
|
|
.TP
|
||
|
|
\f2stride\fP
|
||
|
|
Specifies the number of floats or doubles between
|
||
|
|
the beginning of one control point and the beginning of the next one
|
||
|
|
in the data structure referenced in \f2points\fP.
|
||
|
|
This allows control points to be embedded in arbitrary data structures.
|
||
|
|
The only constraint is that the values for a particular control point
|
||
|
|
must occupy contiguous memory locations.
|
||
|
|
.TP
|
||
|
|
\f2order\fP
|
||
|
|
Specifies the number of control points.
|
||
|
|
Must be positive.
|
||
|
|
.TP
|
||
|
|
\f2points\fP
|
||
|
|
Specifies a pointer to the array of control points.
|
||
|
|
|
||
|
|
.SH DESCRIPTION
|
||
|
|
Evaluators provide a way to use polynomial or rational polynomial mapping
|
||
|
|
to produce vertices,
|
||
|
|
normals,
|
||
|
|
texture coordinates,
|
||
|
|
and colors.
|
||
|
|
The values produced by an evaluator are sent to further stages
|
||
|
|
of GL processing just as if they had been presented using
|
||
|
|
\%\f3glVertex\fP,
|
||
|
|
\%\f3glNormal\fP,
|
||
|
|
\%\f3glTexCoord\fP, and
|
||
|
|
\%\f3glColor\fP commands,
|
||
|
|
except that the generated values do not update the current normal,
|
||
|
|
texture coordinates,
|
||
|
|
or color.
|
||
|
|
.P
|
||
|
|
All polynomial or rational polynomial splines of any degree
|
||
|
|
(up to the maximum degree supported by the GL implementation)
|
||
|
|
can be described using evaluators.
|
||
|
|
These include almost all splines used in computer graphics: B-splines,
|
||
|
|
Bezier curves, Hermite splines, and so on.
|
||
|
|
.P
|
||
|
|
Evaluators define curves based on Bernstein polynomials.
|
||
|
|
Define $p ( u hat ^) $ as
|
||
|
|
.sp
|
||
|
|
.ce
|
||
|
|
$p ( u hat ^) ~~=~~ up 10 { sum from i=0 to n } B sub i sup n ( u hat ^) R sub i$
|
||
|
|
.sp
|
||
|
|
where
|
||
|
|
$R sub i$
|
||
|
|
is a control point and
|
||
|
|
$B sub i sup n ( u hat ^)$
|
||
|
|
is the $i$th Bernstein polynomial of degree $n$ (\f2order\fP = $n ~+~ 1$):
|
||
|
|
.sp
|
||
|
|
.ce
|
||
|
|
$B sub i sup n ( u hat ^) ~~=~~ left ( down 20 {cpile { n above i }} ~~ right ) u hat sup i ( 1 - u hat ^) sup { n - i }$
|
||
|
|
.sp
|
||
|
|
Recall that
|
||
|
|
.sp
|
||
|
|
.ce
|
||
|
|
$0 sup 0 ~==~ 1 $ and $ left ( down 20 {cpile { n above ~0 }} ~~ right ) ~~==~~ 1 $
|
||
|
|
.P
|
||
|
|
\%\f3glMap1\fP is used to define the basis and to specify what kind of values
|
||
|
|
are produced.
|
||
|
|
Once defined,
|
||
|
|
a map can be enabled and disabled by calling \%\f3glEnable\fP and \%\f3glDisable\fP
|
||
|
|
with the map name, one of the nine predefined values for \f2target\fP
|
||
|
|
described below.
|
||
|
|
\%\f3glEvalCoord1\fP evaluates the one-dimensional maps that are enabled.
|
||
|
|
When
|
||
|
|
.br
|
||
|
|
\%\f3glEvalCoord1\fP presents a value $u$,
|
||
|
|
the Bernstein functions are evaluated using $u hat$, where
|
||
|
|
.br
|
||
|
|
|
||
|
|
.ce
|
||
|
|
$u hat ~~=~~ {u ~-~ "u1"} over {"u2" ~-~ "u1"}$
|
||
|
|
|
||
|
|
.br
|
||
|
|
.P
|
||
|
|
\f2target\fP is a symbolic constant that indicates what kind of control points
|
||
|
|
are provided in \f2points\fP,
|
||
|
|
and what output is generated when the map is evaluated.
|
||
|
|
It can assume one of nine predefined values:
|
||
|
|
.TP 25
|
||
|
|
\%\f3GL_MAP1_VERTEX_3\fP
|
||
|
|
Each control point is three floating-point values representing
|
||
|
|
$x$, $y$, and $z$.
|
||
|
|
Internal \%\f3glVertex3\fP commands are generated when the map is evaluated.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_MAP1_VERTEX_4\fP
|
||
|
|
Each control point is four floating-point values representing
|
||
|
|
$x$, $y$, $z$, and $w$.
|
||
|
|
Internal \%\f3glVertex4\fP commands are generated when the map is evaluated.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_MAP1_INDEX\fP
|
||
|
|
Each control point is a single floating-point value representing a color index.
|
||
|
|
Internal \%\f3glIndex\fP commands are generated when the map is evaluated
|
||
|
|
but the current index is not updated with the value of these \%\f3glIndex\fP
|
||
|
|
commands.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_MAP1_COLOR_4\fP
|
||
|
|
Each control point is four floating-point values representing
|
||
|
|
red, green, blue, and alpha.
|
||
|
|
Internal \%\f3glColor4\fP commands are generated when the map is
|
||
|
|
evaluated but the current color is not updated with the value of these
|
||
|
|
\%\f3glColor4\fP commands.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_MAP1_NORMAL\fP
|
||
|
|
Each control point is three floating-point values representing
|
||
|
|
the $x$, $y$, and $z$ components of a normal vector.
|
||
|
|
Internal \%\f3glNormal\fP commands are generated when the map is
|
||
|
|
evaluated but the current normal is not updated with the value of
|
||
|
|
these \%\f3glNormal\fP commands.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_MAP1_TEXTURE_COORD_1\fP
|
||
|
|
Each control point is a single floating-point value representing
|
||
|
|
the $s$ texture coordinate.
|
||
|
|
Internal
|
||
|
|
.br
|
||
|
|
\%\f3glTexCoord1\fP commands are generated when the map is
|
||
|
|
evaluated but the current texture coordinates are not updated with the value
|
||
|
|
of these \%\f3glTexCoord\fP commands.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_MAP1_TEXTURE_COORD_2\fP
|
||
|
|
Each control point is two floating-point values representing
|
||
|
|
the $s$ and $t$ texture coordinates.
|
||
|
|
Internal
|
||
|
|
.br
|
||
|
|
\%\f3glTexCoord2\fP commands are generated when the map is
|
||
|
|
evaluated but the current texture coordinates are not updated with the value
|
||
|
|
of these \%\f3glTexCoord\fP commands.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_MAP1_TEXTURE_COORD_3\fP
|
||
|
|
Each control point is three floating-point values representing
|
||
|
|
the $s$, $t$, and $r$ texture coordinates.
|
||
|
|
Internal \%\f3glTexCoord3\fP commands are generated when the map is
|
||
|
|
evaluated but the current texture coordinates are not updated with the value
|
||
|
|
of these \%\f3glTexCoord\fP commands.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_MAP1_TEXTURE_COORD_4\fP
|
||
|
|
Each control point is four floating-point values representing
|
||
|
|
the $s$, $t$, $r$, and $q$ texture coordinates.
|
||
|
|
Internal
|
||
|
|
.br
|
||
|
|
\%\f3glTexCoord4\fP commands are generated when the map is evaluated but
|
||
|
|
the current texture coordinates are not updated with the value
|
||
|
|
of these \%\f3glTexCoord\fP commands.
|
||
|
|
.P
|
||
|
|
\f2stride\fP,
|
||
|
|
\f2order\fP, and
|
||
|
|
\f2points\fP define the array addressing for accessing the control points.
|
||
|
|
\f2points\fP is the location of the first control point,
|
||
|
|
which occupies one, two, three, or four contiguous memory locations,
|
||
|
|
depending on which map is being defined.
|
||
|
|
\f2order\fP is the number of control points in the array.
|
||
|
|
\f2stride\fP specifies how many float or double locations to advance the internal
|
||
|
|
memory pointer to reach the next control point.
|
||
|
|
.SH NOTES
|
||
|
|
As is the case with all GL commands that accept pointers to data,
|
||
|
|
it is as if the contents of \f2points\fP were copied by \%\f3glMap1\fP before \%\f3glMap1\fP
|
||
|
|
returns.
|
||
|
|
Changes to the contents of \f2points\fP have no effect after \%\f3glMap1\fP is called.
|
||
|
|
.SH ERRORS
|
||
|
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2target\fP is not an accepted value.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_VALUE\fP is generated if \f2u1\fP is equal to \f2u2\fP.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_VALUE\fP is generated if \f2stride\fP is less than the number
|
||
|
|
of values in a control point.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_VALUE\fP is generated if \f2order\fP is less than 1 or
|
||
|
|
greater than the return value of \%\f3GL_MAX_EVAL_ORDER\fP.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glMap1\fP
|
||
|
|
is executed between the execution of
|
||
|
|
\%\f3glBegin\fP
|
||
|
|
and the corresponding execution of \%\f3glEnd\fP.
|
||
|
|
.P
|
||
|
|
When the \%\f3GL_ARB_multitexture\fP extension is supported,
|
||
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glMap1\fP is called and the value
|
||
|
|
of \%\f3GL_ACTIVE_TEXTURE_ARB\fP is not \%\f3GL_TEXTURE0_ARB\fP.
|
||
|
|
.SH ASSOCIATED GETS
|
||
|
|
\%\f3glGetMap\fP
|
||
|
|
.br
|
||
|
|
\%\f3glGet\fP with argument \%\f3GL_MAX_EVAL_ORDER\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP1_VERTEX_3\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP1_VERTEX_4\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP1_INDEX\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP1_COLOR_4\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP1_NORMAL\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP1_TEXTURE_COORD_1\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP1_TEXTURE_COORD_2\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP1_TEXTURE_COORD_3\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP1_TEXTURE_COORD_4\fP
|
||
|
|
.SH SEE ALSO
|
||
|
|
\%\f3glBegin(3G)\fP,
|
||
|
|
\%\f3glColor(3G)\fP,
|
||
|
|
\%\f3glEnable(3G)\fP,
|
||
|
|
\%\f3glEvalCoord(3G)\fP,
|
||
|
|
\%\f3glEvalMesh(3G)\fP,
|
||
|
|
\%\f3glEvalPoint(3G)\fP,
|
||
|
|
\%\f3glMap2(3G)\fP,
|
||
|
|
\%\f3glMapGrid(3G)\fP,
|
||
|
|
\%\f3glNormal(3G)\fP,
|
||
|
|
\%\f3glTexCoord(3G)\fP,
|
||
|
|
\%\f3glVertex(3G)\fP
|