xref: /third_party/openGLES/extensions/EXT/EXT_stencil_wrap.txt

Name

    EXT_stencil_wrap

Name Strings

    GL_EXT_stencil_wrap

Contact

    Dale Kirkland, NVIDIA (dkirkland 'at' nvidia.com)

Status

    Shipping

Version

    Date: 4/4/2002  Version 1.2

Number

    176

Dependencies

    None

Overview

    Various algorithms use the stencil buffer to "count" the number of
    surfaces that a ray passes through.  As the ray passes into an object,
    the stencil buffer is incremented.  As the ray passes out of an object,
    the stencil buffer is decremented.

    GL requires that the stencil increment operation clamps to its maximum
    value.  For algorithms that depend on the difference between the sum
    of the increments and the sum of the decrements, clamping causes an
    erroneous result.

    This extension provides an enable for both maximum and minimum wrapping
    of stencil values.  Instead, the stencil value wraps in both directions.

    Two additional stencil operations are specified.  These new operations
    are similiar to the existing INCR and DECR operations, but they wrap
    their result instead of saturating it.  This functionality matches
    the new stencil operations introduced by DirectX 6.

New Procedures and Functions

    None

New Tokens

    Accepted by the <sfail>, <dpfail>, and <dppass> parameter of
    StencilOp:

        INCR_WRAP_EXT             0x8507
        DECR_WRAP_EXT             0x8508

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

    None

Additions to Chapter 3 of the GL Specification (Rasterization)

    None

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

    Section 4.1.4 "Stencil Test" (page 144), change the 3rd paragraph to read:

    "...  The symbolic constants are KEEP, ZERO, REPLACE, INCR, DECR,
    INVERT, INCR_WRAP_EXT, and DECR_WRAP_EXT.  The correspond to
    keeping the current value, setting it to zero, replacing it with
    the reference value, incrementing it with saturation, decrementing
    it with saturation, bitwise inverting it, incrementing it without
    saturation, and decrementing it without saturation.  For purposes of
    incrementing and decrementing, the stencil bits are considered as an
    unsigned integer.  Incrementing or decrementing with saturation will
    clamp values at 0 and the maximum representable value.  Incrementing
    or decrementing without saturation will wrap such that incrementing
    the maximum representable value results in 0 and decrementing 0
    results in the maximum representable value.  ..."

Additions to Chapter 5 of the GL Specification (Special Functions)

    None

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

    None

Additions to the GLX Specification

    None

GLX Protocol

    None

Errors

    INVALID_ENUM is generated by StencilOp if any of its parameters
    are not KEEP, ZERO, REPLACE, INCR, DECR, INVERT, INCR_WRAP_EXT,
    or DECR_WRAP_EXT.

New State

(table 6.15, page 205)
    Get Value                 Type  Get Command   Initial Value   Sec    Attribute
    ------------------------  ----  ------------  -------------   -----  ---------
    STENCIL_FAIL               Z8   GetIntegerv        KEEP       4.1.4  stencil-buffer
    STENCIL_PASS_DEPTH_FAIL    Z8   GetIntegerv        KEEP       4.1.4  stencil-buffer
    STENCIL_PASS_DEPTH_PASS    Z8   GetIntegerv        KEEP       4.1.4  stencil-buffer

NOTE: the only change is that Z6 type changes to Z8

New Implementation Dependent State

    None

Revision History

  * Revision 1.2, April 4, 2002 - correct typo in New Tokens section.
    These are parameters to StencilOp, not BlendEquation.