upstream-man-pages/man4/glDepthFunc.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
   3               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
   4 <refentry id="glDepthFunc">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glDepthFunc</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glDepthFunc</refname>
  17         <refpurpose>specify the value used for depth buffer comparisons</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glDepthFunc</function></funcdef>
  23                 <paramdef>GLenum <parameter>func</parameter></paramdef>
  24             </funcprototype>
  25         </funcsynopsis>
  26     </refsynopsisdiv>
  27     <refsect1 id="parameters"><title>Parameters</title>
  28         <variablelist>
  29         <varlistentry>
  30             <term><parameter>func</parameter></term>
  31             <listitem>
  32                 <para>
  33                     Specifies the depth comparison function.
  34                     Symbolic constants
  35                     <constant>GL_NEVER</constant>,
  36                     <constant>GL_LESS</constant>,
  37                     <constant>GL_EQUAL</constant>,
  38                     <constant>GL_LEQUAL</constant>,
  39                     <constant>GL_GREATER</constant>,
  40                     <constant>GL_NOTEQUAL</constant>,
  41                     <constant>GL_GEQUAL</constant>, and
  42                     <constant>GL_ALWAYS</constant> are accepted.
  43                     The initial value is <constant>GL_LESS</constant>.
  44                 </para>
  45             </listitem>
  46         </varlistentry>
  47         </variablelist>
  48     </refsect1>
  49     <refsect1 id="description"><title>Description</title>
  50         <para>
  51             <function>glDepthFunc</function> specifies the function used to compare each incoming pixel depth value
  52             with the depth value present in the depth buffer.
  53             The comparison is performed only if depth testing is enabled.
  54             (See <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> of <constant>GL_DEPTH_TEST</constant>.)
  55         </para>
  56         <para>
  57             <parameter>func</parameter> specifies the conditions under which the pixel will be drawn.
  58             The comparison functions are as follows:
  59         </para>
  60         <variablelist>
  61             <varlistentry>
  62                 <term><constant>GL_NEVER</constant></term>
  63                 <listitem>
  64                     <para>
  65                         Never passes.
  66                     </para>
  67                 </listitem>
  68             </varlistentry>
  69             <varlistentry>
  70                 <term><constant>GL_LESS</constant></term>
  71                 <listitem>
  72                     <para>
  73                         Passes if the incoming depth value is less than the stored depth value.
  74                     </para>
  75                 </listitem>
  76             </varlistentry>
  77             <varlistentry>
  78                 <term><constant>GL_EQUAL</constant></term>
  79                 <listitem>
  80                     <para>
  81                         Passes if the incoming depth value is equal to the stored depth value.
  82                     </para>
  83                 </listitem>
  84             </varlistentry>
  85             <varlistentry>
  86                 <term><constant>GL_LEQUAL</constant></term>
  87                 <listitem>
  88                     <para>
  89                         Passes if the incoming depth value is less than or equal to
  90                         the stored depth value.
  91                     </para>
  92                 </listitem>
  93             </varlistentry>
  94             <varlistentry>
  95                 <term><constant>GL_GREATER</constant></term>
  96                 <listitem>
  97                     <para>
  98                         Passes if the incoming depth value is greater than the stored depth value.
  99                     </para>
 100                 </listitem>
 101             </varlistentry>
 102             <varlistentry>
 103                 <term><constant>GL_NOTEQUAL</constant></term>
 104                 <listitem>
 105                     <para>
 106                         Passes if the incoming depth value is not equal to the stored depth value.
 107                     </para>
 108                 </listitem>
 109             </varlistentry>
 110             <varlistentry>
 111                 <term><constant>GL_GEQUAL</constant></term>
 112                 <listitem>
 113                     <para>
 114                         Passes if the incoming depth value is greater than or equal to
 115                         the stored depth value.
 116                     </para>
 117                 </listitem>
 118             </varlistentry>
 119             <varlistentry>
 120                 <term><constant>GL_ALWAYS</constant></term>
 121                 <listitem>
 122                     <para>
 123                         Always passes.
 124                     </para>
 125                 </listitem>
 126             </varlistentry>
 127         </variablelist>
 128         <para>
 129             The initial value of <parameter>func</parameter> is <constant>GL_LESS</constant>.
 130             Initially, depth testing is disabled.  If depth testing is disabled or if no
 131             depth buffer exists, it is as if the depth test always passes.
 132         </para>
 133     </refsect1>
 134     <refsect1 id="notes"><title>Notes</title>
 135         <para>
 136             Even if the depth buffer exists and the depth mask is non-zero, the
 137             depth buffer is not updated if the depth test is disabled. In order to
 138             unconditionally write to the depth buffer, the depth test should be enabled
 139             and set to <constant>GL_ALWAYS</constant>.
 140         </para>
 141     </refsect1>
 142     <refsect1 id="errors"><title>Errors</title>
 143         <para>
 144             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>func</parameter> is not an accepted value.
 145         </para>
 146     </refsect1>
 147     <refsect1 id="associatedgets"><title>Associated Gets</title>
 148         <para>
 149             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_DEPTH_FUNC</constant>
 150         </para>
 151         <para>
 152             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_DEPTH_TEST</constant>
 153         </para>
 154     </refsect1>
 155     <refsect1 id="seealso"><title>See Also</title>
 156         <para>
 157             <citerefentry><refentrytitle>glDepthRange</refentrytitle></citerefentry>,
 158             <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
 159             <citerefentry><refentrytitle>glPolygonOffset</refentrytitle></citerefentry>
 160         </para>
 161     </refsect1>
 162     <refsect1 id="Copyright"><title>Copyright</title>
 163         <para>
 164             Copyright <trademark class="copyright"></trademark> 1991-2006
 165             Silicon Graphics, Inc. This document is licensed under the SGI
 166             Free Software B License. For details, see
 167             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 168         </para>
 169     </refsect1>
 170 </refentry>