HCoop / clinton / guile-figl.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
rename upstream-man-pages to upstream-doc
[clinton/guile-figl.git] / upstream-doc / man2 / xhtml / gluTessCallback.xml
CommitLineData
7faf1d71
AW		 1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
2<!-- saved from url=(0013)about:internet -->
3<?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>gluTessCallback</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="gluTessCallback"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>gluTessCallback — define a callback for a tessellation object</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">gluTessCallback</b>(</code></td><td>GLUtesselator*  </td><td><var class="pdparam">tess</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">which</var>, </td></tr><tr><td> </td><td>_GLUfuncptr  </td><td><var class="pdparam">CallBackFunc</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>tess</code></em></span></dt><dd><p>
4 Specifies the tessellation object (created with <a class="citerefentry" href="gluNewTess.xml"><span class="citerefentry"><span class="refentrytitle">gluNewTess</span></span></a>).
5 </p></dd><dt><span class="term"><em class="parameter"><code>which</code></em></span></dt><dd><p>
6 Specifies the callback being defined. The following values are valid:
7 <code class="constant">GLU_TESS_BEGIN</code>,
8 <code class="constant">GLU_TESS_BEGIN_DATA</code>,
9 <code class="constant">GLU_TESS_EDGE_FLAG</code>,
10 <code class="constant">GLU_TESS_EDGE_FLAG_DATA</code>,
11 <code class="constant">GLU_TESS_VERTEX</code>,
12 <code class="constant">GLU_TESS_VERTEX_DATA</code>,
13 <code class="constant">GLU_TESS_END</code>,
14 <code class="constant">GLU_TESS_END_DATA</code>,
15 <code class="constant">GLU_TESS_COMBINE</code>,
16 <code class="constant">GLU_TESS_COMBINE_DATA</code>,
17 <code class="constant">GLU_TESS_ERROR</code>, and
18 <code class="constant">GLU_TESS_ERROR_DATA</code>.
19 </p></dd><dt><span class="term"><em class="parameter"><code>CallBackFunc</code></em></span></dt><dd><p>
20 Specifies the function to be called.
21 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
22 <code class="function">gluTessCallback</code> is used to indicate a callback to be used by a tessellation object.
23 If the specified callback is already defined, then it is replaced. If
24 <em class="parameter"><code>CallBackFunc</code></em> is NULL, then the existing callback becomes undefined.
25 </p><p>
26 These callbacks are used by the tessellation object to describe how a
27 polygon specified by the user is broken into triangles. Note that there
28 are two versions of each callback: one with user-specified polygon data
29 and one without. If both versions of a particular callback are specified,
30 then the callback with user-specified polygon data will be used. Note
31 that the <span class="emphasis"><em>polygon_data</em></span> parameter used by some of the functions is
32 a copy of the pointer that was specified when
33 <a class="citerefentry" href="gluTessBeginPolygon.xml"><span class="citerefentry"><span class="refentrytitle">gluTessBeginPolygon</span></span></a> was called. The legal callbacks are as follows:
34 </p><div class="variablelist"><dl><dt><span class="term"><code class="constant">GLU_TESS_BEGIN</code></span></dt><dd><p>
35 The begin callback is invoked like <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a> to indicate the start of
36 a (triangle) primitive. The function takes a single argument of type
37 GLenum. If the <code class="constant">GLU_TESS_BOUNDARY_ONLY</code> property is set to
38 <code class="constant">GLU_FALSE</code>, then the argument is set to either
39 <code class="constant">GLU_TRIANGLE_FAN</code>, <code class="constant">GLU_TRIANGLE_STRIP</code>, or <code class="constant">GLU_TRIANGLES</code>.
40 If the <code class="constant">GLU_TESS_BOUNDARY_ONLY</code> property is set to <code class="constant">GLU_TRUE</code>,
41 then the argument will be set to <code class="constant">GLU_LINE_LOOP</code>. The function
42 prototype for this callback is:
43 </p><pre class="programlisting">
44void begin( GLenum type );
45 </pre><p>
46 </p></dd><dt><span class="term"><code class="constant">GLU_TESS_BEGIN_DATA</code></span></dt><dd><p>
47 The same as the <code class="constant">GLU_TESS_BEGIN</code> callback except that it
48 takes an additional pointer argument. This pointer is identical to the
49 opaque pointer provided when
50 <a class="citerefentry" href="gluTessBeginPolygon.xml"><span class="citerefentry"><span class="refentrytitle">gluTessBeginPolygon</span></span></a> was called. The function prototype for this callback
51 is:
52 </p><pre class="programlisting">
53void beginData( GLenum type, void *polygon_data );
54 </pre><p>
55 </p></dd><dt><span class="term"><code class="constant">GLU_TESS_EDGE_FLAG</code></span></dt><dd><p>
56 The edge flag callback is similar to <a class="citerefentry" href="glEdgeFlag.xml"><span class="citerefentry"><span class="refentrytitle">glEdgeFlag</span></span></a>. The function
57 takes a single boolean flag that indicates which edges lie on the
58 polygon boundary. If the flag is <code class="constant">GLU_TRUE</code>, then each vertex
59 that follows begins an edge that lies on the polygon boundary, that is,
60 an edge that separates an interior region from an exterior one.
61 If the flag is <code class="constant">GLU_FALSE</code>, then each vertex that follows begins an edge
62 that lies in the polygon interior. The edge flag callback (if defined) is
63 invoked before the first vertex callback.
64 </p><p>
65 Since triangle fans and triangle strips do not support edge flags, the begin
66 callback is not called with <code class="constant">GLU_TRIANGLE_FAN</code> or <code class="constant">GLU_TRIANGLE_STRIP</code>
67 if a non-NULL edge flag callback is provided. (If the callback is
68 initialized to NULL, there is no impact on performance). Instead, the fans and
69 strips are converted to independent triangles. The function prototype
70 for this callback is:
71 </p><pre class="programlisting">
72void edgeFlag( GLboolean flag );
73 </pre><p>
74 </p></dd><dt><span class="term"><code class="constant">GLU_TESS_EDGE_FLAG_DATA</code></span></dt><dd><p>
75 The same as the <code class="constant">GLU_TESS_EDGE_FLAG</code> callback except that it takes an additional pointer
76 argument. This pointer is identical to the opaque pointer provided when
77 <a class="citerefentry" href="gluTessBeginPolygon.xml"><span class="citerefentry"><span class="refentrytitle">gluTessBeginPolygon</span></span></a> was called. The function prototype for this callback
78 is:
79 </p><pre class="programlisting">
80void edgeFlagData( GLboolean flag, void *polygon_data );
81 </pre><p>
82 </p></dd><dt><span class="term"><code class="constant">GLU_TESS_VERTEX</code></span></dt><dd><p>
83 The vertex callback is invoked between the begin and end callbacks.
84 It is similar to <a class="citerefentry" href="glVertex.xml"><span class="citerefentry"><span class="refentrytitle">glVertex</span></span></a>, and it defines the vertices of the triangles
85 created by the tessellation process. The function
86 takes a pointer as its only argument. This pointer is identical to
87 the opaque pointer provided by the user when the vertex was described
88 (see <a class="citerefentry" href="gluTessVertex.xml"><span class="citerefentry"><span class="refentrytitle">gluTessVertex</span></span></a>). The function prototype for this callback is:
89 </p><pre class="programlisting">
90void vertex( void *vertex_data );
91 </pre><p>
92 </p></dd><dt><span class="term"><code class="constant">GLU_TESS_VERTEX_DATA</code></span></dt><dd><p>
93 The same as the <code class="constant">GLU_TESS_VERTEX</code> callback except that it takes an additional pointer
94 argument. This pointer is identical to the opaque pointer provided when
95 <a class="citerefentry" href="gluTessBeginPolygon.xml"><span class="citerefentry"><span class="refentrytitle">gluTessBeginPolygon</span></span></a> was called. The function prototype for this callback
96 is:
97 </p><pre class="programlisting">
98void vertexData( void *vertex_data, void *polygon_data );
99 </pre><p>
100 </p></dd><dt><span class="term"><code class="constant">GLU_TESS_END</code></span></dt><dd><p>
101 The end callback serves the same purpose as <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>. It indicates the
102 end of a primitive and it takes no arguments. The function prototype for this
103 callback is:
104 </p><pre class="programlisting">
105void end( void );
106 </pre><p>
107 </p></dd><dt><span class="term"><code class="constant">GLU_TESS_END_DATA</code></span></dt><dd><p>
108 The same as the <code class="constant">GLU_TESS_END</code> callback except that it takes an additional pointer
109 argument. This pointer is identical to the opaque pointer provided when
110 <a class="citerefentry" href="gluTessBeginPolygon.xml"><span class="citerefentry"><span class="refentrytitle">gluTessBeginPolygon</span></span></a> was called. The function prototype for this callback
111 is:
112 </p><pre class="programlisting">
113void endData( void *polygon_data );
114 </pre><p>
115 </p></dd><dt><span class="term"><code class="constant">GLU_TESS_COMBINE</code></span></dt><dd><p>
116 The combine callback is called to create a new vertex when the tessellation
117 detects an intersection or wishes to merge features. The function takes
118 four arguments: an array of three elements each of type GLdouble, an array
119 of four pointers, an array of four elements each of type GLfloat, and a
120 pointer to a pointer. The prototype is:
121 </p><pre class="programlisting">
122void combine( GLdouble coords[3], void *vertex_data[4],
123 GLfloat weight[4], void **outData );
124 </pre><p>
125 </p><p>
126 The vertex is defined as a linear combination of up to four existing vertices,
127 stored in <span class="emphasis"><em>vertex_data</em></span>. The coefficients of the linear
128 combination are given by <span class="emphasis"><em>weight</em></span>; these weights always add up to 1.
129 All vertex pointers are valid even when some of the weights are 0.
130 <span class="emphasis"><em>coords</em></span> gives the location of the new vertex.
131 </p><p>
132 The user must allocate another vertex, interpolate parameters using
133 <span class="emphasis"><em>vertex_data</em></span> and <span class="emphasis"><em>weight</em></span>, and return the new vertex pointer in
134 <span class="emphasis"><em>outData</em></span>. This handle is supplied during rendering callbacks.
135 The user is responsible for freeing the memory some time after
136 <a class="citerefentry" href="gluTessEndPolygon.xml"><span class="citerefentry"><span class="refentrytitle">gluTessEndPolygon</span></span></a> is called.
137 </p><p>
138 For example, if the polygon lies in an arbitrary plane in 3-space,
139 and a color is associated with each vertex, the
140 <code class="constant">GLU_TESS_COMBINE</code> callback might look like this:
141 </p><pre class="programlisting">
142void myCombine( GLdouble coords[3], VERTEX *d[4],
143 GLfloat w[4], VERTEX **dataOut )
144{
145 VERTEX *new = new_vertex();
146
147 new-&gt;x = coords[0];
148 new-&gt;y = coords[1];
149 new-&gt;z = coords[2];
150 new-&gt;r = w[0]*d[0]-&gt;r + w[1]*d[1]-&gt;r + w[2]*d[2]-&gt;r + w[3]*d[3]-&gt;r;
151 new-&gt;g = w[0]*d[0]-&gt;g + w[1]*d[1]-&gt;g + w[2]*d[2]-&gt;g + w[3]*d[3]-&gt;g;
152 new-&gt;b = w[0]*d[0]-&gt;b + w[1]*d[1]-&gt;b + w[2]*d[2]-&gt;b + w[3]*d[3]-&gt;b;
153 new-&gt;a = w[0]*d[0]-&gt;a + w[1]*d[1]-&gt;a + w[2]*d[2]-&gt;a + w[3]*d[3]-&gt;a;
154 *dataOut = new;
155}
156 </pre><p>
157 </p><p>
158 If the tessellation detects an intersection, then the <code class="constant">GLU_TESS_COMBINE</code> or
159 <code class="constant">GLU_TESS_COMBINE_DATA</code> callback (see below) must be defined, and it must
160 write a non-NULL pointer into <span class="emphasis"><em>dataOut</em></span>. Otherwise the
161 <code class="constant">GLU_TESS_NEED_COMBINE_CALLBACK</code> error occurs, and no
162 output is generated.
163 </p></dd><dt><span class="term"><code class="constant">GLU_TESS_COMBINE_DATA</code></span></dt><dd><p>
164 The same as the <code class="constant">GLU_TESS_COMBINE</code> callback except that it takes an additional pointer
165 argument. This pointer is identical to the opaque pointer provided when
166 <a class="citerefentry" href="gluTessBeginPolygon.xml"><span class="citerefentry"><span class="refentrytitle">gluTessBeginPolygon</span></span></a> was called. The function prototype for this callback
167 is:
168 </p><pre class="programlisting">
169void combineData( GLdouble coords[3], void *vertex_data[4],
170 GLfloat weight[4], void **outData,
171 void *polygon_data );
172 </pre><p>
173 </p></dd><dt><span class="term"><code class="constant">GLU_TESS_ERROR</code></span></dt><dd><p>
174 The error callback is called when an error is encountered. The one argument
175 is of type GLenum; it indicates the specific error that occurred and will be
176 set to one of <code class="constant">GLU_TESS_MISSING_BEGIN_POLYGON</code>, <code class="constant">GLU_TESS_MISSING_END_POLYGON</code>,
177 <code class="constant">GLU_TESS_MISSING_BEGIN_CONTOUR</code>, <code class="constant">GLU_TESS_MISSING_END_CONTOUR</code>,
178 <code class="constant">GLU_TESS_COORD_TOO_LARGE</code>, <code class="constant">GLU_TESS_NEED_COMBINE_CALLBACK</code>, or
179 <code class="constant">GLU_OUT_OF_MEMORY</code>. Character
180 strings describing these errors can be retrieved with the
181 <a class="citerefentry" href="gluErrorString.xml"><span class="citerefentry"><span class="refentrytitle">gluErrorString</span></span></a> call. The function prototype for this callback is:
182 </p><pre class="programlisting">
183void error( GLenum errno );
184 </pre><p>
185 </p><p>
186 The GLU library will recover from the first four
187 errors by inserting the missing call(s).
188 <code class="constant">GLU_TESS_COORD_TOO_LARGE</code> indicates that some vertex coordinate exceeded
189 the predefined constant <code class="constant">GLU_TESS_MAX_COORD</code> in absolute value, and
190 that the value has been clamped. (Coordinate values must be small
191 enough so that two can be multiplied together without overflow.)
192 <code class="constant">GLU_TESS_NEED_COMBINE_CALLBACK</code> indicates that the tessellation
193 detected an intersection between two edges in the input data, and the
194 <code class="constant">GLU_TESS_COMBINE</code> or <code class="constant">GLU_TESS_COMBINE_DATA</code> callback was
195 not provided. No output is generated. <code class="constant">GLU_OUT_OF_MEMORY</code> indicates
196 that there is not enough memory so no output is generated.
197 </p></dd><dt><span class="term"><code class="constant">GLU_TESS_ERROR_DATA</code></span></dt><dd><p>
198 The same as the <code class="constant">GLU_TESS_ERROR</code> callback except that it takes an additional pointer
199 argument. This pointer is identical to the opaque pointer provided when
200 <a class="citerefentry" href="gluTessBeginPolygon.xml"><span class="citerefentry"><span class="refentrytitle">gluTessBeginPolygon</span></span></a> was called. The function prototype for this callback
201 is:
202 </p><pre class="programlisting">
203void errorData( GLenum errno, void *polygon_data );
204 </pre><p>
205 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="example"></a><h2>Example</h2><p>
206 Polygons tessellated can be rendered directly like this:
207 </p><pre class="programlisting">
208gluTessCallback(tobj, GLU_TESS_BEGIN, glBegin);
209gluTessCallback(tobj, GLU_TESS_VERTEX, glVertex3dv);
210gluTessCallback(tobj, GLU_TESS_END, glEnd);
211gluTessCallback(tobj, GLU_TESS_COMBINE, myCombine);
212gluTessBeginPolygon(tobj, NULL);
213 gluTessBeginContour(tobj);
214 gluTessVertex(tobj, v, v);
215 ...
216 gluTessEndContour(tobj);
217gluTessEndPolygon(tobj);
218 </pre><p>
219 Typically, the tessellated polygon should be stored in a display list so that
220 it does not need to be retessellated every time it is rendered.
221 </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
222 <a class="citerefentry" href="gluErrorString.xml"><span class="citerefentry"><span class="refentrytitle">gluErrorString</span></span></a>,
223 <a class="citerefentry" href="gluNewTess.xml"><span class="citerefentry"><span class="refentrytitle">gluNewTess</span></span></a>,
224 <a class="citerefentry" href="gluTessBeginContour.xml"><span class="citerefentry"><span class="refentrytitle">gluTessBeginContour</span></span></a>,
225 <a class="citerefentry" href="gluTessBeginPolygon.xml"><span class="citerefentry"><span class="refentrytitle">gluTessBeginPolygon</span></span></a>,
226 <a class="citerefentry" href="gluTessNormal.xml"><span class="citerefentry"><span class="refentrytitle">gluTessNormal</span></span></a>,
227 <a class="citerefentry" href="gluTessProperty.xml"><span class="citerefentry"><span class="refentrytitle">gluTessProperty</span></span></a>,
228 <a class="citerefentry" href="gluTessVertex.xml"><span class="citerefentry"><span class="refentrytitle">gluTessVertex</span></span></a>,
229 <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>,
230 <a class="citerefentry" href="glEdgeFlag.xml"><span class="citerefentry"><span class="refentrytitle">glEdgeFlag</span></span></a>,
231 <a class="citerefentry" href="glVertex.xml"><span class="citerefentry"><span class="refentrytitle">glVertex</span></span></a>
232 </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
233 Copyright <span class="trademark"></span>© 1991-2006
234 Silicon Graphics, Inc. This document is licensed under the SGI
235 Free Software B License. For details, see
236 <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
237 </p></div></div></body></html>
Unnamed repository; edit this file 'description' to name the repository.