upstream-doc/man2/xhtml/glStencilFuncSeparate.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glStencilFuncSeparate</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glStencilFuncSeparate"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glStencilFuncSeparate — set front and/or back function and reference value for stencil testing</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glStencilFuncSeparate</b>(</code></td><td>GLenum  </td><td><var class="pdparam">face</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">func</var>, </td></tr><tr><td> </td><td>GLint  </td><td><var class="pdparam">ref</var>, </td></tr><tr><td> </td><td>GLuint  </td><td><var class="pdparam">mask</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>face</code></em></span></dt><dd><p>
   4                     Specifies whether front and/or back stencil state is updated.
   5                     Three symbolic constants are valid:
   6                     <code class="constant">GL_FRONT</code>,
   7                     <code class="constant">GL_BACK</code>, and
   8                     <code class="constant">GL_FRONT_AND_BACK</code>.
   9                 </p></dd><dt><span class="term"><em class="parameter"><code>func</code></em></span></dt><dd><p>
  10                     Specifies the test function.
  11                     Eight symbolic constants are valid:
  12                     <code class="constant">GL_NEVER</code>,
  13                     <code class="constant">GL_LESS</code>,
  14                     <code class="constant">GL_LEQUAL</code>,
  15                     <code class="constant">GL_GREATER</code>,
  16                     <code class="constant">GL_GEQUAL</code>,
  17                     <code class="constant">GL_EQUAL</code>,
  18                     <code class="constant">GL_NOTEQUAL</code>, and
  19                     <code class="constant">GL_ALWAYS</code>. The initial value is <code class="constant">GL_ALWAYS</code>.
  20                 </p></dd><dt><span class="term"><em class="parameter"><code>ref</code></em></span></dt><dd><p>
  21                     Specifies the reference value for the stencil test.
  22                     <em class="parameter"><code>ref</code></em> is clamped to the range
  23                     <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  24
  25                         <mml:mfenced open="[" close="]">
  26                             <mml:mn>0</mml:mn>
  27                             <mml:mrow>
  28                                 <mml:msup><mml:mn>2</mml:mn>
  29                                 <mml:mi mathvariant="italic">n</mml:mi>
  30                                 </mml:msup>
  31                                 <mml:mo>-</mml:mo>
  32                                 <mml:mn>1</mml:mn>
  33                             </mml:mrow>
  34                         </mml:mfenced>
  35                     </mml:math>,
  36                     where
  37                     <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">n</mml:mi></mml:math>
  38                     is the number of bitplanes in the stencil buffer. The
  39                     initial value is 0.
  40                 </p></dd><dt><span class="term"><em class="parameter"><code>mask</code></em></span></dt><dd><p>
  41                     Specifies a mask that is ANDed with both the reference value
  42                     and the stored stencil value when the test is done. The initial value
  43                     is all 1's.
  44                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  45             Stenciling,
  46             like depth-buffering,
  47             enables and disables drawing on a per-pixel basis.
  48             You draw into the stencil planes using GL drawing primitives,
  49             then render geometry and images,
  50             using the stencil planes to mask out portions of the screen.
  51             Stenciling is typically used in multipass rendering algorithms
  52             to achieve special effects,
  53             such as decals,
  54             outlining,
  55             and constructive solid geometry rendering.
  56         </p><p>
  57             The stencil test conditionally eliminates a pixel based on the outcome
  58             of a comparison between the reference value
  59             and the value in the stencil buffer.
  60             To enable and disable the test, call <a class="citerefentry" href="glEnable.xml"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a> and <a class="citerefentry" href="glDisable.xml"><span class="citerefentry"><span class="refentrytitle">glDisable</span></span></a>
  61             with argument <code class="constant">GL_STENCIL_TEST</code>.
  62             To specify actions based on the outcome of the stencil test, call
  63             <a class="citerefentry" href="glStencilOp.xml"><span class="citerefentry"><span class="refentrytitle">glStencilOp</span></span></a> or
  64             <a class="citerefentry" href="glStencilOpSeparate.xml"><span class="citerefentry"><span class="refentrytitle">glStencilOpSeparate</span></span></a>.
  65         </p><p>
  66             There can be two separate sets of <em class="parameter"><code>func</code></em>, <em class="parameter"><code>ref</code></em>, and
  67             <em class="parameter"><code>mask</code></em> parameters; one affects back-facing polygons, and the other
  68             affects front-facing polygons as well as other non-polygon primitives.
  69             <a class="citerefentry" href="glStencilFunc.xml"><span class="citerefentry"><span class="refentrytitle">glStencilFunc</span></span></a> sets both front
  70             and back stencil state to the same values, as if
  71             <a class="citerefentry" href="glStencilFuncSeparate.xml"><span class="citerefentry"><span class="refentrytitle">glStencilFuncSeparate</span></span></a> were called
  72             with <em class="parameter"><code>face</code></em> set to <code class="constant">GL_FRONT_AND_BACK</code>.
  73         </p><p>
  74             <em class="parameter"><code>func</code></em> is a symbolic constant that determines the stencil comparison function.
  75             It accepts one of eight values,
  76             shown in the following list.
  77             <em class="parameter"><code>ref</code></em> is an integer reference value that is used in the stencil comparison.
  78             It is clamped to the range
  79             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  80
  81                 <mml:mfenced open="[" close="]">
  82                     <mml:mn>0</mml:mn>
  83                     <mml:mrow>
  84                         <mml:msup><mml:mn>2</mml:mn>
  85                         <mml:mi mathvariant="italic">n</mml:mi>
  86                         </mml:msup>
  87                         <mml:mo>-</mml:mo>
  88                         <mml:mn>1</mml:mn>
  89                     </mml:mrow>
  90                 </mml:mfenced>
  91             </mml:math>,
  92             where
  93             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">n</mml:mi></mml:math>
  94             is the number of bitplanes in the stencil buffer.
  95             <em class="parameter"><code>mask</code></em> is bitwise ANDed with both the reference value
  96             and the stored stencil value,
  97             with the ANDed values participating in the comparison.
  98         </p><p>
  99             If <span class="emphasis"><em>stencil</em></span> represents the value stored in the corresponding
 100             stencil buffer location,
 101             the following list shows the effect of each comparison function
 102             that can be specified by <em class="parameter"><code>func</code></em>.
 103             Only if the comparison succeeds is the pixel passed through
 104             to the next stage in the rasterization process
 105             (see <a class="citerefentry" href="glStencilOp.xml"><span class="citerefentry"><span class="refentrytitle">glStencilOp</span></span></a>).
 106             All tests treat <span class="emphasis"><em>stencil</em></span> values as unsigned integers in the range
 107             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 108
 109                 <mml:mfenced open="[" close="]">
 110                     <mml:mn>0</mml:mn>
 111                     <mml:mrow>
 112                         <mml:msup><mml:mn>2</mml:mn>
 113                         <mml:mi mathvariant="italic">n</mml:mi>
 114                         </mml:msup>
 115                         <mml:mo>-</mml:mo>
 116                         <mml:mn>1</mml:mn>
 117                     </mml:mrow>
 118                 </mml:mfenced>
 119             </mml:math>,
 120             where
 121             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">n</mml:mi></mml:math>
 122             is the number of bitplanes in the stencil buffer.
 123         </p><p>
 124             The following values are accepted by <em class="parameter"><code>func</code></em>:
 125         </p><div class="variablelist"><dl><dt><span class="term"><code class="constant">GL_NEVER</code></span></dt><dd><p>
 126                         Always fails.
 127                     </p></dd><dt><span class="term"><code class="constant">GL_LESS</code></span></dt><dd><p>
 128                         Passes if ( <em class="parameter"><code>ref</code></em> &amp; <em class="parameter"><code>mask</code></em> ) &lt; ( <span class="emphasis"><em>stencil</em></span> &amp; <em class="parameter"><code>mask</code></em> ).
 129                     </p></dd><dt><span class="term"><code class="constant">GL_LEQUAL</code></span></dt><dd><p>
 130                         Passes if ( <em class="parameter"><code>ref</code></em> &amp; <em class="parameter"><code>mask</code></em> ) &lt;= ( <span class="emphasis"><em>stencil</em></span> &amp; <em class="parameter"><code>mask</code></em> ).
 131                     </p></dd><dt><span class="term"><code class="constant">GL_GREATER</code></span></dt><dd><p>
 132                         Passes if ( <em class="parameter"><code>ref</code></em> &amp; <em class="parameter"><code>mask</code></em> ) &gt; ( <span class="emphasis"><em>stencil</em></span> &amp; <em class="parameter"><code>mask</code></em> ).
 133                     </p></dd><dt><span class="term"><code class="constant">GL_GEQUAL</code></span></dt><dd><p>
 134                         Passes if ( <em class="parameter"><code>ref</code></em> &amp; <em class="parameter"><code>mask</code></em> ) &gt;= ( <span class="emphasis"><em>stencil</em></span> &amp; <em class="parameter"><code>mask</code></em> ).
 135                     </p></dd><dt><span class="term"><code class="constant">GL_EQUAL</code></span></dt><dd><p>
 136                         Passes if ( <em class="parameter"><code>ref</code></em> &amp; <em class="parameter"><code>mask</code></em> ) = ( <span class="emphasis"><em>stencil</em></span> &amp; <em class="parameter"><code>mask</code></em> ).
 137                     </p></dd><dt><span class="term"><code class="constant">GL_NOTEQUAL</code></span></dt><dd><p>
 138                         Passes if ( <em class="parameter"><code>ref</code></em> &amp; <em class="parameter"><code>mask</code></em> ) != ( <span class="emphasis"><em>stencil</em></span> &amp; <em class="parameter"><code>mask</code></em> ).
 139                     </p></dd><dt><span class="term"><code class="constant">GL_ALWAYS</code></span></dt><dd><p>
 140                         Always passes.
 141                     </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
 142             <code class="function">glStencilFuncSeparate</code> is available only if
 143             the GL version is 2.0 or greater.
 144         </p><p>
 145             Initially, the stencil test is disabled.
 146             If there is no stencil buffer,
 147             no stencil modification can occur and it is as if
 148             the stencil test always passes.
 149         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
 150             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>func</code></em> is not one of the eight
 151             accepted values.
 152         </p><p>
 153             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glStencilFuncSeparate</code>
 154             is executed between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>
 155             and the corresponding execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
 156         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
 157             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument
 158             <code class="constant">GL_STENCIL_FUNC</code>, <code class="constant">GL_STENCIL_VALUE_MASK</code>,
 159             <code class="constant">GL_STENCIL_REF</code>, <code class="constant">GL_STENCIL_BACK_FUNC</code>,
 160             <code class="constant">GL_STENCIL_BACK_VALUE_MASK</code>, <code class="constant">GL_STENCIL_BACK_REF</code>,
 161             or <code class="constant">GL_STENCIL_BITS</code>
 162         </p><p>
 163             <a class="citerefentry" href="glIsEnabled.xml"><span class="citerefentry"><span class="refentrytitle">glIsEnabled</span></span></a> with argument <code class="constant">GL_STENCIL_TEST</code>
 164         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 165             <a class="citerefentry" href="glAlphaFunc.xml"><span class="citerefentry"><span class="refentrytitle">glAlphaFunc</span></span></a>,
 166             <a class="citerefentry" href="glBlendFunc.xml"><span class="citerefentry"><span class="refentrytitle">glBlendFunc</span></span></a>,
 167             <a class="citerefentry" href="glDepthFunc.xml"><span class="citerefentry"><span class="refentrytitle">glDepthFunc</span></span></a>,
 168             <a class="citerefentry" href="glEnable.xml"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a>,
 169             <a class="citerefentry" href="glLogicOp.xml"><span class="citerefentry"><span class="refentrytitle">glLogicOp</span></span></a>,
 170             <a class="citerefentry" href="glStencilFunc.xml"><span class="citerefentry"><span class="refentrytitle">glStencilFunc</span></span></a>,
 171             <a class="citerefentry" href="glStencilMask.xml"><span class="citerefentry"><span class="refentrytitle">glStencilMask</span></span></a>,
 172             <a class="citerefentry" href="glStencilMaskSeparate.xml"><span class="citerefentry"><span class="refentrytitle">glStencilMaskSeparate</span></span></a>,
 173             <a class="citerefentry" href="glStencilOp.xml"><span class="citerefentry"><span class="refentrytitle">glStencilOp</span></span></a>,
 174             <a class="citerefentry" href="glStencilOpSeparate.xml"><span class="citerefentry"><span class="refentrytitle">glStencilOpSeparate</span></span></a>
 175         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 176             Copyright <span class="trademark"></span>© 2006 Khronos Group.
 177             This material may be distributed subject to the terms and conditions set forth in
 178             the Open Publication License, v 1.0, 8 June 1999.
 179             <a class="ulink" href="http://opencontent.org/openpub/" target="_top">http://opencontent.org/openpub/</a>.
 180         </p></div></div></body></html>