extensions/NV/NV_fragment_coverage_to_color.txt

Name

    NV_fragment_coverage_to_color

Name Strings

    GL_NV_fragment_coverage_to_color

Contact

    Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com)
    Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com)
    Mark Kilgard, NVIDIA Corporation (mjk 'at' nvidia.com)

Contributors

    Jeff Bolz, NVIDIA Corporation
    Pat Brown, NVIDIA Corporation
    Mark Kilgard, NVIDIA Corporation
    James Helferty, NVIDIA Corporation

Status

    Shipping

Version

    Last Modified Date:         March 27, 2015
    Revision:                   2

Number

    OpenGL Extension #467
    OpenGL ES Extension #229

Dependencies

    This extension is written against the OpenGL 4.3 specification
    (Compatibility Profile).

    This extension interacts with NV_multisample_coverage.

    This extension interacts with EXT_raster_multisample and 
    NV_framebuffer_mixed_samples.

    This extension interacts with OpenGL ES 3.1.

    When implemented for OpenGL ES 3.1, this extension interacts with
    OES_sample_shading.

Overview

    This extension allows the fragment coverage value, represented as an
    integer bitfield, to be substituted for a color output being written to a
    single-component color buffer with integer components (e.g., R8UI).  The
    capability provided by this extension is different from simply writing the
    gl_SampleMask fragment shader output in that the coverage value written to
    the framebuffer is taken after alpha test, stencil test, and depth test,
    as well as after the multisample fragment operations such as
    alpha-to-coverage.

    This functionality may be useful for deferred rendering algorithms, where
    the second pass needs to know which samples belong to which original 
    fragments.

New Procedures and Functions

    void FragmentCoverageColorNV(uint color);

New Tokens

    Accepted by the <cap> parameter of Enable, Disable, IsEnabled:

        FRAGMENT_COVERAGE_TO_COLOR_NV                   0x92DD

    Accepted by the <pname> parameter of GetBooleanv, GetDoublev,
    GetIntegerv, and GetFloatv:

        FRAGMENT_COVERAGE_COLOR_NV                      0x92DE

Additions to Chapter 17 of the OpenGL 4.3 (Compatibility Profile) Specification
(Rasterization)

    Modify Figure 17.1 (Per-fragment operations), p. 530

    Add a new box "Fragment Coverage to Color" between "Occlusion Query" and
    "Blending".

    (note: If EXT_raster_multisample or NV_framebuffer_mixed_samples are 
    supported, the "Coverage Reduction" stage is after the "Fragment coverage 
    to color" stage.)


    Add a new Section 17.3.X (Fragment Coverage to Color) between 17.3.6 (Depth
    Buffer Test) and 17.3.7 (Occlusion Queries)

    Fragment coverage to color is enabled or disabled with the generic Enable
    and Disable commands using the symbolic constant
    FRAGMENT_COVERAGE_TO_COLOR_NV. When disabled, this step is skipped. When
    enabled, the fragment coverage, treated as an integer bitfield, is
    substituted for the red component of one of the fragment color values.
    The fragment color value updated with the coverage mask is specified using

        FragmentCoverageColorNV(uint color);

    where <color> is an integer between 0 and the value of MAX_DRAW_BUFFERS
    minus one, inclusive.

    Errors:

    - INVALID_VALUE error is generated if <color> is greater than or equal to
      MAX_DRAW_BUFFERS.

    If the buffer that the coverage value will be written to does not have a
    RED base internal format with signed or unsigned integer components, then
    the values output in color <color> are undefined. If the fragment color
    will be written to multiple color buffers (e.g. via the <DrawBuffer>
    command using FRONT_AND_BACK), then the values written to those buffers
    are undefined.

    If the color buffer has fewer bits than the sample coverage, the low bits
    of the sample coverage will be taken without any clamping. If the buffer
    has more bits than the sample coverage, the high bits of the sample
    coverage will be filled with zeros.

    If SAMPLE_SHADING is enabled, the coverage is split among the multiple
    fragment invocations processed per pixel.
    

New Implementation Dependent State

    None.

New State

    Get Value                       Get Command    Type    Initial Value    Attribute
    ---------                       -----------    ----    -------------    ---------
    FRAGMENT_COVERAGE_TO_COLOR_NV   IsEnabled      B       FALSE            enable/color-buffer
    FRAGMENT_COVERAGE_COLOR_NV      GetIntegerv    Z+      0                color-buffer


Additions to the AGL/GLX/WGL Specifications

    None.

GLX Protocol

    None.
    
Modifications to the OpenGL Shading Language Specification, Version 4.30

    None.

Errors

    INVALID_VALUE is generated by FragmentCoverageColorNV if <color> is greater
    than or equal to the value of MAX_DRAW_BUFFERS. 

Dependencies on NV_multisample_coverage

    The coverage values written to the color buffer only includes bits for
    color samples, not for coverage samples.

Dependencies on EXT_raster_multisample and NV_framebuffer_mixed_samples

    If the number of effective raster samples is greater than the number of
    color samples, then each color sample receives the full coverage mask of
    the fragment.

Interactions with OpenGL ES 3.1

    If OES_sample_shading is present, change all references to SAMPLE_SHADING
    to SAMPLE_SHADING_OES. Otherwise, ignore all references to SAMPLE_SHADING.

    Ignore all references to GetDoublev.

    In new section titled "Fragment Coverage to Color", remove the last
    sentence from the paragraph beginning "If the buffer that the coverage
    value will be written to...", which refers to writing a single color value
    to multiple color buffers.

Issues

    1) If coverage information is written to a color buffer with multiple
    components or non-integer components, should this case be treated as
    undefined, as an error, or should writes be implicitly disabled?

    RESOLVED: Undefined.

    2) How do we handle fewer/more bits in the sample coverage than in the 
    color buffer?

    RESOLVED: If there are fewer bits in the sample coverage than the color
    buffer, the mask is zero-extended. If there are more bits in the sample
    coverage than the color buffer, only the LSBs are written.

    3) How does this interact with EXT_raster_multisample/
    NV_framebuffer_mixed_samples?

    RESOLVED: Coverage to color may be used while the number of effective
    raster samples is greater than the number of color samples. All color
    samples (that are written) will receive the same coverage mask. 

    4) Where does this belong in the pipeline?

    RESOLVED: Anywhere between "depth test" and "color logic op" will work.
    Since this only works for integer buffers, blending and sRGB are 
    irrelevant. However, color logic op can be used just like in normal 
    integer color rendering.

    (5) How does this interact with sample shading?

    RESOLVED: Sample shading effectively splits a pixel into several fragment
    shader invocations, and each invocation receives a partial coverage mask.
    When these invocations reach the coverage-to-color stage, they write out
    their partial coverage.

    (6) When using NV_fragment_coverage_to_color with EXT_raster_multisample
    or NV_framebuffer_mixed_samples, how do these features interact?

    RESOLVED: Both may be used simultaneously, and the coverage_to_color
    functionality is applied before coverage reduction in the pipeline. This
    means the full raster sample mask will be written to the color buffer, not
    the reduced color sample mask.

Revision History

    Revision 2, 2015/03/27
      - Add ES interactions

    Revision 1
      - Internal revisions.