diff options
Diffstat (limited to 'nx-X11/extras/ogl-sample/main/doc/man/manglu/standard/tesscallback.gl')
| -rw-r--r-- | nx-X11/extras/ogl-sample/main/doc/man/manglu/standard/tesscallback.gl | 307 |
1 files changed, 307 insertions, 0 deletions
diff --git a/nx-X11/extras/ogl-sample/main/doc/man/manglu/standard/tesscallback.gl b/nx-X11/extras/ogl-sample/main/doc/man/manglu/standard/tesscallback.gl new file mode 100644 index 000000000..efaf5160a --- /dev/null +++ b/nx-X11/extras/ogl-sample/main/doc/man/manglu/standard/tesscallback.gl @@ -0,0 +1,307 @@ +_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: 2004/03/14 08:29:09 $ $Revision: 1.1.1.4 $ +_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) + |