Name

    EXT_depth_bounds_test

Name Strings

    GL_EXT_depth_bounds_test

Contact

    Cass Everitt, NVIDIA Corporation (cass 'at' nvidia.com)
    Mark J. Kilgard, NVIDIA Corporation (mjk 'at' nvidia.com)

Notice

    Copyright NVIDIA Corporation, 2002, 2003.

Status

    Implemented in GeForce FX 5900 (NV35) drivers as of June 2003.

    Also supported by GeForce FX 5700 (NV36) and GeForce6 (NV4x).

Version

    Last Modified Date:  2004/05/17
    NVIDIA Revision:     5

Number

    297

Dependencies

    Written based on the wording of the OpenGL 1.3 specification.

Overview

    This extension adds a new per-fragment test that is, logically,
    after the scissor test and before the alpha test.  The depth bounds
    test compares the depth value stored at the location given by the
    incoming fragment's (xw,yw) coordinates to a user-defined minimum
    and maximum depth value.  If the stored depth value is outside the
    user-defined range (exclusive), the incoming fragment is discarded.

    Unlike the depth test, the depth bounds test has NO dependency on
    the fragment's window-space depth value.

    This functionality is useful in the context of attenuated stenciled
    shadow volume rendering.  To motivate the functionality's utility
    in this context, we first describe how conventional scissor testing
    can be used to optimize shadow volume rendering.

    If an attenuated light source's illumination can be bounded to a
    rectangle in XY window-space, the conventional scissor test can be
    used to discard shadow volume fragments that are guaranteed to be
    outside the light source's window-space XY rectangle.  The stencil
    increments and decrements that would otherwise be generated by these
    scissored fragments are inconsequential because the light source's
    illumination can pre-determined to be fully attenuated outside the
    scissored region.  In other words, the scissor test can be used to
    discard shadow volume fragments rendered outside the scissor, thereby
    improving performance, without affecting the ultimate illumination
    of these pixels with respect to the attenuated light source.

    This scissoring optimization can be used both when rendering
    the stenciled shadow volumes to update stencil (incrementing and
    decrementing the stencil buffer) AND when adding the illumination
    contribution of attenuated light source's.

    In a similar fashion, we can compute the attenuated light source's
    window-space Z bounds (zmin,zmax) of consequential illumination.
    Unless a depth value (in the depth buffer) at a pixel is within
    the range [zmin,zmax], the light source's illumination can be
    pre-determined to be inconsequential for the pixel.  Said another
    way, the pixel being illuminated is either far enough in front of
    or behind the attenuated light source so that the light source's
    illumination for the pixel is fully attenuated.  The depth bounds
    test can perform this test.

Issues

    Where should the depth bounds test take place in the OpenGL
    fragment processing pipeline?

      RESOLUTION:  After scissor test, before alpha test.  In practice,
      this is a logical placement of the test.  An implementation is
      free to perform the test in a manner that is consistent with the
      specified ordering.

      Importantly, the depth bounds test occurs before any fragment
      operation that has a side-effect such as stencil and/or depth buffer
      writes (ie, the stencil or depth test).  This makes it possible
      to discard incoming fragment's without concern for preserving such
      side-effects.

    Is the depth bounds test consistent with early depth rejection?

      Yes.  If an OpenGL implementation supports some conservative bounds
      on depth values in subregions of the depth buffer (hierarchical
      depth buffers, etc), the depth bounds test can reject fragments
      based on these conservative bounds.

    How are the depth bounds specified?

      RESOLUTION:  Normalized window-space depth values.  This means
      the depth values are specified in the range [0.0, 1.0] similar
      to glDepthRange.

    Can the zmin bound be greater than the zmax bound?

      RESOLUTION:  zmin must be less than or equal to zmax or an
      INVALID_VALUE error is generated.

      Another way to interpret this situation is to have zmin>zmax reject
      all fragments where the corresponding pixel's depth value is between
      zmin and zmax.  But this does not seem useful enough to specify.

    What should the glDepthBoundsEXT routine mimic?

      RESOLUTION:  glDepthBoundsEXT should mimic glDepthRange in parameter
      types and clamping, excepting that zmin must be less than zmax.

    Do the depth bounds have anything to do with the depth range?

      RESOLUTION:  No.  These are totally independent pieces of state.
      To reinforce the point, having a depth range and depth bounds with
      no overlap is perfectly well-defined (even if a little odd).

    What push/pop attrib bits should affect the depth bounds test enable?

      RESOLUTION:  GL_ENABLE_BIT and GL_DEPTH_BUFFER_BIT.

    How does depth bounds testing interact with polygon offset
    or depth replace operations (say from ARB_fragment_program,
    NV_texture_shader, or NV_fragment_program)?

      RESOLUTION:  There are NO interactions.  The depth bounds test has
      NO dependency on the incoming fragment's depth value so it doesn't
      matter if there is a polygon offset or depth replace operation.

    Does depth bounds testing affect bitmap/draw/copy pixels operations
    involving depth component pixels?

      RESOLUTION:  Yes, depth bounds testing affects all rasterized
      primitives (just like all other fragment operations).

    How does depth bounds test interact with multisampling?

      RESOLUTION:  The depth bounds test is performed per-sample when
      multisampling is active, just like the depth test.

    At what precision is the depth bounds test carried out?

      RESOLUTION:  For the purposes of the test, the bounds are converted to
      fixed-point as though they were to be written to the depth buffer, and
      the comparison uses those quantized bounds.

    Can you have the depth test disabled and still have the depth bounds
    test enabled?

      RESOLUTION:  Yes.  The two tests operate independently.

    How does the depth bounds test operate if there is no depth buffer?

      RESOLUTION:  It is as if the depth bounds test always passes
      (analogous to the depth test).

