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