NV_coverage_sample

GL_NV_coverage_sample
EGL_NV_coverage_sample

Gary King, NVIDIA Corporation (gking 'at' nvidia.com)

Copyright NVIDIA Corporation, 2005 - 2007

NVIDIA Proprietary

Last Modified Date:  2007/03/20
NVIDIA Revision: 1.0

EGL Extension #17
OpenGL ES Extension #72

Written based on the wording of the OpenGL 2.0 specification
and the EXT_framebuffer_object specification.

Written based on the wording of the EGL 1.2 specification.

Requires OpenGL-ES 2.0 and OES_framebuffer_object.

Requires EGL 1.1.

Anti-aliasing is a critical component for delivering high-quality
OpenGL rendering.  Traditionally, OpenGL implementations have
implemented two anti-aliasing algorithms: edge anti-aliasing
and multisampling.

Edge anti-aliasing computes fractional fragment coverage for all
primitives in a rendered frame, and blends edges of abutting
and/or overlapping primitives to produce smooth results.  The
image quality produced by this approach is exceptionally high;
however, applications are render their geometry perfectly ordered
back-to-front in order to avoid artifacts such as bleed-through.
Given the algorithmic complexity and performance cost of performing
exact geometric sorts, edge anti-aliasing has been used very
sparingly, and almost never in interactive games.

Multisampling, on the other hand, computes and stores subpixel
(a.k.a. "sample") coverage for rasterized fragments, and replicates
all post-alpha test operations (e.g., depth test, stencil test,
alpha blend) for each sample.  After the entire scene is rendered,
the samples are filtered to compute the final anti-aliased image.
Because the post-alpha test operations are replicated for each sample,
all of the bleed-through and ordering artifacts that could occur with
edge anti-aliasing are avoided completely; however, since each sample
must be computed and stored separately, anti-aliasing quality is
limited by framebuffer storage and rendering performance.

This extension introduces a new anti-aliasing algorithm to OpenGL,
which dramatically improves multisampling quality without
adversely affecting multisampling's robustness or significantly
increasing the storage required, coverage sampling.

Coverage sampling adds an additional high-precision geometric
coverage buffer to the framebuffer, which is used to produce
high-quality filtered results (with or without the presence of a
multisample buffer).  This coverage information is computed and stored
during rasterization; since applications may render objects where the
specified geometry does not correspond to the visual result (examples
include alpha-testing for "imposters," or extruded volume rendering
for stencil shadow volumes), coverage buffer updates may be masked
by the application, analagous to masking the depth buffer.

NVIDIA Proprietary

void CoverageMaskNV( boolean mask )
void CoverageOperationNV( enum operation )

Accepted by the <attrib_list> parameter of eglChooseConfig
and eglCreatePbufferSurface, and by the <attribute>
parameter of eglGetConfigAttrib

EGL_COVERAGE_BUFFERS_NV           0x30E0
EGL_COVERAGE_SAMPLES_NV           0x30E1

Accepted by the <internalformat> parameter of
RenderbufferStorageEXT and the <format> parameter of ReadPixels

COVERAGE_COMPONENT_NV             0x8ED0

Accepted by the <internalformat> parameter of
RenderbufferStorageEXT

COVERAGE_COMPONENT4_NV            0x8ED1

Accepted by the <operation> parameter of CoverageOperationNV

COVERAGE_ALL_FRAGMENTS_NV         0x8ED5
COVERAGE_EDGE_FRAGMENTS_NV        0x8ED6
COVERAGE_AUTOMATIC_NV             0x8ED7

Accepted by the <attachment> parameter of
FramebufferRenderbuffer, and GetFramebufferAttachmentParameteriv

COVERAGE_ATTACHMENT_NV            0x8ED2

Accepted by the <buf> parameter of Clear

COVERAGE_BUFFER_BIT_NV            0x8000

Accepted by the <pname> parameter of GetIntegerv

COVERAGE_BUFFERS_NV               0x8ED3
COVERAGE_SAMPLES_NV               0x8ED4

Insert a new section, after Section 3.2.1 (Multisampling)

"3.2.2 Coverage Sampling

