upstream-man-pages/man2/gluTessCallback.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
   3               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
   4 <refentry id="gluTessCallback">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>gluTessCallback</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>gluTessCallback</refname>
  17         <refpurpose>define a callback for a tessellation object</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>gluTessCallback</function></funcdef>
  23                 <paramdef>GLUtesselator* <parameter>tess</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>which</parameter></paramdef>
  25                 <paramdef>_GLUfuncptr <parameter>CallBackFunc</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28     </refsynopsisdiv>
  29     <!-- eqn: ignoring delim $$ -->
  30     <refsect1 id="parameters"><title>Parameters</title>
  31         <variablelist>
  32         <varlistentry>
  33             <term><parameter>tess</parameter></term>
  34             <listitem>
  35                 <para>
  36                     Specifies the tessellation object (created with <citerefentry><refentrytitle>gluNewTess</refentrytitle></citerefentry>).
  37                 </para>
  38             </listitem>
  39         </varlistentry>
  40         <varlistentry>
  41             <term><parameter>which</parameter></term>
  42             <listitem>
  43                 <para>
  44                     Specifies the callback being defined. The following values are valid:
  45                     <constant>GLU_TESS_BEGIN</constant>,
  46                     <constant>GLU_TESS_BEGIN_DATA</constant>,
  47                     <constant>GLU_TESS_EDGE_FLAG</constant>,
  48                     <constant>GLU_TESS_EDGE_FLAG_DATA</constant>,
  49                     <constant>GLU_TESS_VERTEX</constant>,
  50                     <constant>GLU_TESS_VERTEX_DATA</constant>,
  51                     <constant>GLU_TESS_END</constant>,
  52                     <constant>GLU_TESS_END_DATA</constant>,
  53                     <constant>GLU_TESS_COMBINE</constant>,
  54                     <constant>GLU_TESS_COMBINE_DATA</constant>,
  55                     <constant>GLU_TESS_ERROR</constant>, and
  56                     <constant>GLU_TESS_ERROR_DATA</constant>.
  57                 </para>
  58             </listitem>
  59         </varlistentry>
  60         <varlistentry>
  61             <term><parameter>CallBackFunc</parameter></term>
  62             <listitem>
  63                 <para>
  64                     Specifies the function to be called.
  65                 </para>
  66             </listitem>
  67         </varlistentry>
  68         </variablelist>
  69     </refsect1>
  70     <refsect1 id="description"><title>Description</title>
  71         <para>
  72             <function>gluTessCallback</function> is used to indicate a callback to be used by a tessellation object.
  73             If the specified callback is already defined, then it is replaced. If
  74             <parameter>CallBackFunc</parameter> is NULL, then the existing callback becomes undefined.
  75         </para>
  76         <para>
  77             These callbacks are used by the tessellation object to describe how a
  78             polygon specified by the user is broken into triangles. Note that there
  79             are two versions of each callback: one with user-specified polygon data
  80             and one without. If both versions of a particular callback are specified,
  81             then the callback with user-specified polygon data will be used. Note
  82             that the <emphasis>polygon_data</emphasis> parameter used by some of the functions is
  83             a copy of the pointer that was specified when
  84             <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The legal callbacks are as follows:
  85         </para>
  86         <variablelist>
  87             <varlistentry>
  88                 <term><constant>GLU_TESS_BEGIN</constant></term>
  89                 <listitem>
  90                     <para>
  91                         The begin callback is invoked like <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> to indicate the start of
  92                         a (triangle) primitive. The function takes a single argument of type
  93                         GLenum. If the <constant>GLU_TESS_BOUNDARY_ONLY</constant> property is set to
  94                         <constant>GLU_FALSE</constant>, then the argument is set to either
  95                         <constant>GLU_TRIANGLE_FAN</constant>, <constant>GLU_TRIANGLE_STRIP</constant>, or <constant>GLU_TRIANGLES</constant>.
  96                         If the <constant>GLU_TESS_BOUNDARY_ONLY</constant> property is set to <constant>GLU_TRUE</constant>,
  97                         then the argument will be set to <constant>GLU_LINE_LOOP</constant>. The function
  98                         prototype for this callback is:
  99                         <programlisting>
 100 void begin( GLenum type );
 101                         </programlisting>
 102                     </para>
 103                 </listitem>
 104             </varlistentry>
 105             <varlistentry>
 106                 <term><constant>GLU_TESS_BEGIN_DATA</constant></term>
 107                 <listitem>
 108                     <para>
 109                         The same as the <constant>GLU_TESS_BEGIN</constant> callback except that it
 110                         takes an additional pointer argument. This pointer is identical to the
 111                         opaque pointer provided when
 112                         <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback
 113                         is:
 114                         <programlisting>
 115 void beginData( GLenum type, void *polygon_data );
 116                         </programlisting>
 117                     </para>
 118                 </listitem>
 119             </varlistentry>
 120             <varlistentry>
 121                 <term><constant>GLU_TESS_EDGE_FLAG</constant></term>
 122                 <listitem>
 123                     <para>
 124                         The edge flag callback is similar to <citerefentry><refentrytitle>glEdgeFlag</refentrytitle></citerefentry>. The function
 125                         takes a single boolean flag that indicates which edges lie on the
 126                         polygon boundary. If the flag is <constant>GLU_TRUE</constant>, then each vertex
 127                         that follows begins an edge that lies on the polygon boundary, that is,
 128                         an edge that separates an interior region from an exterior one.
 129                         If the flag is <constant>GLU_FALSE</constant>, then each vertex that follows begins an edge
 130                         that lies in the polygon interior. The edge flag callback (if defined) is
 131                         invoked before the first vertex callback.
 132                     </para>
 133                     <para>
 134                         Since triangle fans and triangle strips do not support edge flags, the begin
 135                         callback is not called with <constant>GLU_TRIANGLE_FAN</constant> or <constant>GLU_TRIANGLE_STRIP</constant>
 136                         if a non-NULL edge flag callback is provided. (If the callback is
 137                         initialized to NULL, there is no impact on performance). Instead, the fans and
 138                         strips are converted to independent triangles. The function prototype
 139                         for this callback is:
 140                         <programlisting>
 141 void edgeFlag( GLboolean flag );
 142                         </programlisting>
 143                     </para>
 144                 </listitem>
 145             </varlistentry>
 146             <varlistentry>
 147                 <term><constant>GLU_TESS_EDGE_FLAG_DATA</constant></term>
 148                 <listitem>
 149                     <para>
 150                         The same as the <constant>GLU_TESS_EDGE_FLAG</constant> callback except that it takes an additional pointer
 151                         argument. This pointer is identical to the opaque pointer provided when
 152                         <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback
 153                         is:
 154                         <programlisting>
 155 void edgeFlagData( GLboolean flag, void *polygon_data );
 156                         </programlisting>
 157                     </para>
 158                 </listitem>
 159             </varlistentry>
 160             <varlistentry>
 161                 <term><constant>GLU_TESS_VERTEX</constant></term>
 162                 <listitem>
 163                     <para>
 164                         The vertex callback is invoked between the begin and end callbacks.
 165                         It is similar to <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>, and it defines the vertices of the triangles
 166                         created by the tessellation process. The function
 167                         takes a pointer as its only argument.  This pointer is identical to
 168                         the opaque pointer provided by the user when the vertex was described
 169                         (see <citerefentry><refentrytitle>gluTessVertex</refentrytitle></citerefentry>). The function prototype for this callback is:
 170                         <programlisting>
 171 void vertex( void *vertex_data );
 172                         </programlisting>
 173                     </para>
 174                 </listitem>
 175             </varlistentry>
 176             <varlistentry>
 177                 <term><constant>GLU_TESS_VERTEX_DATA</constant></term>
 178                 <listitem>
 179                     <para>
 180                         The same as the <constant>GLU_TESS_VERTEX</constant> callback except that it takes an additional pointer
 181                         argument. This pointer is identical to the opaque pointer provided when
 182                         <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback
 183                         is:
 184                         <programlisting>
 185 void vertexData( void *vertex_data, void *polygon_data );
 186                         </programlisting>
 187                     </para>
 188                 </listitem>
 189             </varlistentry>
 190             <varlistentry>
 191                 <term><constant>GLU_TESS_END</constant></term>
 192                 <listitem>
 193                     <para>
 194                         The end callback serves the same purpose as <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>. It indicates the
 195                         end of a primitive and it takes no arguments. The function prototype for this
 196                         callback is:
 197                         <programlisting>
 198 void end( void );
 199                         </programlisting>
 200                     </para>
 201                 </listitem>
 202             </varlistentry>
 203             <varlistentry>
 204                 <term><constant>GLU_TESS_END_DATA</constant></term>
 205                 <listitem>
 206                     <para>
 207                         The same as the <constant>GLU_TESS_END</constant> callback except that it takes an additional pointer
 208                         argument. This pointer is identical to the opaque pointer provided when
 209                         <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback
 210                         is:
 211                         <programlisting>
 212 void endData( void *polygon_data );
 213                         </programlisting>
 214                     </para>
 215                 </listitem>
 216             </varlistentry>
 217             <varlistentry>
 218                 <term><constant>GLU_TESS_COMBINE</constant></term>
 219                 <listitem>
 220                     <para>
 221                         The combine callback is called to create a new vertex when the tessellation
 222                         detects an intersection or wishes to merge features. The function takes
 223                         four arguments: an array of three elements each of type GLdouble, an array
 224                         of four pointers, an array of four elements each of type GLfloat, and a
 225                         pointer to a pointer. The prototype is:
 226                         <programlisting>
 227 void combine( GLdouble coords[3], void *vertex_data[4],
 228               GLfloat weight[4], void **outData );
 229                         </programlisting>
 230                     </para>
 231                     <para>
 232                         The vertex is defined as a linear combination of up to four existing vertices,
 233                         stored in <emphasis>vertex_data</emphasis>. The coefficients of the linear
 234                         combination are given by <emphasis>weight</emphasis>; these weights always add up to 1.
 235                         All vertex pointers are valid even when some of the weights are 0.
 236                         <emphasis>coords</emphasis> gives the location of the new vertex.
 237                     </para>
 238                     <para>
 239                         The user must allocate another vertex, interpolate parameters using
 240                         <emphasis>vertex_data</emphasis> and <emphasis>weight</emphasis>, and return the new vertex pointer in
 241                         <emphasis>outData</emphasis>. This handle is supplied during rendering callbacks.
 242                         The user is responsible for freeing the memory some time after
 243                         <citerefentry><refentrytitle>gluTessEndPolygon</refentrytitle></citerefentry> is called.
 244                     </para>
 245                     <para>
 246                         For example, if the polygon lies in an arbitrary plane in 3-space,
 247                         and a color is associated with each vertex, the
 248                         <constant>GLU_TESS_COMBINE</constant> callback might look like this:
 249                         <programlisting>
 250 void myCombine( GLdouble coords[3], VERTEX *d[4],
 251                 GLfloat w[4], VERTEX **dataOut )
 252 {
 253    VERTEX *new = new_vertex();
 254
 255    new-&gt;x = coords[0];
 256    new-&gt;y = coords[1];
 257    new-&gt;z = coords[2];
 258    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;
 259    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;
 260    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;
 261    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;
 262    *dataOut = new;
 263 }
 264                         </programlisting>
 265                     </para>
 266                     <para>
 267                         If the tessellation detects an intersection, then the <constant>GLU_TESS_COMBINE</constant> or
 268                         <constant>GLU_TESS_COMBINE_DATA</constant> callback (see below) must be defined, and it must
 269                         write a non-NULL pointer into <emphasis>dataOut</emphasis>. Otherwise the
 270                         <constant>GLU_TESS_NEED_COMBINE_CALLBACK</constant> error occurs, and no
 271                         output is generated.
 272                     </para>
 273                 </listitem>
 274             </varlistentry>
 275             <varlistentry>
 276                 <term><constant>GLU_TESS_COMBINE_DATA</constant></term>
 277                 <listitem>
 278                     <para>
 279                         The same as the <constant>GLU_TESS_COMBINE</constant> callback except that it takes an additional pointer
 280                         argument. This pointer is identical to the opaque pointer provided when
 281                         <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback
 282                         is:
 283                         <programlisting>
 284 void combineData( GLdouble coords[3], void *vertex_data[4],
 285                   GLfloat weight[4], void **outData,
 286                   void *polygon_data );
 287                         </programlisting>
 288                     </para>
 289                 </listitem>
 290             </varlistentry>
 291             <varlistentry>
 292                 <term><constant>GLU_TESS_ERROR</constant></term>
 293                 <listitem>
 294                     <para>
 295                         The error callback is called when an error is encountered. The one argument
 296                         is of type GLenum; it indicates the specific error that occurred and will be
 297                         set to one of <constant>GLU_TESS_MISSING_BEGIN_POLYGON</constant>, <constant>GLU_TESS_MISSING_END_POLYGON</constant>,
 298                         <constant>GLU_TESS_MISSING_BEGIN_CONTOUR</constant>, <constant>GLU_TESS_MISSING_END_CONTOUR</constant>,
 299                         <constant>GLU_TESS_COORD_TOO_LARGE</constant>, <constant>GLU_TESS_NEED_COMBINE_CALLBACK</constant>, or
 300                         <constant>GLU_OUT_OF_MEMORY</constant>. Character
 301                         strings describing these errors can be retrieved with the
 302                         <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry> call. The function prototype for this callback is:
 303                         <programlisting>
 304 void error( GLenum errno );
 305                         </programlisting>
 306                     </para>
 307                     <para>
 308                         The GLU library will recover from the first four
 309                         errors by inserting the missing call(s).
 310                         <constant>GLU_TESS_COORD_TOO_LARGE</constant> indicates that some vertex coordinate exceeded
 311                         the predefined constant <constant>GLU_TESS_MAX_COORD</constant> in absolute value, and
 312                         that the value has been clamped. (Coordinate values must be small
 313                         enough so that two can be multiplied together without overflow.)
 314                         <constant>GLU_TESS_NEED_COMBINE_CALLBACK</constant> indicates that the tessellation
 315                         detected an intersection between two edges in the input data, and the
 316                         <constant>GLU_TESS_COMBINE</constant> or <constant>GLU_TESS_COMBINE_DATA</constant> callback was
 317                         not provided. No output is generated. <constant>GLU_OUT_OF_MEMORY</constant> indicates
 318                         that there is not enough memory so no output is generated.
 319                     </para>
 320                 </listitem>
 321             </varlistentry>
 322             <varlistentry>
 323                 <term><constant>GLU_TESS_ERROR_DATA</constant></term>
 324                 <listitem>
 325                     <para>
 326                         The same as the <constant>GLU_TESS_ERROR</constant> callback except that it takes an additional pointer
 327                         argument. This pointer is identical to the opaque pointer provided when
 328                         <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry> was called. The function prototype for this callback
 329                         is:
 330                         <programlisting>
 331 void errorData( GLenum errno, void *polygon_data );
 332                         </programlisting>
 333                     </para>
 334                 </listitem>
 335             </varlistentry>
 336         </variablelist>
 337     </refsect1>
 338     <refsect1 id="example"><title>Example</title>
 339         <para>
 340             Polygons tessellated can be rendered directly like this:
 341             <programlisting>
 342 gluTessCallback(tobj, GLU_TESS_BEGIN, glBegin);
 343 gluTessCallback(tobj, GLU_TESS_VERTEX, glVertex3dv);
 344 gluTessCallback(tobj, GLU_TESS_END, glEnd);
 345 gluTessCallback(tobj, GLU_TESS_COMBINE, myCombine);
 346 gluTessBeginPolygon(tobj, NULL);
 347    gluTessBeginContour(tobj);
 348       gluTessVertex(tobj, v, v);
 349       ...
 350    gluTessEndContour(tobj);
 351 gluTessEndPolygon(tobj);
 352             </programlisting>
 353             Typically, the tessellated polygon should be stored in a display list so that
 354             it does not need to be retessellated every time it is rendered.
 355         </para>
 356     </refsect1>
 357     <refsect1 id="seealso"><title>See Also</title>
 358         <para>
 359             <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>,
 360             <citerefentry><refentrytitle>gluNewTess</refentrytitle></citerefentry>,
 361             <citerefentry><refentrytitle>gluTessBeginContour</refentrytitle></citerefentry>,
 362             <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry>,
 363             <citerefentry><refentrytitle>gluTessNormal</refentrytitle></citerefentry>,
 364             <citerefentry><refentrytitle>gluTessProperty</refentrytitle></citerefentry>,
 365             <citerefentry><refentrytitle>gluTessVertex</refentrytitle></citerefentry>,
 366             <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>,
 367             <citerefentry><refentrytitle>glEdgeFlag</refentrytitle></citerefentry>,
 368             <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>
 369         </para>
 370     </refsect1>
 371     <refsect1 id="Copyright"><title>Copyright</title>
 372         <para>
 373             Copyright <trademark class="copyright"></trademark> 1991-2006
 374             Silicon Graphics, Inc. This document is licensed under the SGI
 375             Free Software B License. For details, see
 376             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 377         </para>
 378     </refsect1>
 379 </refentry>