xref: /third_party/openGLES/extensions/ARB/ARB_depth_buffer_float.txt

Name

    ARB_depth_buffer_float

Name Strings

    GL_ARB_depth_buffer_float

Contributors

    Pierre Boudier

Contact

    Pierre Boudier, AMD pierre.boudier 'at' amd.com)

Notice

    Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at
        http://www.khronos.org/registry/speccopyright.html

Specification Update Policy

    Khronos-approved extension specifications are updated in response to
    issues and bugs prioritized by the Khronos OpenGL Working Group. For
    extensions which have been promoted to a core Specification, fixes will
    first appear in the latest version of that core Specification, and will
    eventually be backported to the extension document. This policy is
    described in more detail at
        https://www.khronos.org/registry/OpenGL/docs/update_policy.php

Status

    Approved by the ARB on July 11, 2008

Version

    Last Modified Date:         October 18, 2012
    Revision:                   7

Number

    ARB Extension #43

Dependencies

    OpenGL 2.0 is required.

    ARB_color_buffer_float is required.

    EXT_packed_depth_stencil is required.

    ARB_framebuffer_object is required.
    
    This extension modifies EXT_depth_bounds_test.

    This extension modifies NV_copy_depth_to_color.

    This extension is written against the OpenGL 2.0 specification.

Overview

    This extension provides new texture internal formats whose depth
    components are stored as 32-bit floating-point values, rather than the
    normalized unsigned integers used in existing depth formats.
    Floating-point depth textures support all the functionality supported for
    fixed-point depth textures, including shadow mapping and rendering support
    via EXT_framebuffer_object.  Floating-point depth textures can store
    values outside the range [0,1].

    Additionally, this extension provides new packed depth/stencil pixel
    formats (see EXT_packed_depth_stencil) that have 64-bit pixels consisting
    of a 32-bit floating-point depth value, 8 bits of stencil, and 24 unused
    bites.  A packed depth/stencil texture internal format is also provided.

    This extension does not provide support for WGL or GLX pixel formats with
    floating-point depth buffers.  The existing (but not commonly used)
    WGL_EXT_depth_float extension could be used for this purpose.


New Procedures and Functions

    None

