upstream-doc/man2/gluNurbsProperty.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="gluNurbsProperty">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>gluNurbsProperty</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>gluNurbsProperty</refname>
  17         <refpurpose>set a NURBS property</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>gluNurbsProperty</function></funcdef>
  23                 <paramdef>GLUnurbs* <parameter>nurb</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>property</parameter></paramdef>
  25                 <paramdef>GLfloat <parameter>value</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>property</parameter></term>
  42             <listitem>
  43                 <para>
  44                     Specifies the property to be set. Valid values are
  45                     <constant>GLU_SAMPLING_TOLERANCE</constant>,
  46                     <constant>GLU_DISPLAY_MODE</constant>,
  47                     <constant>GLU_CULLING</constant>,
  48                     <constant>GLU_AUTO_LOAD_MATRIX</constant>,
  49                     <constant>GLU_PARAMETRIC_TOLERANCE</constant>,
  50                     <constant>GLU_SAMPLING_METHOD</constant>,
  51                     <constant>GLU_U_STEP</constant>,
  52                     <constant>GLU_V_STEP</constant>, or
  53                     <constant>GLU_NURBS_MODE</constant>.
  54                 </para>
  55             </listitem>
  56         </varlistentry>
  57         <varlistentry>
  58             <term><parameter>value</parameter></term>
  59             <listitem>
  60                 <para>
  61                     Specifies the value of the indicated property.
  62                     It may be a numeric value or one of
  63                     <constant>GLU_OUTLINE_POLYGON</constant>,
  64                     <constant>GLU_FILL</constant>,
  65                     <constant>GLU_OUTLINE_PATCH</constant>,
  66                     <constant>GLU_TRUE</constant>,
  67                     <constant>GLU_FALSE</constant>,
  68                     <constant>GLU_PATH_LENGTH</constant>,
  69                     <constant>GLU_PARAMETRIC_ERROR</constant>,
  70                     <constant>GLU_DOMAIN_DISTANCE</constant>,
  71                     <constant>GLU_NURBS_RENDERER</constant>, or
  72                     <constant>GLU_NURBS_TESSELLATOR</constant>.
  73                 </para>
  74             </listitem>
  75         </varlistentry>
  76         </variablelist>
  77     </refsect1>
  78     <refsect1 id="description"><title>Description</title>
  79         <para>
  80             <function>gluNurbsProperty</function> is used to control properties stored in a NURBS object. These
  81             properties affect the way that a NURBS curve is rendered. The accepted
  82             values for <parameter>property</parameter> are as follows:
  83         </para>
  84         <variablelist>
  85             <varlistentry>
  86                 <term><constant>GLU_NURBS_MODE</constant></term>
  87                 <listitem>
  88                     <para>
  89                         <parameter>value</parameter> should be set to be either <constant>GLU_NURBS_RENDERER</constant> or
  90                         <constant>GLU_NURBS_TESSELLATOR</constant>. When set to <constant>GLU_NURBS_RENDERER</constant>, NURBS objects
  91                         are tessellated into OpenGL primitives and sent to the pipeline for
  92                         rendering. When set to <constant>GLU_NURBS_TESSELLATOR</constant>, NURBS objects are
  93                         tessellated into OpenGL primitives but the vertices, normals, colors, and/or textures are
  94                         retrieved back through a callback interface (see <citerefentry><refentrytitle>gluNurbsCallback</refentrytitle></citerefentry>). This allows the user to cache the
  95                         tessellated results for further processing.
  96                         The initial value is <constant>GLU_NURBS_RENDERER</constant>.
  97                     </para>
  98                 </listitem>
  99             </varlistentry>
 100             <varlistentry>
 101                 <term><constant>GLU_SAMPLING_METHOD</constant> </term>
 102                 <listitem>
 103                     <para>
 104                         Specifies how a NURBS surface should be
 105                         tessellated.
 106                         <parameter>value</parameter> may be one of <constant>GLU_PATH_LENGTH</constant>,
 107                         <constant>GLU_PARAMETRIC_ERROR</constant>,  <constant>GLU_DOMAIN_DISTANCE</constant>,
 108                         <constant>GLU_OBJECT_PATH_LENGTH</constant>, or
 109                         <constant>GLU_OBJECT_PARAMETRIC_ERROR</constant>.
 110                         When set to <constant>GLU_PATH_LENGTH</constant>, the surface is rendered so that
 111                         the maximum length, in
 112                         pixels, of the edges of the tessellation polygons is no greater than
 113                         what is specified by <constant>GLU_SAMPLING_TOLERANCE</constant>.
 114                     </para>
 115                     <para>
 116                         <constant>GLU_PARAMETRIC_ERROR</constant> specifies that the surface is rendered in such a
 117                         way that the value specified by <constant>GLU_PARAMETRIC_TOLERANCE</constant> describes the
 118                         maximum distance, in pixels, between the tessellation polygons and the
 119                         surfaces they approximate.
 120                     </para>
 121                     <para>
 122                         <constant>GLU_DOMAIN_DISTANCE</constant> allows users to specify, in parametric coordinates,
 123                         how many sample points per unit length are taken in <emphasis>u</emphasis>, <emphasis>v</emphasis>
 124                         direction.
 125                     </para>
 126                     <para>
 127                         <constant>GLU_OBJECT_PATH_LENGTH</constant>  is similar to <constant>GLU_PATH_LENGTH</constant>
 128                         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>.
 129                     </para>
 130                     <para>
 131                         <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.
 132                     </para>
 133                     <para>
 134                         The initial value of <constant>GLU_SAMPLING_METHOD</constant> is <constant>GLU_PATH_LENGTH</constant>.
 135                     </para>
 136                 </listitem>
 137             </varlistentry>
 138             <varlistentry>
 139                 <term><constant>GLU_SAMPLING_TOLERANCE</constant></term>
 140                 <listitem>
 141                     <para>
 142                         Specifies the maximum length, in pixels or in object space length unit,
 143                         to use when the sampling method is set to <constant>GLU_PATH_LENGTH</constant> or
 144                         <constant>GLU_OBJECT_PATH_LENGTH</constant>.
 145                         The NURBS code is conservative when rendering a curve
 146                         or surface, so the actual length can be somewhat shorter. The initial
 147                         value is 50.0 pixels.
 148                     </para>
 149                 </listitem>
 150             </varlistentry>
 151             <varlistentry>
 152                 <term><constant>GLU_PARAMETRIC_TOLERANCE</constant></term>
 153                 <listitem>
 154                     <para>
 155                         Specifies the maximum distance, in pixels or in object space length unit,
 156                         to use when the sampling method is <constant>GLU_PARAMETRIC_ERROR</constant> or
 157                         <constant>GLU_OBJECT_PARAMETRIC_ERROR</constant>.
 158                         The initial value is 0.5.
 159                     </para>
 160                 </listitem>
 161             </varlistentry>
 162             <varlistentry>
 163                 <term><constant>GLU_U_STEP</constant></term>
 164                 <listitem>
 165                     <para>
 166                         Specifies the number of sample points per unit length taken
 167                         along the <emphasis>u</emphasis> axis in parametric coordinates. It is needed when
 168                         <constant>GLU_SAMPLING_METHOD</constant> is set to <constant>GLU_DOMAIN_DISTANCE</constant>.
 169                         The initial value is 100.
 170                     </para>
 171                 </listitem>
 172             </varlistentry>
 173             <varlistentry>
 174                 <term><constant>GLU_V_STEP</constant></term>
 175                 <listitem>
 176                     <para>
 177                         Specifies the number of sample points per unit length taken
 178                         along the <emphasis>v</emphasis> axis in parametric coordinate. It is needed when
 179                         <constant>GLU_SAMPLING_METHOD</constant> is set to <constant>GLU_DOMAIN_DISTANCE</constant>. The initial
 180                         value is 100.
 181                     </para>
 182                 </listitem>
 183             </varlistentry>
 184             <varlistentry>
 185                 <term><constant>GLU_DISPLAY_MODE</constant></term>
 186                 <listitem>
 187                     <para>
 188                         <parameter>value</parameter> can be set to
 189                         <constant>GLU_OUTLINE_POLYGON</constant>, <constant>GLU_FILL</constant>, or
 190                         <constant>GLU_OUTLINE_PATCH</constant>.
 191                         When <constant>GLU_NURBS_MODE</constant> is set to be <constant>GLU_NURBS_RENDERER</constant>,
 192                         <parameter>value</parameter> defines how a NURBS surface should be rendered.
 193                         When <parameter>value</parameter> is set to <constant>GLU_FILL</constant>, the surface is rendered as a
 194                         set of polygons. When <parameter>value</parameter> is set to
 195                         <constant>GLU_OUTLINE_POLYGON</constant>, the NURBS library draws only the outlines
 196                         of the polygons created by tessellation. When <parameter>value</parameter> is set to
 197                         <constant>GLU_OUTLINE_PATCH</constant> just the outlines of patches and trim
 198                         curves defined by the user are drawn.
 199                     </para>
 200                     <para>
 201                         When <constant>GLU_NURBS_MODE</constant> is set to be <constant>GLU_NURBS_TESSELLATOR</constant>,
 202                         <parameter>value</parameter> defines how a NURBS surface should be tessellated.
 203                         When <constant>GLU_DISPLAY_MODE</constant> is set to <constant>GLU_FILL</constant> or
 204                         <constant>GLU_OUTLINE_POLYGON</constant>,
 205                         the NURBS surface is tessellated into OpenGL triangle primitives that can be
 206                         retrieved back  through callback functions. If <constant>GLU_DISPLAY_MODE</constant> is set to
 207                         <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.
 208                     </para>
 209                     <para>
 210                         The initial value is <constant>GLU_FILL</constant>.
 211                     </para>
 212                 </listitem>
 213             </varlistentry>
 214             <varlistentry>
 215                 <term><constant>GLU_CULLING</constant></term>
 216                 <listitem>
 217                     <para>
 218                         <parameter>value</parameter> is a boolean value that, when set to <constant>GLU_TRUE</constant>, indicates that
 219                         a NURBS curve should be discarded prior to tessellation if its control points
 220                         lie outside the current viewport. The initial value is <constant>GLU_FALSE</constant>.
 221                     </para>
 222                 </listitem>
 223             </varlistentry>
 224             <varlistentry>
 225                 <term><constant>GLU_AUTO_LOAD_MATRIX</constant></term>
 226                 <listitem>
 227                     <para>
 228                         <parameter>value</parameter> is a boolean value. When set to <constant>GLU_TRUE</constant>, the NURBS code
 229                         downloads the projection matrix, the modelview matrix, and the
 230                         viewport from the GL server to compute sampling and
 231                         culling
 232                         matrices for each NURBS curve that is rendered. Sampling and culling matrices
 233                         are required to determine the tessellation of a NURBS surface into line segments
 234                         or polygons and to cull a NURBS surface if it lies outside the viewport.
 235                     </para>
 236                     <para>
 237                         If this mode is set to <constant>GLU_FALSE</constant>, then the program needs
 238                         to provide a projection matrix, a modelview matrix, and a viewport
 239                         for the NURBS renderer to use to construct sampling and culling matrices.
 240                         This can be done with the <citerefentry><refentrytitle>gluLoadSamplingMatrices</refentrytitle></citerefentry> function.
 241                         This mode is initially set to <constant>GLU_TRUE</constant>.
 242                         Changing it from <constant>GLU_TRUE</constant> to <constant>GLU_FALSE</constant> does not affect
 243                         the sampling and culling matrices until
 244                         <citerefentry><refentrytitle>gluLoadSamplingMatrices</refentrytitle></citerefentry>
 245                         is called.
 246                     </para>
 247                 </listitem>
 248             </varlistentry>
 249         </variablelist>
 250     </refsect1>
 251     <refsect1 id="notes"><title>Notes</title>
 252         <para>
 253             If <constant>GLU_AUTO_LOAD_MATRIX</constant> is true, sampling and culling may be
 254             executed incorrectly if NURBS routines are compiled into a display list.
 255         </para>
 256         <para>
 257             A <parameter>property</parameter> of
 258             <constant>GLU_PARAMETRIC_TOLERANCE</constant>,
 259             <constant>GLU_SAMPLING_METHOD</constant>,
 260             <constant>GLU_U_STEP</constant>, or
 261             <constant>GLU_V_STEP</constant>,
 262             or a <parameter>value</parameter> of
 263             <constant>GLU_PATH_LENGTH</constant>,
 264             <constant>GLU_PARAMETRIC_ERROR</constant>,
 265             <constant>GLU_DOMAIN_DISTANCE</constant>
 266             are only available if the GLU version is 1.1 or greater. They are not
 267             valid parameters in GLU 1.0.
 268         </para>
 269         <para>
 270             <citerefentry><refentrytitle>gluGetString</refentrytitle></citerefentry> can
 271             be used to determine the GLU version.
 272         </para>
 273         <para>
 274             <constant>GLU_NURBS_MODE</constant> is only available if the GLU version is 1.3 or
 275             greater.
 276         </para>
 277         <para>
 278             The <constant>GLU_OBJECT_PATH_LENGTH</constant> and <constant>GLU_OBJECT_PARAMETRIC_ERROR</constant>
 279             values for the <constant>GLU_SAMPLING_METHOD</constant> property are only available if
 280             the GLU version is 1.3 or greater.
 281         </para>
 282     </refsect1>
 283     <refsect1 id="seealso"><title>See Also</title>
 284         <para>
 285             <citerefentry><refentrytitle>gluGetNurbsProperty</refentrytitle></citerefentry>,
 286             <citerefentry><refentrytitle>gluGetString</refentrytitle></citerefentry>,
 287             <citerefentry><refentrytitle>gluLoadSamplingMatrices</refentrytitle></citerefentry>,
 288             <citerefentry><refentrytitle>gluNewNurbsRenderer</refentrytitle></citerefentry>,
 289             <citerefentry><refentrytitle>gluNurbsCallback</refentrytitle></citerefentry>
 290         </para>
 291     </refsect1>
 292     <refsect1 id="Copyright"><title>Copyright</title>
 293         <para>
 294             Copyright <trademark class="copyright"></trademark> 1991-2006
 295             Silicon Graphics, Inc. This document is licensed under the SGI
 296             Free Software B License. For details, see
 297             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 298         </para>
 299     </refsect1>
 300 </refentry>