upstream-man-pages/man2/glPolygonOffset.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="glPolygonOffset">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glPolygonOffset</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glPolygonOffset</refname>
  17         <refpurpose>set the scale and units used to calculate depth values</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glPolygonOffset</function></funcdef>
  23                 <paramdef>GLfloat <parameter>factor</parameter></paramdef>
  24                 <paramdef>GLfloat <parameter>units</parameter></paramdef>
  25             </funcprototype>
  26         </funcsynopsis>
  27     </refsynopsisdiv>
  28     <!-- eqn: ignoring delim $$ -->
  29     <refsect1 id="parameters"><title>Parameters</title>
  30         <variablelist>
  31         <varlistentry>
  32             <term><parameter>factor</parameter></term>
  33             <listitem>
  34                 <para>
  35                     Specifies a scale factor that is used to create a variable
  36                     depth offset for each polygon. The initial value is 0.
  37                 </para>
  38             </listitem>
  39         </varlistentry>
  40         <varlistentry>
  41             <term><parameter>units</parameter></term>
  42             <listitem>
  43                 <para>
  44                     Is multiplied by an implementation-specific value to
  45                     create a constant depth offset. The initial value is 0.
  46                 </para>
  47             </listitem>
  48         </varlistentry>
  49         </variablelist>
  50     </refsect1>
  51     <refsect1 id="description"><title>Description</title>
  52         <para>
  53             When <constant>GL_POLYGON_OFFSET_FILL</constant>, <constant>GL_POLYGON_OFFSET_LINE</constant>, or
  54             <constant>GL_POLYGON_OFFSET_POINT</constant> is enabled, each
  55             fragment's <emphasis>depth</emphasis> value will be offset after it is interpolated
  56             from the <emphasis>depth</emphasis> values of the appropriate vertices.
  57             The value of the offset is
  58             <inlineequation><mml:math>
  59                 <!-- eqn: factor  *  DZ   +   r  *  units:-->
  60                 <mml:mrow>
  61                     <mml:mrow>
  62                         <mml:mi mathvariant="italic">factor</mml:mi>
  63                         <mml:mo>&times;</mml:mo>
  64                         <mml:mi mathvariant="italic">DZ</mml:mi>
  65                     </mml:mrow>
  66                     <mml:mo>+</mml:mo>
  67                     <mml:mrow>
  68                         <mml:mi mathvariant="italic">r</mml:mi>
  69                         <mml:mo>&times;</mml:mo>
  70                         <mml:mi mathvariant="italic">units</mml:mi>
  71                     </mml:mrow>
  72                 </mml:mrow>
  73             </mml:math></inlineequation>,
  74             where
  75             <inlineequation><mml:math>
  76                 <!-- eqn: DZ:-->
  77                 <mml:mi mathvariant="italic">DZ</mml:mi>
  78             </mml:math></inlineequation>
  79             is a measurement of the change in depth relative to the screen
  80             area of the polygon, and
  81             <inlineequation><mml:math><mml:mi mathvariant="italic">r</mml:mi></mml:math></inlineequation>
  82             is the smallest value that is guaranteed to
  83             produce a resolvable offset for a given implementation.
  84             The offset is added before the depth test is performed and before
  85             the value is written into the depth buffer.
  86         </para>
  87         <para>
  88             <function>glPolygonOffset</function> is useful for rendering hidden-line images, for applying decals
  89             to surfaces, and for rendering solids with highlighted edges.
  90         </para>
  91     </refsect1>
  92     <refsect1 id="notes"><title>Notes</title>
  93         <para>
  94             <function>glPolygonOffset</function> is available only if the GL version is 1.1 or greater.
  95         </para>
  96         <para>
  97             <function>glPolygonOffset</function> has no effect on depth coordinates placed in the
  98             feedback buffer.
  99         </para>
 100         <para>
 101             <function>glPolygonOffset</function> has no effect on selection.
 102         </para>
 103     </refsect1>
 104     <refsect1 id="errors"><title>Errors</title>
 105         <para>
 106             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glPolygonOffset</function> is executed
 107             between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
 108             execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 109         </para>
 110     </refsect1>
 111     <refsect1 id="associatedgets"><title>Associated Gets</title>
 112         <para>
 113             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument
 114             <constant>GL_POLYGON_OFFSET_FILL</constant>,
 115             <constant>GL_POLYGON_OFFSET_LINE</constant>,
 116             or <constant>GL_POLYGON_OFFSET_POINT</constant>.
 117         </para>
 118         <para>
 119             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_POLYGON_OFFSET_FACTOR</constant> or
 120             <constant>GL_POLYGON_OFFSET_UNITS</constant>.
 121         </para>
 122     </refsect1>
 123     <refsect1 id="seealso"><title>See Also</title>
 124         <para>
 125             <citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry>,
 126             <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
 127             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>,
 128             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry>
 129         </para>
 130     </refsect1>
 131     <refsect1 id="Copyright"><title>Copyright</title>
 132         <para>
 133             Copyright <trademark class="copyright"></trademark> 1991-2006
 134             Silicon Graphics, Inc. This document is licensed under the SGI
 135             Free Software B License. For details, see
 136             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 137         </para>
 138     </refsect1>
 139 </refentry>