New Tokens

    Accepted by the <internalformat> parameter of TexImage1D, TexImage2D,
    TexImage3D, CopyTexImage1D, CopyTexImage2D, and RenderbufferStorageEXT,
    and returned in the <data> parameter of GetTexLevelParameter and
    GetRenderbufferParameterivEXT:

        DEPTH_COMPONENT32F                              0x8CAC
        DEPTH32F_STENCIL8                               0x8CAD

    Accepted by the <type> parameter of DrawPixels, ReadPixels, TexImage1D,
    TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, TexSubImage3D, and
    GetTexImage:

        FLOAT_32_UNSIGNED_INT_24_8_REV                  0x8DAD

Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation)

    Modify Section 2.11.1 (Controling the Viewport), p. 41

    (modify second paragraph) The factor and offset applied to z_d 
    encoded by n and f are set using

        void DepthRange(clampd n, clampd f);
    
    z_w is represented as either fixed-point or floating-point
    depending on whether the framebuffer's depth buffer uses
    fixed-point or floating-point representation.  If the depth buffer
    uses fixed-point representation, we assume that the representation
    used represents each value k/(2^m - 1), where k is in 
    {0,1,...,2^m-1}, as k (e.g. 1.0 is represented in binary as a 
    string of all ones).  The parameters n and f are clamped to [0, 1]
    when using DepthRange.  When n  and f are applied to z_d, they are
    clamped to the range appropriate given the depth buffer's representation.

Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization)

    Modify Section 3.5.5 (Depth Offset), p. 112    

    (modify third paragraph) The minimum resolvable difference r is 
    an implementation dependent parameter that depends on the depth 
    buffer representation.  It is the smallest difference in window 
    coordinate z values that is guaranteed to remain distinct 
    throughout polygon rasterization and in the depth buffer.  All 
    pairs of fragments generated by the rasterization of two polygons 
    with otherwise identical vertices, but z_w values that differ by r,
    will have distinct depth values.

    For fixed-point depth buffer representations, r is constant
    throughout the range of the entire depth buffer.  For
    floating-point depth buffers, there is no single minimum resolvable
    difference.  In this case, the minimum resolvable difference for a 
    given polygon is dependent on the maximum exponent, e, in the range
    of z values spanned by the primitive.  If n is the number of bits 
    in the floating-point mantissa, the minimum resolvable difference, 
    r, for the given primitive is defined as

        r = 2^(e - n).                                       (3.11)

    (modify fourth paragraph) The offset value o for a polygon is

        o = m * factor + r * units.                          (3.12)

    m is computed as described above.  If the depth buffer uses a
    fixed-point representation, m is a function of depth values in the
    range [0, 1], and o is applied to depth values in the same range.
    
    (modify last paragraph) For fixed-point depth buffers, fragment 
    depth values are always limited to the range [0, 1], either by 
    clamping after offset addition is performed (preferred), or by 
    clamping the vertex values used in the rasterization of the 
    polygons.  Fragment depth values are clamped when the depth
    buffer uses a floating-point representation.


    Add a row to table 3.5, p. 128

    type Parameter                       GL Type    Special
    ------------------------------       -------    -------
    ...                                  ...        ...    
    FLOAT_32_UNSIGNED_INT_24_8_REV       N/A        Yes
    ...                                  ...        ...


    Modify Section 3.6.4 (Rasterization of Pixel Rectangles), p. 128

    (modify second paragraph as updated by EXT_packed_depth_stencil)
    ... If the GL is in color index mode and <format> is not one of
    COLOR_INDEX, STENCIL_INDEX, DEPTH_COMPONENT, or DEPTH_STENCIL_EXT,
    then the error INVALID_OPERATION occurs.  If <type> is BITMAP and
    <format> is not COLOR_INDEX or STENCIL_INDEX then the error
    INVALID_ENUM occurs.  If <format> is DEPTH_STENCIL_EXT and <type>
    is not UNSIGNED_INT_24_8_EXT or FLOAT_32_UNSIGNED_INT_24_8_REV,
    then the error INVALID_ENUM occurs.  Some additional constraints 
    on the combinations of <format> and <type> values that are accepted
    are discussed below.

    (modify fifth paragraph of "Unpacking," p 130. as updated by
    EXT_packed_depth_stencil) Calling DrawPixels with a <type> of
    UNSIGNED_BYTE_3_3_2, ..., UNSIGNED_INT_2_10_10_10_REV, or 
    UNSIGNED_INT_24_8_EXT is a special case in which all the components 
    of each group are packed into a single unsigned byte, unsigned 
    short, or unsigned int, depending on the type.  If <type> is 
    FLOAT_32_UNSIGNED_INT_24_8_REV, the components of each group
    are two 32-bit words.  The first word contains the float component.
    The second word contains packed 24-bit and 8-bit components.


    Add two rows to table 3.8, p. 132

    type Parameter                       GL Type  Components  Pixel Formats
    ------------------------------       -------  ----------  -------------
    ...                                  ...      ...         ...        
    FLOAT_32_UNSIGNED_INT_24_8_REV       N/A      2           DEPTH_STENCIL_EXT
    ...                                  ...      ...         ...


    Add a row to table 3.11, p. 134

    FLOAT_32_UNSIGNED_INT_24_8_REV:

       31 30 29 28 ... 4 3 2 1 0    31 30 29 ... 9 8 7 6 5 ... 2 1 0
      +-------------------------+  +--------------------------------+
      |    Float Component      |  | 2nd Component  | 1st Component | 
      +-------------------------+  +--------------------------------+
    

    (modify last paragraph of "Final Conversion," p. 136) For a depth 
    component, an element is processed according to the depth buffer's 
    representation.  For fixed-point depth buffers, the element is first
    clamped to [0, 1] and then converted to fixed-point as if it were a
    window z value (see section 2.11.1, Controling the Viewport).  
    Conversion is not necessary when the depth buffer uses
    a floating-point representation, but clamping is.


    Modify Section 3.8.1 (Texture Image Specification), p. 150

    (modify the second paragraph, p. 151, as modified by 
    ARB_color_buffer_float) The selected groups are processed exactly 
    as for DrawPixels, stopping just before final conversion.  Each R,
    G, B, A, or depth value so generated is clamped based on the 
    component type in the <internalFormat>.  Fixed-point and Floating-point
    components are clamped to [0, 1].
    32-bit floating-point components are in the standard IEEE float format.
    16-bit floating-point components have 1 sign bit, 5 exponent bits,
    and 10 mantissa bits.  Stencil index values are masked by 2^n-1 
    where n is the number of stencil bits in the internal format 
    resolution (see below).  If the base internal format is 
    DEPTH_STENCIL_EXT and <format> is not DEPTH_STENCIL_EXT, then the
    values of the stencil index texture components are undefined.


    Add two rows to table 3.16, p. 154

    Sized                   Base               R    G    B    A    L    I    D    S
    Internal Format         InternalFormat    bits bits bits bits bits bits bits bits
    ------------------      ----------------- ---- ---- ---- ---- ---- ---- ---- ----
    ...                     ...               ...  ...  ...  ...  ...  ...  ...  ...
    DEPTH_COMPONENT32F      DEPTH_COMPONENT                                 f32
    DEPTH32F_STENCIL8       DEPTH_STENCIL_EXT                               f32  8
    ...                     ...               ...  ...  ...  ...  ...  ...  ...  ...


    Modify Section 3.8.14 (Texture Comparison Modes), p. 185

    (modify second paragraph of "Depth Texture Comparison Mode," p.
    188)

    Let D_t be the depth texture value, and R be the interpolated
    texture coordinate. If the texture's internal format indicates a
    fixed-point depth texture, then D_t and R are clamped to [0, 1];
    otherwise no clamping is performed. The effective texture value L_t,
    I_t, or A_t is computed as follows:


    Modify Section 3.11.2 (Shader Execution), p. 194

    (modify first paragraph of "Shader Outputs," p, 196, as modified by
    ARB_color_buffer_float) The OpenGL Shading Language specification 
    describes the values that may be output by a fragment shader.  
    These are gl_FragColor, gl_FragData[n], and gl_FragDepth.  If 
    fragment clamping is enabled, the final fragment color values or 
    the final fragment data values written by a fragment shader are 
    clamped to the range [0, 1] and then may be converted to 
    fixed-point as described in section 2.14.9.  If fragment clamping
    is disabled, the final fragment color values or the final fragment
    data values are not modified.  For fixed-point depth buffers the 
    final fragment depth written by a fragment shader is first clamped
    to [0, 1] and then converted to fixed-point as if it were a window
    z value (see section 2.11.1).  Conversion is not applied for floating-point
    depth buffers.  Note that the depth range computation is not applied here.


Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment
Operations and the Frame Buffer)


    (modify third paragraph in the introduction, p. 198, as modified by
    ARB_color_buffer_float) Color buffers consist of either unsigned 
    integer color indices, R, G, B and optionally A unsigned integer 
    values, or R, G, B, and optionally A floating-point values.  Depth
    buffers consist of either unsigned integer values of the format 
    described in section 2.11.1, or floating-point values.  The number
    of bitplanes...    


    Modify Section 4.2.3 (Clearing the Buffers), p. 215

    (modify fourth paragraph)

    The functions

        void ClearDepth(clampd d);

    are used to set the depth value used when clearing the depth buffer.
    ClearDepth takes a floating-point value that is clamped to the range
    [0, 1].  When clearing a fixed-point depth buffer, the depth clear
    value is clamped to the range [0, 1], and converted to fixed-point
    according to the rules for a window z value given in section 2.11.1.
    No conversion are applied when clearing a floating-point
    depth buffer.

    Modify Section 4.3.1 (Writing to the Stencil Buffer), p. 218

    (modify paragraph added by EXT_packed_depth_stencil, p. 219)
    If the <format> is DEPTH_STENCIL_EXT, then values are taken from
    both the depth buffer and the stencil buffer.  If there is no depth
    buffer or if there is no stencil buffer, then the error
    INVALID_OPERATION occurs.  If the <type> parameter is not
    UNSIGNED_INT_24_8_EXT, or FLOAT_32_UNSIGNED_INT_24_8_REV then
    the error INVALID_ENUM occurs.


    Modify Section 4.3.2 (Reading Pixels), p. 219

    (modify "Conversion of Depth values," p. 222, as modified by 
    EXT_packed_depth_stencil) This step only applies if <format> is
    DEPTH_COMPONENT or  DEPTH_STENCIL_EXT and the depth buffer uses a
    fixed-point representation.  An element taken from the depth buffer
    is taken to be a fixed-point value in [0, 1] with m bits, where
    m is the number of bits in the depth buffer (see section 2.11.1).
    No conversion is necessary if <format> is DEPTH_COMPONENT or 
    DEPTH_STENCIL_EXT and the depth buffer uses a floating-point 
    representation.


    Add a row to table 4.6, p. 223

      type Parameter                      Index Mask
      ------------------------------      ----------
      ...                                 ...      
      FLOAT_32_UNSIGNED_INT_24_8_REV      2^8-1


    Add a row to table 4.7, p. 224

    type Parameter                       GL Type  Component Conversion
    ------------------------------       -------  --------------------
    ...                                  ...      ...
    FLOAT_32_UNSIGNED_INT_24_8_REV       float    c = f (depth only)


Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions)

    None.


