NAME

       gleTextureMode - set the type of GLE automatic texture coordinate generation.

SYNTAX

       void gleTextureMode (int mode);

ARGUMENTS

       mode      bitwise OR of GLE texture mode flags

DESCRIPTION

       In  addition to the default glTexGen modes that are supplied by OpenGL, the tubing library
       also contains some of  its  own  automatic  texture  coordinate  generation  routines.  In
       addition, user-defined texture coord generation routines can be supplied.

       To use texture mapping with the extrusion library, one must remember to "do the obvious":

              Enable texture mapping through OpenGL

              Define and load (glTexImage2D/glBindTexture) a texture

              If using the routine below, then disable glTexgGen

       gleTextureMode  can  be used to set the type of automatic texture coordinate generation to
       be used. The argument should be a bitwise-OR of any of the following flags:

       GLE_TEXTURE_ENABLE
              If this bit is set, then texturing is  enabled.  If  this  bit  is  NOT  set,  then
              automatic texture coordinate generation is disabled.

       The  way  in which the automatic texture coordinate generation occurs is determined by one
       of the following flags. One and only one of these should be  selected  at  a  time.  These
       tokens are enumerants, not bit-flags.

       GLE_TEXTURE_VERTEX_FLAT
              Uses the vertexes "x" coordinate as the texture "u" coordinate, and the accumulated
              segment length as the "v" coordinate.

       GLE_TEXTURE_NORMAL_FLAT
              Uses the normal vector's "x" coordinate as the  texture  "u"  coordinate,  and  the
              accumulated segment length as the "v" coordinate.

       GLE_TEXTURE_VERTEX_CYL
              Uses  u = phi/(2*pi) = arctan (vy/vx)/(2*pi) as the texture "u" coordinate, and the
              accumulated segment length as the "v" coordinate.  In the above equation, "vx"  and
              "vy" stand for the vertex's x and y coordinates.

       GLE_TEXTURE_NORMAL_CYL
              Uses  u = phi/(2*pi) = arctan (ny/nx)/(2*pi) as the texture "u" coordinate, and the
              accumulated segment length as the "v" coordinate.  In the above equation, "nx"  and
              "ny" stand for the normal's x and y coordinates.

       GLE_TEXTURE_VERTEX_SPH
              Uses  u = phi/(2*pi) = arctan (vy/vx)/(2*pi) as the texture "u" coordinate, and v =
              theta/pi = (1.0 - arccos(vz))/pi as  the  texture  "v"  coordinate.  In  the  above
              equation, "vx","vy" and "vz" stand for the vertex's x, y and z coordinates.

       GLE_TEXTURE_NORMAL_SPH
              Uses  u = phi/(2*pi) = arctan (ny/nx)/(2*pi) as the texture "u" coordinate, and v =
              theta/pi = (1.0 - arccos(nz))/pi as  the  texture  "v"  coordinate.  In  the  above
              equation, "nx","ny" and "nz" stand for the normal's x, y and z coordinates.

       GLE_TEXTURE_VERTEX_MODEL_FLAT

       GLE_TEXTURE_NORMAL_MODEL_FLAT

       GLE_TEXTURE_VERTEX_MODEL_CYL

       GLE_TEXTURE_NORMAL_MODEL_CYL

       GLE_TEXTURE_VERTEX_MODEL_SPH

       GLE_TEXTURE_NORMAL_MODEL_SPH
              These  define texture mapping modes that are very similar to those described above,
              except that the untransformed vertices  and/or  normals  are  used.  As  a  result,
              textures  tends to stick to the extrusion according to the extrusions local surface
              coordinates rather than according to real-space coordinates. This will  in  general
              provide  the  correct  style  of  texture  mapping when affine transforms are being
              applied to the contour, since the coordinates used are those prior  to  the  affine
              transform.

