path: root/xc/extras/ogl-sample/main/doc/man/manglu/standard/tesscallback.gl

_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)