271 lines
7.9 KiB
Plaintext
271 lines
7.9 KiB
Plaintext
'\" e
|
|
'\"! 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 texgen.gl
|
|
.ds Xs 27155 9 texgen.gl
|
|
.TH GLTEXGEN 3G
|
|
.SH NAME
|
|
.B "glTexGend, glTexGenf, glTexGeni, glTexGendv, glTexGenfv, glTexGeniv
|
|
\- control the generation of texture coordinates
|
|
|
|
.SH C SPECIFICATION
|
|
void \f3glTexGend\fP(
|
|
GLenum \fIcoord\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglTexGend( 'u
|
|
GLenum \fIpname\fP,
|
|
GLdouble \fIparam\fP )
|
|
.fi
|
|
void \f3glTexGenf\fP(
|
|
GLenum \fIcoord\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglTexGenf( 'u
|
|
GLenum \fIpname\fP,
|
|
GLfloat \fIparam\fP )
|
|
.fi
|
|
void \f3glTexGeni\fP(
|
|
GLenum \fIcoord\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglTexGeni( 'u
|
|
GLenum \fIpname\fP,
|
|
GLint \fIparam\fP )
|
|
.fi
|
|
|
|
.EQ
|
|
delim $$
|
|
.EN
|
|
.SH PARAMETERS
|
|
.TP \w'\fIparams\fP\ \ 'u
|
|
\f2coord\fP
|
|
Specifies a texture coordinate.
|
|
Must be one of \%\f3GL_S\fP, \%\f3GL_T\fP, \%\f3GL_R\fP, or \%\f3GL_Q\fP.
|
|
.TP
|
|
\f2pname\fP
|
|
Specifies the symbolic name of the texture-coordinate generation function.
|
|
Must be \%\f3GL_TEXTURE_GEN_MODE\fP.
|
|
.TP
|
|
\f2param\fP
|
|
Specifies a single-valued texture generation parameter,
|
|
one of \%\f3GL_OBJECT_LINEAR\fP, \%\f3GL_EYE_LINEAR\fP, or \%\f3GL_SPHERE_MAP\fP.
|
|
.SH C SPECIFICATION
|
|
void \f3glTexGendv\fP(
|
|
GLenum \fIcoord\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglTexGendv( 'u
|
|
GLenum \fIpname\fP,
|
|
const GLdouble \fI*params\fP )
|
|
.fi
|
|
void \f3glTexGenfv\fP(
|
|
GLenum \fIcoord\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglTexGenfv( 'u
|
|
GLenum \fIpname\fP,
|
|
const GLfloat \fI*params\fP )
|
|
.fi
|
|
void \f3glTexGeniv\fP(
|
|
GLenum \fIcoord\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglTexGeniv( 'u
|
|
GLenum \fIpname\fP,
|
|
const GLint \fI*params\fP )
|
|
.fi
|
|
|
|
.SH PARAMETERS
|
|
.TP
|
|
\f2coord\fP
|
|
Specifies a texture coordinate.
|
|
Must be one of \%\f3GL_S\fP, \%\f3GL_T\fP, \%\f3GL_R\fP, or \%\f3GL_Q\fP.
|
|
.TP
|
|
\f2pname\fP
|
|
Specifies the symbolic name of the texture-coordinate generation function
|
|
or function parameters.
|
|
Must be
|
|
\%\f3GL_TEXTURE_GEN_MODE\fP,
|
|
\%\f3GL_OBJECT_PLANE\fP, or
|
|
\%\f3GL_EYE_PLANE\fP.
|
|
.TP
|
|
\f2params\fP
|
|
Specifies a pointer to an array of texture generation parameters.
|
|
If \f2pname\fP is \%\f3GL_TEXTURE_GEN_MODE\fP,
|
|
then the array must contain a single symbolic constant,
|
|
one of
|
|
\%\f3GL_OBJECT_LINEAR\fP,
|
|
\%\f3GL_EYE_LINEAR\fP, or
|
|
\%\f3GL_SPHERE_MAP\fP.
|
|
Otherwise,
|
|
\f2params\fP holds the coefficients for the texture-coordinate generation function
|
|
specified by \f2pname\fP.
|
|
.SH DESCRIPTION
|
|
\%\f3glTexGen\fP selects a texture-coordinate generation function
|
|
or supplies coefficients for one of the functions.
|
|
\f2coord\fP names one of the (\f2s\fP, \f2t\fP, \f2r\fP, \f2q\fP) texture
|
|
coordinates; it must be one of the symbols
|
|
\%\f3GL_S\fP,
|
|
\%\f3GL_T\fP,
|
|
\%\f3GL_R\fP, or
|
|
\%\f3GL_Q\fP.
|
|
\f2pname\fP must be one of three symbolic constants:
|
|
\%\f3GL_TEXTURE_GEN_MODE\fP,
|
|
\%\f3GL_OBJECT_PLANE\fP, or
|
|
\%\f3GL_EYE_PLANE\fP.
|
|
If \f2pname\fP is \%\f3GL_TEXTURE_GEN_MODE\fP,
|
|
then \f2params\fP chooses a mode,
|
|
one of
|
|
\%\f3GL_OBJECT_LINEAR\fP,
|
|
\%\f3GL_EYE_LINEAR\fP, or
|
|
\%\f3GL_SPHERE_MAP\fP.
|
|
If \f2pname\fP is either \%\f3GL_OBJECT_PLANE\fP or \%\f3GL_EYE_PLANE\fP,
|
|
\f2params\fP contains coefficients for the corresponding
|
|
texture generation function.
|
|
.P
|
|
If the texture generation function is \%\f3GL_OBJECT_LINEAR\fP,
|
|
the function
|
|
.P
|
|
.ce
|
|
$g ~=~ p sub 1^x sub o ~+~ p sub 2^y sub o ~+~ p sub 3^z sub o ~+~ p sub 4^w sub o$
|
|
.P
|
|
.br
|
|
is used, where $g$ is the value computed for the coordinate named in \f2coord\fP,
|
|
$p sub 1$,
|
|
$p sub 2$,
|
|
$p sub 3$,
|
|
and
|
|
$p sub 4$ are the four values supplied in \f2params\fP, and
|
|
$x sub o$,
|
|
$y sub o$,
|
|
$z sub o$, and
|
|
$w sub o$ are the object coordinates of the vertex.
|
|
This function can be used, for example, to texture-map terrain using sea level
|
|
as a reference plane
|
|
(defined by $p sub 1$, $p sub 2$, $p sub 3$, and $p sub 4$).
|
|
The altitude of a terrain vertex is computed by the \%\f3GL_OBJECT_LINEAR\fP
|
|
coordinate generation function as its distance from sea level;
|
|
that altitude can then be used to index the texture image to map white snow
|
|
onto peaks and green grass onto foothills.
|
|
.P
|
|
If the texture generation function is \%\f3GL_EYE_LINEAR\fP, the function
|
|
.P
|
|
.ce
|
|
$g ~=~ p sub 1 sup prime ^x sub e ~+~ p sub 2 sup prime ^y sub e ~+~ p sub 3 sup prime ^z sub e ~+~ p sub 4 sup prime ^w sub e$
|
|
.P
|
|
.br
|
|
is used, where
|
|
.P
|
|
.ce
|
|
$( p sub 1 sup prime
|
|
~~p sub 2 sup prime~~p sub 3 sup prime~~
|
|
{ p sub 4 sup prime}) ~=~ ( p sub 1~~ p sub 2~~ p sub 3~~ p sub 4 ) ~M sup -1$
|
|
.P
|
|
.br
|
|
and
|
|
$x sub e$,
|
|
$y sub e$,
|
|
$z sub e$, and
|
|
$w sub e$ are the eye coordinates of the vertex,
|
|
$p sub 1$,
|
|
$p sub 2$,
|
|
$p sub 3$,
|
|
and
|
|
$p sub 4$ are the values supplied in \f2params\fP, and
|
|
$M$ is the modelview matrix when \%\f3glTexGen\fP is invoked.
|
|
If $M$ is poorly conditioned or singular,
|
|
texture coordinates generated by the resulting function may be inaccurate
|
|
or undefined.
|
|
.P
|
|
Note that the values in \f2params\fP define a reference plane in eye coordinates.
|
|
The modelview matrix that is applied to them may not be the same one
|
|
in effect when the polygon vertices are transformed.
|
|
This function establishes a field of texture coordinates
|
|
that can produce dynamic contour lines on moving objects.
|
|
.P
|
|
If \f2pname\fP is \%\f3GL_SPHERE_MAP\fP and \f2coord\fP is either
|
|
\%\f3GL_S\fP or
|
|
\%\f3GL_T\fP,
|
|
$s$ and $t$ texture coordinates are generated as follows.
|
|
Let \f2u\fP be the unit vector pointing from the origin to the polygon vertex
|
|
(in eye coordinates).
|
|
Let \f2n\fP sup prime be the current normal,
|
|
after transformation to eye coordinates.
|
|
Let
|
|
.P
|
|
.ce
|
|
$f ~=~ ( f sub x~~f sub y~~f sub z ) sup T$
|
|
be the reflection vector such that
|
|
.P
|
|
.ce
|
|
$f ~=~ u ~-~ 2 n sup prime n sup prime sup T u$
|
|
.br
|
|
.P
|
|
Finally, let $ m ~=~ 2 sqrt { f sub x sup {~2} ~+~ f sub y sup {~2} ~+~ (f sub z ~+~ 1 ) sup 2}$.
|
|
Then the values assigned to the $s$ and $t$ texture coordinates are
|
|
.P
|
|
.ce 1
|
|
$s ~=~ f sub x over m ~+~ 1 over 2$
|
|
.sp
|
|
.ce 1
|
|
$t ~=~ f sub y over m ~+~ 1 over 2$
|
|
.P
|
|
To enable or disable a texture-coordinate generation function, call
|
|
\%\f3glEnable\fP or \%\f3glDisable\fP
|
|
with one of the symbolic texture-coordinate names
|
|
(\%\f3GL_TEXTURE_GEN_S\fP,
|
|
\%\f3GL_TEXTURE_GEN_T\fP,
|
|
\%\f3GL_TEXTURE_GEN_R\fP, or
|
|
\%\f3GL_TEXTURE_GEN_Q\fP) as the argument.
|
|
When enabled,
|
|
the specified texture coordinate is computed
|
|
according to the generating function associated with that coordinate.
|
|
When disabled,
|
|
subsequent vertices take the specified texture coordinate
|
|
from the current set of texture coordinates. Initially, all texture
|
|
generation functions are set to \%\f3GL_EYE_LINEAR\fP and are disabled.
|
|
Both $s$ plane equations are (1, 0, 0, 0),
|
|
both $t$ plane equations are (0, 1, 0, 0),
|
|
and all $r$ and $q$ plane equations are (0, 0, 0, 0).
|
|
.P
|
|
When the \%\f3GL_ARB_multitexture\fP extension is supported, \%\f3glTexGen\fP set the
|
|
texture generation parameters for the currently active texture unit,
|
|
selected with \%\f3glActiveTextureARB\fP.
|
|
.SH ERRORS
|
|
\%\f3GL_INVALID_ENUM\fP is generated when \f2coord\fP or \f2pname\fP is not an
|
|
accepted defined value,
|
|
or when \f2pname\fP is \%\f3GL_TEXTURE_GEN_MODE\fP and \f2params\fP is not an
|
|
accepted defined value.
|
|
.P
|
|
\%\f3GL_INVALID_ENUM\fP is generated when \f2pname\fP is \%\f3GL_TEXTURE_GEN_MODE\fP,
|
|
\f2params\fP is \%\f3GL_SPHERE_MAP\fP,
|
|
and \f2coord\fP is either \%\f3GL_R\fP or \%\f3GL_Q\fP.
|
|
.P
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glTexGen\fP
|
|
is executed between the execution of \%\f3glBegin\fP
|
|
and the corresponding execution of \%\f3glEnd\fP.
|
|
.SH ASSOCIATED GETS
|
|
\%\f3glGetTexGen\fP
|
|
.br
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_TEXTURE_GEN_S\fP
|
|
.br
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_TEXTURE_GEN_T\fP
|
|
.br
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_TEXTURE_GEN_R\fP
|
|
.br
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_TEXTURE_GEN_Q\fP
|
|
.SH SEE ALSO
|
|
\%\f3glActiveTextureARB(3G)\fP,
|
|
\%\f3glCopyPixels(3G)\fP,
|
|
\%\f3glCopyTexImage2D(3G)\fP,
|
|
\%\f3glCopyTexSubImage1D(3G)\fP,
|
|
\%\f3glCopyTexSubImage2D(3G)\fP,
|
|
\%\f3glCopyTexSubImage3D(3G)\fP,
|
|
\%\f3glTexEnv(3G)\fP,
|
|
\%\f3glTexImage1D(3G)\fP,
|
|
\%\f3glTexImage2D(3G)\fP,
|
|
\%\f3glTexImage3D(3G)\fP,
|
|
\%\f3glTexParameter(3G)\fP,
|
|
\%\f3glTexSubImage1D(3G)\fP,
|
|
\%\f3glTexSubImage2D(3G)\fP,
|
|
\%\f3glTexSubImage3D(3G)\fP
|