diff options
Diffstat (limited to 'xc/extras/ogl-sample/main/doc/man/manglu/standard/tesscallback.gl')
| -rwxr-xr-x | xc/extras/ogl-sample/main/doc/man/manglu/standard/tesscallback.gl | 307 |
1 files changed, 0 insertions, 307 deletions
diff --git a/xc/extras/ogl-sample/main/doc/man/manglu/standard/tesscallback.gl b/xc/extras/ogl-sample/main/doc/man/manglu/standard/tesscallback.gl deleted file mode 100755 index ae76ad2c7..000000000 --- a/xc/extras/ogl-sample/main/doc/man/manglu/standard/tesscallback.gl +++ /dev/null @@ -1,307 +0,0 @@ -_C_ License Applicability. Except to the extent portions of this file are -_C_ made subject to an alternative license as permitted in the SGI Free -_C_ Software License B, Version 1.1 (the "License"), the contents of this -_C_ file are subject only to the provisions of the License. You may not use -_C_ this file except in compliance with the License. You may obtain a copy -_C_ of the License at Silicon Graphics, Inc., attn: Legal Services, 1600 -_C_ Amphitheatre Parkway, Mountain View, CA 94043-1351, or at: -_C_ -_C_ http://oss.sgi.com/projects/FreeB -_C_ -_C_ Note that, as provided in the License, the Software is distributed on an -_C_ "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS -_C_ DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND -_C_ CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A -_C_ PARTICULAR PURPOSE, AND NON-INFRINGEMENT. -_C_ -_C_ Original Code. The Original Code is: OpenGL Sample Implementation, -_C_ Version 1.2.1, released January 26, 2000, developed by Silicon Graphics, -_C_ Inc. The Original Code is Copyright (c) 1991-2000 Silicon Graphics, Inc. -_C_ Copyright in any portions created by third parties is as indicated -_C_ elsewhere herein. All Rights Reserved. -_C_ -_C_ Additional Notice Provisions: The application programming interfaces -_C_ established by SGI in conjunction with the Original Code are The -_C_ OpenGL(R) Graphics System: A Specification (Version 1.2.1), released -_C_ April 1, 1999; The OpenGL(R) Graphics System Utility Library (Version -_C_ 1.3), released November 4, 1998; and OpenGL(R) Graphics with the X -_C_ Window System(R) (Version 1.3), released October 19, 1998. This software -_C_ was created using the OpenGL(R) version 1.2.1 Sample Implementation -_C_ published by SGI, but has not been independently verified as being -_C_ compliant with the OpenGL(R) version 1.2.1 Specification. -_C_ -_C_ $Date: 2001/03/19 17:45:27 $ $Revision: 1.1.1.1 $ -_C_ The first character in this file must be an '_'! -_C_ Anything on a line after _C_ is ignored -_define(_filters,eqn)_C_ -_C_ eqn is automatically replaced with neqn for nroff -_header(TessCallback, define a callback for a tessellation object) -_names(TessCallback) -.EQ -delim $$ -.EN -.SH PARAMETERS -_phead(_param1) -Specifies the tessellation object (created with _cmnd(NewTess)). -_phead(_param2) -Specifies the callback being defined. The following values are valid: -_gluconst(TESS_BEGIN), -_gluconst(TESS_BEGIN_DATA), -_gluconst(TESS_EDGE_FLAG), -_gluconst(TESS_EDGE_FLAG_DATA), -_gluconst(TESS_VERTEX), -_gluconst(TESS_VERTEX_DATA), -_gluconst(TESS_END), -_gluconst(TESS_END_DATA), -_gluconst(TESS_COMBINE), -_gluconst(TESS_COMBINE_DATA), -_gluconst(TESS_ERROR), and -_gluconst(TESS_ERROR_DATA). -_phead(_param3) -Specifies the function to be called. -.SH DESCRIPTION -_cmnd 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 -_param3 is NULL, then the existing callback becomes undefined. -.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 \f2polygon_data\fP parameter used by some of the functions is -a copy of the pointer that was specified when -_cmnd(TessBeginPolygon) was called. The legal callbacks are as follows: -.TP 10 -_gluconst(TESS_BEGIN) -The begin callback is invoked like _glcmnd(Begin) to indicate the start of -a (triangle) primitive. The function takes a single argument of type -GLenum. If the _gluconst(TESS_BOUNDARY_ONLY) property is set to -_const(FALSE), then the argument is set to either -_const(TRIANGLE_FAN), _const(TRIANGLE_STRIP), or _const(TRIANGLES). If -the _gluconst(TESS_BOUNDARY_ONLY) property is set to _const(TRUE), -then the argument will be set to _const(LINE_LOOP). The function -prototype for this callback is: -.RS -.Ex -void begin ( GLenum type ); -.Ee -.RE -.TP -_gluconst(TESS_BEGIN_DATA) -The same as the _gluconst(TESS_BEGIN) callback except that it -takes an additional pointer argument. This pointer is identical to the -opaque pointer provided when -_cmnd(TessBeginPolygon) was called. The function prototype for this callback -is: -.RS -.Ex -void beginData ( GLenum type, void *polygon_data ); -.Ee -.RE -.TP -_gluconst(TESS_EDGE_FLAG) -The edge flag callback is similar to _glcmnd(EdgeFlag). The function -takes a single boolean flag that indicates which edges lie on the -polygon boundary. If the flag is _const(TRUE), 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 _const(FALSE), 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. -.IP -Since triangle fans and triangle strips do not support edge flags, the begin -callback is not called with _const(TRIANGLE_FAN) or _const(TRIANGLE_STRIP) -if a non-NULL edge flag callback is provided. (If the callback is -initialized to NULL, there is no impact on performance). Instead, the fans and -strips are converted to independent triangles. The function prototype -for this callback is: -.RS -.Ex -void edgeFlag ( GLboolean flag ); -.Ee -.RE -.TP -_gluconst(TESS_EDGE_FLAG_DATA) -The same as the _gluconst(TESS_EDGE_FLAG) callback except that it takes an additional pointer -argument. This pointer is identical to the opaque pointer provided when -_cmnd(TessBeginPolygon) was called. The function prototype for this callback -is: -.RS -.Ex -void edgeFlagData ( GLboolean flag, void *polygon_data ); -.Ee -.RE -.TP -_gluconst(TESS_VERTEX) -The vertex callback is invoked between the begin and end callbacks. -It is similar to _glcmnd(Vertex), 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 _cmnd(TessVertex)). The function prototype for this callback is: -.RS -.Ex -void vertex ( void *vertex_data ); -.Ee -.RE -.TP -_gluconst(TESS_VERTEX_DATA) -The same as the _gluconst(TESS_VERTEX) callback except that it takes an additional pointer -argument. This pointer is identical to the opaque pointer provided when -_cmnd(TessBeginPolygon) was called. The function prototype for this callback -is: -.RS -.Ex -void vertexData ( void *vertex_data, void *polygon_data ); -.Ee -.RE -.TP -_gluconst(TESS_END) -The end callback serves the same purpose as _glcmnd(End). It indicates the -end of a primitive and it takes no arguments. The function prototype for this -callback is: -.RS -.Ex -void end ( void ); -.Ee -.RE -.TP -_gluconst(TESS_END_DATA) -The same as the _gluconst(TESS_END) callback except that it takes an additional pointer -argument. This pointer is identical to the opaque pointer provided when -_cmnd(TessBeginPolygon) was called. The function prototype for this callback -is: -.RS -.Ex -void endData ( void *polygon_data); -.Ee -.RE -.TP 10 -_gluconst(TESS_COMBINE) -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: -.RS -.Ex -void combine( GLdouble coords[3], void *vertex_data[4], - GLfloat weight[4], void **outData ); -.Ee -.RE -.IP -The vertex is defined as a linear combination of up to four existing vertices, -stored in \f2vertex_data\fP. The coefficients of the linear -combination are given by \f2weight\fP; these weights always add up to 1. -All vertex pointers are valid even when some of the weights are 0. -\f2coords\fP gives the location of the new vertex. -.IP -The user must allocate another vertex, interpolate parameters using -\f2vertex_data\fP and \f2weight\fP, and return the new vertex pointer in -\f2outData\fP. This handle is supplied during rendering callbacks. -The user is responsible for freeing the memory some time after -_cmnd(TessEndPolygon) is called. -.IP -For example, if the polygon lies in an arbitrary plane in 3-space, -and a color is associated with each vertex, the -_gluconst(TESS_COMBINE) callback might look like this: -.RS -.Ex -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; -} -.Ee -.RE -.IP -If the tessellation detects an intersection, then the _gluconst(TESS_COMBINE) or -_gluconst(TESS_COMBINE_DATA) callback (see below) must be defined, and it must -write a non-NULL pointer into \f2dataOut\fP. Otherwise the -_gluconst(TESS_NEED_COMBINE_CALLBACK) error occurs, and no -output is generated. -.TP -_gluconst(TESS_COMBINE_DATA) -The same as the _gluconst(TESS_COMBINE) callback except that it takes an additional pointer -argument. This pointer is identical to the opaque pointer provided when -_cmnd(TessBeginPolygon) was called. The function prototype for this callback -is: -.RS -.Ex -void combineData ( GLdouble coords[3], void *vertex_data[4], - GLfloat weight[4], void **outData, - void *polygon_data ); -.Ee -.RE -.TP 10 -_gluconst(TESS_ERROR) -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 _gluconst(TESS_MISSING_BEGIN_POLYGON), _gluconst(TESS_MISSING_END_POLYGON), -_gluconst(TESS_MISSING_BEGIN_CONTOUR), _gluconst(TESS_MISSING_END_CONTOUR), -_gluconst(TESS_COORD_TOO_LARGE), _gluconst(TESS_NEED_COMBINE_CALLBACK) or -_gluconst(OUT_OF_MEMORY). Character -strings describing these errors can be retrieved with the -_cmnd(ErrorString) call. The function prototype for this callback is: -.RS -.Ex -void error ( GLenum errno ); -.Ee -.RE -.IP -The GLU library will recover from the first four -errors by inserting the missing call(s). -_gluconst(TESS_COORD_TOO_LARGE) indicates that some vertex coordinate exceeded -the predefined constant _gluconst(TESS_MAX_COORD) 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.) -_gluconst(TESS_NEED_COMBINE_CALLBACK) indicates that the tessellation -detected an intersection between two edges in the input data, and the -_gluconst(TESS_COMBINE) or _gluconst(TESS_COMBINE_DATA) callback was -not provided. No output is generated. _gluconst(OUT_OF_MEMORY) indicates -that there is not enough memory so no output is generated. -.TP -_gluconst(TESS_ERROR_DATA) -The same as the _gluconst(TESS_ERROR) callback except that it takes an additional pointer -argument. This pointer is identical to the opaque pointer provided when -_cmnd(TessBeginPolygon) was called. The function prototype for this callback -is: -.RS -.Ex -void errorData ( GLenum errno, void *polygon_data ); -.Ee -.RE -.SH EXAMPLE -Polygons tessellated can be rendered directly like this: -.sp -.Ex -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, NULL); - gluTessBeginContour(tobj); - gluTessVertex(tobj, v, v); - ... - gluTessEndContour(tobj); -gluTessEndPolygon(tobj); -.Ee -.sp -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. -.SH SEE ALSO -_glcmnd(Begin), _glcmnd(EdgeFlag), _glcmnd(Vertex), _cmnd(NewTess), -_cmnd(ErrorString), _cmnd(TessVertex), -_cmnd(TessBeginPolygon), -_cmnd(TessBeginContour), _cmnd(TessProperty), _cmnd(TessNormal) - |