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