upstream-doc/man2/gluBeginTrim.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="gluBeginTrim">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>gluBeginTrim</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>gluBeginTrim</refname>
  17         <refpurpose>delimit a NURBS trimming loop definition</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>gluBeginTrim</function></funcdef>
  23                 <paramdef>GLUnurbs* <parameter>nurb</parameter></paramdef>
  24             </funcprototype>
  25         </funcsynopsis>
  26     </refsynopsisdiv>
  27     <refsynopsisdiv><title>C Specification</title>
  28         <funcsynopsis>
  29             <funcprototype>
  30                 <funcdef>void <function>gluEndTrim</function></funcdef>
  31                 <paramdef>GLUnurbs* <parameter>nurb</parameter></paramdef>
  32             </funcprototype>
  33         </funcsynopsis>
  34     </refsynopsisdiv>
  35     <!-- eqn: ignoring delim $$ -->
  36     <refsect1 id="parameters"><title>Parameters</title>
  37         <variablelist>
  38         <varlistentry>
  39             <term><parameter>nurb</parameter></term>
  40             <listitem>
  41                 <para>
  42                     Specifies the NURBS object (created with <citerefentry><refentrytitle>gluNewNurbsRenderer</refentrytitle></citerefentry>).
  43                 </para>
  44             </listitem>
  45         </varlistentry>
  46         </variablelist>
  47     </refsect1>
  48     <refsect1 id="description"><title>Description</title>
  49         <para>
  50             Use <function>gluBeginTrim</function> to mark the beginning of a
  51             trimming loop and <citerefentry><refentrytitle>gluEndTrim</refentrytitle></citerefentry> to mark the end
  52             of a trimming loop. A trimming loop is
  53             a set of oriented curve segments (forming a closed curve) that
  54             define boundaries of a NURBS surface. You include these
  55             trimming loops in the definition of a NURBS
  56             surface, between calls to <citerefentry><refentrytitle>gluBeginSurface</refentrytitle></citerefentry> and <citerefentry><refentrytitle>gluEndSurface</refentrytitle></citerefentry>.
  57         </para>
  58         <para>
  59             The definition for a NURBS surface can contain many
  60             trimming loops. For example, if you wrote a definition
  61             for a NURBS surface that resembled a rectangle with
  62             a hole punched out, the definition would contain two
  63             trimming loops. One loop would define the outer edge
  64             of the rectangle; the other would define
  65             the hole punched out of the rectangle. The definitions
  66             of each of these trimming loops would be bracketed by a
  67             <function>gluBeginTrim</function>/<citerefentry><refentrytitle>gluEndTrim</refentrytitle></citerefentry> pair.
  68         </para>
  69         <para>
  70             The definition of a single closed trimming loop can consist
  71             of multiple curve segments, each described as a piecewise
  72             linear curve (see <citerefentry><refentrytitle>gluPwlCurve</refentrytitle></citerefentry>) or as a single NURBS
  73             curve (see <citerefentry><refentrytitle>gluNurbsCurve</refentrytitle></citerefentry>), or as a combination of
  74             both in any order. The only library calls that can
  75             appear in a trimming loop definition (between the calls
  76             to <function>gluBeginTrim</function> and <citerefentry><refentrytitle>gluEndTrim</refentrytitle></citerefentry>) are
  77             <citerefentry><refentrytitle>gluPwlCurve</refentrytitle></citerefentry> and <citerefentry><refentrytitle>gluNurbsCurve</refentrytitle></citerefentry>.
  78         </para>
  79         <para>
  80             The area of the NURBS surface that is displayed is the
  81             region in the domain to the left of the trimming curve
  82             as the curve parameter increases. Thus, the retained
  83             region of the NURBS surface is inside a
  84             counterclockwise trimming loop and outside a clockwise
  85             trimming loop. For the rectangle mentioned earlier,
  86             the trimming loop for the outer edge of the rectangle runs
  87             counterclockwise, while the trimming loop for the punched-out hole
  88             runs clockwise.
  89         </para>
  90         <para>
  91             If you use more than one curve to define a single trimming
  92             loop, the curve segments must form a closed loop (that is,
  93             the endpoint of each curve must be the starting point of the
  94             next curve, and the endpoint of the final curve must
  95             be the starting point of the first curve). If the
  96             endpoints of the curve are sufficiently close together
  97             but not exactly coincident, they will be coerced to match.
  98             If the endpoints are not sufficiently close, an error results
  99             (see <citerefentry><refentrytitle>gluNurbsCallback</refentrytitle></citerefentry>).
 100         </para>
 101         <para>
 102             If a trimming loop definition contains multiple curves,
 103             the direction of the curves must be consistent (that is, the
 104             inside must be to the left of all of the curves). Nested
 105             trimming loops are legal as long as the curve orientations
 106             alternate correctly.
 107             If trimming curves are self-intersecting,
 108             or intersect one another, an error results.
 109         </para>
 110         <para>
 111             If no trimming information is given
 112             for a NURBS surface, the entire surface is drawn.
 113         </para>
 114     </refsect1>
 115     <refsect1 id="example"><title>Example</title>
 116         <para>
 117             This code fragment defines a trimming loop that consists of one
 118             piecewise linear curve, and two NURBS curves:
 119             <programlisting>
 120 gluBeginTrim(nobj);
 121    gluPwlCurve(..., GLU_MAP1_TRIM_2);
 122    gluNurbsCurve(..., GLU_MAP1_TRIM_2);
 123    gluNurbsCurve(..., GLU_MAP1_TRIM_3);
 124 gluEndTrim(nobj);
 125             </programlisting>
 126         </para>
 127     </refsect1>
 128     <refsect1 id="seealso"><title>See Also</title>
 129         <para>
 130             <citerefentry><refentrytitle>gluBeginSurface</refentrytitle></citerefentry>,
 131             <citerefentry><refentrytitle>gluNewNurbsRenderer</refentrytitle></citerefentry>,
 132             <citerefentry><refentrytitle>gluNurbsCallback</refentrytitle></citerefentry>,
 133             <citerefentry><refentrytitle>gluNurbsCurve</refentrytitle></citerefentry>,
 134             <citerefentry><refentrytitle>gluPwlCurve</refentrytitle></citerefentry>
 135         </para>
 136     </refsect1>
 137     <refsect1 id="Copyright"><title>Copyright</title>
 138         <para>
 139             Copyright <trademark class="copyright"></trademark> 1991-2006
 140             Silicon Graphics, Inc. This document is licensed under the SGI
 141             Free Software B License. For details, see
 142             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 143         </para>
 144     </refsect1>
 145 </refentry>