Coverage sampling is a mechanism to antialias all GL primitives: points,
lines, polygons, bitmaps and images.  The technique is similar to
multisampling, with all primitives being sampled multiple times at each
pixel, and a sample resolve applied to compute the color values stored
in the framebuffer's color buffers.  As with multisampling, coverage
sampling resolves color sample and coverage values to a single, displayable
color each time a pixel is updated, so antialiasing appears to be automatic
at the application level.  Coverage sampling may be used simultaneously 
with multisampling; however, this is not required.

An additional buffer, called the coverage buffer, is added to
the framebuffer.  This buffer stores additional coverage information
that may be used to produce higher-quality antialiasing than what is
provided by conventional multisampling.

When the framebuffer includes a multisample buffer (3.5.6), the
samples contain this coverage information, and the framebuffer
does not include the coverage buffer.

If the value of COVERAGE_BUFFERS_NV is one, the rasterization of
all primitives is changed, and is referred to as coverage sample
rasterization.  Otherwise, primitive rasterization is referred to
as multisample rasterization (if SAMPLE_BUFFERS is one) or
single-sample rasterization (otherwise).  The value of
COVERAGE_BUFFERS_NV is queried by calling GetIntegerv with <pname>
set to COVERAGE_BUFFERS_NV.

During coverage sample rasterization the pixel fragment contents
are modified to include COVERAGE_SAMPLES_NV coverage values.  The
value of COVERAGE_SAMPLES_NV is an implementation-dependent
constant, and is queried by calling GetIntegerv with <pname> set
to COVERAGE_SAMPLES_NV.

The command

  CoverageOperationNV(enum operation)

may be used to modify the manner in which coverage sampling is
performed for all primitives.  If <operation> is
COVERAGE_ALL_FRAGMENTS_NV, coverage sampling will be performed and the
coverage buffer updated for all fragments generated during rasterization.
If <operation> is COVERAGE_EDGE_FRAGMENTS_NV, coverage sampling will
only be performed for fragments generated at the edge of the
primitive (by only updating fragments at the edges of primitives,
applications may get better visual results when rendering partially
transparent objects).  If <operation> is COVERAGE_AUTOMATIC_NV,
the GL will automatically select the appropriate coverage operation,
dependent on the GL blend mode and the use of gl_LastFragColor / 
gl_LastFragData in the bound fragment program.  If blending is enabled,
or gl_LastFragColor / gl_LastFragData appears in the bound fragment
program, COVERAGE_AUTOMATIC_NV will behave identically to
COVERAGE_EDGE_FRAGMENTS_NV; otherwise, COVERAGE_AUTOMATIC_NV will behave
identically to COVERAGE_ALL_FRAGMENTS_NV.  The default coverage operation
is COVERAGE_AUTOMATIC_NV."

Insert a new section, after Section 3.3.3 (Point Multisample
Rasterization)

"3.3.4  Point Coverage Sample Rasterization

If the value of COVERAGE_BUFFERS_NV is one, then points are
rasterized using the following algorithm, regardless of whether
point antialiasing (POINT_SMOOTH) is enabled or disabled.  Point
rasterization produces fragments using the same algorithm described
in section 3.3.3; however, sample points are divided into SAMPLES
multisample points and COVERAGE_SAMPLES_NV coverage sample points.

Rasterization for multisample points uses the algorithm described
in section 3.3.3.  Rasterization for coverage sample points uses
implementation-dependent algorithms, ultimately storing the results
in the coverage buffer."

Insert a new section, after Section 3.4.4 (Line Multisample
Rasterization)

"3.4.5  Line Coverage Sample Rasterization

If the value of COVERAGE_BUFFERS_NV is one, then lines are
rasterized using the following algorithm, regardless of whether
line antialiasing (LINE_SMOOTH) is enabled or disabled.  Line
rasterization produces fragments using the same algorithm described
in section 3.4.4; however, sample points are divided into SAMPLES 
multisample points and COVERAGE_SAMPLES_NV coverage sample points.

Rasterization for multisample points uses the algorithm described in
section 3.4.4.  Rasterization for coverage sample points uses
implementation-dependent algorithms, ultimately storing results in
the coverage buffer."    

Insert a new section, after Section 3.5.6 (Polygon Multisample
Rasterization)

"3.5.7  Polygon Coverage Sample Rasterization