Additions to Chapter 6 of the OpenGL 2.0 Specification (State and
State Requests)

    Modify DEPTH_RANGE entry in table 6.9 (Transformation State) p. 270

                                 Init
    Get Value   Type Get Command Value Description            Sec.   Attribute
    ----------- ---- ----------- ----- ---------------------- ------ ---------
    DEPTH_RANGE 2xR  GetFloatv   0,1   Depth range near & far 2.11.1 viewport


    Modify DEPTH_BOUNDS_EXT entry in table 6.19 (Pixel Operation) p. 280

                                      Init
    Get Value        Type Get Command Value Description              Sec   Attribute
    --------------------- ----------- ----- ------------------------ ----- ------------
    DEPTH_BOUNDS_EXT 2xR  GetFloatv   0,1   Depth bounds zmin & zmax 4.1.X depth-buffer


    Modify DEPTH_CLEAR_VALUE entry in table 6.21 (Framebuffer Control) p. 280

                                       Init
    Get Value         Type Get Command Value Description              Sec   Attribute
    ----------------- ---- ----------- ----  ------------------------ ----- ------------
    DEPTH_CLEAR_VALUE  R   GetFloatv    1    Depth buffer clear value 4.2.3 depth-buffer


Additions to Appendix A of the OpenGL 2.0 Specification (Invariance)

    None.

