332 lines
11 KiB
Plaintext
332 lines
11 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 map2.gl -
|
||
|
|
.ds Xs 16004 12 map2.gl
|
||
|
|
.TH GLMAP2 3G
|
||
|
|
.SH NAME
|
||
|
|
.B "glMap2d, glMap2f
|
||
|
|
\- define a two-dimensional evaluator
|
||
|
|
|
||
|
|
.SH C SPECIFICATION
|
||
|
|
void \f3glMap2d\fP(
|
||
|
|
GLenum \fItarget\fP,
|
||
|
|
.nf
|
||
|
|
.ta \w'\f3void \fPglMap2d( 'u
|
||
|
|
GLdouble \fIu1\fP,
|
||
|
|
GLdouble \fIu2\fP,
|
||
|
|
GLint \fIustride\fP,
|
||
|
|
GLint \fIuorder\fP,
|
||
|
|
GLdouble \fIv1\fP,
|
||
|
|
GLdouble \fIv2\fP,
|
||
|
|
GLint \fIvstride\fP,
|
||
|
|
GLint \fIvorder\fP,
|
||
|
|
const GLdouble \fI*points\fP )
|
||
|
|
.fi
|
||
|
|
void \f3glMap2f\fP(
|
||
|
|
GLenum \fItarget\fP,
|
||
|
|
.nf
|
||
|
|
.ta \w'\f3void \fPglMap2f( 'u
|
||
|
|
GLfloat \fIu1\fP,
|
||
|
|
GLfloat \fIu2\fP,
|
||
|
|
GLint \fIustride\fP,
|
||
|
|
GLint \fIuorder\fP,
|
||
|
|
GLfloat \fIv1\fP,
|
||
|
|
GLfloat \fIv2\fP,
|
||
|
|
GLint \fIvstride\fP,
|
||
|
|
GLint \fIvorder\fP,
|
||
|
|
const GLfloat \fI*points\fP )
|
||
|
|
.fi
|
||
|
|
|
||
|
|
.EQ
|
||
|
|
delim $$
|
||
|
|
.EN
|
||
|
|
.SH PARAMETERS
|
||
|
|
.TP \w'\fIustride\fP\ \ 'u
|
||
|
|
\f2target\fP
|
||
|
|
Specifies the kind of values that are generated by the evaluator.
|
||
|
|
Symbolic constants
|
||
|
|
\%\f3GL_MAP2_VERTEX_3\fP,
|
||
|
|
\%\f3GL_MAP2_VERTEX_4\fP,
|
||
|
|
\%\f3GL_MAP2_INDEX\fP,
|
||
|
|
\%\f3GL_MAP2_COLOR_4\fP,
|
||
|
|
\%\f3GL_MAP2_NORMAL\fP,
|
||
|
|
\%\f3GL_MAP2_TEXTURE_COORD_1\fP,
|
||
|
|
\%\f3GL_MAP2_TEXTURE_COORD_2\fP,
|
||
|
|
\%\f3GL_MAP2_TEXTURE_COORD_3\fP, and
|
||
|
|
\%\f3GL_MAP2_TEXTURE_COORD_4\fP are accepted.
|
||
|
|
.TP
|
||
|
|
\f2u1\fP, \f2u2\fP
|
||
|
|
Specify a linear mapping of $u$,
|
||
|
|
as presented to \%\f3glEvalCoord2\fP,
|
||
|
|
to $u hat$,
|
||
|
|
one of the two variables that are evaluated by the equations specified
|
||
|
|
by this command. Initially, \f2u1\fP is 0 and \f2u2\fP is 1.
|
||
|
|
.TP
|
||
|
|
\f2ustride\fP
|
||
|
|
Specifies the number of floats or doubles between
|
||
|
|
the beginning of control point
|
||
|
|
$R sub ij$
|
||
|
|
and the beginning of control point
|
||
|
|
$R sub { (i+1) j }$,
|
||
|
|
where $i$ and $j$ are the $u$ and $v$ control point indices, respectively.
|
||
|
|
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. The initial value of \f2ustride\fP is 0.
|
||
|
|
.TP
|
||
|
|
\f2uorder\fP
|
||
|
|
Specifies the dimension of the control point array in the $u$ axis.
|
||
|
|
Must be positive. The initial value is 1.
|
||
|
|
.TP
|
||
|
|
\f2v1\fP, \f2v2\fP
|
||
|
|
Specify a linear mapping of $v$,
|
||
|
|
as presented to \%\f3glEvalCoord2\fP,
|
||
|
|
to $v hat$,
|
||
|
|
one of the two variables that are evaluated by the equations specified
|
||
|
|
by this command. Initially, \f2v1\fP is 0 and \f2v2\fP is 1.
|
||
|
|
.TP
|
||
|
|
\f2vstride\fP
|
||
|
|
Specifies the number of floats or doubles between
|
||
|
|
the beginning of control point
|
||
|
|
$R sub ij$
|
||
|
|
and the beginning of control point
|
||
|
|
$R sub { i (j+1) }$,
|
||
|
|
where $i$ and $j$ are the $u$ and $v$ control point indices, respectively.
|
||
|
|
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. The initial value of \f2vstride\fP is 0.
|
||
|
|
.TP
|
||
|
|
\f2vorder\fP
|
||
|
|
Specifies the dimension of the control point array in the $v$ axis.
|
||
|
|
Must be positive. The initial value is 1.
|
||
|
|
.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 on 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 surfaces used in computer graphics,
|
||
|
|
including B-spline surfaces,
|
||
|
|
NURBS surfaces,
|
||
|
|
Bezier surfaces, and so on.
|
||
|
|
.P
|
||
|
|
Evaluators define surfaces based on bivariate Bernstein polynomials.
|
||
|
|
Define $p ( u hat , v hat ) $ as
|
||
|
|
.ce
|
||
|
|
.sp
|
||
|
|
.EQ
|
||
|
|
p ( u hat , v hat ) ~~=~~
|
||
|
|
down 30 {{size 18 {sum}} from {size 8 {i~=~0}} to {size 9 {n}} } ~
|
||
|
|
{{size 18 {sum}} from {size 8 {j~=~0}} to {size 9 {m}} } ~
|
||
|
|
up 15 { B sub i sup n ( u hat ) ~ B sub j sup m ( v hat ) ~ R sub ij }
|
||
|
|
.EN
|
||
|
|
.sp
|
||
|
|
.P
|
||
|
|
where $R sub ij$ is a control point,
|
||
|
|
$B sub i sup n ( u hat )$
|
||
|
|
is the $i$th Bernstein polynomial of degree
|
||
|
|
.br
|
||
|
|
$n$ (\f2uorder\fP = $n ~+~ 1$)
|
||
|
|
.ce
|
||
|
|
.sp
|
||
|
|
.EQ
|
||
|
|
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 }
|
||
|
|
.EN
|
||
|
|
.sp
|
||
|
|
and $B sub j sup m ( v hat )$
|
||
|
|
is the $j$th Bernstein polynomial of degree $m$ (\f2vorder\fP = $m ~+~ 1$)
|
||
|
|
.ce
|
||
|
|
.sp
|
||
|
|
.EQ
|
||
|
|
B sub j sup m ( v hat ) ~~=~~ left ( ^down 20 {cpile { m above j }} ~^ right ) v hat sup j ( 1 - v hat ) sup { m - j }
|
||
|
|
.EN
|
||
|
|
.sp
|
||
|
|
Recall that
|
||
|
|
.ce
|
||
|
|
$0 sup 0 ~==~ 1 $ and $ left ( ^ down 20 {cpile { n above 0 }} ~^ right ) ~~==~~ 1 $
|
||
|
|
.sp
|
||
|
|
\%\f3glMap2\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.
|
||
|
|
When \%\f3glEvalCoord2\fP presents values $u$ and $v$,
|
||
|
|
the bivariate Bernstein polynomials are evaluated using $u hat$ and $v hat$,
|
||
|
|
where
|
||
|
|
.sp
|
||
|
|
.ce
|
||
|
|
$u hat ~~=~~ {u ~-~ "u1"} over {"u2" ~-~ "u1"}$
|
||
|
|
.sp
|
||
|
|
.ce
|
||
|
|
$v hat ~~=~~ {v ~-~ "v1"} over {"v2" ~-~ "v1"}$
|
||
|
|
.sp
|
||
|
|
\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_MAP2_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_MAP2_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_MAP2_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_MAP2_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_MAP2_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_MAP2_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_MAP2_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_MAP2_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_MAP2_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
|
||
|
|
\f2ustride\fP,
|
||
|
|
\f2uorder\fP,
|
||
|
|
\f2vstride\fP,
|
||
|
|
\f2vorder\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.
|
||
|
|
There are $ "uorder" ~times~ "vorder" $ control points in the array.
|
||
|
|
\f2ustride\fP specifies how many float or double locations are skipped to advance
|
||
|
|
the internal memory pointer from control point
|
||
|
|
$R sub {i j} $ to control point $R sub {(i+1) j} $.
|
||
|
|
\f2vstride\fP specifies how many float or double locations are skipped to advance
|
||
|
|
the internal memory pointer from control point
|
||
|
|
$R sub {i j} $ to control point $R sub {i (j+1) } $.
|
||
|
|
.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 \%\f3glMap2\fP before \%\f3glMap2\fP
|
||
|
|
returns.
|
||
|
|
Changes to the contents of \f2points\fP have no effect after \%\f3glMap2\fP is called.
|
||
|
|
.P
|
||
|
|
Initially, \%\f3GL_AUTO_NORMAL\fP is enabled. If \%\f3GL_AUTO_NORMAL\fP is enabled,
|
||
|
|
normal vectors are generated when either
|
||
|
|
\%\f3GL_MAP2_VERTEX_3\fP or \%\f3GL_MAP2_VERTEX_4\fP is used to generate
|
||
|
|
vertices.
|
||
|
|
.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,
|
||
|
|
or if \f2v1\fP is equal to \f2v2\fP.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_VALUE\fP is generated if either \f2ustride\fP or \f2vstride\fP
|
||
|
|
is less than the number of values in a control point.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_VALUE\fP is generated if either \f2uorder\fP or \f2vorder\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 \%\f3glMap2\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 \%\f3glMap2\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_MAP2_VERTEX_3\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP2_VERTEX_4\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP2_INDEX\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP2_COLOR_4\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP2_NORMAL\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP2_TEXTURE_COORD_1\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP2_TEXTURE_COORD_2\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP2_TEXTURE_COORD_3\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_MAP2_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,
|
||
|
|
\%\f3glMap1(3G)\fP,
|
||
|
|
\%\f3glMapGrid(3G)\fP,
|
||
|
|
\%\f3glNormal(3G)\fP,
|
||
|
|
\%\f3glTexCoord(3G)\fP,
|
||
|
|
\%\f3glVertex(3G)\fP
|