If the value of COVERAGE_BUFFERS_NV is one, then polygons are
rasterized using the following algorithm, regardless of whether
polygon antialiasing (POLYGON_SMOOTH) is enabled or disabled.  Polygon
rasterization produces fragments using the same algorithm described in
section 3.5.6; however, sample points are divided into SAMPLES multisample
points and COVERAGE_SAMPLES_NV coverage sample points.

Rasterization for multisample points uses the algorithm described in
section 3.5.7.  Rasterization for coverage sample points uses
implementation-dependent algorithms, ultimately storing results in the
coverage buffer."

Insert a new section, after Section 3.6.6 (Pixel Rectangle Multisample
Rasterization)

"3.6.7  Pixel Rectangle Coverage Sample Rasterization

If the value of COVERAGE_BUFFERS_NV is one, then pixel rectangles are
rasterized using the algorithm described in section 3.6.6."

Modify the first sentence of the second-to-last paragraph of section
3.7 (Bitmaps) to read:

"Bitmap Multisample and Coverage Sample Rasterization

If MULTISAMPLE is enabled, and the value of SAMPLE_BUFFERS is one;
or if the value of COVERAGE_BUFFERS_NV is one, then bitmaps are
rasterized using the following algorithm. [...]"

Insert after the first paragraph of Section 4.2.2 (Fine Control of
Buffer Updates):

"The coverage buffer can be enabled or disabled for writing coverage
sample values using

    void CoverageMaskNV( boolean mask );

If <mask> is non-zero, the coverage buffer is enabled for writing;
otherwise, it is disabled.  In the initial state, the coverage
buffer is enabled for writing."

And change the text of the last 2 paragraphs of Section 4.2.2 to read:

"The state required for the various masking operations is three
integers and two bits: an integer for color indices, an integer for
the front and back stencil values, a bit for depth values, and a
bit for coverage sample values.  A set of four bits is also required
indicating which components of an RGBA value should be written.  In the
initial state, the integer masks are all ones, as are the bits
controlling the depth value, coverage sample value and RGBA component
writing.

Fine Control of Multisample Buffer Updates

When the value of SAMPLE_BUFFERS is one, ColorMask, DepthMask, 
CoverageMask, and StencilMask or StencilMaskSeparate control the
modification of values in the multisample buffer. [...]"

Change paragraph 2 of Section 4.2.3 (Clearing the Buffers) to read:

"is the bitwise OR of a number of values indicating which buffers are to
be cleared.  The values are COLOR_BUFFER_BIT, DEPTH_BUFFER_BIT,
STENCIL_BUFFER_BIT, ACCUM_BUFFER_BIT and COVERAGE_BUFFER_BIT_NV, indicating
the buffers currently enabled for color writing, the depth buffer,
the stencil buffer, the accumulation buffer and the virtual-coverage
buffer, respectively. [...]"

Insert a new paragraph after paragraph 4 of Section 4.3.2 (Reading Pixels)
(beginning with "If there is a multisample buffer ..."):

"If the <format> is COVERAGE_COMPONENT_NV, then values are taken from the
coverage buffer; again, if there is no coverage buffer, the error
INVALID_OPERATION occurs.  When <format> is COVERAGE_COMPONENT_NV,
<type> must be GL_UNSIGNED_BYTE.  Any other value for <type> will
generate the error INVALID_ENUM.  If there is a multisample buffer, the 
values are undefined."

Add a new table at the end of Section 4.4.2.1 (Renderbuffer Objects)

"+-------------------------+-----------------------+-----------+
 |  Sized internal format  | Base Internal Format  | C Samples |
 +-------------------------+-----------------------+-----------+
 | COVERAGE_COMPONENT4_NV  | COVERAGE_COMPONENT_NV |     4     |
 +-------------------------+-----------------------+-----------+
 Table 1.ooo Desired component resolution for each sized internal
 format that can be used only with renderbuffers"

Add to the bullet list in Section 4.4.4 (Framebuffer Completeness)

"An internal format is 'coverage-renderable' if it is COVERAGE_COMPONENT_NV
or one of the COVERAGE_COMPONENT_NV formats from table 1.ooo.  No other
formats are coverage-renderable"

Add to the bullet list in Section 4.4.4.1 (Framebuffer Attachment
Completeness)

