upstream-doc/man2/xhtml/glAlphaFunc.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>glAlphaFunc</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glAlphaFunc"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glAlphaFunc — specify the alpha test function</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">glAlphaFunc</b>(</code></td><td>GLenum  </td><td><var class="pdparam">func</var>, </td></tr><tr><td> </td><td>GLclampf  </td><td><var class="pdparam">ref</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 alpha comparison function.
   5                     Symbolic constants
   6                     <code class="constant">GL_NEVER</code>,
   7                     <code class="constant">GL_LESS</code>,
   8                     <code class="constant">GL_EQUAL</code>,
   9                     <code class="constant">GL_LEQUAL</code>,
  10                     <code class="constant">GL_GREATER</code>,
  11                     <code class="constant">GL_NOTEQUAL</code>,
  12                     <code class="constant">GL_GEQUAL</code>, and
  13                     <code class="constant">GL_ALWAYS</code> are accepted. 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 that incoming alpha values are compared to.
  16                     This value 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:mn>1</mml:mn>
  22                         </mml:mfenced>
  23                     </mml:math>,
  24                     where 0 represents the lowest possible alpha value
  25                     and 1 the highest possible value.
  26                     The initial reference value is 0.
  27                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  28             The alpha test discards fragments depending on the outcome of a comparison
  29             between an incoming fragment's alpha value and a constant reference value.
  30             <code class="function">glAlphaFunc</code> specifies the reference value and the comparison function.
  31             The comparison is performed only if alpha testing is enabled. By
  32             default, it is not enabled.
  33             (See
  34             <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> of <code class="constant">GL_ALPHA_TEST</code>.)
  35         </p><p>
  36             <em class="parameter"><code>func</code></em> and <em class="parameter"><code>ref</code></em> specify the conditions under which
  37             the pixel is drawn.
  38             The incoming alpha value is compared to <em class="parameter"><code>ref</code></em>
  39             using the function specified by <em class="parameter"><code>func</code></em>.
  40             If the value passes the comparison,
  41             the incoming fragment is drawn
  42             if it also passes subsequent stencil and depth buffer tests.
  43             If the value fails the comparison,
  44             no change is made to the frame buffer at that pixel location. The
  45             comparison functions are as follows:
  46         </p><div class="variablelist"><dl><dt><span class="term"><code class="constant">GL_NEVER</code></span></dt><dd><p>
  47                         Never passes.
  48                     </p></dd><dt><span class="term"><code class="constant">GL_LESS</code></span></dt><dd><p>
  49                         Passes if the incoming alpha value is less than the reference value.
  50                     </p></dd><dt><span class="term"><code class="constant">GL_EQUAL</code></span></dt><dd><p>
  51                         Passes if the incoming alpha value is equal to the reference value.
  52                     </p></dd><dt><span class="term"><code class="constant">GL_LEQUAL</code></span></dt><dd><p>
  53                         Passes if the incoming alpha value is less than or equal to the reference value.
  54                     </p></dd><dt><span class="term"><code class="constant">GL_GREATER</code></span></dt><dd><p>
  55                         Passes if the incoming alpha value is greater than the reference value.
  56                     </p></dd><dt><span class="term"><code class="constant">GL_NOTEQUAL</code></span></dt><dd><p>
  57                         Passes if the incoming alpha value is not equal to the reference value.
  58                     </p></dd><dt><span class="term"><code class="constant">GL_GEQUAL</code></span></dt><dd><p>
  59                         Passes if the incoming alpha value is greater than or equal to
  60                         the reference value.
  61                     </p></dd><dt><span class="term"><code class="constant">GL_ALWAYS</code></span></dt><dd><p>
  62                         Always passes (initial value).
  63                     </p></dd></dl></div><p>
  64             <code class="function">glAlphaFunc</code> operates on all pixel write operations,
  65             including those resulting from the scan conversion of points,
  66             lines,
  67             polygons,
  68             and bitmaps,
  69             and from pixel draw and copy operations.
  70             <code class="function">glAlphaFunc</code> does not affect screen clear operations.
  71         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
  72             Alpha testing is performed only in RGBA mode.
  73         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
  74             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>func</code></em> is not an accepted value.
  75         </p><p>
  76             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glAlphaFunc</code>
  77             is executed between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>
  78             and the corresponding execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
  79         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
  80             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_ALPHA_TEST_FUNC</code>
  81         </p><p>
  82             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_ALPHA_TEST_REF</code>
  83         </p><p>
  84             <a class="citerefentry" href="glIsEnabled.xml"><span class="citerefentry"><span class="refentrytitle">glIsEnabled</span></span></a> with argument <code class="constant">GL_ALPHA_TEST</code>
  85         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
  86             <a class="citerefentry" href="glBlendFunc.xml"><span class="citerefentry"><span class="refentrytitle">glBlendFunc</span></span></a>,
  87             <a class="citerefentry" href="glClear.xml"><span class="citerefentry"><span class="refentrytitle">glClear</span></span></a>,
  88             <a class="citerefentry" href="glDepthFunc.xml"><span class="citerefentry"><span class="refentrytitle">glDepthFunc</span></span></a>,
  89             <a class="citerefentry" href="glEnable.xml"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a>,
  90             <a class="citerefentry" href="glStencilFunc.xml"><span class="citerefentry"><span class="refentrytitle">glStencilFunc</span></span></a>
  91         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
  92             Copyright <span class="trademark"></span>© 1991-2006
  93             Silicon Graphics, Inc. This document is licensed under the SGI
  94             Free Software B License. For details, see
  95             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
  96         </p></div></div></body></html>