gluTessCallback  -  define  a  callback for a tessellation
       object



C SPECIFICATION

       void gluTessCallback( GLUtesselator* tess,
                             GLenum which,
                             _GLUfuncptr CallBackFunc )



PARAMETERS

       tess          Specifies the tessellation  object  (created
                     with gluNewTess).

       which         Specifies  the  callback  being defined. The
                     following values are valid:  GLU_TESS_BEGIN,
                     GLU_TESS_BEGIN_DATA,     GLU_TESS_EDGE_FLAG,
                     GLU_TESS_EDGE_FLAG_DATA,    GLU_TESS_VERTEX,
                     GLU_TESS_VERTEX_DATA,          GLU_TESS_END,
                     GLU_TESS_END_DATA,         GLU_TESS_COMBINE,
                     GLU_TESS_COMBINE_DATA,  GLU_TESS_ERROR,  and
                     GLU_TESS_ERROR_DATA.

       CallBackFunc  Specifies the function to be called.


DESCRIPTION

       gluTessCallback is used to indicate a callback to be  used
       by  a  tessellation  object.  If the specified callback is
       already defined, then it is replaced. If  CallBackFunc  is
       NULL, then the existing callback becomes undefined.

       These  callbacks  are  used  by the tessellation object to
       describe how a polygon specified by  the  user  is  broken
       into  triangles.  Note that there are two versions of each
       callback: one with user-specified  polygon  data  and  one
       without.  If  both  versions  of a particular callback are
       specified, then the callback with  user-specified  polygon
       data  will  be  used. Note that the polygon_data parameter
       used by some of the functions is a  copy  of  the  pointer
       that  was  specified  when gluTessBeginPolygon was called.
       The legal callbacks are as follows:

       GLU_TESS_BEGIN
                 The begin callback is invoked  like  glBegin  to
                 indicate  the  start  of a (triangle) primitive.
                 The function takes a  single  argument  of  type
                 GLenum.  If  the GLU_TESS_BOUNDARY_ONLY property
                 is set to GL_FALSE, then the argument is set  to
                 either  GL_TRIANGLE_FAN,  GL_TRIANGLE_STRIP,  or
                 GL_TRIANGLES.  If   the   GLU_TESS_BOUNDARY_ONLY
                 property  is  set  to GL_TRUE, then the argument
                 will be set to GL_LINE_LOOP. The function proto-
                 The  function  takes  a single boolean flag that
                 indicates which edges lie on the polygon  bound-
                 ary.  If  the  flag is GL_TRUE, then each vertex
                 that follows begins an edge  that  lies  on  the
                 polygon  boundary,  that  is, an edge that sepa-
                 rates an interior region from an  exterior  one.
                 If  the  flag is GL_FALSE, then each vertex that
                 follows begins an edge that lies in the  polygon
                 interior. The edge flag callback (if defined) is
                 invoked before the first vertex callback.

                 Since triangle fans and triangle strips  do  not
                 support  edge  flags,  the begin callback is not
                 called with GL_TRIANGLE_FAN or GL_TRIANGLE_STRIP
                 if  a  non-NULL  edge flag callback is provided.
                 (If the callback is initialized to  NULL,  there
                 is  no impact on performance). Instead, the fans
                 and strips are converted to  independent  trian-
                 gles.  The  function prototype for this callback
                 is:
                 void edgeFlag ( GLboolean flag );

       GLU_TESS_EDGE_FLAG_DATA
                 The  same  as  the  GLU_TESS_EDGE_FLAG  callback
                 except that it takes an additional pointer argu-
                 ment. This pointer is identical  to  the  opaque
                 pointer  provided  when  gluTessBeginPolygon was
                 called. The function prototype for this callback
                 is:
                 void  edgeFlagData ( GLboolean flag, void *poly-
                 gon_data );

       GLU_TESS_VERTEX
                 The vertex callback is invoked between the begin
                 and  end  callbacks.  It is similar to glVertex,
                 and it defines the  vertices  of  the  triangles
                 created  by  the tessellation process. The func-
                 tion takes a pointer as its only argument.  This
                 pointer  is identical to the opaque pointer pro-
                 vided by the user when the vertex was  described
                 (see  gluTessVertex). The function prototype for
                 this callback is:
                 void vertex ( void *vertex_data );

       GLU_TESS_VERTEX_DATA
                 The same as the GLU_TESS_VERTEX callback  except
                 that  it  takes  an additional pointer argument.
                 This pointer is identical to the opaque  pointer
                 provided  when  gluTessBeginPolygon  was called.
                 The function prototype for this callback is:
                 void vertexData ( void *vertex_data, void *poly-
                 gon_data );
                 void endData ( void *polygon_data);

       GLU_TESS_COMBINE
                 The combine callback is called to create  a  new
                 vertex  when  the tessellation detects an inter-
                 section, or wishes to merge features. The  func-
                 tion  takes  four  arguments:  an array of three
                 elements each of type GLdouble, an array of four
                 pointers, an array of four elements each of type
                 GLfloat, and a pointer to a pointer. The  proto-
                 type is:
                 void  combine(  GLdouble  coords[3],  void *ver-
                 tex_data[4],
                               GLfloat weight[4], void  **outData
                 );

                 The vertex is defined as a linear combination of
                 up to four existing  vertices,  stored  in  ver-
                 tex_data.  The coefficients of the linear combi-
                 nation are given by weight; these weights always
                 add up to 1.  All vertex pointers are valid even
                 when some of the weights are  0.   coords  gives
                 the location of the new vertex.

                 The  user must allocate another vertex, interpo-
                 late parameters using  vertex_data  and  weight,
                 and  return  the  new vertex pointer in outData.
                 This handle is supplied during  rendering  call-
                 backs.   The user is responsible for freeing the
                 memory  some  time  after  gluTessEndPolygon  is
                 called.

                 For example, if the polygon lies in an arbitrary
                 plane in 3-space, and a color is associated with
                 each vertex, the GLU_TESS_COMBINE callback might
                 look like this:
                 void  myCombine(  GLdouble   coords[3],   VERTEX
                 *d[4],
                                 GLfloat w[4], VERTEX **dataOut )
                 {
                    VERTEX *new = new_vertex();

                    new->x = coords[0];
                    new->y = coords[1];
                    new->z = coords[2];
                    new->r  =  w[0]*d[0]->r  +   w[1]*d[1]->r   +
                 w[2]*d[2]->r + w[3]*d[3]->r;
                    new->g   =   w[0]*d[0]->g  +  w[1]*d[1]->g  +
                 w[2]*d[2]->g + w[3]*d[3]->g;
                    new->b  =  w[0]*d[0]->b  +   w[1]*d[1]->b   +
                 w[2]*d[2]->b + w[3]*d[3]->b;
                    new->a   =   w[0]*d[0]->a  +  w[1]*d[1]->a  +

                 This pointer is identical to the opaque  pointer
                 provided  when  gluTessBeginPolygon  was called.
                 The function prototype for this callback is:
                 void  combineData  (  GLdouble  coords[3],  void
                 *vertex_data[4],
                                    GLfloat    weight[4],    void
                 **outData,
                                    void *polygon_data );

       GLU_TESS_ERROR
                 The error callback is called when  an  error  is
                 encountered. The one argument is of type GLenum;
                 it indicates the specific  error  that  occurred
                 and     will     be     set     to     one    of
                 GLU_TESS_MISSING_BEGIN_POLYGON,
                 GLU_TESS_MISSING_END_POLYGON,
                 GLU_TESS_MISSING_BEGIN_CONTOUR,
                 GLU_TESS_MISSING_END_CONTOUR,
                 GLU_TESS_COORD_TOO_LARGE,
                 GLU_TESS_NEED_COMBINE_CALLBACK                or
                 GLU_OUT_OF_MEMORY. Character strings  describing
                 these   errors   can   be   retrieved  with  the
                 gluErrorString call. The function prototype  for
                 this callback is:
                 void error ( GLenum errno );

                 The GLU library will recover from the first four
                 errors  by  inserting   the   missing   call(s).
                 GLU_TESS_COORD_TOO_LARGE   indicates  that  some
                 vertex coordinate exceeded the  predefined  con-
                 stant  GLU_TESS_MAX_COORD in absolute value, and
                 that the value  has  been  clamped.  (Coordinate
                 values  must  be small enough so that two can be
                 multiplied    together    without     overflow.)
                 GLU_TESS_NEED_COMBINE_CALLBACK   indicates  that
                 the  tessellation   detected   an   intersection
                 between  two  edges  in  the input data, and the
                 GLU_TESS_COMBINE or GLU_TESS_COMBINE_DATA  call-
                 back  was  not provided. No output is generated.
                 GLU_OUT_OF_MEMORY indicates that  there  is  not
                 enough memory so no output is generated.

       GLU_TESS_ERROR_DATA
                 The  same  as the GLU_TESS_ERROR callback except
                 that it takes an  additional  pointer  argument.
                 This  pointer is identical to the opaque pointer
                 provided when  gluTessBeginPolygon  was  called.
                 The function prototype for this callback is:
                 void  errorData  (  GLenum  errno,  void  *poly-
                 gon_data );


EXAMPLE

       every time it is rendered.


SEE ALSO

       glBegin, glEdgeFlag, glVertex, gluNewTess, gluErrorString,
       gluTessVertex,  gluTessBeginPolygon,  gluTessBeginContour,
       gluTessProperty, gluTessNormal




                                                                1