1Name 2 3 ARB_shader_stencil_export 4 5Name Strings 6 7 GL_ARB_shader_stencil_export 8 9Contributors 10 11 Graham Sellers, AMD 12 Andrew Lewycky, AMD 13 Mais Alnasser, AMD 14 15Contact 16 17 Graham Sellers, AMD (graham.sellers 'at' amd.com) 18 19Notice 20 21 Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at 22 http://www.khronos.org/registry/speccopyright.html 23 24Specification Update Policy 25 26 Khronos-approved extension specifications are updated in response to 27 issues and bugs prioritized by the Khronos OpenGL Working Group. For 28 extensions which have been promoted to a core Specification, fixes will 29 first appear in the latest version of that core Specification, and will 30 eventually be backported to the extension document. This policy is 31 described in more detail at 32 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 33 34Status 35 36 Complete. Approved by the ARB on June 9, 2010. 37 Approved by the Khronos Board of Promoters on July 23, 2010. 38 39Version 40 41 Last Modified Date: 05/20/2010 42 Author Revision: 6 43 44Number 45 46 ARB Extension #106 47 48Dependencies 49 50 OpenGL 1.0 is required. 51 52 ARB_fragment_shader is required. 53 54 This extension is written against the OpenGL Shading Language Specification 55 version 1.40.05 56 57Overview 58 59 In OpenGL, the stencil test is a powerful mechanism to selectively discard 60 fragments based on the content of the stencil buffer. However, facilites 61 to update the content of the stencil buffer are limited to operations such 62 as incrementing the existing value, or overwriting with a fixed reference 63 value. 64 65 This extension provides a mechanism whereby a shader may generate the 66 stencil reference value per invocation. When stencil testing is enabled, 67 this allows the test to be performed against the value generated in the 68 shader. When the stencil operation is set to GL_REPLACE, this allows a 69 value generated in the shader to be written to the stencil buffer directly. 70 71IP Status 72 73 No known IP claims. 74 75New Procedures and Functions 76 77 None. 78 79New Tokens 80 81 None. 82 83Additions to Chapter 2 of the OpenGL 2.1 Specification (OpenGL Operation) 84 85 None. 86 87Additions to Chapter 3 of the OpenGL 2.1 Specification (Rasterization) 88 89 None. 90 91Additions to Chapter 4 of the OpenGL 2.1 Specification (Per-Fragment Operations 92and the Framebuffer) 93 94 None. 95 96Additions to Chapter 5 of the OpenGL 2.1 Specification (Special 97Functions) 98 99 None. 100 101Additions to Chapter 6 of the OpenGL 2.1 Specification (State and 102State Requests) 103 104 None. 105 106Additions to the OpenGL Shading Language Version 1.40.05 107 108 Add a new Section 3.3.x, GL_ARB_shader_stencil_export Extension (p. 11) 109 110 3.3.x GL_ARB_shader_stencil_export 111 112 To use the GL_ARB_shader_stencil_export extension in a shader it must be 113 enabled using the #extension directive. 114 115 The shading language preprocessor #define GL_ARB_shader_stencil_export will 116 be defined to 1 if the GL_ARB_shader_stencil_export extension is supported. 117 118 Modify Section 7.2, "Fragment Shader Special Variables": 119 120 Add to the list of built-in special variables, p.63: 121 122 out int gl_FragStencilRefARB; 123 124 Modify the paragraph beginning, "Fragment shaders output values to the 125 OpenGL pipeline..." to: 126 127 Fragment shaders output values to the OpenGL pipeline using the built-in 128 variables gl_FragColor, gl_FragData, gl_FragDepth, and gl_FragStencilRefARB 129 unless the discard statement is executed. Both gl_FragColor and gl_FragData 130 are deprecated; the preferred usage is to explicitly declare these outputs 131 in the fragment shader using the out storage qualifier. 132 133 Insert a new paragraph after the paragraph describing gl_FragDepth: 134 135 Writing to gl_FragStencilRefARB will establish the stencil reference value 136 for the fragment being processed. Only the least significant bits of the 137 integer gl_FragStencilRefARB are considered up to the value of STENCIL_BITS 138 and higher order bits are discarded. If stencil testing is enabled and no 139 shader writes to gl_FragStencilRefARB, then the fixed function value for 140 stencil reference will be used as the fragment's stencil reference value. 141 If a shader statically assignes a value to gl_FragStencilRefARB, and there 142 is an execution path through the shader that does not set 143 gl_FragStencilRefARB, then the value of the fragment's stencil reference 144 value may be undefined for executions of the shader that take that path. 145 That is, if the set of linked shaders statically contain a write to 146 gl_FragStencilRefARB, then it is responsible for always writing it. 147 148 Modify the first paragraph on p.64: 149 150 If a shader executes the discard keyword, the fragment is discarded, and 151 the values of any user-defined fragment outputs, gl_FragDepth, gl_FragColor, 152 gl_FragData, and gl_FragStencilRefARB become irrelevant. 153 154Additions to the AGL/GLX/WGL Specifications 155 156 None. 157 158GLX Protocol 159 160 None. 161 162Errors 163 164 None. 165 166New State 167 168 None. 169 170New Implementation Dependent State 171 172 None. 173 174Issues 175 176 1) Should gl_FragStencilRefARB be initialized to the current stencil 177 reference value on input to the fragment shader? 178 179 RESOLVED: No. gl_FragStencilRefARB is write-only. If the current stencil 180 reference value is required in a shader, the application should place 181 it in a uniform. 182 183 2) Is it possible to output the stencil mask from the shader? 184 185 RESOLVED: No. 186 187 3) Is the global stencil mask still applied? 188 189 RESOLVED: Yes. The mask is global as there is no way to export the 190 stencil mask from the shader. 191 192 4) How is two-sided stencil handled? How do we export front and back 193 stencil references? 194 195 RESOLVED: There is only one export from the shader. However, two sided 196 stencil reference generation may be achived as: 197 198 if (gl_FrontFacing) 199 gl_FragStencilRefARB = foo; 200 else 201 gl_FragStencilRefARB = bar; 202 203 If both front and back stencil reference values are needed in a single 204 shader, user defined uniforms may be used. 205 206 5) If the value written to gl_FragStencilRefARB is outside of the range of 207 values representable by the stencil buffer, what happens? 208 209 RESOLVED: The additional bits are discarded. This is logical as the 210 stencil mask is still applied and its bit-depth is that of the stencil 211 buffer. If clamping is desired, this should be performed in the shader. 212 213 6) Why is gl_FragStencilRef signed? 214 215 For consistency with the ref parameter to glStencilFunc, which is a 216 GLint. It is masked with the stencil mask value, so it makes no practical 217 difference whether it's signed or unsigned unless the implementation 218 supports 32-bit stencil buffers. An interesting note is that the GL 219 specification states that the comparison made in the stencil test 220 is unsigned. 221 222Revision History 223 224 Rev. Date Author Changes 225 ---- -------- -------- ----------------------------------------- 226 227 6 05/20/2010 gsellers Add issue 6. 228 5 04/07/2010 gsellers Remove erroneous language stating that 229 gl_FragStencilRefARB is initialized to the fixed 230 function reference value. 231 4 09/27/2009 gsellers Update issues 1, 4 and 5. 232 3 07/16/2009 gsellers Address two-sided stencil references. 233 Add issues 3, 4 and 5. 234 2 07/14/2009 gsellers Add ARB suffix to gl_FragStencilRef. Resolve (1) 235 1 07/10/2009 gsellers Initial draft. 236