<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
              "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="gluTessCallback">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>gluTessCallback</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>gluTessCallback</refname>
        <refpurpose>define a callback for a tessellation object</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>gluTessCallback</function></funcdef>
                <paramdef>GLUtesselator* <parameter>tess</parameter></paramdef>
                <paramdef>GLenum <parameter>which</parameter></paramdef>
                <paramdef>_GLUfuncptr <parameter>CallBackFunc</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <!-- eqn: ignoring delim $$ -->
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>tess</parameter></term>
            <listitem>
                <para>
                    Specifies the tessellation object (created with <citerefentry><refentrytitle>gluNewTess</refentrytitle></citerefentry>).
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>which</parameter></term>
            <listitem>
                <para>
                    Specifies the callback being defined. The following values are valid:
                    <constant>GLU_TESS_BEGIN</constant>,
                    <constant>GLU_TESS_BEGIN_DATA</constant>,
                    <constant>GLU_TESS_EDGE_FLAG</constant>,
                    <constant>GLU_TESS_EDGE_FLAG_DATA</constant>,
                    <constant>GLU_TESS_VERTEX</constant>,
                    <constant>GLU_TESS_VERTEX_DATA</constant>,
                    <constant>GLU_TESS_END</constant>, 
                    <constant>GLU_TESS_END_DATA</constant>, 
                    <constant>GLU_TESS_COMBINE</constant>, 
                    <constant>GLU_TESS_COMBINE_DATA</constant>,
                    <constant>GLU_TESS_ERROR</constant>, and
                    <constant>GLU_TESS_ERROR_DATA</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>CallBackFunc</parameter></term>
            <listitem>
                <para>
                    Specifies the function to be called.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>gluTessCallback</function> 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 
            <parameter>CallBackFunc</parameter> is NULL, then the existing callback becomes undefined.
        </para>
        <para>
            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 <emphasis>polygon_data</emphasis> parameter used by some of the functions is
            a copy of the pointer that was specified when 
            <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The legal callbacks are as follows:
        </para>
        <variablelist>
            <varlistentry>
                <term><constant>GLU_TESS_BEGIN</constant></term>
                <listitem>
                    <para>
                        The begin callback is invoked like <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> to indicate the start of 
                        a (triangle) primitive. The function takes a single argument of type
                        GLenum. If the <constant>GLU_TESS_BOUNDARY_ONLY</constant> property is set to
                        <constant>GLU_FALSE</constant>, then the argument is set to either
                        <constant>GLU_TRIANGLE_FAN</constant>, <constant>GLU_TRIANGLE_STRIP</constant>, or <constant>GLU_TRIANGLES</constant>.
                        If the <constant>GLU_TESS_BOUNDARY_ONLY</constant> property is set to <constant>GLU_TRUE</constant>,
                        then the argument will be set to <constant>GLU_LINE_LOOP</constant>. The function
                        prototype for this callback is:
                        <programlisting>
void begin( GLenum type );
                        </programlisting>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLU_TESS_BEGIN_DATA</constant></term>
                <listitem>
                    <para>
                        The same as the <constant>GLU_TESS_BEGIN</constant> callback except that it 
                        takes an additional pointer argument. This pointer is identical to the 
                        opaque pointer provided when
                        <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback
                        is:
                        <programlisting>
void beginData( GLenum type, void *polygon_data );
                        </programlisting>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLU_TESS_EDGE_FLAG</constant></term>
                <listitem>
                    <para>
                        The edge flag callback is similar to <citerefentry><refentrytitle>glEdgeFlag</refentrytitle></citerefentry>. The function
                        takes a single boolean flag that indicates which edges lie on the
                        polygon boundary. If the flag is <constant>GLU_TRUE</constant>, 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 <constant>GLU_FALSE</constant>, 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.
                    </para>
                    <para>
                        Since triangle fans and triangle strips do not support edge flags, the begin 
                        callback is not called with <constant>GLU_TRIANGLE_FAN</constant> or <constant>GLU_TRIANGLE_STRIP</constant>
                        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:
                        <programlisting>
