upstream-doc/man2/xhtml/gluTessVertex.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>gluTessVertex</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="gluTessVertex"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>gluTessVertex — specify a vertex on a polygon</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">gluTessVertex</b>(</code></td><td>GLUtesselator*  </td><td><var class="pdparam">tess</var>, </td></tr><tr><td> </td><td>GLdouble *  </td><td><var class="pdparam">location</var>, </td></tr><tr><td> </td><td>GLvoid*  </td><td><var class="pdparam">data</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>tess</code></em></span></dt><dd><p>
   4                     Specifies the tessellation object (created with <a class="citerefentry" href="gluNewTess.xml"><span class="citerefentry"><span class="refentrytitle">gluNewTess</span></span></a>).
   5                 </p></dd><dt><span class="term"><em class="parameter"><code>location</code></em></span></dt><dd><p>
   6                     Specifies the location of the vertex.
   7                 </p></dd><dt><span class="term"><em class="parameter"><code>data</code></em></span></dt><dd><p>
   8                     Specifies an opaque pointer passed back to the program with the vertex callback
   9                     (as specified by <a class="citerefentry" href="gluTessCallback.xml"><span class="citerefentry"><span class="refentrytitle">gluTessCallback</span></span></a>).
  10                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  11             <code class="function">gluTessVertex</code> describes a vertex on a polygon that the program defines. Successive
  12             <code class="function">gluTessVertex</code> calls describe a closed contour. For example,
  13             to describe a quadrilateral, <code class="function">gluTessVertex</code> should be called four times.
  14             <code class="function">gluTessVertex</code> can only be called between <a class="citerefentry" href="gluTessBeginContour.xml"><span class="citerefentry"><span class="refentrytitle">gluTessBeginContour</span></span></a> and
  15             <a class="citerefentry" href="gluTessEndContour.xml"><span class="citerefentry"><span class="refentrytitle">gluTessEndContour</span></span></a>.
  16         </p><p>
  17             <em class="parameter"><code>data</code></em> normally points to a structure containing the vertex
  18             location, as well as other per-vertex attributes such as color and normal.
  19             This pointer is passed back to the user through the <code class="constant">GLU_TESS_VERTEX</code>
  20             or <code class="constant">GLU_TESS_VERTEX_DATA</code> callback after tessellation
  21             (see the <a class="citerefentry" href="gluTessCallback.xml"><span class="citerefentry"><span class="refentrytitle">gluTessCallback</span></span></a> reference page).
  22         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="example"></a><h2>Example</h2><p>
  23             A quadrilateral with a triangular hole in it can be described as follows:
  24             </p><pre class="programlisting">
  25 gluTessBeginPolygon(tobj, NULL);
  26    gluTessBeginContour(tobj);
  27       gluTessVertex(tobj, v1, v1);
  28       gluTessVertex(tobj, v2, v2);
  29       gluTessVertex(tobj, v3, v3);
  30       gluTessVertex(tobj, v4, v4);
  31    gluTessEndContour(tobj);
  32    gluTessBeginContour(tobj);
  33       gluTessVertex(tobj, v5, v5);
  34       gluTessVertex(tobj, v6, v6);
  35       gluTessVertex(tobj, v7, v7);
  36    gluTessEndContour(tobj);
  37 gluTessEndPolygon(tobj);
  38             </pre><p>
  39         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
  40             It is a common error to use a local variable for <em class="parameter"><code>location</code></em> or <em class="parameter"><code>data</code></em> and store
  41             values into it as part of a loop.
  42             For example:
  43             </p><pre class="programlisting">
  44 for (i = 0; i &lt; NVERTICES; ++i) {
  45    GLdouble data[3];
  46    data[0] = vertex[i][0];
  47    data[1] = vertex[i][1];
  48    data[2] = vertex[i][2];
  49    gluTessVertex(tobj, data, data);
  50 }
  51             </pre><p>
  52         </p><p>
  53             This doesn't work.
  54             Because the pointers specified by <em class="parameter"><code>location</code></em> and <em class="parameter"><code>data</code></em> might not be
  55             dereferenced until <a class="citerefentry" href="gluTessEndPolygon.xml"><span class="citerefentry"><span class="refentrytitle">gluTessEndPolygon</span></span></a> is executed,
  56             all the vertex coordinates but the very last set could be overwritten
  57             before tessellation begins.
  58         </p><p>
  59             Two common symptoms of this problem are when the data consists of a single
  60             point (when a local variable is used for <em class="parameter"><code>data</code></em>) and a
  61             <code class="constant">GLU_TESS_NEED_COMBINE_CALLBACK</code> error (when a local variable is
  62             used for <em class="parameter"><code>location</code></em>).
  63         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
  64             <a class="citerefentry" href="gluNewTess.xml"><span class="citerefentry"><span class="refentrytitle">gluNewTess</span></span></a>,
  65             <a class="citerefentry" href="gluTessBeginContour.xml"><span class="citerefentry"><span class="refentrytitle">gluTessBeginContour</span></span></a>,
  66             <a class="citerefentry" href="gluTessBeginPolygon.xml"><span class="citerefentry"><span class="refentrytitle">gluTessBeginPolygon</span></span></a>,
  67             <a class="citerefentry" href="gluTessCallback.xml"><span class="citerefentry"><span class="refentrytitle">gluTessCallback</span></span></a>,
  68             <a class="citerefentry" href="gluTessEndPolygon.xml"><span class="citerefentry"><span class="refentrytitle">gluTessEndPolygon</span></span></a>,
  69             <a class="citerefentry" href="gluTessNormal.xml"><span class="citerefentry"><span class="refentrytitle">gluTessNormal</span></span></a>,
  70             <a class="citerefentry" href="gluTessProperty.xml"><span class="citerefentry"><span class="refentrytitle">gluTessProperty</span></span></a>
  71         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
  72             Copyright <span class="trademark"></span>© 1991-2006
  73             Silicon Graphics, Inc. This document is licensed under the SGI
  74             Free Software B License. For details, see
  75             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
  76         </p></div></div></body></html>