Name

    ARM_shader_framebuffer_fetch_depth_stencil

Name Strings

    GL_ARM_shader_framebuffer_fetch_depth_stencil

Contributors

    Jan-Harald Fredriksen
    Michael Stokes
    Sandeep Kakarlapudi
    Tom Olson

Contact

    Jan-Harald Fredriksen (jan-harald.fredriksen 'at' arm.com)

Status

    Shipping.

Version

    Revision 7
    Last Modified Date: September 26, 2014

Number

    TBD

Dependencies

    OpenGL ES 2.0 or higher is required.

    ESSL 1.00 or higher is required.

    This extension is written against the OpenGL ES Shading Language
    specification, Language Version 1.00, Document Revision 17 and revision
    OpenGL ES 2.0.25 of the API specification.

    This extension has a minor dependency on OpenGL ES 3.1.

    EXT_shader_framebuffer_fetch and ARM_shader_framebuffer_fetch affect the
    wording of this extension.

Overview

    Existing extensions, such as EXT_shader_framebuffer_fetch, allow fragment
    shaders to read existing framebuffer color data as input. This enables
    use-cases such as programmable blending, and other operations that may not
    be possible to implement with fixed-function blending.

    This extension adds similar capabilities for depth and stencil values.

    One use-case for this is soft depth-blending of particles. Normally, this
    would require two render passes: one that writes out the depth values of the
    background geometry to a depth texture, and one that renders the particles
    while reading from the depth texture to do the blending. This extension
    allows this to be done in a single pass.

New Procedures and Functions

    None

New Tokens

    None

New Macro Definitions

    #define GL_ARM_shader_framebuffer_fetch_depth_stencil 1

New Built-in Variables

   lowp int gl_LastFragStencilARM

   If GL_FRAGMENT_PRECISION_HIGH is defined or __VERSION__ is 300 add:
       highp float gl_LastFragDepthARM
   otherwise add this:
       mediump float gl_LastFragDepthARM

