upstream-doc/man2/gluNurbsCallback.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="gluNurbsCallback">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>gluNurbsCallback</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>gluNurbsCallback</refname>
  17         <refpurpose>define a callback for a NURBS object</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>gluNurbsCallback</function></funcdef>
  23                 <paramdef>GLUnurbs* <parameter>nurb</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>nurb</parameter></term>
  34             <listitem>
  35                 <para>
  36                     Specifies the NURBS object (created with <citerefentry><refentrytitle>gluNewNurbsRenderer</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.
  45                     Valid values are <constant>GLU_NURBS_BEGIN</constant>, <constant>GLU_NURBS_VERTEX</constant>, <constant>GLU_NURBS_NORMAL</constant>, <constant>GLU_NURBS_COLOR</constant>, <constant>GLU_NURBS_TEXTURE_COORD</constant>, <constant>GLU_NURBS_END</constant>, <constant>GLU_NURBS_BEGIN_DATA</constant>, <constant>GLU_NURBS_VERTEX_DATA</constant>, <constant>GLU_NURBS_NORMAL_DATA</constant>, <constant>GLU_NURBS_COLOR_DATA</constant>, <constant>GLU_NURBS_TEXTURE_COORD_DATA</constant>, <constant>GLU_NURBS_END_DATA</constant>, and <constant>GLU_NURBS_ERROR</constant>.
  46                 </para>
  47             </listitem>
  48         </varlistentry>
  49         <varlistentry>
  50             <term><parameter>CallBackFunc</parameter></term>
  51             <listitem>
  52                 <para>
  53                     Specifies the function that the callback calls.
  54                 </para>
  55             </listitem>
  56         </varlistentry>
  57         </variablelist>
  58     </refsect1>
  59     <refsect1 id="description"><title>Description</title>
  60         <para>
  61             <function>gluNurbsCallback</function> is used to define a callback to be used by a NURBS
  62             object.
  63             If the specified callback is already defined, then it is replaced.  If
  64             <parameter>CallBackFunc</parameter> is NULL, then this callback will not get
  65             invoked and the related data, if any, will be lost.
  66         </para>
  67         <para>
  68             Except the error callback, these callbacks are used by NURBS tessellator (when <constant>GLU_NURBS_MODE</constant> is set to be <constant>GLU_NURBS_TESSELLATOR</constant>) to return back the OpenGL
  69             polygon primitives resulting from the tessellation. Note that there are two
  70             versions of each callback: one with a user data pointer and one without. If both versions for a particular callback are specified then the callback with
  71             the user data pointer will be used. Note that ``userData'' is a copy of the pointer that was specified at the last call to <function>gluNurbsCallbackData</function>.
  72         </para>
  73         <para>
  74             The error callback function is effective no matter which value that
  75             <constant>GLU_NURBS_MODE</constant> is set to.
  76             All other callback functions are effective only when <constant>GLU_NURBS_MODE</constant>
  77             is set to <constant>GLU_NURBS_TESSELLATOR</constant>.
  78         </para>
  79         <para>
  80             The legal callbacks are as follows:
  81         </para>
  82         <variablelist>
  83             <varlistentry>
  84                 <term><constant>GLU_NURBS_BEGIN</constant></term>
  85                 <listitem>
  86                     <para>
  87                     </para>
  88                     <para>
  89                         The begin callback indicates the start of a primitive. The function
  90                         takes a single argument of type GLenum, which can be one of
  91                         <constant>GLU_LINES</constant>, <constant>GLU_LINE_STRIP</constant>, <constant>GLU_TRIANGLE_FAN</constant>, <constant>GLU_TRIANGLE_STRIP</constant>, <constant>GLU_TRIANGLES</constant>, or <constant>GLU_QUAD_STRIP</constant>. The
  92                         default begin callback function is NULL. The function prototype
  93                         for this callback looks like:
  94                         <programlisting>
  95 void begin( GLenum type );
  96                         </programlisting>
  97                     </para>
  98                 </listitem>
  99             </varlistentry>
 100             <varlistentry>
 101                 <term><constant>GLU_NURBS_BEGIN_DATA</constant></term>
 102                 <listitem>
 103                     <para>
 104                     </para>
 105                     <para>
 106                         The same as the <constant>GLU_NURBS_BEGIN</constant> callback except that it takes an
 107                         additional pointer argument. This pointer is a copy of the pointer that
 108                         was specified at the last call to <function>gluNurbsCallbackData</function>.  The
 109                         default callback function is NULL. The function prototype for this
 110                         callback function looks like:
 111                         <programlisting>
 112 void beginData(GLenum type, void *userData);
 113                         </programlisting>
 114                     </para>
 115                 </listitem>
 116             </varlistentry>
 117             <varlistentry>
 118                 <term><constant>GLU_NURBS_VERTEX</constant></term>
 119                 <listitem>
 120                     <para>
 121                     </para>
 122                     <para>
 123                         The vertex callback indicates a vertex of the primitive. The
 124                         coordinates of the vertex are stored in the parameter ``vertex''. All
 125                         the generated vertices have dimension 3; that is, homogeneous
 126                         coordinates have been transformed into affine coordinates. The default
 127                         vertex callback function is NULL. The function prototype for this
 128                         callback function looks like:
 129                         <programlisting>
 130 void vertex( GLfloat *vertex );
 131                         </programlisting>
 132                     </para>
 133                 </listitem>
 134             </varlistentry>
 135             <varlistentry>
 136                 <term><constant>GLU_NURBS_VERTEX_DATA</constant></term>
 137                 <listitem>
 138                     <para>
 139                     </para>
 140                     <para>
 141                         This is the same as the <constant>GLU_NURBS_VERTEX</constant> callback, except that
 142                         it takes an additional pointer argument. This pointer is a copy of the
 143                         pointer that was specified at the last call to
 144                         <function>gluNurbsCallbackData</function>.  The default callback function is NULL. The
 145                         function prototype for this callback function looks like:
 146                         <programlisting>
 147 void vertexData( GLfloat *vertex, void *userData );
 148                         </programlisting>
 149                     </para>
 150                 </listitem>
 151             </varlistentry>
 152             <varlistentry>
 153                 <term><constant>GLU_NURBS_NORMAL</constant></term>
 154                 <listitem>
 155                     <para>
 156                     </para>
 157                     <para>
 158                         The normal callback is invoked as the vertex normal is generated.
 159                         The components of the normal are stored in the parameter ``normal.''
 160                         In the case of a NURBS curve, the callback function is effective only when
 161                         the user provides a normal map (<constant>GLU_MAP1_NORMAL</constant>).
 162                         In the case of a NURBS surface, if a normal map (<constant>GLU_MAP2_NORMAL</constant>)
 163                         is provided, then the generated normal is computed from the normal map.
 164                         If a normal map is not provided, then a surface normal is computed in
 165                         a manner similar to that described for evaluators when <constant>GLU_AUTO_NORMAL</constant>
 166                         is enabled.
 167                         The default normal callback function is NULL. The function
 168                         prototype for this callback function looks like:
 169                         <programlisting>
 170 void normal( GLfloat *normal );
 171                         </programlisting>
 172                     </para>
 173                 </listitem>
 174             </varlistentry>
 175             <varlistentry>
 176                 <term><constant>GLU_NURBS_NORMAL_DATA</constant></term>
 177                 <listitem>
 178                     <para>
 179                     </para>
 180                     <para>
 181                         The same as the <constant>GLU_NURBS_NORMAL</constant> callback except that it
 182                         takes an additional pointer argument. This pointer is a copy of the pointer
 183                         that was specified at the last call to <function>gluNurbsCallbackData</function>.  The default callback function is NULL. The function prototype for this callback function looks like:
 184                         <programlisting>
 185 void normalData( GLfloat *normal, void *userData );
 186                         </programlisting>
 187                     </para>
 188                 </listitem>
 189             </varlistentry>
 190             <varlistentry>
 191                 <term><constant>GLU_NURBS_COLOR</constant></term>
 192                 <listitem>
 193                     <para>
 194                     </para>
 195                     <para>
 196                         The color callback is invoked as the color of a vertex is generated.
 197                         The components of the color are stored in the parameter ``color.''
 198                         This callback is effective only when the user provides a color map
 199                         (<constant>GLU_MAP1_COLOR_4</constant> or <constant>GLU_MAP2_COLOR_4</constant>). ``color'' contains four
 200                         components: R, G, B, A. The default color callback function is NULL.
 201                         The prototype for this callback function looks like:
 202                         <programlisting>
 203 void color( GLfloat *color );
 204                         </programlisting>
 205                     </para>
 206                 </listitem>
 207             </varlistentry>
 208             <varlistentry>
 209                 <term><constant>GLU_NURBS_COLOR_DATA</constant></term>
 210                 <listitem>
 211                     <para>
 212                     </para>
 213                     <para>
 214                         The same as the <constant>GLU_NURBS_COLOR</constant> callback except that it
 215                         takes an additional pointer argument. This pointer is a copy of the pointer
 216                         that was specified at the last call to <function>gluNurbsCallbackData</function>.  The default callback function is NULL. The function prototype for this callback function looks like:
 217                         <programlisting>
 218 void colorData( GLfloat *color, void *userData );
 219                         </programlisting>
 220                     </para>
 221                 </listitem>
 222             </varlistentry>
 223             <varlistentry>
 224                 <term><constant>GLU_NURBS_TEXTURE_COORD</constant></term>
 225                 <listitem>
 226                     <para>
 227                     </para>
 228                     <para>
 229                         The texture callback is invoked as the texture coordinates
 230                         of a vertex are generated. These coordinates are stored in the parameter
 231                         ``texCoord.'' The number of texture coordinates can be 1, 2, 3, or 4 depending
 232                         on which type of texture map is specified
 233                         (<constant>GLU_MAP1_TEXTURE_COORD_1</constant>,
 234                         <constant>GLU_MAP1_TEXTURE_COORD_2</constant>,
 235                         <constant>GLU_MAP1_TEXTURE_COORD_3</constant>,
 236                         <constant>GLU_MAP1_TEXTURE_COORD_4</constant>,
 237                         <constant>GLU_MAP2_TEXTURE_COORD_1</constant>,
 238                         <constant>GLU_MAP2_TEXTURE_COORD_2</constant>,
 239                         <constant>GLU_MAP2_TEXTURE_COORD_3</constant>,
 240                         <constant>GLU_MAP2_TEXTURE_COORD_4</constant>).
 241                         If no texture map is specified, this callback function will not be called.
 242                         The default texture callback function is NULL. The function prototype
 243                         for this callback function looks like:
 244                         <programlisting>
 245 void texCoord( GLfloat *texCoord );
 246                         </programlisting>
 247                     </para>
 248                 </listitem>
 249             </varlistentry>
 250             <varlistentry>
 251                 <term> <constant>GLU_NURBS_TEXTURE_COORD_DATA</constant></term>
 252                 <listitem>
 253                     <para>
 254                     </para>
 255                     <para>
 256                         This is the same as the <constant>GLU_NURBS_TEXTURE_COORD</constant> callback, except that it
 257                         takes an additional pointer argument. This pointer is a copy of the pointer
 258                         that was specified at the last call to <function>gluNurbsCallbackData</function>.  The default callback function is NULL. The function prototype for this callback function looks like:
 259                         <programlisting>
 260 void texCoordData( GLfloat *texCoord, void *userData );
 261                         </programlisting>
 262                     </para>
 263                 </listitem>
 264             </varlistentry>
 265             <varlistentry>
 266                 <term><constant>GLU_NURBS_END</constant></term>
 267                 <listitem>
 268                     <para>
 269                     </para>
 270                     <para>
 271                         The end callback is invoked at the end of a primitive. The default end callback function is NULL. The function prototype for this callback function looks like:
 272                         <programlisting>
 273 void end( void );
 274                         </programlisting>
 275                     </para>
 276                 </listitem>
 277             </varlistentry>
 278             <varlistentry>
 279                 <term><constant>GLU_NURBS_END_DATA</constant></term>
 280                 <listitem>
 281                     <para>
 282                     </para>
 283                     <para>
 284                         This is the same as the <constant>GLU_NURBS_END</constant> callback, except that it
 285                         takes an additional pointer argument. This pointer is a copy of the pointer
 286                         that was specified at the last call to <function>gluNurbsCallbackData</function>.  The default callback function is NULL. The function prototype for this callback function looks like:
 287                         <programlisting>
 288 void endData( void  *userData );
 289                         </programlisting>
 290                     </para>
 291                 </listitem>
 292             </varlistentry>
 293             <varlistentry>
 294                 <term><constant>GLU_NURBS_ERROR</constant></term>
 295                 <listitem>
 296                     <para>
 297                     </para>
 298                     <para>
 299                         The error function is called when an error is encountered.
 300                         Its single argument
 301                         is of type GLenum, and it indicates the specific error that occurred.
 302                         There are 37 errors unique to NURBS, named
 303                         <constant>GLU_NURBS_ERROR1</constant> through <constant>GLU_NURBS_ERROR37</constant>.
 304                         Character strings describing these errors can be retrieved with
 305                         <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>.
 306                     </para>
 307                 </listitem>
 308             </varlistentry>
 309         </variablelist>
 310     </refsect1>
 311     <refsect1 id="notes"><title>Notes</title>
 312         <para>
 313             <function>gluNurbsCallback</function> is available only if the GLU version is 1.2 or greater.
 314         </para>
 315         <para>
 316             GLU version 1.2 supports only the <constant>GLU_ERROR</constant> parameter for
 317             <parameter>which</parameter>. The <constant>GLU_ERROR</constant> value is deprecated in GLU version 1.3 in
 318             favor of <constant>GLU_NURBS_ERROR</constant>.  All other accepted values for <parameter>CallBackFunc</parameter>
 319             are available only if the GLU version is 1.3 or greater.
 320         </para>
 321     </refsect1>
 322     <refsect1 id="seealso"><title>See Also</title>
 323         <para>
 324             <citerefentry><refentrytitle>gluErrorString</refentrytitle></citerefentry>,
 325             <citerefentry><refentrytitle>gluNewNurbsRenderer</refentrytitle></citerefentry>,
 326             <function>gluNurbsCallbackData</function>,
 327             <citerefentry><refentrytitle>gluNurbsProperty</refentrytitle></citerefentry>
 328         </para>
 329     </refsect1>
 330     <refsect1 id="Copyright"><title>Copyright</title>
 331         <para>
 332             Copyright <trademark class="copyright"></trademark> 1991-2006
 333             Silicon Graphics, Inc. This document is licensed under the SGI
 334             Free Software B License. For details, see
 335             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 336         </para>
 337     </refsect1>
 338 </refentry>