"If <attachment> is COVERAGE_ATTACHMENT_NV, then <image> must have a
coverage-renderable internal format."

Add a paragraph at the end of Section 4.4.4.2 (Framebuffer Completeness)

"The values of COVERAGE_BUFFERS_NV and COVERAGE_SAMPLES_NV are derived from
the attachments of the currently bound framebuffer object.  If the current
FRAMEBUFFER_BINDING_OES is not 'framebuffer-complete', then both
COVERAGE_BUFFERS_NV and COVERAGE_SAMPLES_NV are undefined.  Otherwise,
COVERAGE_SAMPLES_NV is equal to the number of coverage samples for the
image attached to COVERAGE_ATTACHMENT_NV, or zero if COVERAGE_ATTACHMENT_NV
is zero."

Add to Table 3.1 (EGLConfig attributes)
+---------------------------+---------+-----------------------------------+
|        Attribute          |   Type  | Notes                             |
+---------------------------+---------+-----------------------------------+
|  EGL_COVERAGE_BUFFERS_NV  | integer | number of coverage buffers        |
|  EGL_COVERAGE_SAMPLES_NV  | integer | number of coverage samples per    |
|                           |         |    pixel                          |
+---------------------------+---------+-----------------------------------+

Modify the first sentence of the last paragraph of the "Buffer 
Descriptions and Attributes" subsection of Section 3.4 (Configuration 
Management), p. 16

"There are no single-sample depth, stencil or coverage buffers for a
multisample EGLConfig; the only depth, stencil and coverage buffers are 
those in the multisample buffer. [...]"

And add the following text at the end of that paragraph:

"The <coverage buffer> is used only by OpenGL ES.  It contains primitive
coverage information that is used to produce a high-quality anti-aliased
image.  The format of the coverage buffer is not specified, and its 
contents are not directly accessible.  Only the existence of the coverage 
buffer, and the number of coverage samples it contains, are exposed by EGL.

EGL_COVERAGE_BUFFERS_NV indicates the number of coverage buffers, which 
must be zero or one.  EGL_COVERAGE_SAMPLES_NV gives the number of coverage
samples per pixel; if EGL_COVERAGE_BUFFERS_NV is zero, then
EGL_COVERAGE_SAMPLES_NV will also be zero."

Add to Table 3.4 (Default values and match criteria for EGLConfig 
attributes)

+---------------------------+-----------+-------------+---------+---------+
|        Attribute          |  Default  |  Selection  |  Sort   |  Sort   |
|                           |           |  Criteria   |  Order  | Priority|
+---------------------------+-----------+-------------+---------+---------+
|  EGL_COVERAGE_BUFFERS_NV  |     0     |   At Least  | Smaller |    7    |
|  EGL_COVERAGE_SAMPLES_NV  |     0     |   At Least  | Smaller |    8    |
+---------------------------+-----------+-------------+---------+---------+
  And renumber existing sort priorities 7-11 as 9-13.

Modify the list in "Sorting of EGLConfigs" (Section 3.4.1, pg 20)

