rename upstream-man-pages to upstream-doc

[clinton/guile-figl.git] / upstream-doc / man2 / gluTessNormal.xml

<?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="gluTessNormal">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>gluTessNormal</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>gluTessNormal</refname>
        <refpurpose>specify a normal for a polygon</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>gluTessNormal</function></funcdef>
                <paramdef>GLUtesselator* <parameter>tess</parameter></paramdef>
                <paramdef>GLdouble <parameter>valueX</parameter></paramdef>
                <paramdef>GLdouble <parameter>valueY</parameter></paramdef>
                <paramdef>GLdouble <parameter>valueZ</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>valueX</parameter></term>
            <listitem>
                <para>
                    Specifies the first component of the normal.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>valueY</parameter></term>
            <listitem>
                <para>
                    Specifies the second component of the normal.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>valueZ</parameter></term>
            <listitem>
                <para>
                    Specifies the third component of the normal.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>gluTessNormal</function> describes a normal for a polygon that the program is defining.
            All input data will be projected onto a plane perpendicular to one of 
            the three coordinate axes before tessellation and all output triangles
            will be oriented CCW with 
            respect to the normal (CW orientation can be obtained by reversing the
            sign of the supplied normal). For example, if you know that all polygons
            lie in the x-y plane, call <function>gluTessNormal</function>(tess, 0.0, 0.0, 1.0)
            before rendering any polygons.
        </para>
        <para>
            If the supplied normal is (0.0, 0.0, 0.0) (the initial value), the normal is
            determined as follows. The direction of the normal, up to its sign, is
            found by fitting a plane to the vertices, without regard to how the
            vertices are connected. It is expected that the input data lies approximately
            in the plane; otherwise, projection perpendicular to one of the three
            coordinate axes may substantially change the geometry. The sign of the
            normal is chosen so that the sum of the signed areas of all input
            contours is nonnegative (where a CCW contour has positive area).
        </para>
        <para>
            The supplied normal persists until it is changed by another call to 
            <function>gluTessNormal</function>.
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>gluTessBeginPolygon</refentrytitle></citerefentry>, 
            <citerefentry><refentrytitle>gluTessEndPolygon</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>