1GLUTESSCALLBACK(3G) GLUTESSCALLBACK(3G)
2
6 gluTessCallback - define a callback for a tessellation object
7
10 void gluTessCallback( GLUtesselator* tess,
11 GLenum which,
12 _GLUfuncptr CallBackFunc )
13
16 tess Specifies the tessellation object (created with
17 gluNewTess).
18 which Specifies the callback being defined. The following val‐
20 ues are valid: GLU_TESS_BEGIN, GLU_TESS_BEGIN_DATA,
21 GLU_TESS_EDGE_FLAG, GLU_TESS_EDGE_FLAG_DATA,
22 GLU_TESS_VERTEX, GLU_TESS_VERTEX_DATA, GLU_TESS_END,
23 GLU_TESS_END_DATA, GLU_TESS_COMBINE,
24 GLU_TESS_COMBINE_DATA, GLU_TESS_ERROR, and
25 GLU_TESS_ERROR_DATA.
26 CallBackFunc Specifies the function to be called.
28
30 gluTessCallback is used to indicate a callback to be used by a tessel‐
31 lation object. If the specified callback is already defined, then it
32 is replaced. If CallBackFunc is NULL, then the existing callback
33 becomes undefined.
34 These callbacks are used by the tessellation object to describe how a
36 polygon specified by the user is broken into triangles. Note that there
37 are two versions of each callback: one with user-specified polygon data
38 and one without. If both versions of a particular callback are speci‐
39 fied, then the callback with user-specified polygon data will be used.
40 Note that the polygon_data parameter used by some of the functions is a
41 copy of the pointer that was specified when gluTessBeginPolygon was
42 called. The legal callbacks are as follows:
43 GLU_TESS_BEGIN
45 The begin callback is invoked like glBegin to indicate the
46 start of a (triangle) primitive. The function takes a single
47 argument of type GLenum. If the GLU_TESS_BOUNDARY_ONLY prop‐
48 erty is set to GL_FALSE, then the argument is set to either
49 GL_TRIANGLE_FAN, GL_TRIANGLE_STRIP, or GL_TRIANGLES. If the
50 GLU_TESS_BOUNDARY_ONLY property is set to GL_TRUE, then the
51 argument will be set to GL_LINE_LOOP. The function prototype
52 for this callback is:
53 void begin ( GLenum type );
54 GLU_TESS_BEGIN_DATA
56 The same as the GLU_TESS_BEGIN callback except that it takes
57 an additional pointer argument. This pointer is identical to
58 the opaque pointer provided when gluTessBeginPolygon was
59 called. The function prototype for this callback is:
60 void beginData ( GLenum type, void *polygon_data );
61 GLU_TESS_EDGE_FLAG
63 The edge flag callback is similar to glEdgeFlag. The function
64 takes a single boolean flag that indicates which edges lie on
65 the polygon boundary. If the flag is GL_TRUE, then each ver‐
66 tex that follows begins an edge that lies on the polygon
67 boundary, that is, an edge that separates an interior region
68 from an exterior one. If the flag is GL_FALSE, then each
69 vertex that follows begins an edge that lies in the polygon
70 interior. The edge flag callback (if defined) is invoked
71 before the first vertex callback.
72 Since triangle fans and triangle strips do not support edge
74 flags, the begin callback is not called with GL_TRIANGLE_FAN
75 or GL_TRIANGLE_STRIP if a non-NULL edge flag callback is pro‐
76 vided. (If the callback is initialized to NULL, there is no
77 impact on performance). Instead, the fans and strips are con‐
78 verted to independent triangles. The function prototype for
79 this callback is:
80 void edgeFlag ( GLboolean flag );
81 GLU_TESS_EDGE_FLAG_DATA
83 The same as the GLU_TESS_EDGE_FLAG callback except that it
84 takes an additional pointer argument. This pointer is identi‐
85 cal to the opaque pointer provided when gluTessBeginPolygon
86 was called. The function prototype for this callback is:
87 void edgeFlagData ( GLboolean flag, void *polygon_data );
88 GLU_TESS_VERTEX
90 The vertex callback is invoked between the begin and end
91 callbacks. It is similar to glVertex, and it defines the
92 vertices of the triangles created by the tessellation
93 process. The function takes a pointer as its only argument.
94 This pointer is identical to the opaque pointer provided by
95 the user when the vertex was described (see gluTessVertex).
96 The function prototype for this callback is:
97 void vertex ( void *vertex_data );
98 GLU_TESS_VERTEX_DATA
100 The same as the GLU_TESS_VERTEX callback except that it takes
101 an additional pointer argument. This pointer is identical to
102 the opaque pointer provided when gluTessBeginPolygon was
103 called. The function prototype for this callback is:
104 void vertexData ( void *vertex_data, void *polygon_data );
105 GLU_TESS_END
107 The end callback serves the same purpose as glEnd. It indi‐
108 cates the end of a primitive and it takes no arguments. The
109 function prototype for this callback is:
110 void end ( void );
111 GLU_TESS_END_DATA
113 The same as the GLU_TESS_END callback except that it takes an
114 additional pointer argument. This pointer is identical to the
115 opaque pointer provided when gluTessBeginPolygon was called.
116 The function prototype for this callback is:
117 void endData ( void *polygon_data);
118 GLU_TESS_COMBINE
120 The combine callback is called to create a new vertex when
121 the tessellation detects an intersection, or wishes to merge
122 features. The function takes four arguments: an array of
123 three elements each of type GLdouble, an array of four point‐
124 ers, an array of four elements each of type GLfloat, and a
125 pointer to a pointer. The prototype is:
126 void combine( GLdouble coords[3], void *vertex_data[4],
127 GLfloat weight[4], void **outData );
128 The vertex is defined as a linear combination of up to four
130 existing vertices, stored in vertex_data. The coefficients of
131 the linear combination are given by weight; these weights
132 always add up to 1. All vertex pointers are valid even when
133 some of the weights are 0. coords gives the location of the
134 new vertex.
135 The user must allocate another vertex, interpolate parameters
137 using vertex_data and weight, and return the new vertex
138 pointer in outData. This handle is supplied during rendering
139 callbacks. The user is responsible for freeing the memory
140 some time after gluTessEndPolygon is called.
141 For example, if the polygon lies in an arbitrary plane in
143 3-space, and a color is associated with each vertex, the
144 GLU_TESS_COMBINE callback might look like this:
145 void myCombine( GLdouble coords[3], VERTEX *d[4],
146 GLfloat w[4], VERTEX **dataOut ) {
147 VERTEX *new = new_vertex();
148 new->x = coords[0];
150 new->y = coords[1];
151 new->z = coords[2];
152 new->r = w[0]*d[0]->r + w[1]*d[1]->r + w[2]*d[2]->r +
153 w[3]*d[3]->r;
154 new->g = w[0]*d[0]->g + w[1]*d[1]->g + w[2]*d[2]->g +
155 w[3]*d[3]->g;
156 new->b = w[0]*d[0]->b + w[1]*d[1]->b + w[2]*d[2]->b +
157 w[3]*d[3]->b;
158 new->a = w[0]*d[0]->a + w[1]*d[1]->a + w[2]*d[2]->a +
159 w[3]*d[3]->a;
160 *dataOut = new; }
161 If the tessellation detects an intersection, then the
163 GLU_TESS_COMBINE or GLU_TESS_COMBINE_DATA callback (see
164 below) must be defined, and it must write a non-NULL pointer
165 into dataOut. Otherwise the GLU_TESS_NEED_COMBINE_CALLBACK
166 error occurs, and no output is generated.
167 GLU_TESS_COMBINE_DATA
169 The same as the GLU_TESS_COMBINE callback except that it
170 takes an additional pointer argument. This pointer is identi‐
171 cal to the opaque pointer provided when gluTessBeginPolygon
172 was called. The function prototype for this callback is:
173 void combineData ( GLdouble coords[3], void *vertex_data[4],
174 GLfloat weight[4], void **outData,
175 void *polygon_data );
176 GLU_TESS_ERROR
178 The error callback is called when an error is encountered.
179 The one argument is of type GLenum; it indicates the specific
180 error that occurred and will be set to one of
181 GLU_TESS_MISSING_BEGIN_POLYGON, GLU_TESS_MISSING_END_POLYGON,
182 GLU_TESS_MISSING_BEGIN_CONTOUR, GLU_TESS_MISSING_END_CONTOUR,
183 GLU_TESS_COORD_TOO_LARGE, GLU_TESS_NEED_COMBINE_CALLBACK or
184 GLU_OUT_OF_MEMORY. Character strings describing these errors
185 can be retrieved with the gluErrorString call. The function
186 prototype for this callback is:
187 void error ( GLenum errno );
188 The GLU library will recover from the first four errors by
190 inserting the missing call(s). GLU_TESS_COORD_TOO_LARGE
191 indicates that some vertex coordinate exceeded the predefined
192 constant GLU_TESS_MAX_COORD in absolute value, and that the
193 value has been clamped. (Coordinate values must be small
194 enough so that two can be multiplied together without over‐
195 flow.) GLU_TESS_NEED_COMBINE_CALLBACK indicates that the
196 tessellation detected an intersection between two edges in
197 the input data, and the GLU_TESS_COMBINE or
198 GLU_TESS_COMBINE_DATA callback was not provided. No output is
199 generated. GLU_OUT_OF_MEMORY indicates that there is not
200 enough memory so no output is generated.
201 GLU_TESS_ERROR_DATA
203 The same as the GLU_TESS_ERROR callback except that it takes
204 an additional pointer argument. This pointer is identical to
205 the opaque pointer provided when gluTessBeginPolygon was
206 called. The function prototype for this callback is:
207 void errorData ( GLenum errno, void *polygon_data );
208
210 Polygons tessellated can be rendered directly like this:
211 gluTessCallback(tobj, GLU_TESS_BEGIN, glBegin); gluTessCallback(tobj,
213 GLU_TESS_VERTEX, glVertex3dv); gluTessCallback(tobj, GLU_TESS_END,
214 glEnd); gluTessCallback(tobj, GLU_TESS_COMBINE, myCombine); gluTessBe‐
215 ginPolygon(tobj, NULL);
216 gluTessBeginContour(tobj);
217 gluTessVertex(tobj, v, v);
218 ...
219 gluTessEndContour(tobj); gluTessEndPolygon(tobj);
220 Typically, the tessellated polygon should be stored in a display list
222 so that it does not need to be retessellated every time it is rendered.
223
225 glBegin(3G), glEdgeFlag(3G), glVertex(3G), gluNewTess(3G),
226 gluErrorString(3G), gluTessVertex(3G), gluTessBeginPolygon(3G),
227 gluTessBeginContour(3G), gluTessProperty(3G), gluTessNormal(3G)
228 GLUTESSCALLBACK(3G)