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

Name

    ARB_depth_clamp

Name Strings

    GL_ARB_depth_clamp

Contact

    Jon Leech (jon 'at' alumni.caltech.edu)
    Mark J. Kilgard, NVIDIA Corporation (mjk 'at' nvidia.com)

Notice

    Copyright (c) 2009-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

    Complete. Approved by the ARB on July 3, 2009.

Version

    Version 3, 2009/08/02.
    Based on NV_depth_clamp version 4, modified 2003/01/08.

Number

    ARB Extension #61

Dependencies

    Written based on the wording of the OpenGL 3.1 specification.

    ARB_compatibility affects the behavior of this extension.

Overview

    Conventional OpenGL clips geometric primitives to a clip volume
    with six faces, two of which are the near and far clip planes.
    Clipping to the near and far planes of the clip volume ensures that
    interpolated depth values (after the depth range transform) must be
    in the [0,1] range.

    In some rendering applications such as shadow volumes, it is useful
    to allow line and polygon primitives to be rasterized without
    clipping the primitive to the near or far clip volume planes (side
    clip volume planes clip normally).  Without the near and far clip
    planes, rasterization (pixel coverage determination) in X and Y
    can proceed normally if we ignore the near and far clip planes.
    The one major issue is that fragments of a  primitive may extend
    beyond the conventional window space depth range for depth values
    (typically the range [0,1]).  Rather than discarding fragments that
    defy the window space depth range (effectively what near and far
    plane clipping accomplish), the depth values can be clamped to the
    current depth range.

    This extension provides exactly such functionality.  This
    functionality is useful to obviate the need for near plane capping
    of stenciled shadow volumes.  The functionality may also be useful
    for rendering geometry "beyond" the far plane if an alternative
    algorithm (rather than depth testing) for hidden surface removal is
    applied to such geometry (specifically, the painter's algorithm).
    Similar situations at the near clip plane can be avoided at the
    near clip plane where apparently solid objects can be "seen through"
    if they intersect the near clip plane.

Issues

    Another way to specify this functionality is to describe it in terms
    of generating the equivalent capping geometry that would need to be
    drawn at the near or far clip plane to have the same effect as not
    clipping to the near and far clip planes and clamping interpolated
    depth values outside the window-space depth range.  Should the
    functionality be described this way?

      RESOLUTION:  No.  Describing the functionality as capping is
      fairly involved.  Eliminating far and near plane clipping and
      clamping interpolated depth values to the depth range is much
      simpler to specify.

    Should depth clamping affect points or just line and polygon geometric
    primitives?

      RESOLUTION:  All geometric primitives are affected by depth
      clamping.

      In the case of points, if you render a point "in front of" the
      near clip plane, it should be rendered with the zw value min(n,f)
      where n and f are the near and far depth range values if depth
      clamping is enabled.  Similarly, a point "behind" the far clip
      plane should be rendered with the zw value max(n,f).

    How should the setting of the raster position function when depth
    clamping is enabled?

      RESOLUTION:  When setting the raster position, clamp the raster
      position zw to the range [min(n,f),max(n,f)] where n and f are
      the near and far depth range values.

      This rule ensures that the raster position zw will never be outside
      the [0,1] range (because n and far are clamped to the [0,1] range).
      We specify the raster position to be updated this way because
      otherwise a raster position zw could be specified outside the [0,1]
      range when depth clamping is enabled, but then if depth clamping
      is subsequently disabled, that out-of-range raster position zw
      could not be written to the depth buffer.

      This semantic can make for some unexpected semantics that are
      described here.  Say that depth clamping is enabled and the raster
      position is set to point behind the far clip plane such that the
      pre-clamped zw is 2.5.  Because depth clamping is enabled the
      raster position zw is clamped to the current near and far depth
      range values.  Say these values are 0.1 and 0.9.  So 2.5 is clamped
      to 0.9.

      Now consider what happens if a bitmap (or image rectangle) is
      rendered with depth testing enabled under various situations.
      If depth clamping remains enabled and the depth range is unchanged,
      the bitmap fragments are generated with a zw of 0.9.

      However, if depth range is subsequently set to 0.2 and 0.8 and
      depth clamping is enabled, the bitmap fragments will have their
      zw depth component clamped to 0.8.  But if the depth range was
      changed to 0.2 and 0.8 but depth range clamped is disabled, the
      bitmap fragments will have a 0.9 zw depth component since then
      the depth clamping is then not applied.

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

      RESOLUTION:  GL_ENABLE_BIT and GL_TRANSFORM_BIT.

    How does depth clamping interact with depth replace operations (say
    from NV_texture_shader)?

      RESOLUTION:  The depth clamp operation occurs as part of the depth
      test so depth clamping occurs AFTER any depth replace operation
      in the pipeline.  A depth replace operation can reassign the
      fragment's zw, but depth clamping if enabled will subsequently
      clamp this new zw.

    Does depth clamping affect read/draw/copy pixels operations involving
    depth component pixels?

      RESOLUTION:  No.

    Does depth clamping occur after polygon offset?

      RESOLUTION:  Yes.  Depth clamping occurs immediately before the
      depth test.

    Can fragments with wc<=0 be generated when this extension is supported?

      RESOLUTION: No. The OpenGL Specification was revised in 2006/08 to
      remove explicit references to w_c <= 0, since the clip volume test
      disallows all such vertices. Corresponding language has been
      removed from this extension specification as well. Such fragments
      should never be generated.

New Procedures and Functions

    None

New Tokens

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

        DEPTH_CLAMP                                   0x864F

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

 --  Section 2.17 "Clipping"

    Add to the end of the 3rd paragraph:

    "Depth clamping is enabled with the generic Enable command and
    disabled with the Disable command. The value of the argument to
    either command is DEPTH_CLAMP. If depth clamping is enabled, the
    "-w_c <= z_c <= w_c" plane equation are ignored by view volume
    clipping (effectively, there is no near or far plane clipping)."


    If and only if the ARB_compatibility extension is supported:

 --  Section 2.22 "Current Raster Position"

    Add to the end of the 4th paragraph:

    "If depth clamping (see section 2.11) is enabled, then raster
    position z_w is first clamped to the range [min(n,f),max(n,f)],
    where n and f are the current near and far depth range values (see
    section 2.12.1)."

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

    None

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

 --  Section 4.1.5 "Depth buffer test"

    Add to the end of the 2nd paragraph:

    "If depth clamping (see section 2.17) is enabled, before the
    incoming fragment's z_w is compared z_w is clamped to the range
    [min(n,f),max(n,f)], where n and f are the current near and far
    depth range values (see section 2.12.1)."

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

    None

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

    None

Additions to the AGL/GLX/WGL Specifications

    None

GLX Protocol

    None

Errors

    None

New State

Add to table 6.7, transformation state

Get Value       Type  Get Command  Initial Value  Description     Sec      Attribute
--------------  ----  -----------  -------------  --------------  ------   ----------------
DEPTH_CLAMP     B     IsEnabled    False          Depth clamping  2.12.2   transform/enable
                                                  on/off

New Implementation Dependent State

    None

Interactions with ARB_compatibility

    If ARB_compatibility is not supported, the language about current
    raster position in section 2.22 is removed.

Revision History

    Version 1, 2009/05/14 (Jon Leech) - rewrite NV_depth_clamp against
    OpenGL 3.1 instead of OpenGL 1.2.1. Clarify which functionality only
    applies to GL 3.1 + ARB_compatibility. Remove NV suffix and assign
    ARB extension string in preparation for inclusion in OpenGL 3.2.

    Version 2, 2009/05/15 (Jon Leech) - Note interaction with
    ARB_compatibility.

    Version 3, 2009/07/01 (Jon Leech) - Match core 3.2 spec updates,
    removing w_c <= 0 language. Update corresponding issue to note this
    was done to the core spec in 2006/08.

    Version 4, 2009/08/02 (Jon Leech) - Assign ARB extension number.