OPERATION

       To best understand how to use the above functions, it is best to understand how the tubing
       is actually drawn. Let us start by defining some terms. The tubing  library  "extrudes"  a
       "contour" along a "path".  The contour is a 2D polyline. The path is a 3D polyline. We use
       the word "segment" to refer to a straight-line segment  of  the  path  polyline.  We  also
       interchangeably use the word "segment" to stand for the section of the extrusion that lies
       along a path segment.

       The tubing library draws segments one at a time. It uses glPushmatrix() and  glPopmatrix()
       to  orient  each  segment along the negative z-axis. The segment starts at z=0 and ends at
       some negative z-value (equal to the length of the segment). The segment is then  drawn  by
       calling  glVertex3f()  (and  glNormal3F())  by  drawing the 2D contour at z=0 and again at
       z=-len. (Of course, if the join style is one of the fancy ones, then  the  end-points  are
       trimmed  in a variety of ways, and do not land exactly on z=0, or z=-len, but they do come
       close). Note that glBegin() and glEnd() are called around each segment.  (Note  also  that
       additional  glBegins/Ends  may  be  called to draw end-caps or filleting triangles for the
       more complex join styles.)

       The obvious way  to  automatically  generate  textures  is  to  warp  the  glVertex()  and
       glNormal()  functions,  and  compute  texture  coordinates based on the 3-space vertex and
       normal coordinates. This is essentially what the tubing code does, except that  it  passes
       some  extra parameters.  The glBegin calls are wrapped, and the integer segment number and
       the floating-point length of the segment are passed in. By knowing the segment number, and
       the segment length, the texture coordinates can be adjusted. Knowing the length allows the
       length to be accumulated, so that a texture is applied lengthwise along the extrusion.  It
       is this accumulated length that is used in the FLAT and CYL mapping modes.

       For  each vertex, not only are the vertex x,y,z coordinates available, but so is a contour
       vertex counter indicating which contour vertex this corresponds to. There is also  a  flag
       indicating  whether the vertex corresponds to a front or back vertex (i.e. a z=0 or z=-len
       vertex).  Again, this info can be used to avoid confusion when drawing  the  more  complex
       join styles.

HINTS

       Here are a few hints, tips, and techniques:

       o      Hint:  Confused?  RUN  THE DEMOS! The best way to understand what all the different
              texture modes are doing is to see them in action.

       o      Hint: The texture matrix can be used to  your  advantage!  That  is,  you  can  use
              glMatrixMode(GL_TEXTURE)  to  control  how  textures  are mapped to the surface. In
              particular, you may/will want to use it to to rescale the V coordinate.

       o      The origin of the contour will in general change  the  vertex  x's  and  y's,  thus
              changing the texture coordinates.

       o      The contour "up" vector will NOT influence the texture coordinates.

       o      For the FLAT and CYL modes, the accumulated length really is the accumulated length
              of the segments in modeling coordinates. Unless the extrusion is very  small,  this
              length  will  probably  be  much  larger  than  1.0,  and  so the resulting texture
              coordinate will wrap. You will generally want to rescale the "V" coordinate to make
              the texture map fit.

       o      If  the  texture is "swimming" around on the surface in an undesired way, try using
              the "MODEL" version of the texture generation flag.

       o      Typically, you will NOT want to use the "SPH" versions of  the  texture  generation
              engine  unless you really, really have an extrusion for which spherical coordinates
              are appropriate. Most uses of extrusions are best handled with the "FLAT" and "CYL"
              generation methods.

       o      User-defined  texture generation callbacks are not currently implemented, but these
              should be very, very easy to hack in as desired.  It should be  easy  to  let  your
              imagination  run  wild in here. Look at texgen.c -- what needs to be done should be
              obvious, I hope.  When in doubt, experiment.

BUGS

       Multiple threads using GLE share a single texture mode.

SEE ALSO

       gleExtrusion, gleSetJoinStyle

AUTHOR

       Linas Vepstas (linas@linas.org)