1Name 2 3 ARM_shader_framebuffer_fetch_depth_stencil 4 5Name Strings 6 7 GL_ARM_shader_framebuffer_fetch_depth_stencil 8 9Contributors 10 11 Jan-Harald Fredriksen 12 Michael Stokes 13 Sandeep Kakarlapudi 14 Tom Olson 15 16Contact 17 18 Jan-Harald Fredriksen (jan-harald.fredriksen 'at' arm.com) 19 20Status 21 22 Shipping. 23 24Version 25 26 Revision 7 27 Last Modified Date: September 26, 2014 28 29Number 30 31 TBD 32 33Dependencies 34 35 OpenGL ES 2.0 or higher is required. 36 37 ESSL 1.00 or higher is required. 38 39 This extension is written against the OpenGL ES Shading Language 40 specification, Language Version 1.00, Document Revision 17 and revision 41 OpenGL ES 2.0.25 of the API specification. 42 43 This extension has a minor dependency on OpenGL ES 3.1. 44 45 EXT_shader_framebuffer_fetch and ARM_shader_framebuffer_fetch affect the 46 wording of this extension. 47 48Overview 49 50 Existing extensions, such as EXT_shader_framebuffer_fetch, allow fragment 51 shaders to read existing framebuffer color data as input. This enables 52 use-cases such as programmable blending, and other operations that may not 53 be possible to implement with fixed-function blending. 54 55 This extension adds similar capabilities for depth and stencil values. 56 57 One use-case for this is soft depth-blending of particles. Normally, this 58 would require two render passes: one that writes out the depth values of the 59 background geometry to a depth texture, and one that renders the particles 60 while reading from the depth texture to do the blending. This extension 61 allows this to be done in a single pass. 62 63New Procedures and Functions 64 65 None 66 67New Tokens 68 69 None 70 71New Macro Definitions 72 73 #define GL_ARM_shader_framebuffer_fetch_depth_stencil 1 74 75New Built-in Variables 76 77 lowp int gl_LastFragStencilARM 78 79 If GL_FRAGMENT_PRECISION_HIGH is defined or __VERSION__ is 300 add: 80 highp float gl_LastFragDepthARM 81 otherwise add this: 82 mediump float gl_LastFragDepthARM 83 84Changes to the OpenGL ES 2.0.25 Specification, Chapter 3 85 86 Remove the last sentence of Paragraph 2 of Chapter 3.8.1, page 86 ("These 87 built-in varying variables include [...]" and add: 88 89 "These built-in varying variables include the fragment's position, eye z 90 coordinate, and front-facing flag, as well as the current depth and stencil 91 values in the framebuffer. 92 93 If a shader reads from gl_LastFragDepthARM or gl_LastFragStencilARM and no 94 image is attached to the depth or stencil attachment, respectively, 95 results are undefined. No error is generated in this case." 96 97Additions to Chapter 3 of the OpenGL ES Shading Language Specification 98 99 Remove Paragraph 2 of section 3.8, page 17, Identifiers ("Identifiers 100 starting with "gl_" are reserved [...]") and add: 101 102 "Identifiers starting with "gl_" are reserved for use by OpenGL ES, and 103 may not be declared in a shader as either a variable or a function. 104 However, as noted in the specification, certain predeclared "gl_" names 105 are allowed to be redeclared in a shader for the specific purpose of 106 changing their precision qualifier." 107 108Additions to Chapter 7 of the OpenGL ES Shading Language Specification 109 110 In section 7.2 (Fragment Shader Special Variables), after the 111 8th paragraph ("If the shader executes the discard keyword,") and before 112 the paragraph on about gl_FragCoord, add: 113 114 "The fragment shader has access to the read-only built-in variables 115 gl_LastFragDepthARM and gl_LastFragStencilARM. These variables contain, 116 respectively, the current value of the depth and stencil buffer for 117 the pixel to which the current fragment is destined. 118 119 If multi-sampling, the values of gl_LastFragDepthARM and 120 gl_LastFragStencilARM depend on whether the fragment shader is invoked 121 per fragment or per covered sample. If the shader is invoked per 122 fragment, the values are an implementation-dependent combination of the 123 samples within the destination pixel that are covered by the current 124 fragment. The values will be between the minimum and maximum value of 125 the samples in the pixel. If the shader is invoked per covered sample, 126 separate values will be provided for each sample. 127 128 If no samples within the destination pixel are covered by the current 129 fragment, the values of gl_LastFragDepthARM and gl_LastFragStencilARM 130 are undefined. 131 132 Both gl_LastFragDepthARM and gl_LastFragStencilARM are declared with a 133 default precision qualifier. This can be changed by redeclaring the 134 corresponding variables with the desired precision qualifier. 135 Redeclarations must be at global scope and must not otherwise alter the 136 declared type of these variables. 137 138 Reads from gl_LastFragDepthARM and gl_LastFragStencilARM need to wait 139 for the processing of all previous fragments destined for the current 140 pixel to complete. For best performance, it is therefore recommended 141 that reads from either of these built-in variables are done as late in 142 the execution of the fragment shader as possible." 143 144 [[ The below paragraph only applies if ESSL 3.10 is supported ]] 145 It is not legal for a fragment shader to read from gl_LastFragDepthARM 146 and gl_LastFragStencilARM if the early_fragment_tests layout qualifier 147 is specified. This will result in a compile-time error. 148 149 Access to gl_LastFragDepthARM and gl_LastFragStencilARM is optional, 150 and must be enabled by: 151 152 #extension GL_ARM_shader_framebuffer_fetch_depth_stencil : <behavior> 153 154 Where <behavior> is as specified in section 3.4." 155 156 In section 7.2 (Fragment Shader Special Variables), at the end of 157 the list of built-in variables, add: 158 159 "lowp int gl_LastFragStencilARM" 160 161 If GL_FRAGMENT_PRECISION_HIGH is defined or __VERSION__ is 300 add: 162 "highp float gl_LastFragDepthARM" 163 otherwise add: 164 "mediump float gl_LastFragDepthARM" 165 166Errors 167 168 None 169 170New State 171 172 None 173 174New Implementation Dependent State 175 176 None 177 178Interactions with EXT_shader_framebuffer_fetch 179 180 As for color, when the value of SAMPLE_BUFFERS is 1 and the current 181 framebuffer depth or stencil is accessed in the fragment shader, the 182 fragment shader will be invoked separately for each covered sample and a 183 separate value for the previous framebuffer color will be provided for each 184 sample. 185 186Interactions with ARM_shader_framebuffer_fetch 187 188 As for color, the fragment shader is invoked separately for each covered 189 sample if FETCH_PER_SAMPLE_ARM is enabled and current framebuffer values 190 are accessed in the fragment shader. 191 192 The presence of multiple color attachments does not affect whether reading 193 gl_LastFragDepthARM and gl_LastFragStencilARM returns a defined result. 194 195Dependencies on OpenGL ES 3.1 196 197 If OpenGL ES 3.1 is not supported, remove all references to the 198 early_fragment_tests layout qualifier. 199 200Issues 201 202 (1) When multisampling is enabled, does the shader run per sample? 203 204 RESOLVED. 205 206 This behavior is inherited from either EXT_shader_framebuffer_fetch or 207 ARM_shader_framebuffer_fetch as described in the interactions section. 208 If neither extension is supported, the shader runs once per fragment. 209 210 (2) How does this extension interact with conventional depth and stencil 211 testing? 212 213 RESOLVED: There is no interaction. The two remain orthogonal. The rest 214 of the pipeline continues as usual after the fragment shader stage. 215 216 (3) What should the precision of gl_LastFragDepthARM be? 217 218 RESOLVED. 219 220 Ideally, it should match the internal precision of the depth buffer, but 221 OpenGL ES 2.0 does not require highp support in the fragment shader, so 222 requiring highp may prevent some implementations from supporting this 223 extension. 224 225 Options include: 226 A) Define gl_LastFragDepth as mediump and return it as 16bit. 227 B) Define gl_LastFragDepth as mediump, but treat it as higher 228 precision internally. 229 C) Define gl_LastFragDepth as highp if the implementation supports 230 highp, else mediump. 231 D) Allow the precision of gl_LastFragDepth to be redeclared. 232 233 Currently, option C is chosen by default, but the precision can be 234 redeclared in the shader in the same manner as for gl_FragData in 235 EXT_shader_framebuffer_fetch 236 237 (4) What performance recommendations should the extension contain? 238 239 RESOLVED. 240 241 There is currently a recommendation to place the framebuffer 242 read as late as possible in the shader. 243 244 (5) Should the value read back include only the samples covered by the 245 current fragment? 246 247 RESOLVED. 248 249 Yes, only the samples covered by the current fragment will be read back. 250 251 The alternative would be to ignore the coverage mask when returning the 252 value, but this seems less desirable. 253 254 If the shader is run per sample both options would give the same result. 255 256 (6) What is meant by undefined results in this extension? 257 258 RESOLVED. 259 260 Reads from gl_LastFragDepthARM and gl_LastFragStencilARM may return 261 undefined results in some cases as described in the text. This means 262 that there is no guarantees on the exact values returned in these 263 cases. The values will typically be a GPU specific 'default' value, 264 or correspond to the API clear value. It is guaranteed that these values 265 will never originate from other GL contexts or applications. 266 267 (7) How do the built-in variables added by this extension interract with 268 the early_fragment_tests layout qualifier in ESSL 3.10? 269 270 RESOLVED. 271 272 Combining early fragment tests with reads from gl_LastFragDepthARM or 273 gl_LastFragStencilARM is an error. 274 275 The early_fragment_tests qualifier requires per-fragment tests to be 276 complete before shader execution, but the built-ins added by this 277 extension will only give predictable results if per-fragment tests are 278 done late. If this is not the case, later fragments may update the depth 279 and stencil buffer values before the current fragment reads them. 280 281Revision History 282 283 Revision 7, 26/09/2014 (Jan-Harald Fredriksen) 284 Added interraction with OpenGL ES 3.10 per issue 7. 285 286 Revision 6, 25/11/2013 (Jan-Harald Fredriksen) 287 Clarified behavior when no depth or stencil buffer is bound. 288 Added and resolved issue 6. 289 290 Revision 5, 26/09/2013 (Jan-Harald Fredriksen) 291 Restricting redeclarations of built-in variables to global scope. 292 293 Revision 4, 15/07/2013 (Jan-Harald Fredriksen) 294 Minor clarification on interaction section. 295 296 Revision 3, 10/07/2013 (Jan-Harald Fredriksen) 297 Updated interactions with ARM_shader_framebuffer_fetch. 298 299 Revision 2, 06/05/2013 (Jan-Harald Fredriksen) 300 Language clarifications. 301 302 Revision 1, 02/05/2013 (Jan-Harald Fredriksen) 303 First draft that only adds depth and stencil fetches. 304