Return to glAlphaFunc.xml CVS log

Up to [Development] / projects / ogl-sample / main / doc / gles / xml

OpenGL ES 1.0 and EGL 1.0 reference manual and man pages (written by
Claude Knaus, based on OpenGL SI man pages).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "DTD/docbook/docbookx.dtd">

<!--
  License Applicability. Except to the extent portions of this file are
  made subject to an alternative license as permitted in the SGI Free
  Software License B, Version 1.1 (the "License"), the contents of this
  file are subject only to the provisions of the License. You may not use
  this file except in compliance with the License. You may obtain a copy
  of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
  Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:

  http://oss.sgi.com/projects/FreeB

  Note that, as provided in the License, the Software is distributed on an
  "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
  DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
  CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
  PARTICULAR PURPOSE, AND NON-INFRINGEMENT.

  Original Code. The Original Code is: OpenGL ES Reference Manual,
  Version 1.0, released September 2003, developed by Silicon Graphics,
  Inc.  The Original Code is Copyright (c) 2003 Silicon Graphics, Inc.
  Copyright in any portions created by third parties is as indicated
  elsewhere herein.  All Rights Reserved.
-->

<refentry id="glAlphaFunc">
  <refmeta>
    <refentrytitle>glAlphaFunc</refentrytitle>
    <manvolnum>3G</manvolnum>
  </refmeta>

  <refnamediv>
    <refdescriptor>glAlphaFunc</refdescriptor>
    <refname>glAlphaFunc</refname>
    <refname>glAlphaFuncx</refname>
    <refpurpose>specify the alpha test function</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>C Specification</title>

    <funcsynopsis>
      <funcprototype>
        <funcdef>void <function>glAlphaFunc</function></funcdef>
        <paramdef>GLenum <parameter>func</parameter></paramdef>
        <paramdef>GLclampf <parameter>ref</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>void <function>glAlphaFuncx</function></funcdef>
        <paramdef>GLenum <parameter>func</parameter></paramdef>
        <paramdef>GLclampx <parameter>ref</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>
          <parameter>func</parameter>
        </term>

        <listitem>
          <para>Specifies the alpha comparison function. Symbolic
          constants 
          <constant>GL_NEVER</constant>, 
          <constant>GL_LESS</constant>, 
          <constant>GL_EQUAL</constant>, 
          <constant>GL_LEQUAL</constant>, 
          <constant>GL_GREATER</constant>, 
          <constant>GL_NOTEQUAL</constant>, 
          <constant>GL_GEQUAL</constant>, and 
          <constant>GL_ALWAYS</constant>
          are accepted. The initial value is 
          <constant>GL_ALWAYS</constant>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <parameter>ref</parameter>
        </term>

        <listitem>
          <para>Specifies the reference value that incoming alpha
            values are compared to. This value is clamped to the
            range [0, 1], where 0 represents the lowest possible
            alpha value and 1 the highest possible value. The initial
            reference value is 0.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The alpha test discards fragments depending on the
      outcome of a comparison between an incoming fragment's alpha
      value and a constant reference value. 
      <function>glAlphaFunc</function>
      specifies the reference value and the comparison function. The
      comparison is performed only if alpha testing is enabled.
      To enable and disable alpha testing, call
      <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and 
      <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry>
      with argument <constant>GL_ALPHA_TEST</constant>.
      Alpha testing is initially disabled.
    </para>

    <para>
      <parameter>func</parameter> and <parameter>ref</parameter>
      specify the conditions under which the pixel is drawn. The
      incoming alpha value is compared to <parameter>ref</parameter>
      using the function specified by <parameter>func</parameter>.

      If the value passes the comparison, the incoming fragment is
      drawn if it also passes subsequent stencil and depth buffer
      tests. If the value fails the comparison, no change is made to
      the frame buffer at that pixel location. The comparison
      functions are as follows:
    </para>

    <variablelist>
      <varlistentry>
        <term>
          <constant>GL_NEVER</constant>
        </term>

        <listitem>
          <para>Never passes.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_LESS</constant>
        </term>

        <listitem>
          <para>Passes if the incoming alpha value is less than the
          reference value.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_EQUAL</constant>
        </term>

        <listitem>
          <para>Passes if the incoming alpha value is equal to the
          reference value.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_LEQUAL</constant>
        </term>

        <listitem>
          <para>Passes if the incoming alpha value is less than or
          equal to the reference value.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_GREATER</constant>
        </term>

        <listitem>
          <para>Passes if the incoming alpha value is greater than
          the reference value.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_NOTEQUAL</constant>
        </term>

        <listitem>
          <para>Passes if the incoming alpha value is not equal to
          the reference value.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_GEQUAL</constant>
        </term>

        <listitem>
          <para>Passes if the incoming alpha value is greater than
          or equal to the reference value.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_ALWAYS</constant>
        </term>

        <listitem>
          <para>Always passes (initial value).</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>
      <function>glAlphaFunc</function>
      operates on all pixel write operations, including those
      resulting from the scan conversion of points, lines, and
      polygons. 
      <function>glAlphaFunc</function> 
      does not affect
      <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>.
    </para>
  </refsect1>

  <refsect1>
    <title>Errors</title>

    <para>
      <constant>GL_INVALID_ENUM</constant> is generated if 
      <parameter>func</parameter> is not an accepted value.
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry><refentrytitle>glBlendFunc</refentrytitle></citerefentry>, 
      <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry>, 
      <citerefentry><refentrytitle>glDepthFunc</refentrytitle></citerefentry>, 
      <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>, 
      <citerefentry><refentrytitle>glStencilFunc</refentrytitle></citerefentry>
    </para>
  </refsect1>
</refentry>