gluTessCallback.3gl

OpenGL man pages

gluTessCallback.3gl (GLU version 1.2 and later)

Name

  gluTessCallback - define a callback for a tessellation object

C Specification

  void gluTessCallback(	GLUtesselator *tess,
			GLenum which,
			void (*fn)() )

Parameters


  tess	 Specifies the tessellation object (created with gluNewTess).

  which	 Specifies the callback	being defined.	The following values are
	 valid:	GLU_TESS_BEGIN,	GLU_TESS_BEGIN_DATA, GLU_TESS_EDGE_FLAG,
	 GLU_TESS_EDGE_FLAG_DATA, GLU_TESS_VERTEX, GLU_TESS_VERTEX_DATA,
	 GLU_TESS_END, GLU_TESS_END_DATA, GLU_TESS_COMBINE,
	 GLU_TESS_COMBINE_DATA,	GLU_TESS_ERROR,	and GLU_TESS_ERROR_DATA.

  fn	 Specifies the function	to be called.

Description

  gluTessCallback 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 fn	is NULL, then the existing callback becomes undefined.

  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
  "polygon_data" is a copy of the pointer that was specified when
  gluTessBeginPolygon was called.

  The legal callbacks are as follows:

  GLU_TESS_BEGIN
	    The	begin callback is invoked like glBegin to indicate the start
	    of a (triangle) primitive. The function takes a single argument
	    of type GLenum.  If	the GLU_TESS_BOUNDARY_ONLY property is set to
	    GL_FALSE then the argument is set to either	GL_TRIANGLE_FAN,
	    GL_TRIANGLE_STRIP, or GL_TRIANGLES.	If the GLU_TESS_BOUNDARY_ONLY
	    property is	set to GL_TRUE then the	argument will be set to
	    GL_LINE_LOOP. The function prototype for this callback looks
	    like:

	    void begin ( GLenum	type );

  GLU_TESS_BEGIN_DATA
	    The	same as	the GLU_TESS_BEGIN callback except that	it takes an
	    additional pointer argument. This pointer is identical to the
	    opaque pointer provided when gluTessBeginPolygon was called. The
	    function prototype for this	callback looks like:

	    void beginData ( GLenum type, void *polygon_data );

  GLU_TESS_EDGE_FLAG
	    The	edge flag callback is similar to glEdgeFlag.  The function
	    takes a single Boolean flag	that indicates which edges lie on the
	    polygon boundary. If the flag is GL_TRUE, then each	vertex that
	    follows begins an edge which lies on the polygon boundary -- that
	    is,	an edge	which separates	an interior region from	an exterior
	    one.  If the flag is GL_FALSE, then	each vertex that follows
	    begins an edge which lies in the polygon interior. The edge	flag
	    callback (if defined) is invoked before the	first vertex callback
	    is made.

	    Since triangle fans	and triangle strips do not support edge
	    flags, the begin callback is not called with GL_TRIANGLE_FAN or
	    GL_TRIANGLE_STRIP if an edge flag callback is provided.  Instead,
	    the	fans and strips	are converted to independent triangles.	The
	    function prototype for this	callback looks like:

	    void edgeFlag ( GLboolean flag );

  GLU_TESS_EDGE_FLAG_DATA
	    The	same as	the GLU_TESS_EDGE_FLAG callback	except that it takes
	    an additional pointer argument. This pointer is identical to the
	    opaque pointer provided when gluTessBeginPolygon was called. The
	    function prototype for this	callback looks like:

	    void edgeFlagData (	GLboolean flag,	void *polygon_data );

  GLU_TESS_VERTEX
	    The	vertex callback	is invoked between the begin and end
	    callbacks.	It is similar to glVertex, 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 gluTessVertex). The function prototype
	    for	this callback looks like:

	    void vertex	( void *vertex_data );

  GLU_TESS_VERTEX_DATA
	    The	same as	the GLU_TESS_VERTEX callback except that it takes an
	    additional pointer argument. This pointer is identical to the
	    opaque pointer provided when gluTessBeginPolygon was called. The
	    function prototype for this	callback looks like:

	    void vertexData ( void *vertex_data, void *polygon_data );

  GLU_TESS_END
	    The	end callback serves the	same purpose as	glEnd. It indicates
	    the	end of a primitive and it takes	no arguments. The function
	    prototype for this callback	looks like:

	    void end ( void );

  GLU_TESS_END_DATA
	    The	same as	the GLU_TESS_END callback except that it takes an
	    additional pointer argument. This pointer is identical to the
	    opaque pointer provided when gluTessBeginPolygon was called. The
	    function prototype for this	callback looks like:
	    void endData ( void	*polygon_data);

  GLU_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 looks like:
	    void combine( GLdouble coords[3], void *vertex_data[4],
			  GLfloat weight[4], void **outData );

	    The	vertex is defined as a linear combination of up	to 4 existing
	    vertices, stored in	vertex_data. The coefficients of the linear
	    combination	are given by weight; these weights always sum to 1.0.
	    All	vertex pointers	are valid even when some of the	weights	are
	    zero.  coords gives	the location of	the new	vertex.

	    The	user must allocate another vertex, interpolate parameters
	    using vertex_data and weight, and return the new vertex pointer
	    in outData.	 This handle is	supplied during	rendering callbacks.
	    The	user is	responsible for	freeing	the memory sometime after
	    gluTessEndPolygon is called.

	    For	example, if the	polygon	lies in	an arbitrary plane in 3-space,
	    and we associate a color with each vertex, the GLU_TESS_COMBINE
	    callback might look like this:

	    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;
            }

	    If the tessellation	detects	an intersection, then the
	    GLU_TESS_COMBINE or	GLU_TESS_COMBINE_DATA callback (see below)
	    must be defined, and it must write a non-NULL pointer into
	    dataOut. Otherwise the GLU_TESS_NEED_COMBINE_CALLBACK error
	    occurs, and	no output is generated.	 (This is the only error that
	    can	occur during tessellation and rendering.)

  GLU_TESS_COMBINE_DATA
	    The	same as	the GLU_TESS_COMBINE callback except that it takes an
	    additional pointer argument. This pointer is identical to the
	    opaque pointer provided when gluTessBeginPolygon was called. The
	    function prototype for this	callback looks like:

	    void combineData ( GLdouble	coords[3], void	*vertex_data[4],
			       GLfloat weight[4], void **outData,
			       void *polygon_data );

  GLU_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
	    GLU_TESS_MISSING_BEGIN_POLYGON, GLU_TESS_MISSING_END_POLYGON,
	    GLU_TESS_MISSING_BEGIN_CONTOUR, GLU_TESS_MISSING_END_CONTOUR,
	    GLU_TESS_COORD_TOO_LARGE, GLU_TESS_NEED_COMBINE_CALLBACK.
	    Character strings describing these errors can be retrieved with
	    the	gluErrorString call. The function prototype for	this callback
	    looks like:

	    void error ( GLenum	errno );

	    The	GLU library will recover from the first	four errors by
	    inserting the missing call(s).  GLU_TESS_COORD_TOO_LARGE says
	    that some vertex coordinate	exceeded the predefined	constant
	    GLU_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.)
	    GLU_TESS_NEED_COMBINE_CALLBACK says	that the tessellation
	    detected an	intersection between two edges in the input data, and
	    the	GLU_TESS_COMBINE or GLU_TESS_COMBINE_DATA callback was not
	    provided.  No output will be generated.

  GLU_TESS_ERROR_DATA
	    The	same as	the GLU_TESS_ERROR callback except that	it takes an
	    additional pointer argument. This pointer is identical to the
	    opaque pointer provided when gluTessBeginPolygon was called. The
	    function prototype for this	callback looks like:

	    void errorData ( GLenum errno, void	*polygon_data );

Example

  Polygons tessellated can be rendered directly	like this:

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

  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.

gluTessCallback.3gl

gluTessCallback.3gl (GLU version 1.2 and later)

Name

C Specification

Parameters

Description

Example

See Also