" [...]
  5.  Smaller EGL_SAMPLE_BUFFERS
  6.  Smaller EGL_SAMPLES
  7.  Smaller EGL_COVERAGE_BUFFERS_NV
  8.  Smaller EGL_COVERAGE_SAMPLES_NV
  9.  Smaller EGL_DEPTH_SIZE
  10. Smaller EGL_STENCIL_SIZE
  11. Smaller EGL_ALPHA_MASK_SIZE
  12. Special: [...]
  13. Smaller EGL_CONFIG_ID [...]"

    glCoverageMaskNV(GL_TRUE);
    glDepthMask(GL_TRUE);
    glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE);

    while (1) 
    {
        glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | 
                GL_COVERAGE_BUFFER_BIT_NV);
        glDrawElements(...);
        eglSwapBuffers(...);
    }

    while (1)
    {
        glDepthMask(GL_TRUE);
        glCoverageMaskNV(GL_TRUE);
        glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE);
        glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | 
                GL_COVERAGE_BUFFER_BIT_NV);

        //  first render pass: render Z-only (occlusion surface), with 
        //  coverage info.  color writes are disabled

        glCoverageMaskNV(GL_TRUE);
        glDepthMask(GL_TRUE);
        glColorMask(GL_FALSE, GL_FALSE, GL_FALSE, GL_FALSE);
        glDepthFunc(GL_LESS);
        glDrawElements(...);

        //  second render pass: set Z test to Z-equals, disable Z-writes & 
        //  coverage writes.  enable color writes.  coverage may be 
        //  disabled, because subsequent rendering passes are rendering 
        //  identical geometry -- since the final coverage buffer will be 
        //  unchanged, we can disable coverage writes as an optimization.

        glCoverageMaskNV(GL_FALSE);
        glDepthMask(GL_FALSE);
        glDepthFunc(GL_EQUAL);
        glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE);
        glDrawElements(...);

        eglSwapBuffers();
    }

    while (1)
    {
        glDepthMask(GL_TRUE);
        glCoverageMaskNV(GL_TRUE);
        glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE);
        glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | 
                GL_COVERAGE_BUFFER_BIT_NV);

        // render opaque, Z-buffered geometry with coverage info for the
        // entire primitive.  Overwrite coverage data for all fragments, so
        // that interior fragments do not get resolved incorrectly.

        glDepthFunc(GL_LESS);
        glCoverageOperationNV(GL_COVERAGE_ALL_FRAGMENTS_NV);
        glDrawElements(...);

        // render translucent, Z-buffered geometry.  to ensure that visible
        // edges of opaque geometry remain anti-aliased, change the 
        // coverage operation to just edge fragments.  this will maintain 
        // the coverage information underneath the translucent geometry, 
        // except at translucent edges.

        glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
        glCoverageOperationNV(GL_COVERAGE_EDGE_FRAGMENTS_NV);
        glEnable(GL_BLEND);
        glDrawElements(...);
        glDisable(GL_BLEND);

        eglSwapBuffers();
    }

    while (1)
    {
        glDepthMask(GL_TRUE);
        glCoverageMaskNV(GL_TRUE);
        glColorMask(GL_TRUE, GL_TRUE, GL_TRUE, GL_TRUE);
        glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | 
                GL_COVERAGE_BUFFER_BIT_NV);

        // render opaque, Z-buffered geometry, with coverage info.
        glDepthFunc(GL_LESS);
        glDrawElements(...);

        // render opacity-mapped geometry.  disable Z writes, enable alpha
        // blending. also, disable coverage writes -- the edges of the 
        // geometry used for the HUD/particle system have alpha values 
        // tapering to zero, so edge coverage is uninteresting, and 
        // interior coverage should still refer to the underlying opaque 
        // geometry, so that opaque edges visible through the translucent
        // regions remain anti-aliased.

        glCoverageMaskNV(GL_FALSE);
        glDepthMask(GL_FALSE);
        glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
        glEnable(GL_BLEND);
        glDrawElements(...);
        glDisable(GL_BLEND);
        
        eglSwapBuffers();
    }

1.  Is any specific discussion of coverage sampling resolves required,
    particularly with respect to application-provided framebuffer objects?

    RESOLVED:  No.  Because the coverage sampling resolve is an
    implementation-dependent algorithm, it is always legal behavior for
    framebuffer read / copy functions to return the value in the selected
    ReadBuffer as if COVERAGE_BUFFERS_NV was zero.  This allows
    textures attached to the color attachment points of framebuffer objects
    to behave predictably, even when COVERAGE_BUFFERS_NV is one.

    Implementations are encouraged, whenever possible, to use the highest-
    quality coverage sample resolve supported for calls to eglSwapBuffers,
    eglCopyBuffers, ReadPixels, CopyPixels and CopyTex{Sub}Image.
    
2.  Should all render buffer & texture types be legal sources for image
    resolves and coverage attachment?

    RESOLVED: This spec should not place any arbitrary limits on usage;
    however, there are many reasons why implementers may not wish to 
    support coverage sampling for all surface types.

    Implementations may return FRAMEBUFFER_UNSUPPORTED_OES from
    CheckFramebufferStatusOES if an object bound to COVERAGE_ATTACHMENT_NV
    is incompatible with one or more objects bound to DEPTH_ATTACHMENT_OES,
    STENCIL_ATTACHMENT_OES, or COLOR_ATTACHMENTi_OES.