upstream-man-pages/man2/xhtml/glStencilFunc.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>glStencilFunc</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glStencilFunc"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glStencilFunc — set front and 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">glStencilFunc</b>(</code></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>func</code></em></span></dt><dd><p>
   4                     Specifies the test function.
   5                     Eight symbolic constants are valid:
   6                     <code class="constant">GL_NEVER</code>,
   7                     <code class="constant">GL_LESS</code>,
   8                     <code class="constant">GL_LEQUAL</code>,
   9                     <code class="constant">GL_GREATER</code>,
  10                     <code class="constant">GL_GEQUAL</code>,
  11                     <code class="constant">GL_EQUAL</code>,
  12                     <code class="constant">GL_NOTEQUAL</code>, and
  13                     <code class="constant">GL_ALWAYS</code>. The initial value is <code class="constant">GL_ALWAYS</code>.
  14                 </p></dd><dt><span class="term"><em class="parameter"><code>ref</code></em></span></dt><dd><p>
  15                     Specifies the reference value for the stencil test.
  16                     <em class="parameter"><code>ref</code></em> is clamped to the range
  17                     <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  18
  19                         <mml:mfenced open="[" close="]">
  20                             <mml:mn>0</mml:mn>
  21                             <mml:mrow>
  22                                 <mml:msup><mml:mn>2</mml:mn>
  23                                 <mml:mi mathvariant="italic">n</mml:mi>
  24                                 </mml:msup>
  25                                 <mml:mo>-</mml:mo>
  26                                 <mml:mn>1</mml:mn>
  27                             </mml:mrow>
  28                         </mml:mfenced>
  29                     </mml:math>,
  30                     where
  31                     <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">n</mml:mi></mml:math>
  32                     is the number of bitplanes in the stencil buffer. The
  33                     initial value is 0.
  34                 </p></dd><dt><span class="term"><em class="parameter"><code>mask</code></em></span></dt><dd><p>
  35                     Specifies a mask that is ANDed with both the reference value
  36                     and the stored stencil value when the test is done. The initial value
  37                     is all 1's.
  38                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  39             Stenciling,
  40             like depth-buffering,
  41             enables and disables drawing on a per-pixel basis.
  42             Stencil planes are first drawn into using GL drawing primitives, then
  43             geometry and images are rendered using the stencil planes to mask out
  44             portions of the screen.
  45             Stenciling is typically used in multipass rendering algorithms
  46             to achieve special effects,
  47             such as decals,
  48             outlining,
  49             and constructive solid geometry rendering.
  50         </p><p>
  51             The stencil test conditionally eliminates a pixel based on the outcome
  52             of a comparison between the reference value
  53             and the value in the stencil buffer.
  54             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>
  55             with argument <code class="constant">GL_STENCIL_TEST</code>.
  56             To specify actions based on the outcome of the stencil test, call
  57             <a class="citerefentry" href="glStencilOp.xml"><span class="citerefentry"><span class="refentrytitle">glStencilOp</span></span></a> or
  58             <a class="citerefentry" href="glStencilOpSeparate.xml"><span class="citerefentry"><span class="refentrytitle">glStencilOpSeparate</span></span></a>.
  59         </p><p>
  60             There can be two separate sets of <em class="parameter"><code>func</code></em>, <em class="parameter"><code>ref</code></em>, and
  61             <em class="parameter"><code>mask</code></em> parameters; one affects back-facing polygons, and the other
  62             affects front-facing polygons as well as other non-polygon primitives.
  63             <a class="citerefentry" href="glStencilFunc.xml"><span class="citerefentry"><span class="refentrytitle">glStencilFunc</span></span></a> sets both front
  64             and back stencil state to the same values. Use <a class="citerefentry" href="glStencilFuncSeparate.xml"><span class="citerefentry"><span class="refentrytitle">glStencilFuncSeparate</span></span></a>
  65             to set front and back stencil state to different values.
  66         </p><p>
  67             <em class="parameter"><code>func</code></em> is a symbolic constant that determines the stencil comparison function.
  68             It accepts one of eight values,
  69             shown in the following list.
  70             <em class="parameter"><code>ref</code></em> is an integer reference value that is used in the stencil comparison.
  71             It is clamped to the range
  72             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  73
  74                 <mml:mfenced open="[" close="]">
  75                     <mml:mn>0</mml:mn>
  76                     <mml:mrow>
  77                         <mml:msup><mml:mn>2</mml:mn>
  78                         <mml:mi mathvariant="italic">n</mml:mi>
  79                         </mml:msup>
  80                         <mml:mo>-</mml:mo>
  81                         <mml:mn>1</mml:mn>
  82                     </mml:mrow>
  83                 </mml:mfenced>
  84             </mml:math>,
  85             where
  86             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">n</mml:mi></mml:math>
  87             is the number of bitplanes in the stencil buffer.
  88             <em class="parameter"><code>mask</code></em> is bitwise ANDed with both the reference value
  89             and the stored stencil value,
  90             with the ANDed values participating in the comparison.
  91         </p><p>
  92             If <span class="emphasis"><em>stencil</em></span> represents the value stored in the corresponding
  93             stencil buffer location,
  94             the following list shows the effect of each comparison function
  95             that can be specified by <em class="parameter"><code>func</code></em>.
  96             Only if the comparison succeeds is the pixel passed through
  97             to the next stage in the rasterization process
  98             (see <a class="citerefentry" href="glStencilOp.xml"><span class="citerefentry"><span class="refentrytitle">glStencilOp</span></span></a>).
  99             All tests treat <span class="emphasis"><em>stencil</em></span> values as unsigned integers in the range
 100             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 101
 102                 <mml:mfenced open="[" close="]">
 103                     <mml:mn>0</mml:mn>
 104                     <mml:mrow>
 105                         <mml:msup><mml:mn>2</mml:mn>
 106                         <mml:mi mathvariant="italic">n</mml:mi>
 107                         </mml:msup>
 108                         <mml:mo>-</mml:mo>
 109                         <mml:mn>1</mml:mn>
 110                     </mml:mrow>
 111                 </mml:mfenced>
 112             </mml:math>,
 113             where
 114             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">n</mml:mi></mml:math>
 115             is the number of bitplanes in the stencil buffer.
 116         </p><p>
 117             The following values are accepted by <em class="parameter"><code>func</code></em>:
 118         </p><div class="variablelist"><dl><dt><span class="term"><code class="constant">GL_NEVER</code></span></dt><dd><p>
 119                         Always fails.
 120                     </p></dd><dt><span class="term"><code class="constant">GL_LESS</code></span></dt><dd><p>
 121                         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> ).
 122                     </p></dd><dt><span class="term"><code class="constant">GL_LEQUAL</code></span></dt><dd><p>
 123                         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> ).
 124                     </p></dd><dt><span class="term"><code class="constant">GL_GREATER</code></span></dt><dd><p>
 125                         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> ).
 126                     </p></dd><dt><span class="term"><code class="constant">GL_GEQUAL</code></span></dt><dd><p>
 127                         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> ).
 128                     </p></dd><dt><span class="term"><code class="constant">GL_EQUAL</code></span></dt><dd><p>
 129                         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> ).
 130                     </p></dd><dt><span class="term"><code class="constant">GL_NOTEQUAL</code></span></dt><dd><p>
 131                         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> ).
 132                     </p></dd><dt><span class="term"><code class="constant">GL_ALWAYS</code></span></dt><dd><p>
 133                         Always passes.
 134                     </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
 135             Initially, the stencil test is disabled.
 136             If there is no stencil buffer,
 137             no stencil modification can occur and it is as if
 138             the stencil test always passes.
 139         </p><p>
 140             <a class="citerefentry" href="glStencilFunc.xml"><span class="citerefentry"><span class="refentrytitle">glStencilFunc</span></span></a> is the same as
 141             calling <a class="citerefentry" href="glStencilFuncSeparate.xml"><span class="citerefentry"><span class="refentrytitle">glStencilFuncSeparate</span></span></a>
 142             with <em class="parameter"><code>face</code></em> set to <code class="constant">GL_FRONT_AND_BACK</code>.
 143         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
 144             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>func</code></em> is not one of the eight
 145             accepted values.
 146         </p><p>
 147             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glStencilFunc</code>
 148             is executed between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>
 149             and the corresponding execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
 150         </p></div><div class="refsect1" lang="en" xml:lang="en"><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" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 159             <a class="citerefentry" href="glAlphaFunc.xml"><span class="citerefentry"><span class="refentrytitle">glAlphaFunc</span></span></a>,
 160             <a class="citerefentry" href="glBlendFunc.xml"><span class="citerefentry"><span class="refentrytitle">glBlendFunc</span></span></a>,
 161             <a class="citerefentry" href="glDepthFunc.xml"><span class="citerefentry"><span class="refentrytitle">glDepthFunc</span></span></a>,
 162             <a class="citerefentry" href="glEnable.xml"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a>,
 163             <a class="citerefentry" href="glLogicOp.xml"><span class="citerefentry"><span class="refentrytitle">glLogicOp</span></span></a>,
 164             <a class="citerefentry" href="glStencilFuncSeparate.xml"><span class="citerefentry"><span class="refentrytitle">glStencilFuncSeparate</span></span></a>,
 165             <a class="citerefentry" href="glStencilMask.xml"><span class="citerefentry"><span class="refentrytitle">glStencilMask</span></span></a>,
 166             <a class="citerefentry" href="glStencilMaskSeparate.xml"><span class="citerefentry"><span class="refentrytitle">glStencilMaskSeparate</span></span></a>,
 167             <a class="citerefentry" href="glStencilOp.xml"><span class="citerefentry"><span class="refentrytitle">glStencilOp</span></span></a>,
 168             <a class="citerefentry" href="glStencilOpSeparate.xml"><span class="citerefentry"><span class="refentrytitle">glStencilOpSeparate</span></span></a>
 169         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 170             Copyright <span class="trademark"></span>© 1991-2006
 171             Silicon Graphics, Inc. This document is licensed under the SGI
 172             Free Software B License. For details, see
 173             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
 174         </p></div></div></body></html>