Return to glSampleCoverage.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="glSampleCoverage">
  <refmeta>
    <refentrytitle>glSampleCoverage</refentrytitle>
    <manvolnum>3G</manvolnum>
  </refmeta>

  <refnamediv>
    <refdescriptor>glSampleCoverage</refdescriptor>
    <refname>glSampleCoverage</refname>
    <refname>glSampleCoveragex</refname>
    <refpurpose>specify mask to modify multisampled pixel fragments</refpurpose>
  </refnamediv>

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

    <funcsynopsis>
      <funcprototype>
        <funcdef>void <function>glSampleCoverage</function></funcdef>
        <paramdef>GLclampf <parameter>value</parameter></paramdef>
        <paramdef>GLboolean <parameter>invert</parameter></paramdef>
      </funcprototype>
      <funcprototype>
        <funcdef>void <function>glSampleCoveragex</function></funcdef>
        <paramdef>GLclampx <parameter>value</parameter></paramdef>
        <paramdef>GLboolean <parameter>invert</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>
          <parameter>value</parameter>
        </term>

        <listitem>
          <para>Specifies the coverage of the modification mask.
          The value is clamped to the range [0, 1], where 0 represents
          no coverage and 1 full coverage. The initial value is 1.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <parameter>invert</parameter>
        </term>

        <listitem>
          <para>Specifies whether the modification mask implied by
          <parameter>value</parameter> is inverted or not.
          The initial value is <constant>GL_FALSE</constant>.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para><function>glSampleCoverage</function> defines a mask to modify
    the coverage of multisampled pixel fragments. This capability is used
    for antialiased screen-door transparency and smooth transitions between
    two renderings of an object (often for level-of-detail management in
    simulation systems).</para>

    <para>
    When multisampling is enabled (see
    <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
    with argument
    <constant>GL_MULTISAMPLE</constant>) a ``fragment mask'' is computed for
    each fragment
    generated by a primitive.  This mask reflects the amount of the pixel
    covered by the fragment, and determines the frame buffer samples that may
    be affected by the fragment.</para>

    <para>
    If conversion of alpha values to masks is enabled
    (<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
    with argument
    <constant>GL_SAMPLE_ALPHA_TO_MASK</constant>),
    the fragment alpha value is used to
    generate a temporary modification mask which is then ANDed with the
    fragment mask.  One way to interpret this is as a form of dithering: a
    multivalued alpha (coverage or opacity) for the whole fragment is
    converted to simple binary values of coverage at many locations (the
    samples).</para>

    <para>
    After conversion of alpha values to masks, if replacement of alpha values
    is enabled
    (<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
    with argument
    <constant>GL_SAMPLE_ALPHA_TO_ONE</constant>), the
    fragment's alpha is set to the maximum allowable value.</para>

    <para>
    Finally, if fragment mask modification is enabled
    (<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
    with argument
    <constant>GL_SAMPLE_MASK</constant>),
    <function>glSampleCoverage</function> defines an additional modification
    mask.  value is used to generate a modification mask in much the same way
    alpha was used above.  If invert is <constant>GL_TRUE</constant>,
    then the modification mask
    specified by value will be inverted.  The final modification mask will
    then be ANDed with the fragment mask resulting from the previous steps.
    This can be viewed as an ``override'' control that selectively fades the
    effects of multisampled fragments.</para>

    <para>Note that
    <function>glSampleCoverage</function>(value, <constant>GL_TRUE</constant>)
    is not necessarily equivalent to 
   <function>glSampleCoverage</function>(1.0 - value, <constant>GL_FALSE</constant>);
    due to round-off and other
    issues, complementing the coverage will not necessarily yield an inverted
    modification mask.</para>
  </refsect1>

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

    <para>
      <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
    </para>
  </refsect1>
</refentry>