gluTessCallback

gluTessCallback

NAME

gluTessCallback -- define a callback for a tessellation object

C SPECIFICATION

void gluTessCallback(GLUtriangulatorObj *tobj,

GLenum which,

void (*fn)() )

PARAMETERS

tobj

Specifies the tessellation object (created with gluNewTess).

which

Specifies the callback being defined. The following values are valid: GLU_BEGIN, GLU_EDGE_FLAG, GLU_VERTEX, GLU_END, and GLU_ERROR.

fn

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 fn is NULL, then the existing callback is erased.

These callbacks are used by the tessellation object to describe how a polygon specified by the user is broken into triangles.

The legal callbacks are as follows:

GLU_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 that is either GL_TRIANGLE_FAN, GL_TRIANGLE_STRIP, or GL_TRIANGLES.

GLU_EDGE_FLAG

The edge flag callback is similar to glEdgeFlag. The function takes a single Boolean flag that indicates which edges of the created triangles were part of the original polygon defined by the user, and which were created by the tessellation process. If the flag is GL_TRUE, then each vertex that follows begins an edge that was part of the original polygon. If the flag is GL_FALSE, then each vertex that follows begins an edge that was generated by the tessellator. The edge flag callback (if defined) is invoked before the first vertex callback is made.

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 an edge flag callback is provided. Instead, the fans and strips are converted to independent triangles.

GLU_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 function takes a pointer as its only argument. This pointer is identical to the opaque pointer provided by the user when the vertex was described (see gluTessVertex).

GLU_END

The end callback serves the same purpose as glEnd. It indicates the end of a primitive and it takes no arguments.

GLU_ERROR

The error callback is called when an error is encountered. The one argument is of type GLenum, and it indicates the specific error that occurred. There are eight errors unique to polygon tessellation, named GLU_TESS_ERROR1 through GLU_TESS_ERROR8. Character strings describing these errors can be retrieved with the gluErrorString call.

EXAMPLE

Polygons tessellated can be rendered directly like this:

gluTessCallback(tobj, GLU_BEGIN, glBegin);

gluTessCallback(tobj, GLU_VERTEX, glVertex3dv);

gluTessCallback(tobj, GLU_END, glEnd);

gluBeginPolygon(tobj);

gluTessVertex(tobj, v, v);

...

gluEndPolygon(tobj);

Typically, the tessellated polygon should be stored in a display list so that it does not need to be retessellated every time it is rendered.