| Name |
| |
| AMD_stencil_operation_extended |
| |
| Name Strings |
| |
| GL_AMD_stencil_operation_extended |
| |
| Contact |
| |
| Graham Sellers, AMD (graham.sellers 'at' amd.com) |
| |
| Status |
| |
| Shipping |
| |
| Version |
| |
| Last Modified Date: 01/11/2012 |
| Author Revision: 4 |
| |
| Number |
| |
| 413 |
| |
| Dependencies |
| |
| OpenGL 1.0 is required. |
| |
| The definition of this extension is affected by EXT_stencil_wrap and |
| OpenGL 2.0. |
| |
| This extension is written against the OpenGL Specification, Version 4.2 |
| (Core Profile). |
| |
| Overview |
| |
| Stencil buffers are special buffers that allow tests to be made against an |
| incoming value and action taken based on that value. The stencil buffer is |
| updated during rasterization, and the operation used to update the stencil |
| buffer is chosen based on whether the fragment passes the stencil test, |
| and if it does, whether it passes the depth test. Traditional OpenGL |
| includes support for several primitive operations, such as incrementing, |
| or clearing the content of the stencil buffer, or replacing it with a |
| specified reference value. |
| |
| This extension adds support for an additional set of operations that may |
| be performed on the stencil buffer under each circumstance. Additionally, |
| this extension separates the value used as the source for stencil |
| operations from the reference value, allowing different values to be used |
| in the stencil test, and in the update of the stencil buffer. |
| |
| IP Status |
| |
| None. |
| |
| New Procedures and Functions |
| |
| void StencilOpValueAMD(enum face, uint value); |
| |
| New Tokens |
| |
| Accepted by the <sfail>, <dpfail> and <dppass> parameters of StencilOp |
| and StencilOpSeparate: |
| |
| SET_AMD 0x874A |
| AND 0x1501 |
| XOR 0x1506 |
| OR 0x1507 |
| NOR 0x1508 |
| EQUIV 0x1509 |
| NAND 0x150E |
| REPLACE_VALUE_AMD 0x874B |
| |
| Accepted by the <param> parameter of GetIntegerv, GetFloatv, GetBooleanv |
| GetDoublev and GetInteger64v: |
| |
| STENCIL_OP_VALUE_AMD 0x874C |
| STENCIL_BACK_OP_VALUE_AMD 0x874D |
| |
| Additions to Chapter 2 of the OpenGL 4.2 (Core Profile) Specification |
| (OpenGL Operation) |
| |
| None. |
| |
| Additions to Chapter 3 of the OpenGL 4.2 (Core Profile) Specification |
| (Rasterization) |
| |
| None. |
| |
| Additions to Chapter 4 of the OpenGL 4.2 (Core Profile) Specification |
| (Per-Fragment Operations and the Framebuffer) |
| |
| Add to the functions introduced in Section 4.1.4 "Stencil Test", p.287 |
| |
| The stencil test is controlled with |
| |
| <leave existing functions in place> |
| void StencilOpValueAMD(enum face, uint value); |
| |
| Modify the paragraph beginning "StencilFuncSeparate and StencilOpSeparate |
| take a <face> argument...", p.288 |
| |
| StencilFuncSeparate, StencilOpSeparate and StencilOpValue take a |
| <face> argument which can be FRONT, BACK or FRONT_AND_BACK and indicates |
| which set of state is affected. |
| |
| Replace the second and third paragraphs on p.288, describing StencilOp and |
| StencilOpSeparate with the following three paragraphs: |
| |
| StencilOp and StencilOpSeparate take three arguments that indicate what |
| happens to the stored stencil value if this or certain subsequent tests fail |
| or pass. sfail indicates what action is taken if the stencil test fails. |
| The inputs to the stencil operation are the stencil reference value, the |
| stencil operation source value, and the current content of the stencil |
| buffer. The accepted symbolic constants are KEEP, ZERO, SET_AMD, REPLACE, |
| REPLACE_VALUE_AMD, INCR, DECR, INVERT, INCR_WRAP, DECR_WRAP, AND, XOR, OR, |
| NOR, EQUIV, and NAND. These correspond to keeping the current value, setting |
| to zero, setting to the maximum representable value, replacing with the |
| reference value, replacing with the operation source value, incrementing by |
| the operation source value with saturation, decrementing by the operation |
| source value with saturation, bitwise inverting it, incrementing by the |
| operation source value without saturation, decrementing by the operation |
| source value without saturation, logically ANDing the operation source |
| value value with it, logically XORing the operation source value value with |
| it, logically ORing the operation source value with it, logically NORing |
| the operation source value with it, logically XORing the operation source |
| value with it and replacing the it with the logically inverted result of |
| that computation, and logically NANDing the operation source value with it, |
| respectively. |
| |
| For purposes of increment, decrement, the stencil bits are considered |
| as an unsigned integer. Incrementing or decrementing with saturation clamps |
| the stencil value between 0 and the maximum representable value. |
| Incrementing without saturation will wrap such that incrementing the |
| content of the stencil buffer in such a way that overflow occurs will cause |
| the result of the operation to be masked by the number of bits representable |
| by the stencil buffer. Decrementing without saturation will wrap such that |
| decrementing the content of the stencil buffer in a manner such that the |
| result of the subtraction would be negative causes the two's complement |
| result to be interpreted as an unsigned integer and masked to the number of |
| bits representable by the stencil buffer. |
| |
| The stencil operation source value is set by calling StencilOpValueAMD |
| with <face> set to GL_FRONT, GL_BACK or GL_FRONT_AND_BACK, and <value> set |
| to the new value of the stencil operation source value. |
| |
| Modify the paragraph beginning "If the stencil test fails, the ... ", p.288 |
| as follows: |
| |
| If the stencil test fails, the incoming fragment is discarded. The state |
| required consists of the most recent values passed to StencilFunc or |
| StencilFuncSeparate, to StencilOp or StencilOpSeparate, and to |
| StencilOpValueAMD, and a bit indicating whether stencil testing is enabled |
| or disabled. In the initial state, stenciling is disabled, the front and |
| back reference values are both zero, the front and back stencil comparison |
| functions are both ALWAYS, the front and back stencil mask are both set to |
| the value 2^S - 1, where S is greater than or equal to the number of bits |
| in the deepest buffer supported by the GL implementation, and the front |
| and back stencil operation values are both 1. Initially, all three front |
| and back stencil operations are KEEP. |
| |
| Additions to Chapter 5 of the OpenGL 4.2 (Core Profile) Specification |
| (Special Functions) |
| |
| None. |
| |
| Additions to Chapter 6 of the OpenGL 4.2 (Core Profile) Specification |
| (State and State Requests) |
| |
| None. |
| |
| Additions to the AGL/GLX/WGL Specifications |
| |
| None. |
| |
| GLX Protocol |
| |
| None. |
| |
| Errors |
| |
| INVALID_ENUM is generated by StencilOpValueAMD if <face> is not FRONT, |
| BACK or FRONT_AND_BACK. |
| |
| New State |
| |
| Modify Table 6.20 "Pixel Operations", p.394: |
| |
| +--------------------------------+----------+---------------+-----------+-------------------------------------------+--------+ |
| | | | Get | Initial | | | |
| | Get Value | Type | Command | Value | Description | Sec. | |
| +--------------------------------+----------+---------------+-----------+-------------------------------------------+--------+ |
| | STENCIL_FAIL | Z16 | GetIntegerv | KEEP | Front stencil fail action | 4.1.4 | |
| | STENCIL_PASS_DEPTH_FAIL | Z16 | GetIntegerv | KEEP | Front stencil depth buffer fail action | 4.1.4 | |
| | STENCIL_PASS_DEPTH_PASS | Z16 | GetIntegerv | KEEP | Front stencil depth buffer pass action | 4.1.4 | |
| | STENCIL_BACK_FAIL | Z16 | GetIntegerv | KEEP | Back stencil fail action | 4.1.4 | |
| | STENCIL_BACK_PASS_DEPTH_FAIL | Z16 | GetIntegerv | KEEP | Back stencil depth buffer fail action | 4.1.4 | |
| | STENCIL_BACK_PASS_DEPTH_PASS | Z16 | GetIntegerv | KEEP | Back stencil depth buffer pass action | 4.1.4 | |
| | STENCIL_OP_VALUE_AMD | Z+ | GetIntegerv | 1 | Front stencil operation value | 4.1.4 | |
| | STENCIL_BACK_OP_VALUE_AMD | Z+ | GetIngeterv | 1 | Back stencil operation value | 4.1.4 | |
| +--------------------------------+----------+---------------+-----------+-------------------------------------------+--------+ |
| |
| NOTE: The existing STENCIL{_BACK}_{*} enumerants change have changed from Z8 to Z16. |
| |
| Dependencies on EXT_stencil_wrap |
| |
| If EXT_stencil_wrap is not supported, remove references to INCR_WRAP and |
| DECR_WRAP. Also, change the definition of the STENCIL_{*} state to Z14 |
| rather than Z16. |
| |
| Dependencies on OpenGL 2.0 |
| |
| If the GL version is less than 2.0, remove all references to |
| StencilOpSeparate. Furthermore, the <face> parameter to StencilOpValueAMD |
| must be FRONT_AND_BACK, otherwise an INVALID_ENUM error will be generated. |
| |
| Issues |
| |
| 1) Is the stencil mask applied to the stencil operation value? |
| |
| RESOLVED: No, only to the reference and current values before the test. |
| The stencil operation is carried out on the full value. The stencil write |
| mask is applied to the result during stencil buffer update, however. |
| |
| 2) Is this really backwards compatible? Does it break OpenGL? |
| |
| RESOLVED: Yes, this is backwards compatible and does not break anything. |
| The INCR{_WRAP} and DECR{_WRAP} operations have been semantically redefined |
| to be generalized add and subtract operations. However, the stencil |
| operation source value is used in the addition operation and its default is |
| 1. Therefore, in the default state (assuming the stencil operation source |
| value is not changed), INCR and DECR still increment and decrement by 1. |
| |
| 3) What if I want to apply a logical operation with the stencil reference |
| value and the current stencil buffer contents? |
| |
| RESOLVED: Set the stencil operation source value to the same thing as the |
| stencil reference value. |
| |
| Revision History |
| |
| Rev. Date Author Changes |
| ---- ---------- -------- ----------------------------------------- |
| 4 01/11/2012 gsellers Update for OpenGL 4.2. Prepare for posting. |
| 3 12/17/2010 yunzhang update enum definitions |
| 2 06/10/2010 gsellers Add separate stencil op value. Add issues. |
| 1 06/08/2010 gsellers Initial revision |