Changes to the OpenGL ES 2.0.25 Specification, Chapter 3

    Remove the last sentence of Paragraph 2 of Chapter 3.8.1, page 86 ("These
    built-in varying variables include [...]" and add:

    "These built-in varying variables include the fragment's position, eye z
    coordinate, and front-facing flag, as well as the current depth and stencil
    values in the framebuffer.

    If a shader reads from gl_LastFragDepthARM or gl_LastFragStencilARM and no
    image is attached to the depth or stencil attachment, respectively,
    results are undefined.  No error is generated in this case."

Additions to Chapter 3 of the OpenGL ES Shading Language Specification

    Remove Paragraph 2 of section 3.8, page 17, Identifiers ("Identifiers
    starting with "gl_" are reserved [...]") and add:

    "Identifiers starting with "gl_" are reserved for use by OpenGL ES, and
    may not be declared in a shader as either a variable or a function.
    However, as noted in the specification, certain predeclared "gl_" names
    are allowed to be redeclared in a shader for the specific purpose of
    changing their precision qualifier."

Additions to Chapter 7 of the OpenGL ES Shading Language Specification

    In section 7.2 (Fragment Shader Special Variables), after the
    8th paragraph ("If the shader executes the discard keyword,") and before
    the paragraph on about gl_FragCoord, add:

        "The fragment shader has access to the read-only built-in variables
        gl_LastFragDepthARM and gl_LastFragStencilARM. These variables contain,
        respectively, the current value of the depth and stencil buffer for
        the pixel to which the current fragment is destined.

        If multi-sampling, the values of gl_LastFragDepthARM and
        gl_LastFragStencilARM depend on whether the fragment shader is invoked
        per fragment or per covered sample. If the shader is invoked per
        fragment, the values are an implementation-dependent combination of the
        samples within the destination pixel that are covered by the current
        fragment. The values will be between the minimum and maximum value of
        the samples in the pixel. If the shader is invoked per covered sample,
        separate values will be provided for each sample.

        If no samples within the destination pixel are covered by the current
        fragment, the values of gl_LastFragDepthARM and gl_LastFragStencilARM
        are undefined.

        Both gl_LastFragDepthARM and gl_LastFragStencilARM are declared with a
        default precision qualifier. This can be changed by redeclaring the
        corresponding variables with the desired precision qualifier.
        Redeclarations must be at global scope and must not otherwise alter the
        declared type of these variables.

        Reads from gl_LastFragDepthARM and gl_LastFragStencilARM need to wait
        for the processing of all previous fragments destined for the current
        pixel to complete. For best performance, it is therefore recommended
        that reads from either of these built-in variables are done as late in
        the execution of the fragment shader as possible."

        [[ The below paragraph only applies if ESSL 3.10 is supported ]]
        It is not legal for a fragment shader to read from gl_LastFragDepthARM
        and gl_LastFragStencilARM if the early_fragment_tests layout qualifier
        is specified. This will result in a compile-time error.

        Access to gl_LastFragDepthARM and gl_LastFragStencilARM is optional,
        and must be enabled by:

        #extension GL_ARM_shader_framebuffer_fetch_depth_stencil : <behavior>

        Where <behavior> is as specified in section 3.4."

    In section 7.2 (Fragment Shader Special Variables), at the end of
    the list of built-in variables, add:

        "lowp int gl_LastFragStencilARM"

    If GL_FRAGMENT_PRECISION_HIGH is defined or __VERSION__ is 300 add:
        "highp float gl_LastFragDepthARM"
    otherwise add:
         "mediump float gl_LastFragDepthARM"

Errors

    None

New State

    None

New Implementation Dependent State

    None

Interactions with EXT_shader_framebuffer_fetch

    As for color, when the value of SAMPLE_BUFFERS is 1 and the current
    framebuffer depth or stencil is accessed in the fragment shader, the
    fragment shader will be invoked separately for each covered sample and a
    separate value for the previous framebuffer color will be provided for each
    sample.

Interactions with ARM_shader_framebuffer_fetch

    As for color, the fragment shader is invoked separately for each covered
    sample if FETCH_PER_SAMPLE_ARM is enabled and current framebuffer values
    are accessed in the fragment shader.

    The presence of multiple color attachments does not affect whether reading
    gl_LastFragDepthARM and gl_LastFragStencilARM returns a defined result.

Dependencies on OpenGL ES 3.1

    If OpenGL ES 3.1 is not supported, remove all references to the
    early_fragment_tests layout qualifier.

Issues

    (1) When multisampling is enabled, does the shader run per sample?

        RESOLVED.

        This behavior is inherited from either EXT_shader_framebuffer_fetch or
        ARM_shader_framebuffer_fetch as described in the interactions section.
        If neither extension is supported, the shader runs once per fragment.

    (2) How does this extension interact with conventional depth and stencil
        testing?

        RESOLVED: There is no interaction.  The two remain orthogonal. The rest
        of the pipeline continues as usual after the fragment shader stage.

    (3) What should the precision of gl_LastFragDepthARM be?

        RESOLVED.

        Ideally, it should match the internal precision of the depth buffer, but
        OpenGL ES 2.0 does not require highp support in the fragment shader, so
        requiring highp may prevent some implementations from supporting this
        extension.

        Options include:
          A) Define gl_LastFragDepth as mediump and return it as 16bit.
          B) Define gl_LastFragDepth as mediump, but treat it as higher
             precision internally.
          C) Define gl_LastFragDepth as highp if the implementation supports
             highp, else mediump.
          D) Allow the precision of gl_LastFragDepth to be redeclared.

        Currently, option C is chosen by default, but the precision can be
        redeclared in the shader in the same manner as for gl_FragData in
        EXT_shader_framebuffer_fetch

    (4) What performance recommendations should the extension contain?

        RESOLVED.

        There is currently a recommendation to place the framebuffer
        read as late as possible in the shader.

    (5) Should the value read back include only the samples covered by the
        current fragment?

        RESOLVED.

        Yes, only the samples covered by the current fragment will be read back.

        The alternative would be to ignore the coverage mask when returning the
        value, but this seems less desirable.

        If the shader is run per sample both options would give the same result.

    (6) What is meant by undefined results in this extension?

        RESOLVED.

        Reads from gl_LastFragDepthARM and gl_LastFragStencilARM may return
        undefined results in some cases as described in the text. This means
        that there is no guarantees on the exact values returned in these
        cases. The values will typically be a GPU specific 'default' value,
        or correspond to the API clear value. It is guaranteed that these values
        will never originate from other GL contexts or applications.

    (7) How do the built-in variables added by this extension interract with
        the early_fragment_tests layout qualifier in ESSL 3.10?

        RESOLVED.

        Combining early fragment tests with reads from gl_LastFragDepthARM or
        gl_LastFragStencilARM is an error.

        The early_fragment_tests qualifier requires per-fragment tests to be
        complete before shader execution, but the built-ins added by this
        extension will only give predictable results if per-fragment tests are
        done late. If this is not the case, later fragments may update the depth
        and stencil buffer values before the current fragment reads them.

Revision History

    Revision 7, 26/09/2014 (Jan-Harald Fredriksen)
        Added interraction with OpenGL ES 3.10 per issue 7.

    Revision 6, 25/11/2013 (Jan-Harald Fredriksen)
        Clarified behavior when no depth or stencil buffer is bound.
        Added and resolved issue 6.

    Revision 5, 26/09/2013 (Jan-Harald Fredriksen)
        Restricting redeclarations of built-in variables to global scope.

    Revision 4, 15/07/2013 (Jan-Harald Fredriksen)
        Minor clarification on interaction section.

    Revision 3, 10/07/2013 (Jan-Harald Fredriksen)
        Updated interactions with ARM_shader_framebuffer_fetch.

    Revision 2, 06/05/2013 (Jan-Harald Fredriksen)
        Language clarifications.

    Revision 1, 02/05/2013 (Jan-Harald Fredriksen)
        First draft that only adds depth and stencil fetches.