void edgeFlag( GLboolean flag );
                        </programlisting>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLU_TESS_EDGE_FLAG_DATA</constant></term>
                <listitem>
                    <para>
                        The same as the <constant>GLU_TESS_EDGE_FLAG</constant> callback except that it takes an additional pointer
                        argument. This pointer is identical to the opaque pointer provided when
                        <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback
                        is:
                        <programlisting>
void edgeFlagData( GLboolean flag, void *polygon_data );
                        </programlisting>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLU_TESS_VERTEX</constant></term>
                <listitem>
                    <para>
                        The vertex callback is invoked between the begin and end callbacks.
                        It is similar to <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>, 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 <citerefentry><refentrytitle>gluTessVertex</refentrytitle></citerefentry>). The function prototype for this callback is:
                        <programlisting>
void vertex( void *vertex_data );
                        </programlisting>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLU_TESS_VERTEX_DATA</constant></term>
                <listitem>
                    <para>
                        The same as the <constant>GLU_TESS_VERTEX</constant> callback except that it takes an additional pointer 
                        argument. This pointer is identical to the opaque pointer provided when
                        <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback
                        is:
                        <programlisting>
void vertexData( void *vertex_data, void *polygon_data );
                        </programlisting>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLU_TESS_END</constant></term>
                <listitem>
                    <para>
                        The end callback serves the same purpose as <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>. It indicates the 
                        end of a primitive and it takes no arguments. The function prototype for this
                        callback is:
                        <programlisting>
void end( void );
                        </programlisting>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLU_TESS_END_DATA</constant></term>
                <listitem>
                    <para>
                        The same as the <constant>GLU_TESS_END</constant> callback except that it takes an additional pointer 
                        argument. This pointer is identical to the opaque pointer provided when
                        <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback
                        is:
                        <programlisting>
void endData( void *polygon_data );
                        </programlisting>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLU_TESS_COMBINE</constant></term>
                <listitem>
                    <para>
                        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:
                        <programlisting>
void combine( GLdouble coords[3], void *vertex_data[4], 
              GLfloat weight[4], void **outData );
                        </programlisting>
                    </para>
                    <para>
                        The vertex is defined as a linear combination of up to four existing vertices, 
                        stored in <emphasis>vertex_data</emphasis>. The coefficients of the linear
                        combination are given by <emphasis>weight</emphasis>; these weights always add up to 1.
                        All vertex pointers are valid even when some of the weights are 0.
                        <emphasis>coords</emphasis> gives the location of the new vertex.
                    </para>
                    <para>
                        The user must allocate another vertex, interpolate parameters using 
                        <emphasis>vertex_data</emphasis> and <emphasis>weight</emphasis>, and return the new vertex pointer in
                        <emphasis>outData</emphasis>. This handle is supplied during rendering callbacks.
                        The user is responsible for freeing the memory some time after 
                        <citerefentry><refentrytitle>gluTessEndPolygon</refentrytitle></citerefentry> is called.
                    </para>
                    <para>
                        For example, if the polygon lies in an arbitrary plane in 3-space,
                        and a color is associated with each vertex, the
                        <constant>GLU_TESS_COMBINE</constant> callback might look like this:
                        <programlisting>
