1GLUTESSCALLBACK(3G) OpenGL Manual GLUTESSCALLBACK(3G)
2
6 gluTessCallback - define a callback for a tessellation object
7
9 void gluTessCallback(GLUtesselator* tess, GLenum which,
10 _GLUfuncptr CallBackFunc);
11
13 tess
14 Specifies the tessellation object (created with gluNewTess()).
15 which
17 Specifies the callback being defined. The following values are
18 valid: GLU_TESS_BEGIN, GLU_TESS_BEGIN_DATA, GLU_TESS_EDGE_FLAG,
19 GLU_TESS_EDGE_FLAG_DATA, GLU_TESS_VERTEX, GLU_TESS_VERTEX_DATA,
20 GLU_TESS_END, GLU_TESS_END_DATA, GLU_TESS_COMBINE,
21 GLU_TESS_COMBINE_DATA, GLU_TESS_ERROR, and GLU_TESS_ERROR_DATA.
22 CallBackFunc
24 Specifies the function to be called.
25
27 gluTessCallback is used to indicate a callback to be used by a
28 tessellation object. If the specified callback is already defined, then
29 it is replaced. If CallBackFunc is NULL, then the existing callback
30 becomes undefined.
31 These callbacks are used by the tessellation object to describe how a
33 polygon specified by the user is broken into triangles. Note that there
34 are two versions of each callback: one with user-specified polygon data
35 and one without. If both versions of a particular callback are
36 specified, then the callback with user-specified polygon data will be
37 used. Note that the polygon_data parameter used by some of the
38 functions is a copy of the pointer that was specified when
39 gluTessBeginPolygon() was called. The legal callbacks are as follows:
40 GLU_TESS_BEGIN
42 The begin callback is invoked like glBegin() to indicate the start
43 of a (triangle) primitive. The function takes a single argument of
44 type GLenum. If the GLU_TESS_BOUNDARY_ONLY property is set to
45 GLU_FALSE, then the argument is set to either GLU_TRIANGLE_FAN,
46 GLU_TRIANGLE_STRIP, or GLU_TRIANGLES. If the GLU_TESS_BOUNDARY_ONLY
47 property is set to GLU_TRUE, then the argument will be set to
48 GLU_LINE_LOOP. The function prototype for this callback is:
49 void begin( GLenum type );
51 GLU_TESS_BEGIN_DATA
55 The same as the GLU_TESS_BEGIN callback except that it takes an
56 additional pointer argument. This pointer is identical to the
57 opaque pointer provided when gluTessBeginPolygon() was called. The
58 function prototype for this callback is:
59 void beginData( GLenum type, void *polygon_data );
61 GLU_TESS_EDGE_FLAG
65 The edge flag callback is similar to glEdgeFlag(). The function
66 takes a single boolean flag that indicates which edges lie on the
67 polygon boundary. If the flag is GLU_TRUE, then each vertex that
68 follows begins an edge that lies on the polygon boundary, that is,
69 an edge that separates an interior region from an exterior one. If
70 the flag is GLU_FALSE, then each vertex that follows begins an edge
71 that lies in the polygon interior. The edge flag callback (if
72 defined) is invoked before the first vertex callback.
73 Since triangle fans and triangle strips do not support edge flags,
75 the begin callback is not called with GLU_TRIANGLE_FAN or
76 GLU_TRIANGLE_STRIP if a non-NULL edge flag callback is provided.
77 (If the callback is initialized to NULL, there is no impact on
78 performance). Instead, the fans and strips are converted to
79 independent triangles. The function prototype for this callback is:
80 void edgeFlag( GLboolean flag );
82 GLU_TESS_EDGE_FLAG_DATA
86 The same as the GLU_TESS_EDGE_FLAG callback except that it takes an
87 additional pointer argument. This pointer is identical to the
88 opaque pointer provided when gluTessBeginPolygon() was called. The
89 function prototype for this callback is:
90 void edgeFlagData( GLboolean flag, void *polygon_data );
92 GLU_TESS_VERTEX
96 The vertex callback is invoked between the begin and end callbacks.
97 It is similar to glVertex(), and it defines the vertices of the
98 triangles created by the tessellation process. The function takes a
99 pointer as its only argument. This pointer is identical to the
100 opaque pointer provided by the user when the vertex was described
101 (see gluTessVertex()). The function prototype for this callback is:
102 void vertex( void *vertex_data );
104 GLU_TESS_VERTEX_DATA
108 The same as the GLU_TESS_VERTEX callback except that it takes an
109 additional pointer argument. This pointer is identical to the
110 opaque pointer provided when gluTessBeginPolygon() was called. The
111 function prototype for this callback is:
112 void vertexData( void *vertex_data, void *polygon_data );
114 GLU_TESS_END
118 The end callback serves the same purpose as glEnd(). It indicates
119 the end of a primitive and it takes no arguments. The function
120 prototype for this callback is:
121 void end( void );
123 GLU_TESS_END_DATA
127 The same as the GLU_TESS_END callback except that it takes an
128 additional pointer argument. This pointer is identical to the
129 opaque pointer provided when gluTessBeginPolygon() was called. The
130 function prototype for this callback is:
131 void endData( void *polygon_data );
133 GLU_TESS_COMBINE
137 The combine callback is called to create a new vertex when the
138 tessellation detects an intersection or wishes to merge features.
139 The function takes four arguments: an array of three elements each
140 of type GLdouble, an array of four pointers, an array of four
141 elements each of type GLfloat, and a pointer to a pointer. The
142 prototype is:
143 void combine( GLdouble coords[3], void *vertex_data[4],
145 GLfloat weight[4], void **outData );
146 The vertex is defined as a linear combination of up to four
149 existing vertices, stored in vertex_data. The coefficients of the
150 linear combination are given by weight; these weights always add up
151 to 1. All vertex pointers are valid even when some of the weights
152 are 0. coords gives the location of the new vertex.
153 The user must allocate another vertex, interpolate parameters using
155 vertex_data and weight, and return the new vertex pointer in
156 outData. This handle is supplied during rendering callbacks. The
157 user is responsible for freeing the memory some time after
158 gluTessEndPolygon() is called.
159 For example, if the polygon lies in an arbitrary plane in 3-space,
161 and a color is associated with each vertex, the GLU_TESS_COMBINE
162 callback might look like this:
163 void myCombine( GLdouble coords[3], VERTEX *d[4],
165 GLfloat w[4], VERTEX **dataOut )
166 {
167 VERTEX *new = new_vertex();
168 new->x = coords[0];
170 new->y = coords[1];
171 new->z = coords[2];
172 new->r = w[0]*d[0]->r + w[1]*d[1]->r + w[2]*d[2]->r + w[3]*d[3]->r;
173 new->g = w[0]*d[0]->g + w[1]*d[1]->g + w[2]*d[2]->g + w[3]*d[3]->g;
174 new->b = w[0]*d[0]->b + w[1]*d[1]->b + w[2]*d[2]->b + w[3]*d[3]->b;
175 new->a = w[0]*d[0]->a + w[1]*d[1]->a + w[2]*d[2]->a + w[3]*d[3]->a;
176 *dataOut = new;
177 }
178 If the tessellation detects an intersection, then the
181 GLU_TESS_COMBINE or GLU_TESS_COMBINE_DATA callback (see below) must
182 be defined, and it must write a non-NULL pointer into dataOut.
183 Otherwise the GLU_TESS_NEED_COMBINE_CALLBACK error occurs, and no
184 output is generated.
185 GLU_TESS_COMBINE_DATA
187 The same as the GLU_TESS_COMBINE callback except that it takes an
188 additional pointer argument. This pointer is identical to the
189 opaque pointer provided when gluTessBeginPolygon() was called. The
190 function prototype for this callback is:
191 void combineData( GLdouble coords[3], void *vertex_data[4],
193 GLfloat weight[4], void **outData,
194 void *polygon_data );
195 GLU_TESS_ERROR
199 The error callback is called when an error is encountered. The one
200 argument is of type GLenum; it indicates the specific error that
201 occurred and will be set to one of GLU_TESS_MISSING_BEGIN_POLYGON,
202 GLU_TESS_MISSING_END_POLYGON, GLU_TESS_MISSING_BEGIN_CONTOUR,
203 GLU_TESS_MISSING_END_CONTOUR, GLU_TESS_COORD_TOO_LARGE,
204 GLU_TESS_NEED_COMBINE_CALLBACK, or GLU_OUT_OF_MEMORY. Character
205 strings describing these errors can be retrieved with the
206 gluErrorString() call. The function prototype for this callback is:
207 void error( GLenum errno );
209 The GLU library will recover from the first four errors by
212 inserting the missing call(s). GLU_TESS_COORD_TOO_LARGE indicates
213 that some vertex coordinate exceeded the predefined constant
214 GLU_TESS_MAX_COORD in absolute value, and that the value has been
215 clamped. (Coordinate values must be small enough so that two can be
216 multiplied together without overflow.)
217 GLU_TESS_NEED_COMBINE_CALLBACK indicates that the tessellation
218 detected an intersection between two edges in the input data, and
219 the GLU_TESS_COMBINE or GLU_TESS_COMBINE_DATA callback was not
220 provided. No output is generated. GLU_OUT_OF_MEMORY indicates that
221 there is not enough memory so no output is generated.
222 GLU_TESS_ERROR_DATA
224 The same as the GLU_TESS_ERROR callback except that it takes an
225 additional pointer argument. This pointer is identical to the
226 opaque pointer provided when gluTessBeginPolygon() was called. The
227 function prototype for this callback is:
228 void errorData( GLenum errno, void *polygon_data );
230
234 Polygons tessellated can be rendered directly like this:
235 gluTessCallback(tobj, GLU_TESS_BEGIN, glBegin);
237 gluTessCallback(tobj, GLU_TESS_VERTEX, glVertex3dv);
238 gluTessCallback(tobj, GLU_TESS_END, glEnd);
239 gluTessCallback(tobj, GLU_TESS_COMBINE, myCombine);
240 gluTessBeginPolygon(tobj, NULL);
241 gluTessBeginContour(tobj);
242 gluTessVertex(tobj, v, v);
243 ...
244 gluTessEndContour(tobj);
245 gluTessEndPolygon(tobj);
246 Typically, the tessellated polygon should be stored in a display list
249 so that it does not need to be retessellated every time it is rendered.
250
252 gluErrorString(), gluNewTess(), gluTessBeginContour(),
253 gluTessBeginPolygon(), gluTessNormal(), gluTessProperty(),
254 gluTessVertex(), glBegin(), glEdgeFlag(), glVertex()
255
257 Copyright © 1991-2006 Silicon Graphics, Inc. This document is licensed
258 under the SGI Free Software B License. For details, see
259 http://oss.sgi.com/projects/FreeB/.
260
262 opengl.org
263opengl.org 07/13/2018 GLUTESSCALLBACK(3G)