readme

Mesa is an open-source implementation of the OpenGL specification - a system for rendering interacti

/*
** $Header: /home/krh/git/sync/mesa-cvs-repo/Mesa/src/glu/sgi/libtess/README,v 1.1 2001/03/17 00:25:41 brianp Exp $
*/

General Polygon Tesselation
---------------------------

  This note describes a tesselator for polygons consisting of one or
  more closed contours.  It is backward-compatible with the current
  OpenGL Utilities tesselator, and is intended to replace it.  Here is
  a summary of the major differences:

   - input contours can be intersecting, self-intersecting, or degenerate.
  
   - supports a choice of several winding rules for determining which parts
     of the polygon are on the "interior".  This makes it possible to do
     CSG operations on polygons.
  
   - boundary extraction: instead of tesselating the polygon, returns a
     set of closed contours which separate the interior from the exterior.
  
   - returns the output as a small number of triangle fans and strips,
     rather than a list of independent triangles (when possible).
  
   - output is available as an explicit mesh (a quad-edge structure),
     in addition to the normal callback interface.
  
   - the algorithm used is extremely robust.


The interface
-------------

  The tesselator state is maintained in a "tesselator object".
  These are allocated and destroyed using

     GLUtesselator *gluNewTess( void );
     void gluDeleteTess( GLUtesselator *tess );

  Several tesselator objects may be used simultaneously.

  Inputs
  ------
  
  The input contours are specified with the following routines:

     void gluTessBeginPolygon( GLUtesselator *tess );
     void gluTessBeginContour( GLUtesselator *tess );
     void gluTessVertex( GLUtesselator *tess, GLUcoord coords[3], void *data );
     void gluTessEndContour( GLUtesselator *tess );
     void gluTessEndPolygon( GLUtesselator *tess );

  Within each BeginPolygon/EndPolygon pair, there can be zero or more
  calls to BeginContour/EndContour.  Within each contour, there are zero
  or more calls to gluTessVertex().  The vertices specify a closed
  contour (the last vertex of each contour is automatically linked to
  the first).

  "coords" give the coordinates of the vertex in 3-space.  For useful
  results, all vertices should lie in some plane, since the vertices
  are projected onto a plane before tesselation.  "data" is a pointer
  to a user-defined vertex structure, which typically contains other
  information such as color, texture coordinates, normal, etc.  It is
  used to refer to the vertex during rendering.

  The library can be compiled in single- or double-precision; the type
  GLUcoord represents either "float" or "double" accordingly.  The GLU
  version will be available in double-precision only.  Compile with
  GLU_TESS_API_FLOAT defined to get the single-precision version.

  When EndPolygon is called, the tesselation algorithm determines
  which regions are interior to the given contours, according to one
  of several "winding rules" described below.  The interior regions
  are then tesselated, and the output is provided as callbacks.


  Rendering Callbacks
  -------------------

  Callbacks are specified by the client using

     void gluTessCallback( GLUtesselator *tess, GLenum which, void (*fn)());

  If "fn" is NULL, any previously defined callback is discarded.
  
  The callbacks used to provide output are:	/* which == */

     void begin( GLenum type );			/* GLU_TESS_BEGIN */
     void edgeFlag( GLboolean flag );		/* GLU_TESS_EDGE_FLAG */
     void vertex( void *data );			/* GLU_TESS_VERTEX */
     void end( void );				/* GLU_TESS_END */

  Any of the callbacks may be left undefined; if so, the corresponding
  information will not be supplied during rendering.

  The "begin" callback indicates the start of a primitive; type is one
  of GL_TRIANGLE_STRIP, GL_TRIANGLE_FAN, or GL_TRIANGLES (but see the
  notes on "boundary extraction" below).
  
  It is followed by any number of "vertex" callbacks, which supply the
  vertices in the same order as expected by the corresponding glBegin()
  call.  After the last vertex of a given primitive, there is a callback
  to "end".

  If the "edgeFlag" callback is provided, no triangle fans or strips
  will be used.  When edgeFlag is called, if "flag" is GL_TRUE then each
  vertex which follows begins an edge which lies on the polygon boundary
  (ie. an edge which separates an interior region from an exterior one).
  If "flag" is GL_FALSE, each vertex which follows begins an edge which lies
  in the polygon interior.  "edgeFlag" will be called before the first
  call to "vertex".

  Other Callbacks
  ---------------

   void mesh( GLUmesh *mesh );			/* GLU_TESS_MESH */

   - Returns an explicit mesh, represented using the quad-edge structure
     (Guibas/Stolfi '85).  Other implementations of this interface might
     use a different mesh structure, so this is available only only as an
     SGI extension.  When the mesh is no longer needed, it should be freed
     using

	void gluDeleteMesh( GLUmesh *mesh );

     There is a brief description of this data structure in the include
     file "mesh.h".  For the full details, see L. Guibas and J. Stolfi,
     Primitives for the manipulation of general subdivisions and the
     computation of Voronoi diagrams, ACM Transactions on Graphics,
     4(2):74-123, April 1985.  For an introduction, see the course notes
     for CS348a, "Mathematical Foundations of Computer Graphics",
     available at the Stanford bookstore (and taught during the fall
     quarter).

   void error( GLenum errno );			/* GLU_TESS_ERROR */

   - errno is 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

     The first four are obvious.  The interface recovers from these
     errors by inserting the missing call(s).
  
     GLU_TESS_COORD_TOO_LARGE says that some vertex coordinate exceeded
     the predefined constant 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 says that the algorithm detected an
     intersection between two edges in the input data, and the "combine"
     callback (below) was not provided.  No output will be generated.


   void combine( GLUcoord coords[3], void *data[4],	/* GLU_TESS_COMBINE */
		 GLUcoord weight[4], void **outData );

   - When the algorithm detects an intersection, or wishes to merge
     features, it needs to create a new vertex.  The vertex is defined
     as a linear combination of up to 4 existing vertices, referenced
     by data[0..3].  The coefficients of the linear combination are
     given by weight[0..3]; these weights always sum to 1.0.  All vertex
     pointers are valid even when some of the weights are zero.
     "coords" gives the location of the new vertex.

     The user must allocate another vertex, interpolate parameters
     using "data" and "weights", and return the new vertex pointer in
     "outData".  This handle is supplied during rendering callbacks.
     For example, if the polygon lies in an arbitrary plane in 3-space,
     and we associate a color with each vertex, the combine callback might
     look like this:
    
     void myCombine( GLUcoord coords[3], VERTEX *d[4],
                     GLUcoord 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 + w[2]*d[2]->a + w[3]*d[3]->a;
        *dataOut = new;
     }

     If the algorithm detects an intersection, then the "combine" callback
     must be defined, and must write a non-NULL pointer into "dataOut".
     Otherwise the GLU_TESS_NEED_COMBINE_CALLBACK error occurs, and no
     output is generated.  This is the only error that can occur during
     tesselation and rendering.


  Control over Tesselation
  ------------------------
  
   void gluTessProperty( GLUtesselator *tess, GLenum which, GLUcoord value );

   Properties defined:

    - GLU_TESS_WINDING_RULE.  Possible values:

	  GLU_TESS_WINDING_ODD
	  GLU_TESS_WINDING_NONZERO
	  GLU_TESS_WINDING_POSITIVE
	  GLU_TESS_WINDING_NEGATIVE
	  GLU_TESS_WINDING_ABS_GEQ_TWO

      The input contours parition the plane into regions.  A winding
      rule determines which of these regions are inside the polygon.
      
      For a single contour C, the winding number of a point x is simply
      the signed number of revolutions we make around x as we travel
      once around C (where CCW is positive).  When there are several
      contours, the individual winding numbers are summed.  This
      procedure associates a signed integer value with each point x in
      the plane.  Note that the winding number is the same for all
      points in a single region.

      The winding rule classifies a region as "inside" if its winding
      number belongs to the chosen category (odd, nonzero, positive,