NAME

gluTessCallback - define a callback for a tessellation object

C SPECIFICATION

void gglluuTTeessssCCaallllbbaacckk( GLUtesselator* _t_e_s_s,
                      GLenum _w_h_i_c_h,
                      _GLUfuncptr _C_a_l_l_B_a_c_k_F_u_n_c )

delim $$

PARAMETERS

_t_e_s_s
Specifies the tessellation object (created with gglluuNNeewwTTeessss).
_w_h_i_c_h
Specifies the callback being defined. The following values are valid: GGLLUU__TTEESSSS__BBEEGGIINN, GGLLUU__TTEESSSS__BBEEGGIINN__DDAATTAA, GGLLUU__TTEESSSS__EEDDGGEE__FFLLAAGG, GGLLUU__TTEESSSS__EEDDGGEE__FFLLAAGG__DDAATTAA, GGLLUU__TTEESSSS__VVEERRTTEEXX, GGLLUU__TTEESSSS__VVEERRTTEEXX__DDAATTAA, GGLLUU__TTEESSSS__EENNDD, GGLLUU__TTEESSSS__EENNDD__DDAATTAA, GGLLUU__TTEESSSS__CCOOMMBBIINNEE, GGLLUU__TTEESSSS__CCOOMMBBIINNEE__DDAATTAA, GGLLUU__TTEESSSS__EERRRROORR, and GGLLUU__TTEESSSS__EERRRROORR__DDAATTAA.
_C_a_l_l_B_a_c_k_F_u_n_c
Specifies the function to be called.

DESCRIPTION

gglluuTTeessssCCaallllbbaacckk 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 _C_a_l_l_B_a_c_k_F_u_n_c 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 _p_o_l_y_g_o_n___d_a_t_a parameter used by some of the functions is a copy of the pointer that was specified when gglluuTTeessssBBeeggiinnPPoollyyggoonn was called. The legal callbacks are as follows:

GGLLUU__TTEESSSS__BBEEGGIINN
The begin callback is invoked like ggllBBeeggiinn to indicate the start of a (triangle) primitive. The function takes a single argument of type GLenum. If the GGLLUU__TTEESSSS__BBOOUUNNDDAARRYY__OONNLLYY property is set to GGLL__FFAALLSSEE, then the argument is set to either GGLL__TTRRIIAANNGGLLEE__FFAANN, GGLL__TTRRIIAANNGGLLEE__SSTTRRIIPP, or GGLL__TTRRIIAANNGGLLEESS. If the GGLLUU__TTEESSSS__BBOOUUNNDDAARRYY__OONNLLYY property is set to GGLL__TTRRUUEE, then the argument will be set to GGLL__LLIINNEE__LLOOOOPP. The function prototype for this callback is: void begin ( GLenum type );
GGLLUU__TTEESSSS__BBEEGGIINN__DDAATTAA
The same as the GGLLUU__TTEESSSS__BBEEGGIINN callback except that it takes an additional pointer argument. This pointer is identical to the opaque pointer provided when gglluuTTeessssBBeeggiinnPPoollyyggoonn was called. The function prototype for this callback is: void beginData ( GLenum type, void *polygon_data );
GGLLUU__TTEESSSS__EEDDGGEE__FFLLAAGG
The edge flag callback is similar to ggllEEddggeeFFllaagg. The function takes a single boolean flag that indicates which edges lie on the polygon boundary. If the flag is GGLL__TTRRUUEE, then each vertex that follows begins an edge that lies on the polygon boundary, that is, an edge that separates an interior region from an exterior one. If the flag is GGLL__FFAALLSSEE, 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 GGLL__TTRRIIAANNGGLLEE__FFAANN or GGLL__TTRRIIAANNGGLLEE__SSTTRRIIPP 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 triangles. The function prototype for this callback is: void edgeFlag ( GLboolean flag );
GGLLUU__TTEESSSS__EEDDGGEE__FFLLAAGG__DDAATTAA
The same as the GGLLUU__TTEESSSS__EEDDGGEE__FFLLAAGG callback except that it takes an additional pointer argument. This pointer is identical to the opaque pointer provided when gglluuTTeessssBBeeggiinnPPoollyyggoonn was called. The function prototype for this callback is: void edgeFlagData ( GLboolean flag, void *polygon_data );
GGLLUU__TTEESSSS__VVEERRTTEEXX
The vertex callback is invoked between the begin and end callbacks. It is similar to ggllVVeerrtteexx, 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 gglluuTTeessssVVeerrtteexx). The function prototype for this callback is: void vertex ( void *vertex_data );
GGLLUU__TTEESSSS__VVEERRTTEEXX__DDAATTAA
The same as the GGLLUU__TTEESSSS__VVEERRTTEEXX callback except that it takes an additional pointer argument. This pointer is identical to the opaque pointer provided when gglluuTTeessssBBeeggiinnPPoollyyggoonn was called. The function prototype for this callback is: void vertexData ( void *vertex_data, void *polygon_data );
GGLLUU__TTEESSSS__EENNDD
The end callback serves the same purpose as ggllEEnndd. It indicates the end of a primitive and it takes no arguments. The function prototype for this callback is: void end ( void );
GGLLUU__TTEESSSS__EENNDD__DDAATTAA
The same as the GGLLUU__TTEESSSS__EENNDD callback except that it takes an additional pointer argument. This pointer is identical to the opaque pointer provided when gglluuTTeessssBBeeggiinnPPoollyyggoonn was called. The function prototype for this callback is: void endData ( void *polygon_data);
GGLLUU__TTEESSSS__CCOOMMBBIINNEE
The combine callback is called to create a new vertex when the tessellation detects an intersection, or wishes to merge features. The function 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 prototype is: void combine( GLdouble coords[3], void *vertex_data[4], GLfloat weight[4], void **outData );
The vertex is defined as a linear combination of up to four existing vertices,
stored in _v_e_r_t_e_x___d_a_t_a. The coefficients of the linear combination are given by _w_e_i_g_h_t; these weights always add up to 1. All vertex pointers are valid even when some of the weights are 0. _c_o_o_r_d_s gives the location of the new vertex.
The user must allocate another vertex, interpolate parameters using
_v_e_r_t_e_x___d_a_t_a and _w_e_i_g_h_t, and return the new vertex pointer in _o_u_t_D_a_t_a. This handle is supplied during rendering callbacks. The user is responsible for freeing the memory some time after gglluuTTeessssEEnnddPPoollyyggoonn is called.
For example, if the polygon lies in an arbitrary plane in 3-space,
and a color is associated with each vertex, the GGLLUU__TTEESSSS__CCOOMMBBIINNEE 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 + w[2]*d[2]->a + w[3]*d[3]->a; *dataOut = new; }

