JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
GLUtessellatorCallback.java
Go to the documentation of this file.
1/*
2* Portions Copyright (C) 2003-2006 Sun Microsystems, Inc.
3* All rights reserved.
4*/
5
6/*
7** License Applicability. Except to the extent portions of this file are
8** made subject to an alternative license as permitted in the SGI Free
9** Software License B, Version 2.0 (the "License"), the contents of this
10** file are subject only to the provisions of the License. You may not use
11** this file except in compliance with the License. You may obtain a copy
12** of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
13** Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:
14**
15** http://oss.sgi.com/projects/FreeB
16**
17** Note that, as provided in the License, the Software is distributed on an
18** "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
19** DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
20** CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
21** PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
22**
23** NOTE: The Original Code (as defined below) has been licensed to Sun
24** Microsystems, Inc. ("Sun") under the SGI Free Software License B
25** (Version 1.1), shown above ("SGI License"). Pursuant to Section
26** 3.2(3) of the SGI License, Sun is distributing the Covered Code to
27** you under an alternative license ("Alternative License"). This
28** Alternative License includes all of the provisions of the SGI License
29** except that Section 2.2 and 11 are omitted. Any differences between
30** the Alternative License and the SGI License are offered solely by Sun
31** and not by SGI.
32**
33** Original Code. The Original Code is: OpenGL Sample Implementation,
34** Version 1.2.1, released January 26, 2000, developed by Silicon Graphics,
35** Inc. The Original Code is Copyright (c) 1991-2000 Silicon Graphics, Inc.
36** Copyright in any portions created by third parties is as indicated
37** elsewhere herein. All Rights Reserved.
38**
39** Additional Notice Provisions: The application programming interfaces
40** established by SGI in conjunction with the Original Code are The
41** OpenGL(R) Graphics System: A Specification (Version 1.2.1), released
42** April 1, 1999; The OpenGL(R) Graphics System Utility Library (Version
43** 1.3), released November 4, 1998; and OpenGL(R) Graphics with the X
44** Window System(R) (Version 1.3), released October 19, 1998. This software
45** was created using the OpenGL(R) version 1.2.1 Sample Implementation
46** published by SGI, but has not been independently verified as being
47** compliant with the OpenGL(R) version 1.2.1 Specification.
48**
49** Author: Eric Veach, July 1994
50** Java Port: Pepijn Van Eeckhoudt, July 2003
51** Java Port: Nathan Parker Burg, August 2003
52*/
53package com.jogamp.opengl.glu;
54
55/**
56 * <b>GLUtessellatorCallback</b> interface provides methods that the user will
57 * override to define the callbacks for a tessellation object.
58 *
59 * @author Eric Veach, July 1994
60 * @author Java Port: Pepijn Van Eeckhoudt, July 2003
61 * @author Java Port: Nathan Parker Burg, August 2003
62 */
63public interface GLUtessellatorCallback {
64 /**
65 * The <b>begin</b> callback method is invoked like
66 * {@link com.jogamp.opengl.GL#glBegin glBegin} to indicate the start of a
67 * (triangle) primitive. The method takes a single argument of type int. If
68 * the <b>GLU_TESS_BOUNDARY_ONLY</b> property is set to <b>GL_FALSE</b>, then
69 * the argument is set to either <b>GL_TRIANGLE_FAN</b>,
70 * <b>GL_TRIANGLE_STRIP</b>, or <b>GL_TRIANGLES</b>. If the
71 * <b>GLU_TESS_BOUNDARY_ONLY</b> property is set to <b>GL_TRUE</b>, then the
72 * argument will be set to <b>GL_LINE_LOOP</b>.
73 *
74 * @param type
75 * Specifics the type of begin/end pair being defined. The following
76 * values are valid: <b>GL_TRIANGLE_FAN</b>, <b>GL_TRIANGLE_STRIP</b>,
77 * <b>GL_TRIANGLES</b> or <b>GL_LINE_LOOP</b>.
78 *
79 * @see GLU#gluTessCallback gluTessCallback
80 * @see #end end
81 * @see #begin begin
82 */
83 public void begin(int type);
84
85 /**
86 * The same as the {@link #begin begin} callback method except that
87 * it takes an additional reference argument. This reference is
88 * identical to the opaque reference provided when {@link
89 * GLU#gluTessBeginPolygon gluTessBeginPolygon} was called.
90 *
91 * @param type
92 * Specifics the type of begin/end pair being defined. The following
93 * values are valid: <b>GL_TRIANGLE_FAN</b>, <b>GL_TRIANGLE_STRIP</b>,
94 * <b>GL_TRIANGLES</b> or <b>GL_LINE_LOOP</b>.
95 * @param polygonData
96 * Specifics a reference to user-defined data.
97 *
98 * @see GLU#gluTessCallback gluTessCallback
99 * @see #endData endData
100 * @see #begin begin
101 */
102 public void beginData(int type, Object polygonData);
103
104
105 /**
106 * The <b>edgeFlag</b> callback method is similar to
107 * {@link com.jogamp.opengl.GL#glEdgeFlag glEdgeFlag}. The method takes
108 * a single boolean boundaryEdge that indicates which edges lie on the
109 * polygon boundary. If the boundaryEdge is <b>GL_TRUE</b>, then each vertex
110 * that follows begins an edge that lies on the polygon boundary, that is,
111 * an edge that separates an interior region from an exterior one. If the
112 * boundaryEdge is <b>GL_FALSE</b>, then each vertex that follows begins an
113 * edge that lies in the polygon interior. The edge flag callback (if
114 * defined) is invoked before the first vertex callback.<P>
115 *
116 * Since triangle fans and triangle strips do not support edge flags, the
117 * begin callback is not called with <b>GL_TRIANGLE_FAN</b> or
118 * <b>GL_TRIANGLE_STRIP</b> if a non-null edge flag callback is provided.
119 * (If the callback is initialized to null, there is no impact on
120 * performance). Instead, the fans and strips are converted to independent
121 * triangles.
122 *
123 * @param boundaryEdge
124 * Specifics which edges lie on the polygon boundary.
125 *
126 * @see GLU#gluTessCallback gluTessCallback
127 * @see #edgeFlagData edgeFlagData
128 */
129 public void edgeFlag(boolean boundaryEdge);
130
131
132 /**
133 * The same as the {@link #edgeFlag edgeFlage} callback method
134 * except that it takes an additional reference argument. This
135 * reference is identical to the opaque reference provided when
136 * {@link GLU#gluTessBeginPolygon gluTessBeginPolygon} was called.
137 *
138 * @param boundaryEdge
139 * Specifics which edges lie on the polygon boundary.
140 * @param polygonData
141 * Specifics a reference to user-defined data.
142 *
143 * @see GLU#gluTessCallback gluTessCallback
144 * @see #edgeFlag edgeFlag
145 */
146 public void edgeFlagData(boolean boundaryEdge, Object polygonData);
147
148
149 /**
150 * The <b>vertex</b> callback method is invoked between the {@link
151 * #begin begin} and {@link #end end} callback methods. It is
152 * similar to {@link com.jogamp.opengl.GL#glVertex3f glVertex3f},
153 * and it defines the vertices of the triangles created by the
154 * tessellation process. The method takes a reference as its only
155 * argument. This reference is identical to the opaque reference
156 * provided by the user when the vertex was described (see {@link
157 * GLU#gluTessVertex gluTessVertex}).
158 *
159 * @param vertexData
160 * Specifics a reference to the vertices of the triangles created
161 * by the tessellation process.
162 *
163 * @see GLU#gluTessCallback gluTessCallback
164 * @see #vertexData vertexData
165 */
166 public void vertex(Object vertexData);
167
168
169 /**
170 * The same as the {@link #vertex vertex} callback method except
171 * that it takes an additional reference argument. This reference is
172 * identical to the opaque reference provided when {@link
173 * GLU#gluTessBeginPolygon gluTessBeginPolygon} was called.
174 *
175 * @param vertexData
176 * Specifics a reference to the vertices of the triangles created
177 * by the tessellation process.
178 * @param polygonData
179 * Specifics a reference to user-defined data.
180 *
181 * @see GLU#gluTessCallback gluTessCallback
182 * @see #vertex vertex
183 */
184 public void vertexData(Object vertexData, Object polygonData);
185
186
187 /**
188 * The end callback serves the same purpose as
189 * {@link com.jogamp.opengl.GL#glEnd glEnd}. It indicates the end of a
190 * primitive and it takes no arguments.
191 *
192 * @see GLU#gluTessCallback gluTessCallback
193 * @see #begin begin
194 * @see #endData endData
195 */
196 public void end();
197
198
199 /**
200 * The same as the {@link #end end} callback method except that it
201 * takes an additional reference argument. This reference is
202 * identical to the opaque reference provided when {@link
203 * GLU#gluTessBeginPolygon gluTessBeginPolygon} was called.
204 *
205 * @param polygonData
206 * Specifics a reference to user-defined data.
207 *
208 * @see GLU#gluTessCallback gluTessCallback
209 * @see #beginData beginData
210 * @see #end end
211 */
212 public void endData(Object polygonData);
213
214
215 /**
216 * The <b>combine</b> callback method is called to create a new vertex when
217 * the tessellation detects an intersection, or wishes to merge features. The
218 * method takes four arguments: an array of three elements each of type
219 * double, an array of four references, an array of four elements each of
220 * type float, and a reference to a reference.<P>
221 *
222 * The vertex is defined as a linear combination of up to four existing
223 * vertices, stored in <i>data</i>. The coefficients of the linear combination
224 * are given by <i>weight</i>; these weights always add up to 1. All vertex
225 * pointers are valid even when some of the weights are 0. <i>coords</i> gives
226 * the location of the new vertex.<P>
227 *
228 * The user must allocate another vertex, interpolate parameters using
229 * <i>data</i> and <i>weight</i>, and return the new vertex pointer in
230 * <i>outData</i>. This handle is supplied during rendering callbacks. The
231 * user is responsible for freeing the memory some time after
232 * {@link GLU#gluTessEndPolygon gluTessEndPolygon} is
233 * called.<P>
234 *
235 * For example, if the polygon lies in an arbitrary plane in 3-space, and a
236 * color is associated with each vertex, the <b>GLU_TESS_COMBINE</b>
237 * callback might look like this:
238 * </UL>
239 * <PRE>
240 * void myCombine(double[] coords, Object[] data,
241 * float[] weight, Object[] outData)
242 * {
243 * MyVertex newVertex = new MyVertex();
244 *
245 * newVertex.x = coords[0];
246 * newVertex.y = coords[1];
247 * newVertex.z = coords[2];
248 * newVertex.r = weight[0]*data[0].r +
249 * weight[1]*data[1].r +
250 * weight[2]*data[2].r +
251 * weight[3]*data[3].r;
252 * newVertex.g = weight[0]*data[0].g +
253 * weight[1]*data[1].g +
254 * weight[2]*data[2].g +
255 * weight[3]*data[3].g;
256 * newVertex.b = weight[0]*data[0].b +
257 * weight[1]*data[1].b +
258 * weight[2]*data[2].b +
259 * weight[3]*data[3].b;
260 * newVertex.a = weight[0]*data[0].a +
261 * weight[1]*data[1].a +
262 * weight[2]*data[2].a +
263 * weight[3]*data[3].a;
264 * outData = newVertex;
265 * }</PRE>
266 *
267 * @param coords
268 * Specifics the location of the new vertex.
269 * @param data
270 * Specifics the vertices used to create the new vertex.
271 * @param weight
272 * Specifics the weights used to create the new vertex.
273 * @param outData
274 * Reference user the put the coodinates of the new vertex.
275 *
276 * @see GLU#gluTessCallback gluTessCallback
277 * @see #combineData combineData
278 */
279 public void combine(double[] coords, Object[] data,
280 float[] weight, Object[] outData);
281
282
283 /**
284 * The same as the {@link #combine combine} callback method except
285 * that it takes an additional reference argument. This reference is
286 * identical to the opaque reference provided when {@link
287 * GLU#gluTessBeginPolygon gluTessBeginPolygon} was called.
288 *
289 * @param coords
290 * Specifics the location of the new vertex.
291 * @param data
292 * Specifics the vertices used to create the new vertex.
293 * @param weight
294 * Specifics the weights used to create the new vertex.
295 * @param outData
296 * Reference user the put the coodinates of the new vertex.
297 * @param polygonData
298 * Specifics a reference to user-defined data.
299 *
300 * @see GLU#gluTessCallback gluTessCallback
301 * @see #combine combine
302 */
303 public void combineData(double[] coords, Object[] data,
304 float[] weight, Object[] outData,
305 Object polygonData);
306
307
308 /**
309 * The <b>error</b> callback method is called when an error is encountered.
310 * The one argument is of type int; it indicates the specific error that
311 * occurred and will be set to one of <b>GLU_TESS_MISSING_BEGIN_POLYGON</b>,
312 * <b>GLU_TESS_MISSING_END_POLYGON</b>, <b>GLU_TESS_MISSING_BEGIN_CONTOUR</b>,
313 * <b>GLU_TESS_MISSING_END_CONTOUR</b>, <b>GLU_TESS_COORD_TOO_LARGE</b>,
314 * <b>GLU_TESS_NEED_COMBINE_CALLBACK</b> or <b>GLU_OUT_OF_MEMORY</b>.
315 * Character strings describing these errors can be retrieved with the
316 * {@link GLU#gluErrorString gluErrorString} call.<P>
317 *
318 * The GLU library will recover from the first four errors by inserting the
319 * missing call(s). <b>GLU_TESS_COORD_TOO_LARGE</b> indicates that some
320 * vertex coordinate exceeded the predefined constant
321 * <b>GLU_TESS_MAX_COORD</b> in absolute value, and that the value has been
322 * clamped. (Coordinate values must be small enough so that two can be
323 * multiplied together without overflow.)
324 * <b>GLU_TESS_NEED_COMBINE_CALLBACK</b> indicates that the tessellation
325 * detected an intersection between two edges in the input data, and the
326 * <b>GLU_TESS_COMBINE</b> or <b>GLU_TESS_COMBINE_DATA</b> callback was not
327 * provided. No output is generated. <b>GLU_OUT_OF_MEMORY</b> indicates that
328 * there is not enough memory so no output is generated.
329 *
330 * @param errnum
331 * Specifics the error number code.
332 *
333 * @see GLU#gluTessCallback gluTessCallback
334 * @see #errorData errorData
335 */
336 public void error(int errnum);
337
338
339 /**
340 * The same as the {@link #error error} callback method except that
341 * it takes an additional reference argument. This reference is
342 * identical to the opaque reference provided when {@link
343 * GLU#gluTessBeginPolygon gluTessBeginPolygon} was called.
344 *
345 * @param errnum
346 * Specifics the error number code.
347 * @param polygonData
348 * Specifics a reference to user-defined data.
349 *
350 * @see GLU#gluTessCallback gluTessCallback
351 * @see #error error
352 */
353 public void errorData(int errnum, Object polygonData);
354
355 //void mesh(jogamp.opengl.tessellator.GLUmesh mesh);
356}
GLUtessellatorCallback interface provides methods that the user will override to define the callbacks...
void error(int errnum)
The error callback method is called when an error is encountered.
void combineData(double[] coords, Object[] data, float[] weight, Object[] outData, Object polygonData)
The same as the combine callback method except that it takes an additional reference argument.
void endData(Object polygonData)
The same as the end callback method except that it takes an additional reference argument.
void combine(double[] coords, Object[] data, float[] weight, Object[] outData)
The combine callback method is called to create a new vertex when the tessellation detects an interse...
void edgeFlagData(boolean boundaryEdge, Object polygonData)
The same as the edgeFlage callback method except that it takes an additional reference argument.
void vertex(Object vertexData)
The vertex callback method is invoked between the begin and end callback methods.
void end()
The end callback serves the same purpose as glEnd.
void vertexData(Object vertexData, Object polygonData)
The same as the vertex callback method except that it takes an additional reference argument.
void begin(int type)
The begin callback method is invoked like glBegin to indicate the start of a (triangle) primitive.
void beginData(int type, Object polygonData)
The same as the begin callback method except that it takes an additional reference argument.
void errorData(int errnum, Object polygonData)
The same as the error callback method except that it takes an additional reference argument.
void edgeFlag(boolean boundaryEdge)
The edgeFlag callback method is similar to glEdgeFlag.