xref: /third_party/openGLES/extensions/ATI/ATI_separate_stencil.txt

Name

    ATI_separate_stencil

Name Strings

    GL_ATI_separate_stencil

Contact

    Benj Lipchak, AMD (benj.lipchak 'at' amd.com)
    Evan Hart, NVIDIA (ehart 'at' nvidia.com)


IP Status

    None

Version

    Date: 11/04/2006
    Revision: 1.1

Number

    289
    
Dependencies

    This spec is written against the 1.2.1 version of the GL spec.
    This spec requires OpenGL 1.0

Overview

    This extension provides the ability to modify the stencil buffer
    differently based on the facing direction of the primitive that
    generated the fragment.

Issues

    


New Procedure and Functions

    StencilOpSeparateATI( GLenum face, GLenum sfail, GLenum dpfail, GLenum dppass)
    StencilFuncSeparateATI( GLenum frontfunc, GLenum backfunc, GLint ref,
                            GLuint mask)

New Tokens

      
    Accepted by the <fail>, <zfail>, and <zpass> parameters of
    StencilOpSeparateATI:
    
      KEEP                                             0x1E00
      ZERO                                             0x0000
      REPLACE                                          0x1E01
      INCR                                             0x1E02
      DECR                                             0x1E03
      INVERT                                           0x150A

    Accepted by the <frontfunc> and <backfunc> parameters of
    StencilFuncSeparateATI:

      NEVER                                            0x0200
      LESS                                             0x0201
      LEQUAL                                           0x0203
      GREATER                                          0x0204
      GEQUAL                                           0x0206
      EQUAL                                            0x0202
      NOTEQUAL                                         0x0205
      ALWAYS                                           0x0207

    Accepted by the <face> parameter of StencilOpSeparateATI:

      FRONT                                            0x0404
      BACK                                             0x0405
      FRONT_AND_BACK                                   0x0408

    Accepted by the <pname> parameter of GetIntegerv:

      STENCIL_BACK_FUNC_ATI                            0x8800
      STENCIL_BACK_FAIL_ATI                            0x8801
      STENCIL_BACK_PASS_DEPTH_FAIL_ATI                 0x8802
      STENCIL_BACK_PASS_DEPTH_PASS_ATI                 0x8803
   
Additions to Chapter 2 of the OpenGL 1.2.1 Specification (Operation)

    None

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

    Section 3.0

    Change the second paragraph on page 57 to read:

      "A grid square along with its parameters of assigned color, z
      (depth), texture coordinates, and facing direction is called a
      fragment; the parameters are collectively dubbed the fragment's
      associated data. ..."

    New section added after section 3.2

      "Facing Direction

      A fragment derives its facing direction from the primitive that
      generates the fragment. All fragments generated by primitves
      other than polygons, triangles, or quadrilaterals are considered
      to be front facing. For all other fragments the detemination is
      made by examining the sign of the area computed by equation 2.7
      of section 2.13.1 (including the possible reversal of this sign
      as indicated by the last call to FrontFace). If the sign is
      positive then the fragments are front facing; otherwise, they
      are back facing."

Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment Operations)

    Section 4.1.4

    Change the first paragraph of section 4.1.4 to read:

    "The stencil test conditionally discards a fragment based on a
    comparison between the value in the stencil buffer at location
    ( xw, yw) and a reference value. The test is controlled with

      void StencilFunc( enum func, int ref, uint mask);
      void StencilFuncSeparateATI( enum frontfunc, enum backfunc,
                                   int ref, uint mask);
      void StencilOp( enum sfail, enum dpfail, enum dppass);
      void StencilOpSeparateATI( enum face, enum sfail, enum dpfail,
                                 enum dppass);

    The test is enabled or disabled with the Enable and Disable
    commands, using the symbolic constant STENCIL_TEST. When disabled,
    the stencil test and the associated modifications are not made, 
    and the fragment is always passed. Additionally, the stencil test
    may treat front and back faces separately. The function
    StencilFuncSeparateATI sets each independently, while the function
    Stencil func sets both front and back to the same test."

    Change the third paragraph of section 4.1.4 to read:

    "StencilOp and StencilOpSeparateATI take three arguments that indicate
    what happens to the stored stencil value if this or certain
    subsequent tests fail or pass. StencilOp sets the ops for both front
    and back facing fragments, while StencilOpSeparateATI sets the ops for
    front facing, back facing, or both types of fragments based on the face
    parameter.  ..."

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

    None

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

    Additions to Table 6.15 Pixel Operations

                                                         Initial
    Get Value                        Type    Get Cmnd    Value      Description  Sec.   Attribute
    ----------                       ------  ---------   ---------  ------------ -----  -------------
    STENCIL_BACK_FUNC_ATI             Z8     GetIntegerv  ALWAYS                 4.1.4  Stencil-buffer
    STENCIL_BACK_FAIL_ATI             Z6     GetIntegerv  KEEP                   4.1.4  Stencil-buffer
    STENCIL_BACK_PASS_DEPTH_FAIL_ATI  Z6     GetIntegerv  KEEP                   4.1.4  Stencil-buffer
    STENCIL_BACK_PASS_DEPTH_PASS_ATI  Z6     GetIntegerv  KEEP                   4.1.4  Stencil-buffer
    STENCIL_OP_SEPARATE_FACE_ATI      B      IsEnabled    FALSE                  4.1.4  Stencil-buffer