SGI OPENGL核心库源码

/* ** $Header: /home/pub/cvs/projects/ogl-sample/main/gfx/lib/glu/libtess/README,v 1.1 2000/04/26 05:53:59 ljp 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