New Procedures and Functions

    void DepthBoundsEXT(clampd zmin, clampd zmax);

New Tokens

    Accepted by the <cap> parameter of Enable, Disable, and IsEnabled,
    and by the <pname> parameter of GetBooleanv, GetIntegerv,
    GetFloatv, and GetDoublev:

        DEPTH_BOUNDS_TEST_EXT                       0x8890

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

        DEPTH_BOUNDS_EXT                            0x8891

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

    None

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

    None

Additions to Chapter 4 of the OpenGL 1.3 Specification (Per-Fragment Operations
and the Framebuffer)

 -- Figure 4.1  Per-fragment operations

    Add a block for the "depth bounds test" after the scissor and before
    the alpha test.
    
 -- Section 4.1.X  Depth Bounds Test (following Section 4.1.2 Scissor Test)

    "The depth bounds test determines whether the depth value (Zpixel)
    stored at the location given by the incoming fragment's (xw,yw)
    location lies within the depth bounds range defined by two values.
    These values are set with

        void DepthBoundsEXT(clampd zmin, clampd zmax);

    Each of zmin and zmax are clamped to lie within [0,1] (being of
    type clampd).  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.

    If there is no depth buffer, it is as if the depth bounds test always
    passes."

 -- Section 4.10  Additional Multisample Fragment Operations

    Add depth bounds test to the list of operations affected by
    multisampling.  Amend the 1st and 2nd sentences in the 2nd paragraph
    to read:

    "If MULTISAMPLE is enabled, and the value of SAMPLE_BUFFERS is one,
    the depth bounds test, alpha test, depth test, blending, and dithering
    operations are performed for each pixel sample, rather than just once
    for each fragment.  Failure of the depth bounds, alpha, stencil, or
    depth test results in termination of the processing of the sample,
    rather than discarding of the fragment."

    Amend the 1st sentence in the 3nd paragraph to read:

    "Depth bounds, stencil, depth, blending, and dithering operations
    are performed for a pixel sample only if that sample's fragment
    coverage bit is a value of 1."

    Amend the 3rd sentence in the 4th paragraph to read:

    "An implementation may choose to identify a centermost sample, and
    to perform depth bounds, alpha, stencil, and depth tests on only
    that sample."

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

    None

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

    None

Additions to the AGL/GLX/WGL Specifications

    None

GLX Protocol

    A new GL rendering command is added. The following command is sent to the 
    server as part of a glXRender request:

        DepthBoundsEXT
            2           12              rendering command length
            2           4229            rendering command opcode
            4           FLOAT32         zmin
            4           FLOAT32         zmax

Errors

    If zmin is greater than zmax, then the error INVALID_VALUE is
    generated.

New State

(table 6.15 "Pixel Operation)

Get Value              Type  Get Command  Initial Value  Description   Sec     Attribute
---------------------  ----  -----------  -------------  ------------  -----   -------------------
DEPTH_BOUNDS_TEST_EXT  B     IsEnabled    False          Depth bounds  4.1.X   depth-buffer/enable
                                                        test enable
DEPTH_BOUNDS_EXT       2xR+  GetFloatv    0,1            Depth bounds  4.1.X   depth-buffer
                                                         zmin & zmax

New Implementation Dependent State

    None

Revision History

    NVIDIA exposed a functionally and enumerant identical version of
    this extension under the name NV_depth_bounds_test.  NVIDIA drivers
    after May 2003 support the EXT_depth_bounds_test name only.  

    Mesa and NVIDIA agreed to make this an EXT extension in April 2003.

    8/27/2003 - GLX protocol specification added.