Subversion Repositories AndroidProjects

<?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="gluNurbsProperty">

    <refmeta>

        <refmetainfo>

            <copyright>

                <year>1991-2006</year>

                <holder>Silicon Graphics, Inc.</holder>

            </copyright>

        </refmetainfo>

        <refentrytitle>gluNurbsProperty</refentrytitle>

        <manvolnum>3G</manvolnum>

    </refmeta>

    <refnamediv>

        <refname>gluNurbsProperty</refname>

        <refpurpose>set a NURBS property</refpurpose>

    </refnamediv>

    <refsynopsisdiv><title>C Specification</title>

        <funcsynopsis>

            <funcprototype>

                <funcdef>void <function>gluNurbsProperty</function></funcdef>

                <paramdef>GLUnurbs* <parameter>nurb</parameter></paramdef>

                <paramdef>GLenum <parameter>property</parameter></paramdef>

                <paramdef>GLfloat <parameter>value</parameter></paramdef>

            </funcprototype>

        </funcsynopsis>

    </refsynopsisdiv>

    <!-- eqn: ignoring delim $$ -->

    <refsect1 id="parameters"><title>Parameters</title>

        <variablelist>

        <varlistentry>

            <term><parameter>nurb</parameter></term>

            <listitem>

                <para>

                    Specifies the NURBS object (created with <citerefentry><refentrytitle>gluNewNurbsRenderer</refentrytitle></citerefentry>).

                </para>

            </listitem>

        </varlistentry>

        <varlistentry>

            <term><parameter>property</parameter></term>

            <listitem>

                <para>

                    Specifies the property to be set. Valid values are

                    <constant>GLU_SAMPLING_TOLERANCE</constant>,

                    <constant>GLU_DISPLAY_MODE</constant>,

                    <constant>GLU_CULLING</constant>,

                    <constant>GLU_AUTO_LOAD_MATRIX</constant>,

                    <constant>GLU_PARAMETRIC_TOLERANCE</constant>,

                    <constant>GLU_SAMPLING_METHOD</constant>,

                    <constant>GLU_U_STEP</constant>,

                    <constant>GLU_V_STEP</constant>, or

                    <constant>GLU_NURBS_MODE</constant>.

                </para>

            </listitem>

        </varlistentry>

        <varlistentry>

            <term><parameter>value</parameter></term>

            <listitem>

                <para>

                    Specifies the value of the indicated property.

                    It may be a numeric value or one of

                    <constant>GLU_OUTLINE_POLYGON</constant>,

                    <constant>GLU_FILL</constant>,

                    <constant>GLU_OUTLINE_PATCH</constant>,

                    <constant>GLU_TRUE</constant>,

                    <constant>GLU_FALSE</constant>,

                    <constant>GLU_PATH_LENGTH</constant>,

                    <constant>GLU_PARAMETRIC_ERROR</constant>,

                    <constant>GLU_DOMAIN_DISTANCE</constant>,

                    <constant>GLU_NURBS_RENDERER</constant>, or

                    <constant>GLU_NURBS_TESSELLATOR</constant>.

                </para>

            </listitem>

        </varlistentry>

        </variablelist>

    </refsect1>

    <refsect1 id="description"><title>Description</title>

        <para>

            <function>gluNurbsProperty</function> is used to control properties stored in a NURBS object. These

            properties affect the way that a NURBS curve is rendered. The accepted

            values for <parameter>property</parameter> are as follows:

        </para>

        <variablelist>

            <varlistentry>

                <term><constant>GLU_NURBS_MODE</constant></term>

                <listitem>

                    <para>

                        <parameter>value</parameter> should be set to be either <constant>GLU_NURBS_RENDERER</constant> or

                        <constant>GLU_NURBS_TESSELLATOR</constant>. When set to <constant>GLU_NURBS_RENDERER</constant>, NURBS objects

                        are tessellated into OpenGL primitives and sent to the pipeline for

                        rendering. When set to <constant>GLU_NURBS_TESSELLATOR</constant>, NURBS objects are

                        tessellated into OpenGL primitives but the vertices, normals, colors, and/or textures are

                        retrieved back through a callback interface (see <citerefentry><refentrytitle>gluNurbsCallback</refentrytitle></citerefentry>). This allows the user to cache the

                        tessellated results for further processing.

                        The initial value is <constant>GLU_NURBS_RENDERER</constant>.

                    </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term><constant>GLU_SAMPLING_METHOD</constant> </term>

                <listitem>

                    <para>

                        Specifies how a NURBS surface should be

                        tessellated.

                        <parameter>value</parameter> may be one of <constant>GLU_PATH_LENGTH</constant>,

                        <constant>GLU_PARAMETRIC_ERROR</constant>,  <constant>GLU_DOMAIN_DISTANCE</constant>,

                        <constant>GLU_OBJECT_PATH_LENGTH</constant>, or

                        <constant>GLU_OBJECT_PARAMETRIC_ERROR</constant>.

                        When set to <constant>GLU_PATH_LENGTH</constant>, the surface is rendered so that

                        the maximum length, in

                        pixels, of the edges of the tessellation polygons is no greater than

                        what is specified by <constant>GLU_SAMPLING_TOLERANCE</constant>.

                    </para>

                    <para>

                        <constant>GLU_PARAMETRIC_ERROR</constant> specifies that the surface is rendered in such a

                        way that the value specified by <constant>GLU_PARAMETRIC_TOLERANCE</constant> describes the

                        maximum distance, in pixels, between the tessellation polygons and the

                        surfaces they approximate.

                    </para>

                    <para>

                        <constant>GLU_DOMAIN_DISTANCE</constant> allows users to specify, in parametric coordinates,

                        how many sample points per unit length are taken in <emphasis>u</emphasis>, <emphasis>v</emphasis>

                        direction.

                    </para>

                    <para>

                        <constant>GLU_OBJECT_PATH_LENGTH</constant>  is similar to <constant>GLU_PATH_LENGTH</constant>

                        except that it is view independent; that is, the surface is rendered so that the maximum length, in object space, of edges of the tessellation polygons is no greater than what is specified by <constant>GLU_SAMPLING_TOLERANCE</constant>.

                    </para>

                    <para>

                        <constant>GLU_OBJECT_PARAMETRIC_ERROR</constant> is similar to  <constant>GLU_PARAMETRIC_ERROR</constant> except that it is view independent; that is, the surface is rendered in such a way that the value specified by <constant>GLU_PARAMETRIC_TOLERANCE</constant> describes the maximum distance, in object space, between the tessellation polygons and the surfaces they approximate.

                    </para>

                    <para>

                        The initial value of <constant>GLU_SAMPLING_METHOD</constant> is <constant>GLU_PATH_LENGTH</constant>.

                    </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term><constant>GLU_SAMPLING_TOLERANCE</constant></term>

                <listitem>

                    <para>

                        Specifies the maximum length, in pixels or in object space length unit,

                        to use when the sampling method is set to <constant>GLU_PATH_LENGTH</constant> or

                        <constant>GLU_OBJECT_PATH_LENGTH</constant>.

                        The NURBS code is conservative when rendering a curve

                        or surface, so the actual length can be somewhat shorter. The initial

                        value is 50.0 pixels.

                    </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term><constant>GLU_PARAMETRIC_TOLERANCE</constant></term>

                <listitem>

                    <para>

                        Specifies the maximum distance, in pixels or in object space length unit,

                        to use when the sampling method is <constant>GLU_PARAMETRIC_ERROR</constant> or

                        <constant>GLU_OBJECT_PARAMETRIC_ERROR</constant>.

                        The initial value is 0.5.

                    </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term><constant>GLU_U_STEP</constant></term>

                <listitem>

                    <para>

                        Specifies the number of sample points per unit length taken

                        along the <emphasis>u</emphasis> axis in parametric coordinates. It is needed when

                        <constant>GLU_SAMPLING_METHOD</constant> is set to <constant>GLU_DOMAIN_DISTANCE</constant>.

                        The initial value is 100.

                    </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term><constant>GLU_V_STEP</constant></term>

                <listitem>

                    <para>

                        Specifies the number of sample points per unit length taken

                        along the <emphasis>v</emphasis> axis in parametric coordinate. It is needed when

                        <constant>GLU_SAMPLING_METHOD</constant> is set to <constant>GLU_DOMAIN_DISTANCE</constant>. The initial

                        value is 100.

                    </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term><constant>GLU_DISPLAY_MODE</constant></term>

                <listitem>

                    <para>

                        <parameter>value</parameter> can be set to

                        <constant>GLU_OUTLINE_POLYGON</constant>, <constant>GLU_FILL</constant>, or

                        <constant>GLU_OUTLINE_PATCH</constant>.

                        When <constant>GLU_NURBS_MODE</constant> is set to be <constant>GLU_NURBS_RENDERER</constant>,

                        <parameter>value</parameter> defines how a NURBS surface should be rendered.

                        When <parameter>value</parameter> is set to <constant>GLU_FILL</constant>, the surface is rendered as a

                        set of polygons. When <parameter>value</parameter> is set to

                        <constant>GLU_OUTLINE_POLYGON</constant>, the NURBS library draws only the outlines

                        of the polygons created by tessellation. When <parameter>value</parameter> is set to

                        <constant>GLU_OUTLINE_PATCH</constant> just the outlines of patches and trim

                        curves defined by the user are drawn.

                    </para>

                    <para>

                        When <constant>GLU_NURBS_MODE</constant> is set to be <constant>GLU_NURBS_TESSELLATOR</constant>,

                        <parameter>value</parameter> defines how a NURBS surface should be tessellated.

                        When <constant>GLU_DISPLAY_MODE</constant> is set to <constant>GLU_FILL</constant> or

                        <constant>GLU_OUTLINE_POLYGON</constant>,

                        the NURBS surface is tessellated into OpenGL triangle primitives that can be

                        retrieved back  through callback functions. If <constant>GLU_DISPLAY_MODE</constant> is set to

                        <constant>GLU_OUTLINE_PATCH</constant>, only the outlines of the patches and trim curves are generated as a sequence of line strips that can be retrieved back through callback functions.

                    </para>

                    <para>

                        The initial value is <constant>GLU_FILL</constant>.

                    </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term><constant>GLU_CULLING</constant></term>

                <listitem>

                    <para>

                        <parameter>value</parameter> is a boolean value that, when set to <constant>GLU_TRUE</constant>, indicates that

                        a NURBS curve should be discarded prior to tessellation if its control points

                        lie outside the current viewport. The initial value is <constant>GLU_FALSE</constant>.

                    </para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term><constant>GLU_AUTO_LOAD_MATRIX</constant></term>

                <listitem>

                    <para>

                        <parameter>value</parameter> is a boolean value. When set to <constant>GLU_TRUE</constant>, the NURBS code

                        downloads the projection matrix, the modelview matrix, and the

                        viewport from the GL server to compute sampling and

                        culling

                        matrices for each NURBS curve that is rendered. Sampling and culling matrices

                        are required to determine the tessellation of a NURBS surface into line segments

                        or polygons and to cull a NURBS surface if it lies outside the viewport.

                    </para>

                    <para>

                        If this mode is set to <constant>GLU_FALSE</constant>, then the program needs

                        to provide a projection matrix, a modelview matrix, and a viewport

                        for the NURBS renderer to use to construct sampling and culling matrices.

                        This can be done with the <citerefentry><refentrytitle>gluLoadSamplingMatrices</refentrytitle></citerefentry> function.

                        This mode is initially set to <constant>GLU_TRUE</constant>.

                        Changing it from <constant>GLU_TRUE</constant> to <constant>GLU_FALSE</constant> does not affect

                        the sampling and culling matrices until

                        <citerefentry><refentrytitle>gluLoadSamplingMatrices</refentrytitle></citerefentry>

                        is called.

                    </para>

                </listitem>

            </varlistentry>

        </variablelist>

    </refsect1>

    <refsect1 id="notes"><title>Notes</title>

        <para>

            If <constant>GLU_AUTO_LOAD_MATRIX</constant> is true, sampling and culling may be

            executed incorrectly if NURBS routines are compiled into a display list.

        </para>

        <para>

            A <parameter>property</parameter> of

            <constant>GLU_PARAMETRIC_TOLERANCE</constant>,

            <constant>GLU_SAMPLING_METHOD</constant>,

            <constant>GLU_U_STEP</constant>, or

            <constant>GLU_V_STEP</constant>,

            or a <parameter>value</parameter> of

            <constant>GLU_PATH_LENGTH</constant>,

            <constant>GLU_PARAMETRIC_ERROR</constant>,

            <constant>GLU_DOMAIN_DISTANCE</constant>

            are only available if the GLU version is 1.1 or greater. They are not

            valid parameters in GLU 1.0.

        </para>

        <para>

            <citerefentry><refentrytitle>gluGetString</refentrytitle></citerefentry> can

            be used to determine the GLU version.

        </para>

        <para>

            <constant>GLU_NURBS_MODE</constant> is only available if the GLU version is 1.3 or

            greater.

        </para>

        <para>

            The <constant>GLU_OBJECT_PATH_LENGTH</constant> and <constant>GLU_OBJECT_PARAMETRIC_ERROR</constant>

            values for the <constant>GLU_SAMPLING_METHOD</constant> property are only available if

            the GLU version is 1.3 or greater.

        </para>

    </refsect1>

    <refsect1 id="seealso"><title>See Also</title>

        <para>

            <citerefentry><refentrytitle>gluGetNurbsProperty</refentrytitle></citerefentry>,

            <citerefentry><refentrytitle>gluGetString</refentrytitle></citerefentry>,

            <citerefentry><refentrytitle>gluLoadSamplingMatrices</refentrytitle></citerefentry>,

            <citerefentry><refentrytitle>gluNewNurbsRenderer</refentrytitle></citerefentry>,

            <citerefentry><refentrytitle>gluNurbsCallback</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>