1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" "http://www.w3.org/TR/MathML2/dtd/xhtml-math11-f.dtd">
<html
xmlns="http://www.w3.org/1999/xhtml"
xmlns:mml="http://www.w3.org/1998/Math/MathML"
><head><title>gluTessCallback</title><link rel="stylesheet" href="style.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.59.1"/><link rel="home" href="index.xml" title="PyOpenGL 2.0.1.07 Man Pages"/><link rel="up" href="reference-GLU.xml" title="GLU"/><link rel="previous" href="gluTessBeginPolygon.3G.xml" title="gluTessBeginPolygon"/><link rel="next" href="gluTessEndPolygon.3G.xml" title="gluTessEndPolygon"/></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">gluTessCallback</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="gluTessBeginPolygon.3G.xml">Prev</a></td><th width="60%" align="center">GLU</th><td width="20%" align="right"><a accesskey="n" href="gluTessEndPolygon.3G.xml">Next</a></td></tr></table><hr/></div><div class="refentry" lang="en"><a name="gluTessCallback.3G"/><div class="titlepage"/><div class="refnamediv"><a name="gluTessCallback.3G-name"/><h2>Name</h2><p>gluTessCallback — define a callback for a tessellation object</p></div><div class="refsynopsisdiv"><a name="gluTessCallback.3G-c_spec"/><h2>C Specification</h2><table class="funcprototype" border="0" cellpadding="0" cellspacing="0"><tr><td valign="top"><code>void<tt>gluTessCallback</tt></code></td><td valign="top"><code>(</code></td><td valign="top"><code>GLUtesselator*<i><tt>tess</tt></i>, GLenum<i><tt>which</tt></i>, _GLfuncptr<i><tt>CallBackFunc</tt></i>);</code></td></tr></table></div><div class="refsynopsisdiv"><a name="gluTessCallback.3G-python_spec"/><h2>Python Specification</h2><table class="funcprototype" border="0" cellpadding="0" cellspacing="0"><tr><td valign="top"><code><tt>gluTessCallback</tt></code></td><td valign="top"><code>(</code></td><td valign="top"><code><i><tt>tess</tt></i>, <i><tt>which</tt></i>, <i><tt>CallBackFunc</tt></i>) →<tt>None</tt></code></td></tr></table></div><div class="refsect1" lang="en"><a name="gluTessCallback.3G-parameters"/><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><i><tt>tess</tt></i></span></dt><dd>
Specifies the tessellation object (created with <a href="gluNewTess.3G.xml"><tt>gluNewTess</tt></a>).
</dd><dt><span class="term"><i><tt>which</tt></i></span></dt><dd>
Specifies the callback being defined. The following values are valid: <tt>GLU_TESS_BEGIN</tt>,
<tt>GLU_TESS_BEGIN_DATA</tt>, <tt>GLU_TESS_EDGE_FLAG</tt>,
<tt>GLU_TESS_EDGE_FLAG_DATA</tt>, <tt>GLU_TESS_VERTEX</tt>,
<tt>GLU_TESS_VERTEX_DATA</tt>, <tt>GLU_TESS_END</tt>,
<tt>GLU_TESS_END_DATA</tt>, <tt>GLU_TESS_COMBINE</tt>,
<tt>GLU_TESS_COMBINE_DATA</tt>, <tt>GLU_TESS_ERROR</tt>, and
<tt>GLU_TESS_ERROR_DATA</tt>.
</dd><dt><span class="term"><i><tt>CallBackFunc</tt></i></span></dt><dd>
Specifies the function to be called.
</dd></dl></div></div><div class="refsect1" lang="en"><a name="gluTessCallback.3G-description"/><h2>Description</h2><p>
<tt>gluTessCallback</tt> 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 <i><tt>CallBackFunc</tt></i> is
<tt>NULL</tt>, then the existing callback becomes undefined.
</p><p>
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 <i><tt>polygon_data</tt></i> parameter used by some of the functions is a copy of the pointer that
was specified when <a href="gluTessBeginPolygon.3G.xml"><tt>gluTessBeginPolygon</tt></a> was called. The legal callbacks are as
follows:
</p><div class="variablelist"><dl><dt><span class="term"><tt>GLU_TESS_BEGIN</tt></span></dt><dd>
The begin callback is invoked like <a href="glBegin.3G.xml"><tt>glBegin</tt></a> to indicate the start
of a (triangle) primitive. The function takes a single argument of type GLenum. If the
<tt>GLU_TESS_BOUNDARY_ONLY</tt> property is set to <tt>GL_FALSE</tt>, then the
argument is set to either <tt>GL_TRIANGLE_FAN</tt>, <tt>GL_TRIANGLE_STRIP</tt>, or
<tt>GL_TRIANGLES</tt>. If the <tt>GLU_TESS_BOUNDARY_ONLY</tt> property is set to
<tt>GL_TRUE</tt>, then the argument will be set to <tt>GL_LINE_LOOP</tt>. The
function prototype for this callback is: void begin ( GLenum type );
</dd><dt><span class="term"><tt>GLU_TESS_BEGIN_DATA</tt></span></dt><dd>
The same as the <tt>GLU_TESS_BEGIN</tt> callback except that it takes an additional pointer
argument. This pointer is identical to the opaque pointer provided when <a href="gluTessBeginPolygon.3G.xml"><tt>gluTessBeginPolygon</tt></a> was called. The function prototype for this callback is:
void beginData ( GLenum type, void *polygon_data );
</dd><dt><span class="term"><tt>GLU_TESS_EDGE_FLAG</tt></span></dt><dd><p>
The edge flag callback is similar to <a href="glEdgeFlag.3G.xml"><tt>glEdgeFlag</tt></a>. The function
takes a single boolean flag that indicates which edges lie on the polygon boundary. If the flag is
<tt>GL_TRUE</tt>, 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
<tt>GL_FALSE</tt>, 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.
</p><p>
Since triangle fans and triangle strips do not support edge flags, the begin callback is not called with
<tt>GL_TRIANGLE_FAN</tt> or <tt>GL_TRIANGLE_STRIP</tt> if a
non-<tt>NULL</tt> edge flag callback is provided. (If the callback is initialized to
<tt>NULL</tt>, 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 );
</p></dd><dt><span class="term"><tt>GLU_TESS_EDGE_FLAG_DATA</tt></span></dt><dd>
The same as the <tt>GLU_TESS_EDGE_FLAG</tt> callback except that it takes an additional pointer
argument. This pointer is identical to the opaque pointer provided when <a href="gluTessBeginPolygon.3G.xml"><tt>gluTessBeginPolygon</tt></a> was called. The function prototype for this callback is:
void edgeFlagData ( GLboolean flag, void *polygon_data );
</dd><dt><span class="term"><tt>GLU_TESS_VERTEX</tt></span></dt><dd>
The vertex callback is invoked between the begin and end callbacks. It is similar to <tt>glVertex</tt>, 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 <a href="gluTessVertex.3G.xml">gluTessVertex</a>). The function prototype for this callback is: void vertex ( void *vertex_data );
</dd><dt><span class="term"><tt>GLU_TESS_VERTEX_DATA</tt></span></dt><dd>
The same as the <tt>GLU_TESS_VERTEX</tt> callback except that it takes an additional pointer
argument. This pointer is identical to the opaque pointer provided when <a href="gluTessBeginPolygon.3G.xml"><tt>gluTessBeginPolygon</tt></a> was called. The function prototype for this callback is:
void vertexData ( void *vertex_data, void *polygon_data );
</dd><dt><span class="term"><tt>GLU_TESS_END</tt></span></dt><dd>
The end callback serves the same purpose as <a href="glBegin.3G.xml"><tt>glEnd</tt></a>. It indicates
the end of a primitive and it takes no arguments. The function prototype for this callback is: void end (
void );
</dd><dt><span class="term"><tt>GLU_TESS_END_DATA</tt></span></dt><dd>
The same as the <tt>GLU_TESS_END</tt> callback except that it takes an additional pointer
argument. This pointer is identical to the opaque pointer provided when <a href="gluTessBeginPolygon.3G.xml"><tt>gluTessBeginPolygon</tt></a> was called. The function prototype for this callback is:
void endData ( void *polygon_data);
</dd><dt><span class="term"><tt>GLU_TESS_COMBINE</tt></span></dt><dd><p>
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 );
</p><p>
The vertex is defined as a linear combination of up to four existing vertices, stored in
<i><tt>vertex_data</tt></i>. The coefficients of the linear combination are given by
<i><tt>weight</tt></i>; these weights always add up to 1. All vertex pointers are valid even when
some of the weights are 0. <i><tt>coords</tt></i> gives the location of the new vertex.
</p><p>
The user must allocate another vertex, interpolate parameters using <i><tt>vertex_data</tt></i> and
<i><tt>weight</tt></i>, and return the new vertex pointer in <i><tt>outData</tt></i>. This
handle is supplied during rendering callbacks. The user is responsible for freeing the memory some time
after <a href="gluTessEndPolygon.3G.xml"><tt>gluTessEndPolygon</tt></a> is called.
</p><p>
For example, if the polygon lies in an arbitrary plane in 3-space, and a color is associated with each
vertex, the <tt>GLU_TESS_COMBINE</tt> 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; }
</p><p>
If the tessellation detects an intersection, then the <tt>GLU_TESS_COMBINE</tt> or
<tt>GLU_TESS_COMBINE_DATA</tt> callback (see below) must be defined, and it must write a
non-<tt>NULL</tt> pointer into <i><tt>dataOut</tt></i>. Otherwise the
<tt>GLU_TESS_NEED_COMBINE_CALLBACK</tt> error occurs, and no output is generated.
</p></dd><dt><span class="term"><tt>GLU_TESS_COMBINE_DATA</tt></span></dt><dd>
The same as the <tt>GLU_TESS_COMBINE</tt> callback except that it takes an additional pointer
argument. This pointer is identical to the opaque pointer provided when <a href="gluTessBeginPolygon.3G.xml"><tt>gluTessBeginPolygon</tt></a> 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 );
</dd><dt><span class="term"><tt>GLU_TESS_ERROR</tt></span></dt><dd><p>
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
<tt>GLU_TESS_MISSING_BEGIN_POLYGON</tt>, <tt>GLU_TESS_MISSING_END_POLYGON</tt>,
<tt>GLU_TESS_MISSING_BEGIN_CONTOUR</tt>, <tt>GLU_TESS_MISSING_END_CONTOUR</tt>,
<tt>GLU_TESS_COORD_TOO_LARGE</tt>, <tt>GLU_TESS_NEED_COMBINE_CALLBACK</tt> or
<tt>GLU_OUT_OF_MEMORY</tt>. Character strings describing these errors can be retrieved with the
<a href="gluErrorString.3G.xml"><tt>gluErrorString</tt></a> call. The function prototype for this callback is:
void error ( GLenum errno );
</p><p>
The GLU library will recover from the first four errors by inserting the missing call(s).
<tt>GLU_TESS_COORD_TOO_LARGE</tt> indicates that some vertex coordinate exceeded the predefined
constant <tt>GLU_TESS_MAX_COORD</tt> 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.)
<tt>GLU_TESS_NEED_COMBINE_CALLBACK</tt> indicates that the tessellation detected an
intersection between two edges in the input data, and the <tt>GLU_TESS_COMBINE</tt> or
<tt>GLU_TESS_COMBINE_DATA</tt> callback was not provided. No output is generated.
<tt>GLU_OUT_OF_MEMORY</tt> indicates that there is not enough memory so no output is generated.
</p></dd><dt><span class="term"><tt>GLU_TESS_ERROR_DATA</tt></span></dt><dd>
The same as the <tt>GLU_TESS_ERROR</tt> callback except that it takes an additional pointer
argument. This pointer is identical to the opaque pointer provided when <a href="gluTessBeginPolygon.3G.xml"><tt>gluTessBeginPolygon</tt></a> was called. The function prototype for this callback is:
void errorData ( GLenum errno, void *polygon_data );
</dd></dl></div></div><div class="refsect1" lang="en"><a name="gluTessCallback.3G-example"/><h2>Example</h2><p>
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, <tt>NULL</tt>); 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.
</p></div><div class="refsect1" lang="en"><a name="gluTessCallback.3G-see_also"/><h2>See Also</h2><p>
<span class="simplelist"><a href="glBegin.3G.xml">glBegin</a>, <a href="glEdgeFlag.3G.xml">glEdgeFlag</a>, <a href="glVertex.3G.xml">glVertex</a>, <a href="gluNewTess.3G.xml">gluNewTess</a>, <a href="gluErrorString.3G.xml">gluErrorString</a>, <a href="gluTessVertex.3G.xml">gluTessVertex</a>, <a href="gluTessBeginPolygon.3G.xml">gluTessBeginPolygon</a>, <a href="gluTessBeginContour.3G.xml">gluTessBeginContour</a>, <a href="gluTessProperty.3G.xml">gluTessProperty</a>, <a href="gluTessNormal.3G.xml">gluTessNormal</a></span>
</p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="gluTessBeginPolygon.3G.xml">Prev</a></td><td width="20%" align="center"><a accesskey="u" href="reference-GLU.xml">Up</a></td><td width="40%" align="right"><a accesskey="n" href="gluTessEndPolygon.3G.xml">Next</a></td></tr><tr><td width="40%" align="left" valign="top">gluTessBeginPolygon</td><td width="20%" align="center"><a accesskey="h" href="index.xml">Home</a></td><td width="40%" align="right" valign="top">gluTessEndPolygon</td></tr></table></div></body></html>
|
