Commit | Line | Data |
---|---|---|
7faf1d71 AW |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd"> | |
4 | <refentry id="gluTessCallback"> | |
5 | <refmeta> | |
6 | <refmetainfo> | |
7 | <copyright> | |
8 | <year>1991-2006</year> | |
9 | <holder>Silicon Graphics, Inc.</holder> | |
10 | </copyright> | |
11 | </refmetainfo> | |
12 | <refentrytitle>gluTessCallback</refentrytitle> | |
13 | <manvolnum>3G</manvolnum> | |
14 | </refmeta> | |
15 | <refnamediv> | |
16 | <refname>gluTessCallback</refname> | |
17 | <refpurpose>define a callback for a tessellation object</refpurpose> | |
18 | </refnamediv> | |
19 | <refsynopsisdiv><title>C Specification</title> | |
20 | <funcsynopsis> | |
21 | <funcprototype> | |
22 | <funcdef>void <function>gluTessCallback</function></funcdef> | |
23 | <paramdef>GLUtesselator* <parameter>tess</parameter></paramdef> | |
24 | <paramdef>GLenum <parameter>which</parameter></paramdef> | |
25 | <paramdef>_GLUfuncptr <parameter>CallBackFunc</parameter></paramdef> | |
26 | </funcprototype> | |
27 | </funcsynopsis> | |
28 | </refsynopsisdiv> | |
29 | <!-- eqn: ignoring delim $$ --> | |
30 | <refsect1 id="parameters"><title>Parameters</title> | |
31 | <variablelist> | |
32 | <varlistentry> | |
33 | <term><parameter>tess</parameter></term> | |
34 | <listitem> | |
35 | <para> | |
36 | Specifies the tessellation object (created with <citerefentry><refentrytitle>gluNewTess</refentrytitle></citerefentry>). | |
37 | </para> | |
38 | </listitem> | |
39 | </varlistentry> | |
40 | <varlistentry> | |
41 | <term><parameter>which</parameter></term> | |
42 | <listitem> | |
43 | <para> | |
44 | Specifies the callback being defined. The following values are valid: | |
45 | <constant>GLU_TESS_BEGIN</constant>, | |
46 | <constant>GLU_TESS_BEGIN_DATA</constant>, | |
47 | <constant>GLU_TESS_EDGE_FLAG</constant>, | |
48 | <constant>GLU_TESS_EDGE_FLAG_DATA</constant>, | |
49 | <constant>GLU_TESS_VERTEX</constant>, | |
50 | <constant>GLU_TESS_VERTEX_DATA</constant>, | |
51 | <constant>GLU_TESS_END</constant>, | |
52 | <constant>GLU_TESS_END_DATA</constant>, | |
53 | <constant>GLU_TESS_COMBINE</constant>, | |
54 | <constant>GLU_TESS_COMBINE_DATA</constant>, | |
55 | <constant>GLU_TESS_ERROR</constant>, and | |
56 | <constant>GLU_TESS_ERROR_DATA</constant>. | |
57 | </para> | |
58 | </listitem> | |
59 | </varlistentry> | |
60 | <varlistentry> | |
61 | <term><parameter>CallBackFunc</parameter></term> | |
62 | <listitem> | |
63 | <para> | |
64 | Specifies the function to be called. | |
65 | </para> | |
66 | </listitem> | |
67 | </varlistentry> | |
68 | </variablelist> | |
69 | </refsect1> | |
70 | <refsect1 id="description"><title>Description</title> | |
71 | <para> | |
72 | <function>gluTessCallback</function> is used to indicate a callback to be used by a tessellation object. | |
73 | If the specified callback is already defined, then it is replaced. If | |
74 | <parameter>CallBackFunc</parameter> is NULL, then the existing callback becomes undefined. | |
75 | </para> | |
76 | <para> | |
77 | These callbacks are used by the tessellation object to describe how a | |
78 | polygon specified by the user is broken into triangles. Note that there | |
79 | are two versions of each callback: one with user-specified polygon data | |
80 | and one without. If both versions of a particular callback are specified, | |
81 | then the callback with user-specified polygon data will be used. Note | |
82 | that the <emphasis>polygon_data</emphasis> parameter used by some of the functions is | |
83 | a copy of the pointer that was specified when | |
84 | <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The legal callbacks are as follows: | |
85 | </para> | |
86 | <variablelist> | |
87 | <varlistentry> | |
88 | <term><constant>GLU_TESS_BEGIN</constant></term> | |
89 | <listitem> | |
90 | <para> | |
91 | The begin callback is invoked like <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> to indicate the start of | |
92 | a (triangle) primitive. The function takes a single argument of type | |
93 | GLenum. If the <constant>GLU_TESS_BOUNDARY_ONLY</constant> property is set to | |
94 | <constant>GLU_FALSE</constant>, then the argument is set to either | |
95 | <constant>GLU_TRIANGLE_FAN</constant>, <constant>GLU_TRIANGLE_STRIP</constant>, or <constant>GLU_TRIANGLES</constant>. | |
96 | If the <constant>GLU_TESS_BOUNDARY_ONLY</constant> property is set to <constant>GLU_TRUE</constant>, | |
97 | then the argument will be set to <constant>GLU_LINE_LOOP</constant>. The function | |
98 | prototype for this callback is: | |
99 | <programlisting> | |
100 | void begin( GLenum type ); | |
101 | </programlisting> | |
102 | </para> | |
103 | </listitem> | |
104 | </varlistentry> | |
105 | <varlistentry> | |
106 | <term><constant>GLU_TESS_BEGIN_DATA</constant></term> | |
107 | <listitem> | |
108 | <para> | |
109 | The same as the <constant>GLU_TESS_BEGIN</constant> callback except that it | |
110 | takes an additional pointer argument. This pointer is identical to the | |
111 | opaque pointer provided when | |
112 | <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback | |
113 | is: | |
114 | <programlisting> | |
115 | void beginData( GLenum type, void *polygon_data ); | |
116 | </programlisting> | |
117 | </para> | |
118 | </listitem> | |
119 | </varlistentry> | |
120 | <varlistentry> | |
121 | <term><constant>GLU_TESS_EDGE_FLAG</constant></term> | |
122 | <listitem> | |
123 | <para> | |
124 | The edge flag callback is similar to <citerefentry><refentrytitle>glEdgeFlag</refentrytitle></citerefentry>. The function | |
125 | takes a single boolean flag that indicates which edges lie on the | |
126 | polygon boundary. If the flag is <constant>GLU_TRUE</constant>, then each vertex | |
127 | that follows begins an edge that lies on the polygon boundary, that is, | |
128 | an edge that separates an interior region from an exterior one. | |
129 | If the flag is <constant>GLU_FALSE</constant>, then each vertex that follows begins an edge | |
130 | that lies in the polygon interior. The edge flag callback (if defined) is | |
131 | invoked before the first vertex callback. | |
132 | </para> | |
133 | <para> | |
134 | Since triangle fans and triangle strips do not support edge flags, the begin | |
135 | callback is not called with <constant>GLU_TRIANGLE_FAN</constant> or <constant>GLU_TRIANGLE_STRIP</constant> | |
136 | if a non-NULL edge flag callback is provided. (If the callback is | |
137 | initialized to NULL, there is no impact on performance). Instead, the fans and | |
138 | strips are converted to independent triangles. The function prototype | |
139 | for this callback is: | |
140 | <programlisting> | |
141 | void edgeFlag( GLboolean flag ); | |
142 | </programlisting> | |
143 | </para> | |
144 | </listitem> | |
145 | </varlistentry> | |
146 | <varlistentry> | |
147 | <term><constant>GLU_TESS_EDGE_FLAG_DATA</constant></term> | |
148 | <listitem> | |
149 | <para> | |
150 | The same as the <constant>GLU_TESS_EDGE_FLAG</constant> callback except that it takes an additional pointer | |
151 | argument. This pointer is identical to the opaque pointer provided when | |
152 | <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback | |
153 | is: | |
154 | <programlisting> | |
155 | void edgeFlagData( GLboolean flag, void *polygon_data ); | |
156 | </programlisting> | |
157 | </para> | |
158 | </listitem> | |
159 | </varlistentry> | |
160 | <varlistentry> | |
161 | <term><constant>GLU_TESS_VERTEX</constant></term> | |
162 | <listitem> | |
163 | <para> | |
164 | The vertex callback is invoked between the begin and end callbacks. | |
165 | It is similar to <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>, and it defines the vertices of the triangles | |
166 | created by the tessellation process. The function | |
167 | takes a pointer as its only argument. This pointer is identical to | |
168 | the opaque pointer provided by the user when the vertex was described | |
169 | (see <citerefentry><refentrytitle>gluTessVertex</refentrytitle></citerefentry>). The function prototype for this callback is: | |
170 | <programlisting> | |
171 | void vertex( void *vertex_data ); | |
172 | </programlisting> | |
173 | </para> | |
174 | </listitem> | |
175 | </varlistentry> | |
176 | <varlistentry> | |
177 | <term><constant>GLU_TESS_VERTEX_DATA</constant></term> | |
178 | <listitem> | |
179 | <para> | |
180 | The same as the <constant>GLU_TESS_VERTEX</constant> callback except that it takes an additional pointer | |
181 | argument. This pointer is identical to the opaque pointer provided when | |
182 | <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback | |
183 | is: | |
184 | <programlisting> | |
185 | void vertexData( void *vertex_data, void *polygon_data ); | |
186 | </programlisting> | |
187 | </para> | |
188 | </listitem> | |
189 | </varlistentry> | |
190 | <varlistentry> | |
191 | <term><constant>GLU_TESS_END</constant></term> | |
192 | <listitem> | |
193 | <para> | |
194 | The end callback serves the same purpose as <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>. It indicates the | |
195 | end of a primitive and it takes no arguments. The function prototype for this | |
196 | callback is: | |
197 | <programlisting> | |
198 | void end( void ); | |
199 | </programlisting> | |
200 | </para> | |
201 | </listitem> | |
202 | </varlistentry> | |
203 | <varlistentry> | |
204 | <term><constant>GLU_TESS_END_DATA</constant></term> | |
205 | <listitem> | |
206 | <para> | |
207 | The same as the <constant>GLU_TESS_END</constant> callback except that it takes an additional pointer | |
208 | argument. This pointer is identical to the opaque pointer provided when | |
209 | <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback | |
210 | is: | |
211 | <programlisting> | |
212 | void endData( void *polygon_data ); | |
213 | </programlisting> | |
214 | </para> | |
215 | </listitem> | |
216 | </varlistentry> | |
217 | <varlistentry> | |
218 | <term><constant>GLU_TESS_COMBINE</constant></term> | |
219 | <listitem> | |
220 | <para> | |
221 | The combine callback is called to create a new vertex when the tessellation | |
222 | detects an intersection or wishes to merge features. The function takes | |
223 | four arguments: an array of three elements each of type GLdouble, an array | |
224 | of four pointers, an array of four elements each of type GLfloat, and a | |
225 | pointer to a pointer. The prototype is: | |
226 | <programlisting> | |
227 | void combine( GLdouble coords[3], void *vertex_data[4], | |
228 | GLfloat weight[4], void **outData ); | |
229 | </programlisting> | |
230 | </para> | |
231 | <para> | |
232 | The vertex is defined as a linear combination of up to four existing vertices, | |
233 | stored in <emphasis>vertex_data</emphasis>. The coefficients of the linear | |
234 | combination are given by <emphasis>weight</emphasis>; these weights always add up to 1. | |
235 | All vertex pointers are valid even when some of the weights are 0. | |
236 | <emphasis>coords</emphasis> gives the location of the new vertex. | |
237 | </para> | |
238 | <para> | |
239 | The user must allocate another vertex, interpolate parameters using | |
240 | <emphasis>vertex_data</emphasis> and <emphasis>weight</emphasis>, and return the new vertex pointer in | |
241 | <emphasis>outData</emphasis>. This handle is supplied during rendering callbacks. | |
242 | The user is responsible for freeing the memory some time after | |
243 | <citerefentry><refentrytitle>gluTessEndPolygon</refentrytitle></citerefentry> is called. | |
244 | </para> | |
245 | <para> | |
246 | For example, if the polygon lies in an arbitrary plane in 3-space, | |
247 | and a color is associated with each vertex, the | |
248 | <constant>GLU_TESS_COMBINE</constant> callback might look like this: | |
249 | <programlisting> | |
250 | void myCombine( GLdouble coords[3], VERTEX *d[4], | |
251 | GLfloat w[4], VERTEX **dataOut ) | |
252 | { | |
253 | VERTEX *new = new_vertex(); | |
254 | ||
255 | new->x = coords[0]; | |
256 | new->y = coords[1]; | |
257 | new->z = coords[2]; | |
258 | new->r = w[0]*d[0]->r + w[1]*d[1]->r + w[2]*d[2]->r + w[3]*d[3]->r; | |
259 | new->g = w[0]*d[0]->g + w[1]*d[1]->g + w[2]*d[2]->g + w[3]*d[3]->g; | |
260 | new->b = w[0]*d[0]->b + w[1]*d[1]->b + w[2]*d[2]->b + w[3]*d[3]->b; | |
261 | new->a = w[0]*d[0]->a + w[1]*d[1]->a + w[2]*d[2]->a + w[3]*d[3]->a; | |
262 | *dataOut = new; | |
263 | } | |
264 | </programlisting> | |
265 | </para> | |
266 | <para> | |
267 | If the tessellation detects an intersection, then the <constant>GLU_TESS_COMBINE</constant> or | |
268 | <constant>GLU_TESS_COMBINE_DATA</constant> callback (see below) must be defined, and it must | |
269 | write a non-NULL pointer into <emphasis>dataOut</emphasis>. Otherwise the | |
270 | <constant>GLU_TESS_NEED_COMBINE_CALLBACK</constant> error occurs, and no | |
271 | output is generated. | |
272 | </para> | |
273 | </listitem> | |
274 | </varlistentry> | |
275 | <varlistentry> | |
276 | <term><constant>GLU_TESS_COMBINE_DATA</constant></term> | |
277 | <listitem> | |
278 | <para> | |
279 | The same as the <constant>GLU_TESS_COMBINE</constant> callback except that it takes an additional pointer | |
280 | argument. This pointer is identical to the opaque pointer provided when | |
281 | <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback | |
282 | is: | |
283 | <programlisting> | |
284 | void combineData( GLdouble coords[3], void *vertex_data[4], | |
285 | GLfloat weight[4], void **outData, | |
286 | void *polygon_data ); | |
287 | </programlisting> | |
288 | </para> | |
289 | </listitem> | |
290 | </varlistentry> | |
291 | <varlistentry> | |
292 | <term><constant>GLU_TESS_ERROR</constant></term> | |
293 | <listitem> | |
294 | <para> | |
295 | The error callback is called when an error is encountered. The one argument | |
296 | is of type GLenum; it indicates the specific error that occurred and will be | |
297 | set to one of <constant>GLU_TESS_MISSING_BEGIN_POLYGON</constant>, <constant>GLU_TESS_MISSING_END_POLYGON</constant>, | |
298 | <constant>GLU_TESS_MISSING_BEGIN_CONTOUR</constant>, <constant>GLU_TESS_MISSING_END_CONTOUR</constant>, | |
299 | <constant>GLU_TESS_COORD_TOO_LARGE</constant>, <constant>GLU_TESS_NEED_COMBINE_CALLBACK</constant>, or | |
300 | <constant>GLU_OUT_OF_MEMORY</constant>. Character | |
301 | strings describing these errors can be retrieved with the | |
302 | <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry> call. The function prototype for this callback is: | |
303 | <programlisting> | |
304 | void error( GLenum errno ); | |
305 | </programlisting> | |
306 | </para> | |
307 | <para> | |
308 | The GLU library will recover from the first four | |
309 | errors by inserting the missing call(s). | |
310 | <constant>GLU_TESS_COORD_TOO_LARGE</constant> indicates that some vertex coordinate exceeded | |
311 | the predefined constant <constant>GLU_TESS_MAX_COORD</constant> in absolute value, and | |
312 | that the value has been clamped. (Coordinate values must be small | |
313 | enough so that two can be multiplied together without overflow.) | |
314 | <constant>GLU_TESS_NEED_COMBINE_CALLBACK</constant> indicates that the tessellation | |
315 | detected an intersection between two edges in the input data, and the | |
316 | <constant>GLU_TESS_COMBINE</constant> or <constant>GLU_TESS_COMBINE_DATA</constant> callback was | |
317 | not provided. No output is generated. <constant>GLU_OUT_OF_MEMORY</constant> indicates | |
318 | that there is not enough memory so no output is generated. | |
319 | </para> | |
320 | </listitem> | |
321 | </varlistentry> | |
322 | <varlistentry> | |
323 | <term><constant>GLU_TESS_ERROR_DATA</constant></term> | |
324 | <listitem> | |
325 | <para> | |
326 | The same as the <constant>GLU_TESS_ERROR</constant> callback except that it takes an additional pointer | |
327 | argument. This pointer is identical to the opaque pointer provided when | |
328 | <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback | |
329 | is: | |
330 | <programlisting> | |
331 | void errorData( GLenum errno, void *polygon_data ); | |
332 | </programlisting> | |
333 | </para> | |
334 | </listitem> | |
335 | </varlistentry> | |
336 | </variablelist> | |
337 | </refsect1> | |
338 | <refsect1 id="example"><title>Example</title> | |
339 | <para> | |
340 | Polygons tessellated can be rendered directly like this: | |
341 | <programlisting> | |
342 | gluTessCallback(tobj, GLU_TESS_BEGIN, glBegin); | |
343 | gluTessCallback(tobj, GLU_TESS_VERTEX, glVertex3dv); | |
344 | gluTessCallback(tobj, GLU_TESS_END, glEnd); | |
345 | gluTessCallback(tobj, GLU_TESS_COMBINE, myCombine); | |
346 | gluTessBeginPolygon(tobj, NULL); | |
347 | gluTessBeginContour(tobj); | |
348 | gluTessVertex(tobj, v, v); | |
349 | ... | |
350 | gluTessEndContour(tobj); | |
351 | gluTessEndPolygon(tobj); | |
352 | </programlisting> | |
353 | Typically, the tessellated polygon should be stored in a display list so that | |
354 | it does not need to be retessellated every time it is rendered. | |
355 | </para> | |
356 | </refsect1> | |
357 | <refsect1 id="seealso"><title>See Also</title> | |
358 | <para> | |
359 | <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>, | |
360 | <citerefentry><refentrytitle>gluNewTess</refentrytitle></citerefentry>, | |
361 | <citerefentry><refentrytitle>gluTessBeginContour</refentrytitle></citerefentry>, | |
362 | <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry>, | |
363 | <citerefentry><refentrytitle>gluTessNormal</refentrytitle></citerefentry>, | |
364 | <citerefentry><refentrytitle>gluTessProperty</refentrytitle></citerefentry>, | |
365 | <citerefentry><refentrytitle>gluTessVertex</refentrytitle></citerefentry>, | |
366 | <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>, | |
367 | <citerefentry><refentrytitle>glEdgeFlag</refentrytitle></citerefentry>, | |
368 | <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry> | |
369 | </para> | |
370 | </refsect1> | |
371 | <refsect1 id="Copyright"><title>Copyright</title> | |
372 | <para> | |
373 | Copyright <trademark class="copyright"></trademark> 1991-2006 | |
374 | Silicon Graphics, Inc. This document is licensed under the SGI | |
375 | Free Software B License. For details, see | |
376 | <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>. | |
377 | </para> | |
378 | </refsect1> | |
379 | </refentry> |