If the tessellation detects an intersection, then the GGLLUU__TTEESSSS__CCOOMMBBIINNEE or
GGLLUU__TTEESSSS__CCOOMMBBIINNEE__DDAATTAA callback (see below) must be defined, and it must write a non-NULL pointer into _d_a_t_a_O_u_t. Otherwise the GGLLUU__TTEESSSS__NNEEEEDD__CCOOMMBBIINNEE__CCAALLLLBBAACCKK error occurs, and no output is generated.
GGLLUU__TTEESSSS__CCOOMMBBIINNEE__DDAATTAA
The same as the GGLLUU__TTEESSSS__CCOOMMBBIINNEE callback except that it takes an additional pointer argument. This pointer is identical to the opaque pointer provided when gglluuTTeessssBBeeggiinnPPoollyyggoonn 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 );
GGLLUU__TTEESSSS__EERRRROORR
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 GGLLUU__TTEESSSS__MMIISSSSIINNGG__BBEEGGIINN__PPOOLLYYGGOONN, GGLLUU__TTEESSSS__MMIISSSSIINNGG__EENNDD__PPOOLLYYGGOONN, GGLLUU__TTEESSSS__MMIISSSSIINNGG__BBEEGGIINN__CCOONNTTOOUURR, GGLLUU__TTEESSSS__MMIISSSSIINNGG__EENNDD__CCOONNTTOOUURR, GGLLUU__TTEESSSS__CCOOOORRDD__TTOOOO__LLAARRGGEE, GGLLUU__TTEESSSS__NNEEEEDD__CCOOMMBBIINNEE__CCAALLLLBBAACCKK or GGLLUU__OOUUTT__OOFF__MMEEMMOORRYY. Character strings describing these errors can be retrieved with the gglluuEErrrroorrSSttrriinngg 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). GGLLUU__TTEESSSS__CCOOOORRDD__TTOOOO__LLAARRGGEE indicates that some vertex coordinate exceeded the predefined constant GGLLUU__TTEESSSS__MMAAXX__CCOOOORRDD 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.) GGLLUU__TTEESSSS__NNEEEEDD__CCOOMMBBIINNEE__CCAALLLLBBAACCKK indicates that the tessellation detected an intersection between two edges in the input data, and the GGLLUU__TTEESSSS__CCOOMMBBIINNEE or GGLLUU__TTEESSSS__CCOOMMBBIINNEE__DDAATTAA callback was not provided. No output is generated. GGLLUU__OOUUTT__OOFF__MMEEMMOORRYY indicates that there is not enough memory so no output is generated.
GGLLUU__TTEESSSS__EERRRROORR__DDAATTAA
The same as the GGLLUU__TTEESSSS__EERRRROORR callback except that it takes an additional pointer argument. This pointer is identical to the opaque pointer provided when gglluuTTeessssBBeeggiinnPPoollyyggoonn was called. The function prototype for this callback is: void errorData ( GLenum errno, void *polygon_data );

EXAMPLE

Polygons tessellated can be rendered directly like this:

gluTessCallback(tobj, GLU_TESS_BEGIN, glBegin); gluTessCallback(tobj, GLU_TESS_VERTEX, glVertex3dv); gluTessCallback(tobj, GLU_TESS_END, glEnd); gluTessCallback(tobj, GLU_TESS_COMBINE, myCombine); gluTessBeginPolygon(tobj, NULL); gluTessBeginContour(tobj); gluTessVertex(tobj, v, v); ... gluTessEndContour(tobj); gluTessEndPolygon(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.

SEE ALSO

ggllBBeeggiinn((33GG)), ggllEEddggeeFFllaagg((33GG)), ggllVVeerrtteexx((33GG)), gglluuNNeewwTTeessss((33GG)), gglluuEErrrroorrSSttrriinngg((33GG)), gglluuTTeessssVVeerrtteexx((33GG)), gglluuTTeessssBBeeggiinnPPoollyyggoonn((33GG)), gglluuTTeessssBBeeggiinnCCoonnttoouurr((33GG)), gglluuTTeessssPPrrooppeerrttyy((33GG)), gglluuTTeessssNNoorrmmaall((33GG))