GLTEXGEN() MachTen Programmer’s Manual GLTEXGEN()

NAME
glTexGend, glTexGenf, glTexGeni, glTexGendv, glTexGenfv,
glTexGeniv - control the generation of texture coordinates

C SPECIFICATION
void glTexGend( GLenum coord,
GLenum pname,
GLdouble param )
void glTexGenf( GLenum coord,
GLenum pname,
GLfloat param )
void glTexGeni( GLenum coord,
GLenum pname,
GLint param )

delim $$

PARAMETERS
coord Specifies a texture coordinate. Must be one of
GL_S, GL_T, GL_R, or GL_Q.

pname Specifies the symbolic name of the texture-
coordinate generation function. Must be
GL_TEXTURE_GEN_MODE.

param Specifies a single-valued texture generation
parameter, one of GL_OBJECT_LINEAR, GL_EYE_LINEAR,
or GL_SPHERE_MAP.

C SPECIFICATION
void glTexGendv( GLenum coord,
GLenum pname,
const GLdouble *params )
void glTexGenfv( GLenum coord,
GLenum pname,
const GLfloat *params )
void glTexGeniv( GLenum coord,
GLenum pname,
const GLint *params )

PARAMETERS
coord Specifies a texture coordinate. Must be one of
GL_S, GL_T, GL_R, or GL_Q.

pname Specifies the symbolic name of the texture-
coordinate generation function or function parame-
ters. Must be GL_TEXTURE_GEN_MODE,
GL_OBJECT_PLANE, or GL_EYE_PLANE.

params Specifies a pointer to an array of texture genera-
tion parameters. If pname is GL_TEXTURE_GEN_MODE,
then the array must contain a single symbolic con-
stant, one of GL_OBJECT_LINEAR, GL_EYE_LINEAR, or
GL_SPHERE_MAP. Otherwise, params holds the coeffi-
cients for the texture-coordinate generation func-
tion specified by pname.

DESCRIPTION
glTexGen selects a texture-coordinate generation function
or supplies coefficients for one of the functions. coord
names one of the (s, t, r, q) texture coordinates; it must
be one of the symbols GL_S, GL_T, GL_R, or GL_Q. pname
must be one of three symbolic constants:
GL_TEXTURE_GEN_MODE, GL_OBJECT_PLANE, or GL_EYE_PLANE. If
pname is GL_TEXTURE_GEN_MODE, then params chooses a mode,
one of GL_OBJECT_LINEAR, GL_EYE_LINEAR, or GL_SPHERE_MAP.
If pname is either GL_OBJECT_PLANE or GL_EYE_PLANE, params
contains coefficients for the corresponding texture gener-
ation function.

If the texture generation function is GL_OBJECT_LINEAR,
the function

$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$

is used, where $g$ is the value computed for the coordi-
nate named in coord, $p sub 1$, $p sub 2$, $p sub 3$, and
$p sub 4$ are the four values supplied in params, 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 ref-
erence plane (defined by $p sub 1$, $p sub 2$, $p sub 3$,
and $p sub 4$). The altitude of a terrain vertex is com-
puted by the GL_OBJECT_LINEAR coordinate generation func-
tion 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.

If the texture generation function is GL_EYE_LINEAR, the
function

$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$

is used, where

$( {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$

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 params,
and $M$ is the modelview matrix when glTexGen is invoked.
If $M$ is poorly conditioned or singular, texture coordi-
nates generated by the resulting function may be inaccu-
rate or undefined.

Note that the values in params 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 con-
tour lines on moving objects.

If pname is GL_SPHERE_MAP and coord is either GL_S or
GL_T, $s$ and $t$ texture coordinates are generated as
follows. Let u be the unit vector pointing from the ori-
gin to the polygon vertex (in eye coordinates). Let n sup
prime be the current normal, after transformation to eye
coordinates. Let

$f ~=~ ( f sub x~~f sub y~~f sub z ) sup T$
be the reflection vector such that

$f ~=~ u ~-~ 2 n sup prime n sup prime sup T u$

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

$s ~=~ f sub x over m ~+~ 1 over 2$

$t ~=~ f sub y over m ~+~ 1 over 2$

To enable or disable a texture-coordinate generation func-
tion, call glEnable or glDisable with one of the symbolic
texture-coordinate names (GL_TEXTURE_GEN_S,
GL_TEXTURE_GEN_T, GL_TEXTURE_GEN_R, or GL_TEXTURE_GEN_Q)
as the argument. When enabled, the specified texture
coordinate is computed according to the generating func-
tion associated with that coordinate. When disabled, sub-
sequent vertices take the specified texture coordinate
from the current set of texture coordinates. Initially,
all texture generation functions are set to GL_EYE_LINEAR
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).

ERRORS
GL_INVALID_ENUM is generated when coord or pname is not an
accepted defined value, or when pname is
GL_TEXTURE_GEN_MODE and params is not an accepted defined
value.

GL_INVALID_ENUM is generated when pname is
GL_TEXTURE_GEN_MODE, params is GL_SPHERE_MAP, and coord is
either GL_R or GL_Q.

GL_INVALID_OPERATION is generated if glTexGen is executed
between the execution of glBegin and the corresponding
execution of glEnd.

ASSOCIATED GETS
glGetTexGen
glIsEnabled with argument GL_TEXTURE_GEN_S
glIsEnabled with argument GL_TEXTURE_GEN_T
glIsEnabled with argument GL_TEXTURE_GEN_R
glIsEnabled with argument GL_TEXTURE_GEN_Q

SEE ALSO
glCopyPixels, glCopyTexImage2D, glCopyTexSubImage1D,
glCopyTexSubImage2D, glTexEnv, glTexImage1D, glTexImage2D,
glTexParameter, glTexSubImage1D, glTexSubImage2D

MachTen 3