upstream-doc/man3/xhtml/glStencilFuncSeparate.xml

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