upstream-man-pages/man3/glStencilFunc.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="glStencilFunc">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glStencilFunc</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glStencilFunc</refname>
  17         <refpurpose>set front and back function and reference value for stencil testing</refpurpose>
  18     </refnamediv>
  19     <!-- eqn: ignoring delim $$ -->
  20     <refsynopsisdiv><title>C Specification</title>
  21         <funcsynopsis>
  22             <funcprototype>
  23                 <funcdef>void <function>glStencilFunc</function></funcdef>
  24                 <paramdef>GLenum <parameter>func</parameter></paramdef>
  25                 <paramdef>GLint <parameter>ref</parameter></paramdef>
  26                 <paramdef>GLuint <parameter>mask</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29     </refsynopsisdiv>
  30     <refsect1 id="parameters"><title>Parameters</title>
  31         <variablelist>
  32         <varlistentry>
  33             <term><parameter>func</parameter></term>
  34             <listitem>
  35                 <para>
  36                     Specifies the test function.
  37                     Eight symbolic constants are valid:
  38                     <constant>GL_NEVER</constant>,
  39                     <constant>GL_LESS</constant>,
  40                     <constant>GL_LEQUAL</constant>,
  41                     <constant>GL_GREATER</constant>,
  42                     <constant>GL_GEQUAL</constant>,
  43                     <constant>GL_EQUAL</constant>,
  44                     <constant>GL_NOTEQUAL</constant>, and
  45                     <constant>GL_ALWAYS</constant>. The initial value is <constant>GL_ALWAYS</constant>.
  46                 </para>
  47             </listitem>
  48         </varlistentry>
  49         <varlistentry>
  50             <term><parameter>ref</parameter></term>
  51             <listitem>
  52                 <para>
  53                     Specifies the reference value for the stencil test.
  54                     <parameter>ref</parameter> is clamped to the range
  55                     <inlineequation><mml:math>
  56                         <!-- eqn: [0, 2 sup n - 1]:-->
  57                         <mml:mfenced open="[" close="]">
  58                             <mml:mn>0</mml:mn>
  59                             <mml:mrow>
  60                                 <mml:msup><mml:mn>2</mml:mn>
  61                                 <mml:mi mathvariant="italic">n</mml:mi>
  62                                 </mml:msup>
  63                                 <mml:mo>-</mml:mo>
  64                                 <mml:mn>1</mml:mn>
  65                             </mml:mrow>
  66                         </mml:mfenced>
  67                     </mml:math></inlineequation>,
  68                     where
  69                     <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
  70                     is the number of bitplanes in the stencil buffer. The
  71                     initial value is 0.
  72                 </para>
  73             </listitem>
  74         </varlistentry>
  75         <varlistentry>
  76             <term><parameter>mask</parameter></term>
  77             <listitem>
  78                 <para>
  79                     Specifies a mask that is ANDed with both the reference value
  80                     and the stored stencil value when the test is done. The initial value
  81                     is all 1's.
  82                 </para>
  83             </listitem>
  84         </varlistentry>
  85         </variablelist>
  86     </refsect1>
  87     <refsect1 id="description"><title>Description</title>
  88         <para>
  89             Stenciling,
  90             like depth-buffering,
  91             enables and disables drawing on a per-pixel basis.
  92             Stencil planes are first drawn into using GL drawing primitives, then
  93             geometry and images are rendered using the stencil planes to mask out
  94             portions of the screen.
  95             Stenciling is typically used in multipass rendering algorithms
  96             to achieve special effects,
  97             such as decals,
  98             outlining,
  99             and constructive solid geometry rendering.
 100         </para>
 101         <para>
 102             The stencil test conditionally eliminates a pixel based on the outcome
 103             of a comparison between the reference value
 104             and the value in the stencil buffer.
 105             To enable and disable the test, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry>
 106             with argument <constant>GL_STENCIL_TEST</constant>.
 107             To specify actions based on the outcome of the stencil test, call
 108             <citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry> or
 109             <citerefentry><refentrytitle>glStencilOpSeparate</refentrytitle></citerefentry>.
 110         </para>
 111         <para>
 112             There can be two separate sets of <parameter>func</parameter>, <parameter>ref</parameter>, and
 113             <parameter>mask</parameter> parameters; one affects back-facing polygons, and the other
 114             affects front-facing polygons as well as other non-polygon primitives.
 115             <citerefentry><refentrytitle>glStencilFunc</refentrytitle></citerefentry> sets both front
 116             and back stencil state to the same values. Use <citerefentry><refentrytitle>glStencilFuncSeparate</refentrytitle></citerefentry>
 117             to set front and back stencil state to different values.
 118         </para>
 119         <para>
 120             <parameter>func</parameter> is a symbolic constant that determines the stencil comparison function.
 121             It accepts one of eight values,
 122             shown in the following list.
 123             <parameter>ref</parameter> is an integer reference value that is used in the stencil comparison.
 124             It is clamped to the range
 125             <inlineequation><mml:math>
 126                 <!-- eqn: [0, 2 sup n - 1]:-->
 127                 <mml:mfenced open="[" close="]">
 128                     <mml:mn>0</mml:mn>
 129                     <mml:mrow>
 130                         <mml:msup><mml:mn>2</mml:mn>
 131                         <mml:mi mathvariant="italic">n</mml:mi>
 132                         </mml:msup>
 133                         <mml:mo>-</mml:mo>
 134                         <mml:mn>1</mml:mn>
 135                     </mml:mrow>
 136                 </mml:mfenced>
 137             </mml:math></inlineequation>,
 138             where
 139             <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
 140             is the number of bitplanes in the stencil buffer.
 141             <parameter>mask</parameter> is bitwise ANDed with both the reference value
 142             and the stored stencil value,
 143             with the ANDed values participating in the comparison.
 144         </para>
 145         <para>
 146             If <emphasis>stencil</emphasis> represents the value stored in the corresponding
 147             stencil buffer location,
 148             the following list shows the effect of each comparison function
 149             that can be specified by <parameter>func</parameter>.
 150             Only if the comparison succeeds is the pixel passed through
 151             to the next stage in the rasterization process
 152             (see <citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>).
 153             All tests treat <emphasis>stencil</emphasis> values as unsigned integers in the range
 154             <inlineequation><mml:math>
 155                 <!-- eqn: [0, 2 sup n - 1]:-->
 156                 <mml:mfenced open="[" close="]">
 157                     <mml:mn>0</mml:mn>
 158                     <mml:mrow>
 159                         <mml:msup><mml:mn>2</mml:mn>
 160                         <mml:mi mathvariant="italic">n</mml:mi>
 161                         </mml:msup>
 162                         <mml:mo>-</mml:mo>
 163                         <mml:mn>1</mml:mn>
 164                     </mml:mrow>
 165                 </mml:mfenced>
 166             </mml:math></inlineequation>,
 167             where
 168             <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
 169             is the number of bitplanes in the stencil buffer.
 170         </para>
 171         <para>
 172             The following values are accepted by <parameter>func</parameter>:
 173         </para>
 174         <variablelist>
 175             <varlistentry>
 176                 <term><constant>GL_NEVER</constant></term>
 177                 <listitem>
 178                     <para>
 179                         Always fails.
 180                     </para>
 181                 </listitem>
 182             </varlistentry>
 183             <varlistentry>
 184                 <term><constant>GL_LESS</constant></term>
 185                 <listitem>
 186                     <para>
 187                         Passes if ( <parameter>ref</parameter> &amp; <parameter>mask</parameter> ) &lt; ( <emphasis>stencil</emphasis> &amp; <parameter>mask</parameter> ).
 188                     </para>
 189                 </listitem>
 190             </varlistentry>
 191             <varlistentry>
 192                 <term><constant>GL_LEQUAL</constant></term>
 193                 <listitem>
 194                     <para>
 195                         Passes if ( <parameter>ref</parameter> &amp; <parameter>mask</parameter> ) &lt;= ( <emphasis>stencil</emphasis> &amp; <parameter>mask</parameter> ).
 196                     </para>
 197                 </listitem>
 198             </varlistentry>
 199             <varlistentry>
 200                 <term><constant>GL_GREATER</constant></term>
 201                 <listitem>
 202                     <para>
 203                         Passes if ( <parameter>ref</parameter> &amp; <parameter>mask</parameter> ) &gt; ( <emphasis>stencil</emphasis> &amp; <parameter>mask</parameter> ).
 204                     </para>
 205                 </listitem>
 206             </varlistentry>
 207             <varlistentry>
 208                 <term><constant>GL_GEQUAL</constant></term>
 209                 <listitem>
 210                     <para>
 211                         Passes if ( <parameter>ref</parameter> &amp; <parameter>mask</parameter> ) &gt;= ( <emphasis>stencil</emphasis> &amp; <parameter>mask</parameter> ).
 212                     </para>
 213                 </listitem>
 214             </varlistentry>
 215             <varlistentry>
 216                 <term><constant>GL_EQUAL</constant></term>
 217                 <listitem>
 218                     <para>
 219                         Passes if ( <parameter>ref</parameter> &amp; <parameter>mask</parameter> ) = ( <emphasis>stencil</emphasis> &amp; <parameter>mask</parameter> ).
 220                     </para>
 221                 </listitem>
 222             </varlistentry>
 223             <varlistentry>
 224                 <term><constant>GL_NOTEQUAL</constant></term>
 225                 <listitem>
 226                     <para>
 227                         Passes if ( <parameter>ref</parameter> &amp; <parameter>mask</parameter> ) != ( <emphasis>stencil</emphasis> &amp; <parameter>mask</parameter> ).
 228                     </para>
 229                 </listitem>
 230             </varlistentry>
 231             <varlistentry>
 232                 <term><constant>GL_ALWAYS</constant></term>
 233                 <listitem>
 234                     <para>
 235                         Always passes.
 236                     </para>
 237                 </listitem>
 238             </varlistentry>
 239         </variablelist>
 240     </refsect1>
 241     <refsect1 id="notes"><title>Notes</title>
 242         <para>
 243             Initially, the stencil test is disabled.
 244             If there is no stencil buffer,
 245             no stencil modification can occur and it is as if
 246             the stencil test always passes.
 247         </para>
 248         <para>
 249             <citerefentry><refentrytitle>glStencilFunc</refentrytitle></citerefentry> is the same as
 250             calling <citerefentry><refentrytitle>glStencilFuncSeparate</refentrytitle></citerefentry>
 251             with <parameter>face</parameter> set to <constant>GL_FRONT_AND_BACK</constant>.
 252         </para>
 253     </refsect1>
 254     <refsect1 id="errors"><title>Errors</title>
 255         <para>
 256             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>func</parameter> is not one of the eight
 257             accepted values.
 258         </para>
 259     </refsect1>
 260     <refsect1 id="associatedgets"><title>Associated Gets</title>
 261         <para>
 262             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument
 263             <constant>GL_STENCIL_FUNC</constant>, <constant>GL_STENCIL_VALUE_MASK</constant>,
 264             <constant>GL_STENCIL_REF</constant>, <constant>GL_STENCIL_BACK_FUNC</constant>,
 265             <constant>GL_STENCIL_BACK_VALUE_MASK</constant>, <constant>GL_STENCIL_BACK_REF</constant>,
 266             or <constant>GL_STENCIL_BITS</constant>
 267         </para>
 268         <para>
 269             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_STENCIL_TEST</constant>
 270         </para>
 271     </refsect1>
 272     <refsect1 id="seealso"><title>See Also</title>
 273         <para>
 274             <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>,
 275             <citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry>,
 276             <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
 277             <citerefentry><refentrytitle>glLogicOp</refentrytitle></citerefentry>,
 278             <citerefentry><refentrytitle>glStencilFuncSeparate</refentrytitle></citerefentry>,
 279             <citerefentry><refentrytitle>glStencilMask</refentrytitle></citerefentry>,
 280             <citerefentry><refentrytitle>glStencilMaskSeparate</refentrytitle></citerefentry>,
 281             <citerefentry><refentrytitle>glStencilOp</refentrytitle></citerefentry>,
 282             <citerefentry><refentrytitle>glStencilOpSeparate</refentrytitle></citerefentry>
 283         </para>
 284     </refsect1>
 285     <refsect1 id="Copyright"><title>Copyright</title>
 286         <para>
 287             Copyright <trademark class="copyright"></trademark> 1991-2006
 288             Silicon Graphics, Inc. This document is licensed under the SGI
 289             Free Software B License. For details, see
 290             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 291         </para>
 292     </refsect1>
 293 </refentry>