void myCombine( GLdouble coords[3], VERTEX *d[4],
                GLfloat w[4], VERTEX **dataOut )
{
   VERTEX *new = new_vertex();

   new-&gt;x = coords[0];
   new-&gt;y = coords[1];
   new-&gt;z = coords[2];
   new-&gt;r = w[0]*d[0]-&gt;r + w[1]*d[1]-&gt;r + w[2]*d[2]-&gt;r + w[3]*d[3]-&gt;r;
   new-&gt;g = w[0]*d[0]-&gt;g + w[1]*d[1]-&gt;g + w[2]*d[2]-&gt;g + w[3]*d[3]-&gt;g;
   new-&gt;b = w[0]*d[0]-&gt;b + w[1]*d[1]-&gt;b + w[2]*d[2]-&gt;b + w[3]*d[3]-&gt;b;
   new-&gt;a = w[0]*d[0]-&gt;a + w[1]*d[1]-&gt;a + w[2]*d[2]-&gt;a + w[3]*d[3]-&gt;a;
   *dataOut = new;
}
                        </programlisting>
                    </para>
                    <para>
                        If the tessellation detects an intersection, then the <constant>GLU_TESS_COMBINE</constant> or 
                        <constant>GLU_TESS_COMBINE_DATA</constant> callback (see below) must be defined, and it must 
                        write a non-NULL pointer into <emphasis>dataOut</emphasis>. Otherwise the 
                        <constant>GLU_TESS_NEED_COMBINE_CALLBACK</constant> error occurs, and no
                        output is generated.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLU_TESS_COMBINE_DATA</constant></term>
                <listitem>
                    <para>
                        The same as the <constant>GLU_TESS_COMBINE</constant> callback except that it takes an additional pointer 
                        argument. This pointer is identical to the opaque pointer provided when
                        <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback
                        is:
                        <programlisting>
void combineData( GLdouble coords[3], void *vertex_data[4], 
                  GLfloat weight[4], void **outData, 
                  void *polygon_data );
                        </programlisting>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLU_TESS_ERROR</constant></term>
                <listitem>
                    <para>
                        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 <constant>GLU_TESS_MISSING_BEGIN_POLYGON</constant>, <constant>GLU_TESS_MISSING_END_POLYGON</constant>, 
                        <constant>GLU_TESS_MISSING_BEGIN_CONTOUR</constant>, <constant>GLU_TESS_MISSING_END_CONTOUR</constant>, 
                        <constant>GLU_TESS_COORD_TOO_LARGE</constant>, <constant>GLU_TESS_NEED_COMBINE_CALLBACK</constant>, or
                        <constant>GLU_OUT_OF_MEMORY</constant>. Character
                        strings describing these errors can be retrieved with the
                        <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry> call. The function prototype for this callback is:
                        <programlisting>
void error( GLenum errno );
                        </programlisting>
                    </para>
                    <para>
                        The GLU library will recover from the first four
                        errors by inserting the missing call(s).
                        <constant>GLU_TESS_COORD_TOO_LARGE</constant> indicates that some vertex coordinate exceeded
                        the predefined constant <constant>GLU_TESS_MAX_COORD</constant> 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.)
                        <constant>GLU_TESS_NEED_COMBINE_CALLBACK</constant> indicates that the tessellation
                        detected an intersection between two edges in the input data, and the
                        <constant>GLU_TESS_COMBINE</constant> or <constant>GLU_TESS_COMBINE_DATA</constant> callback was
                        not provided. No output is generated. <constant>GLU_OUT_OF_MEMORY</constant> indicates
                        that there is not enough memory so no output is generated.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLU_TESS_ERROR_DATA</constant></term>
                <listitem>
                    <para>
                        The same as the <constant>GLU_TESS_ERROR</constant> callback except that it takes an additional pointer 
                        argument. This pointer is identical to the opaque pointer provided when
                        <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback
                        is:
                        <programlisting>
void errorData( GLenum errno, void *polygon_data );
                        </programlisting>
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="example"><title>Example</title>
        <para>
            Polygons tessellated can be rendered directly like this:
            <programlisting>
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);
            </programlisting>
            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.
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>gluNewTess</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>gluTessBeginContour</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>gluTessNormal</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>gluTessProperty</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>gluTessVertex</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glEdgeFlag</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 1991-2006
            Silicon Graphics, Inc. This document is licensed under the SGI
            Free Software B License. For details, see
            <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
        </para>
    </refsect1>
</refentry>