Additions to the AGL/GLX/WGL Specifications

    None.

GLX Protocol

    None.

Dependencies on EXT_depth_bounds_test:

    Modify the definition of DepthBoundsEXT in section 4.1.x Depth
    Bounds Test.

    Modify section 4.1.x (Depth Bounds Test)

    (modify first paragraph) ...These values are set with

        void DepthBoundsEXT(clampd zmin, clampd zmax);

    The paramerters to DepthBoundsEXT are clamped to the range [0, 1].
    Each of zmin and zmax are subject to clamping to the range of the depth
    buffer at the time the depth bounds test is applied.  For 
    fixed-point depth buffers, the applied zmin and zmax are clamped to
    [0, 1].  For floating-point depth buffers, the applied zmin and 
    zmax are clamped to [0, 1]. If zmin <= Zpixel <= zmax, then the depth
    bounds test passes.  Otherwise, the test fails and the fragment is
    discarded.  The test is enabled or disabled using Enable or Disable 
    using the constant DEPTH_BOUNDS_TEST_EXT.  When disabled, it is as 
    if the depth bounds test always passes.  If zmin is greater than 
    zmax, then the error INVALID_VALUE is generated.  The state 
    required consists of two floating-point values and a bit indicating
    whether the test is enabled or disabled.  In the initial state, 
    zmin and zmax are set to 0.0 and 1.0 respectively; and the depth 
    bounds test is disabled.

Errors

    Modify the following error in the EXT_packed_depth_stencil
    specification by adding mention of 
    FLOAT_32_UNSIGNED_INT_24_8_REV:

    The error INVALID_ENUM is generated if DrawPixels or ReadPixels is
    called where format is DEPTH_STENCIL_EXT and type is not
    UNSIGNED_INT_24_8_EXT, or FLOAT_32_UNSIGNED_INT_24_8_REV.


    Modify the following error in the EXT_packed_depth_stencil
    specification by adding mention of 
    FLOAT_32_UNSIGNED_INT_24_8_REV:

    The error INVALID_OPERATION is generated if DrawPixels or 
    ReadPixels is called where type is UNSIGNED_INT_24_8_EXT, 
    or FLOAT_32_UNSIGNED_INT_24_8_REV and format is not
    DEPTH_STENCIL_EXT.


    Add the following error to the NV_copy_depth_to_color
    specification:

    The error INVALID_OPERATION is generated if CopyPixels is called
    where type is DEPTH_STENCIL_TO_RGBA_EXT or DEPTH_STENCL_TO_BGRA_EXT
    and the depth buffer uses a floating point representation.

New State

    None.

