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 1.1 (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 */ 53 package javax.media.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 */ 63 public interface GLUtessellatorCallback { 64 /** 65 * The <b>begin</b> callback method is invoked like 66 * {@link javax.media.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 */ begin(int type)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 */ beginData(int type, Object polygonData)102 public void beginData(int type, Object polygonData); 103 104 105 /** 106 * The <b>edgeFlag</b> callback method is similar to 107 * {@link javax.media.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 */ edgeFlag(boolean boundaryEdge)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 */ edgeFlagData(boolean boundaryEdge, Object polygonData)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 javax.media.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 * byt the tessellatin process. 162 * 163 * @see GLU#gluTessCallback gluTessCallback 164 * @see #vertexData vertexData 165 */ vertex(Object vertexData)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 * byt the tessellatin process. 178 * @param polygonData 179 * Specifics a reference to user-defined data. 180 * 181 * @see GLU#gluTessCallback gluTessCallback 182 * @see #vertex vertex 183 */ vertexData(Object vertexData, Object polygonData)184 public void vertexData(Object vertexData, Object polygonData); 185 186 187 /** 188 * The end callback serves the same purpose as 189 * {@link javax.media.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 */ end()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 */ endData(Object polygonData)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 */ combine(double[] coords, Object[] data, float[] weight, Object[] outData)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 */ combineData(double[] coords, Object[] data, float[] weight, Object[] outData, Object polygonData)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 */ error(int errnum)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 */ errorData(int errnum, Object polygonData)353 public void errorData(int errnum, Object polygonData); 354 355 //void mesh(com.sun.opengl.impl.tessellator.GLUmesh mesh); 356 } 357