1Name 2 3 AMD_stencil_operation_extended 4 5Name Strings 6 7 GL_AMD_stencil_operation_extended 8 9Contact 10 11 Graham Sellers, AMD (graham.sellers 'at' amd.com) 12 13Status 14 15 Shipping 16 17Version 18 19 Last Modified Date: 01/11/2012 20 Author Revision: 4 21 22Number 23 24 413 25 26Dependencies 27 28 OpenGL 1.0 is required. 29 30 The definition of this extension is affected by EXT_stencil_wrap and 31 OpenGL 2.0. 32 33 This extension is written against the OpenGL Specification, Version 4.2 34 (Core Profile). 35 36Overview 37 38 Stencil buffers are special buffers that allow tests to be made against an 39 incoming value and action taken based on that value. The stencil buffer is 40 updated during rasterization, and the operation used to update the stencil 41 buffer is chosen based on whether the fragment passes the stencil test, 42 and if it does, whether it passes the depth test. Traditional OpenGL 43 includes support for several primitive operations, such as incrementing, 44 or clearing the content of the stencil buffer, or replacing it with a 45 specified reference value. 46 47 This extension adds support for an additional set of operations that may 48 be performed on the stencil buffer under each circumstance. Additionally, 49 this extension separates the value used as the source for stencil 50 operations from the reference value, allowing different values to be used 51 in the stencil test, and in the update of the stencil buffer. 52 53IP Status 54 55 None. 56 57New Procedures and Functions 58 59 void StencilOpValueAMD(enum face, uint value); 60 61New Tokens 62 63 Accepted by the <sfail>, <dpfail> and <dppass> parameters of StencilOp 64 and StencilOpSeparate: 65 66 SET_AMD 0x874A 67 AND 0x1501 68 XOR 0x1506 69 OR 0x1507 70 NOR 0x1508 71 EQUIV 0x1509 72 NAND 0x150E 73 REPLACE_VALUE_AMD 0x874B 74 75 Accepted by the <param> parameter of GetIntegerv, GetFloatv, GetBooleanv 76 GetDoublev and GetInteger64v: 77 78 STENCIL_OP_VALUE_AMD 0x874C 79 STENCIL_BACK_OP_VALUE_AMD 0x874D 80 81Additions to Chapter 2 of the OpenGL 4.2 (Core Profile) Specification 82(OpenGL Operation) 83 84 None. 85 86Additions to Chapter 3 of the OpenGL 4.2 (Core Profile) Specification 87(Rasterization) 88 89 None. 90 91Additions to Chapter 4 of the OpenGL 4.2 (Core Profile) Specification 92(Per-Fragment Operations and the Framebuffer) 93 94 Add to the functions introduced in Section 4.1.4 "Stencil Test", p.287 95 96 The stencil test is controlled with 97 98 <leave existing functions in place> 99 void StencilOpValueAMD(enum face, uint value); 100 101 Modify the paragraph beginning "StencilFuncSeparate and StencilOpSeparate 102 take a <face> argument...", p.288 103 104 StencilFuncSeparate, StencilOpSeparate and StencilOpValue take a 105 <face> argument which can be FRONT, BACK or FRONT_AND_BACK and indicates 106 which set of state is affected. 107 108 Replace the second and third paragraphs on p.288, describing StencilOp and 109 StencilOpSeparate with the following three paragraphs: 110 111 StencilOp and StencilOpSeparate take three arguments that indicate what 112 happens to the stored stencil value if this or certain subsequent tests fail 113 or pass. sfail indicates what action is taken if the stencil test fails. 114 The inputs to the stencil operation are the stencil reference value, the 115 stencil operation source value, and the current content of the stencil 116 buffer. The accepted symbolic constants are KEEP, ZERO, SET_AMD, REPLACE, 117 REPLACE_VALUE_AMD, INCR, DECR, INVERT, INCR_WRAP, DECR_WRAP, AND, XOR, OR, 118 NOR, EQUIV, and NAND. These correspond to keeping the current value, setting 119 to zero, setting to the maximum representable value, replacing with the 120 reference value, replacing with the operation source value, incrementing by 121 the operation source value with saturation, decrementing by the operation 122 source value with saturation, bitwise inverting it, incrementing by the 123 operation source value without saturation, decrementing by the operation 124 source value without saturation, logically ANDing the operation source 125 value value with it, logically XORing the operation source value value with 126 it, logically ORing the operation source value with it, logically NORing 127 the operation source value with it, logically XORing the operation source 128 value with it and replacing the it with the logically inverted result of 129 that computation, and logically NANDing the operation source value with it, 130 respectively. 131 132 For purposes of increment, decrement, the stencil bits are considered 133 as an unsigned integer. Incrementing or decrementing with saturation clamps 134 the stencil value between 0 and the maximum representable value. 135 Incrementing without saturation will wrap such that incrementing the 136 content of the stencil buffer in such a way that overflow occurs will cause 137 the result of the operation to be masked by the number of bits representable 138 by the stencil buffer. Decrementing without saturation will wrap such that 139 decrementing the content of the stencil buffer in a manner such that the 140 result of the subtraction would be negative causes the two's complement 141 result to be interpreted as an unsigned integer and masked to the number of 142 bits representable by the stencil buffer. 143 144 The stencil operation source value is set by calling StencilOpValueAMD 145 with <face> set to GL_FRONT, GL_BACK or GL_FRONT_AND_BACK, and <value> set 146 to the new value of the stencil operation source value. 147 148 Modify the paragraph beginning "If the stencil test fails, the ... ", p.288 149 as follows: 150 151 If the stencil test fails, the incoming fragment is discarded. The state 152 required consists of the most recent values passed to StencilFunc or 153 StencilFuncSeparate, to StencilOp or StencilOpSeparate, and to 154 StencilOpValueAMD, and a bit indicating whether stencil testing is enabled 155 or disabled. In the initial state, stenciling is disabled, the front and 156 back reference values are both zero, the front and back stencil comparison 157 functions are both ALWAYS, the front and back stencil mask are both set to 158 the value 2^S - 1, where S is greater than or equal to the number of bits 159 in the deepest buffer supported by the GL implementation, and the front 160 and back stencil operation values are both 1. Initially, all three front 161 and back stencil operations are KEEP. 162 163Additions to Chapter 5 of the OpenGL 4.2 (Core Profile) Specification 164(Special Functions) 165 166 None. 167 168Additions to Chapter 6 of the OpenGL 4.2 (Core Profile) Specification 169(State and State Requests) 170 171 None. 172 173Additions to the AGL/GLX/WGL Specifications 174 175 None. 176 177GLX Protocol 178 179 None. 180 181Errors 182 183 INVALID_ENUM is generated by StencilOpValueAMD if <face> is not FRONT, 184 BACK or FRONT_AND_BACK. 185 186New State 187 188 Modify Table 6.20 "Pixel Operations", p.394: 189 190 +--------------------------------+----------+---------------+-----------+-------------------------------------------+--------+ 191 | | | Get | Initial | | | 192 | Get Value | Type | Command | Value | Description | Sec. | 193 +--------------------------------+----------+---------------+-----------+-------------------------------------------+--------+ 194 | STENCIL_FAIL | Z16 | GetIntegerv | KEEP | Front stencil fail action | 4.1.4 | 195 | STENCIL_PASS_DEPTH_FAIL | Z16 | GetIntegerv | KEEP | Front stencil depth buffer fail action | 4.1.4 | 196 | STENCIL_PASS_DEPTH_PASS | Z16 | GetIntegerv | KEEP | Front stencil depth buffer pass action | 4.1.4 | 197 | STENCIL_BACK_FAIL | Z16 | GetIntegerv | KEEP | Back stencil fail action | 4.1.4 | 198 | STENCIL_BACK_PASS_DEPTH_FAIL | Z16 | GetIntegerv | KEEP | Back stencil depth buffer fail action | 4.1.4 | 199 | STENCIL_BACK_PASS_DEPTH_PASS | Z16 | GetIntegerv | KEEP | Back stencil depth buffer pass action | 4.1.4 | 200 | STENCIL_OP_VALUE_AMD | Z+ | GetIntegerv | 1 | Front stencil operation value | 4.1.4 | 201 | STENCIL_BACK_OP_VALUE_AMD | Z+ | GetIngeterv | 1 | Back stencil operation value | 4.1.4 | 202 +--------------------------------+----------+---------------+-----------+-------------------------------------------+--------+ 203 204 NOTE: The existing STENCIL{_BACK}_{*} enumerants change have changed from Z8 to Z16. 205 206Dependencies on EXT_stencil_wrap 207 208 If EXT_stencil_wrap is not supported, remove references to INCR_WRAP and 209 DECR_WRAP. Also, change the definition of the STENCIL_{*} state to Z14 210 rather than Z16. 211 212Dependencies on OpenGL 2.0 213 214 If the GL version is less than 2.0, remove all references to 215 StencilOpSeparate. Furthermore, the <face> parameter to StencilOpValueAMD 216 must be FRONT_AND_BACK, otherwise an INVALID_ENUM error will be generated. 217 218Issues 219 220 1) Is the stencil mask applied to the stencil operation value? 221 222 RESOLVED: No, only to the reference and current values before the test. 223 The stencil operation is carried out on the full value. The stencil write 224 mask is applied to the result during stencil buffer update, however. 225 226 2) Is this really backwards compatible? Does it break OpenGL? 227 228 RESOLVED: Yes, this is backwards compatible and does not break anything. 229 The INCR{_WRAP} and DECR{_WRAP} operations have been semantically redefined 230 to be generalized add and subtract operations. However, the stencil 231 operation source value is used in the addition operation and its default is 232 1. Therefore, in the default state (assuming the stencil operation source 233 value is not changed), INCR and DECR still increment and decrement by 1. 234 235 3) What if I want to apply a logical operation with the stencil reference 236 value and the current stencil buffer contents? 237 238 RESOLVED: Set the stencil operation source value to the same thing as the 239 stencil reference value. 240 241Revision History 242 243 Rev. Date Author Changes 244 ---- ---------- -------- ----------------------------------------- 245 4 01/11/2012 gsellers Update for OpenGL 4.2. Prepare for posting. 246 3 12/17/2010 yunzhang update enum definitions 247 2 06/10/2010 gsellers Add separate stencil op value. Add issues. 248 1 06/08/2010 gsellers Initial revision 249