Issues

    1.  Should this extension expose floating-point depth buffers through
        WGL/GLX "pixel formats?"

        RESOLVED:  No.  The WGL_EXT_depth_float extension already provides a
        mechanism for requesting a floating-point depth buffer.

    2.  How does an application access the full range of a floating-point
        depth buffer?

        RESOLVED:  This will be a different extension

    3.  Should we add a new state query to determine if the depth buffer is
        using a floating-point representation?

        RESOLVED: No. The old EXT version of this extension had
        DEPTH_BUFFER_FLOAT_MODE_EXT boolean state to see if the depth
        buffer is using a floating-point representation, but in this ARB
        extension we rely on the GetFramebufferAttachmentiv query
        FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE query introduced with
        ARB_framebuffer_object and OpenGL 3.0.


    4.  How does polygon offset work with floating-point depth buffers?

        RESOLVED:  The third paragraph of section 3.5.5 (Depth Offset)
        describes the minimum resolvable difference r as "the smallest
        difference in window coordinate z values that is guaranteed to remain
        distinct throughout polygon rasterization and in the depth buffer."
        The polygon offset value o is computed as a function of r.  The
        minimum resolvable difference r makes sense for fixed-point depth
        values, and even floating-point depth values in the range [-1, 1].
        For unclamped floating-point depth values, there is no constant
        minimum resolvable difference -- the minimum difference necessary to
        change the mantissa of a floating-point value by one bit depends on
        the exponent of the value being offset.  To remedy this problem, the
        minimum resolvable difference is defined to be relative to the range
        of depth values for the given primitive when the depth buffer is
        floating-point.

    5. How does NV_copy_depth_to_color work with floating-point depth values?

        RESOLVED:  It isn't clear that there is any usefulness to copying the
        data for 32-bit floating-point depth values to a fixed-point color
        buffer.  It is even less clear how copying packed data from a
        FLOAT_32_UNSIGNED_24_8_REV depth/stencil buffer to a fixed-point color
        buffer would be useful or even how it should be implemented.  An error
        should be generated if CopyPixels is called where <type> is
        DEPTH_STENCIL_TO_RGBA_EXT or DEPTH_STENCIL_TO_BGRA and the depth buffer
        uses a floating-point representation.

    6. Other OpenGL hardware implementations may be capable of supporting
       floating-point depth buffers.  Why is this an NV extension?

        RESOLVED:  When rendering to floating-point depth buffers, we expect
        that other implementations may only be capable of supporting Z values
        in the range [0,1].  For such implementations, floating-point Z
        buffers do not improve the range of Z values supported, but do offer
        increased precision than conventional 24-bit fixed-point Z buffers,
        particularly around zero.

        This extension was initially proposed as an EXT, but we have changed
        it to an NV extension in the expectation that an EXT may be offered at
        some point in the not-too-distant future.  We expect that the EXT
        could be supported by a larger range of vendors.  NVIDIA would
        continue to support both extensions, where the NV extension could be
        thought of as taking the capability of the EXT version and extending
        it to support Z values outside the range [0,1].

    7. Why don't the new tokens and entry points in this extension have
       "ARB" suffixes like other ARB extensions?

        RESOLVED: Unlike most ARB extensions, this is a strict subset of
        functionality already approved in OpenGL 3.0. This extension
        exists only to support that functionality on older hardware that
        cannot implement a full OpenGL 3.0 driver. Since there are no
        possible behavior changes between the ARB extension and core
        features, source code compatibility is improved by not using
        suffixes on the extension.

Revision History

    Rev.    Date    Author    Changes
    ----  --------  --------  -----------------------------------------
     7    10/18/12  Jon Leech Restrict [0,1] clamp of D_t and R to
                              only occur for fixed-point depth textures,
                              matching actual driver behavior and the
                              original intent of NV_depth_buffer_float
                              (Bug 7975).

     6    08/08/08  Jon Leech Remove DEPTH_BUFFER_FLOAT_MODE query,
                              update issue 3 accordingly, and
                              change dependency from EXT to
                              ARB_framebuffer_object / GL 3.0.

     5    08/07/08  Jon Leech Remove ARB suffixes.

     4    08/06/08  Jon Leech Fix missing _REV in some token names.

     3    07/11/08  Jon Leech Change NV enum values due to incompatible
                              clamping behavior.

     2    06/30/08  jsandmel  Trivial conversion to ARB_depth_buffer_float
     
     1    06/05/08  pboudier  Forked from NV_depth_buffer_float. Restore
                              clamping to [0,1] and remove 'd' entry
                              points. Change suffix from NV to EXT.