1Name 2 3 OES_sample_variables 4 5Name Strings 6 7 GL_OES_sample_variables 8 9Contact 10 11 Daniel Koch, NVIDIA Corporation (dkoch 'at' nvidia.com) 12 13Contributors 14 15 Pat Brown, NVIDIA 16 Eric Werness, NVIDIA 17 Graeme Leese, Broadcom 18 Contributors to ARB_gpu_shader5 19 Contributors to ARB_sample_shading 20 Members of the OpenGL ES Working Group 21 22Notice 23 24 Copyright (c) 2011-2019 The Khronos Group Inc. Copyright terms at 25 http://www.khronos.org/registry/speccopyright.html 26 27Specification Update Policy 28 29 Khronos-approved extension specifications are updated in response to 30 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 31 extensions which have been promoted to a core Specification, fixes will 32 first appear in the latest version of that core Specification, and will 33 eventually be backported to the extension document. This policy is 34 described in more detail at 35 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 36 37Status 38 39 Complete. 40 Ratified by the Khronos Board of Promoters on 2014/03/14. 41 42Version 43 44 Last Modified Date: January 10, 2019 45 Revision: 10 46 47Number 48 49 OpenGL ES Extension #170 50 51Dependencies 52 53 OpenGL ES 3.0 and GLSL ES 3.00 required. 54 55 This extension is written against the OpenGL ES 3.0.2 (April 8, 2013) 56 and the OpenGL ES Shading Language Specification Revision 4 57 (March 6, 2013) specifications. 58 59 This extension interacts with OES_sample_shading. 60 61 This extension interacts with OES_shader_multisample_interpolation. 62 63 This extension interacts with OpenGL ES 3.1. 64 65Overview 66 67 This extension allows fragment shaders more control over multisample 68 rendering. The mask of samples covered by a fragment can be read by 69 the shader and individual samples can be masked out. Additionally 70 fragment shaders can be run on individual samples and the sample's 71 ID and position read to allow better interaction with multisample 72 resources such as textures. 73 74 In multisample rendering, an implementation is allowed to assign the 75 same sets of fragment shader input values to each sample, which then 76 allows the optimization where the shader is only evaluated once and 77 then distributed to the samples that have been determined to be 78 covered by the primitive currently being rasterized. This extension 79 does not change how values are interpolated, but it makes some details 80 of the current sample available. This means that where these features 81 are used (gl_SampleID and gl_SamplePosition), implementations must 82 run the fragment shader for each sample. 83 84 In order to obtain per-sample interpolation on fragment inputs, either 85 OES_sample_shading or OES_shader_multisample_interpolation must 86 be used in conjunction with the features from this extension. 87 88New Procedures and Functions 89 90 None. 91 92New Tokens 93 94 None. 95 96Additions to Chapter 2 of the OpenGL ES 3.0 Specification (OpenGL ES Operation) 97 98 None. 99 100Additions to Chapter 3 of the OpenGL ES 3.0 Specification (Rasterization) 101 102 Modify section 3.9.2, Shader Execution, p. 162 103 104 (Add the following paragraphs to the section Shader Inputs, p. 164, after 105 the paragraph about gl_FrontFacing) 106 107 The built-in read-only variable gl_SampleID is filled with the 108 sample number of the sample currently being processed. This variable 109 is in the range zero to gl_NumSamples minus one, where 110 gl_NumSamples is the 111 total number of samples in the framebuffer, or one if rendering to a 112 non-multisample framebuffer. Using gl_SampleID in a fragment shader 113 causes the entire shader to be executed per-sample. When rendering to a 114 non-multisample buffer, 115 gl_SampleID will always be zero. gl_NumSamples is the sample count 116 of the framebuffer regardless of whether the framebuffer is multisampled 117 or not. 118 119 The built-in read-only variable gl_SamplePosition contains the 120 position of the current sample within the multi-sample draw buffer. 121 The x and y components of gl_SamplePosition contain the sub-pixel 122 coordinate of the current sample and will have values in the range 123 [0, 1]. The sub-pixel coordinate of the center of the pixel is 124 always (0.5, 0.5). Using this variable in a fragment shader 125 causes the entire shader to be executed per-sample. When rendering to a 126 non-multisample buffer, 127 gl_SamplePosition will always be (0.5, 0.5). 128 129 The built-in variable gl_SampleMaskIn is an integer array holding 130 bitfields indicating the set of fragment samples covered by the primitive 131 corresponding to the fragment shader invocation. The number of elements 132 in the array is ceil(gl_MaxSamples/32), where gl_MaxSamples is the 133 the value of MAX_SAMPLES, the maximum number of color samples supported 134 by the implementation. Bit <n> of element <w> in the 135 array is set if and only if the sample numbered <w>*32+<n> is considered 136 covered for this fragment shader invocation. When rendering to a 137 non-multisample buffer, all 138 bits are zero except for bit zero of the first array element. That bit 139 will be one if the pixel is covered and zero otherwise. Bits in the 140 sample mask corresponding to covered samples that will be killed due to 141 SAMPLE_COVERAGE or SAMPLE_MASK will not be set (section 4.1.3). 142 When per-sample shading is active due to the use of a fragment input 143 qualified by "sample" or due to the use of the gl_SampleID or 144 gl_SamplePosition variables, only the bit for the current sample is 145 set in gl_SampleMaskIn. 146 When OpenGL ES API state specifies multiple fragment shader invocations 147 for a given fragment, the bit corresponding to each covered sample will 148 be set in exactly one fragment shader invocation. 149 150 Modify section Shader Outputs, p. 165 151 152 (Replace the second sentence of the first paragraph with the following) 153 154 These outputs are split into two categories, user-defined outputs and the 155 built-in outputs gl_FragColor, gl_FragData[n] (both available only in 156 OpenGL ES Shading Language version 1.00), gl_FragDepth and gl_SampleMask. 157 158 (Insert the following paragraph after the first paragraph of the section) 159 160 The built-in integer array gl_SampleMask can be used to change the 161 sample coverage for a fragment from within the shader. The number 162 of elements in the array is ceil(gl_MaxSamples/32), where 163 gl_MaxSamples is the value of MAX_SAMPLES, the maximum number of 164 color samples supported by the implementation. 165 If bit <n> of element <w> in the array is set to zero, sample 166 <w>*32+<n> should be considered uncovered for the purposes of 167 multisample fragment operations (Section 4.1.3). Modifying the 168 sample mask in this way may exclude covered samples from being 169 processed further at a per-fragment granularity. However, setting 170 sample mask bits to one will never enable samples not covered by the 171 original primitive. If the fragment shader is being executed at 172 any frequency other than per-fragment, bits of the sample mask not 173 corresponding to the current fragment shader invocation are ignored. 174 175 176Additions to Chapter 4 of the OpenGL ES 3.0.2 Specification (Per-Fragment 177Operations and the Framebuffer) 178 179 Modify Section 4.1.3, Multisample Fragment Operations, p. 170 180 181 (modify first paragraph of section) This step modifies fragment alpha and 182 coverage values based on the values of SAMPLE_ALPHA_TO_COVERAGE, 183 SAMPLE_COVERAGE, SAMPLE_COVERAGE_VALUE, 184 SAMPLE_COVERAGE_INVERT, and an output sample mask optionally written by 185 the fragment shader. No changes to the fragment alpha or coverage values 186 are made at this step if the value of 187 SAMPLE_BUFFERS is not one. 188 189 (insert new paragraph before the paragraph on SAMPLE_COVERAGE, p. 171) 190 191 Next, if a fragment shader is active and statically assigns to the 192 built-in output variable gl_SampleMask, the fragment coverage is ANDed 193 with the bits of the sample mask. The initial values for elements of 194 gl_SampleMask are undefined. Bits in each array element that are not 195 written due to flow control or partial writes (i.e., bit-wise operations) 196 will continue to have undefined values. The value of those bits ANDed with 197 the fragment coverage is undefined. If no fragment shader is active, or 198 if the active fragment shader does not statically assign values to 199 gl_SampleMask, the fragment coverage is not modified. 200 201 202Additions to Chapter 5 of the OpenGL ES 3.0.2 Specification (Special Functions) 203 204 None. 205 206Additions to Chapter 6 of the OpenGL ES 3.0.2 Specification (State and 207State Requests) 208 209 None. 210 211Modifications to The OpenGL ES Shading Language Specification, Version 3.00.04 212 213 Including the following line in a shader can be used to control the 214 language features described in this extension: 215 216 #extension GL_OES_sample_variables 217 218 A new preprocessor #define is added to the OpenGL ES Shading Language: 219 220 #define GL_OES_sample_variables 1 221 222 Add to section 7.2 "Fragment Shader Special Variables" 223 224 (add the following to the list of built-in variables that are accessible 225 from a fragment shader) 226 227 in lowp int gl_SampleID; 228 in mediump vec2 gl_SamplePosition; 229 in highp int gl_SampleMaskIn[(gl_MaxSamples+31)/32]; 230 out highp int gl_SampleMask[(gl_MaxSamples+31)/32]; 231 232 (add the following descriptions of the new variables) 233 234 The input variable gl_SampleID is filled with the 235 sample number of the sample currently being processed. This 236 variable is in the range 0 to gl_NumSamples-1, where gl_NumSamples is 237 the total number of samples in the framebuffer, or one if rendering to 238 a non-multisample framebuffer. Any static use of gl_SampleID in a 239 fragment shader causes the entire shader to be executed per-sample. 240 241 The input variable gl_SamplePosition contains the 242 position of the current sample within the multi-sample draw 243 buffer. The x and y components of gl_SamplePosition contain the 244 sub-pixel coordinate of the current sample and will have values in 245 the range 0.0 to 1.0. Any static use of this variable in a fragment 246 shader causes the entire shader to be executed per-sample. 247 248 For the both the input array gl_SampleMaskIn[] and the output 249 array gl_SampleMask[], bit B of mask M (gl_SampleMaskIn[M] 250 or gl_SampleMask[M]) corresponds to sample 32*M+B. These arrays 251 have ceil(gl_MaxSamples/32) elements, where gl_MaxSamples is 252 the maximum number of color samples supported by the implementation. 253 254 The input variable gl_SampleMaskIn indicates the set of samples covered 255 by the primitive generating the fragment during multisample rasterization. 256 It has a sample bit set if and only if the sample is considered covered for 257 this fragment shader invocation. 258 259 The output array gl_SampleMask[] sets the sample mask for 260 the fragment being processed. Coverage for the current fragment will 261 be the logical AND of the coverage mask and the output 262 gl_SampleMask. If the fragment shader 263 statically assigns a value to gl_SampleMask, the sample mask will 264 be undefined for any array elements of any fragment shader 265 invocations that fails to assign a value. If a shader does not 266 statically assign a value to gl_SampleMask, the sample mask has no 267 effect on the processing of a fragment. 268 269 Add to section 7.3 Built-in Constants 270 271 const mediump int gl_MaxSamples = 4; 272 273 Add to Section 7.4 Built-in Uniform State 274 275 (Add the following prototype to the list of built-in uniforms 276 accessible from a fragment shader:) 277 278 uniform lowp int gl_NumSamples; 279 280Additions to the AGL/GLX/WGL/EGL Specifications 281 282 None 283 284Dependencies on OES_sample_shading 285 286 If OES_sample_shading is not supported ignore any mention of API state 287 that forces multiple shader invocations per fragment. 288 289Dependencies on OES_shader_multisample_interpolation 290 291 If OES_shader_multisample_interpolation is not supported ignore any mention of the 292 "sample" qualifier keyword for fragment inputs. 293 294Dependencies on OpenGL ES 3.1 295 296 If OpenGL ES 3.1 is not supported, ignore references to SAMPLE_MASK. 297 298Errors 299 300 None. 301 302New State 303 304 None. 305 306New Implementation Dependent State 307 308 None. 309 310Issues 311 312 (0) This extension is based on ARB_sample_shading. What are the major 313 differences? 314 315 1- rebased against ES 3.0 316 2- various editing for consistency to GL 4.4/GLSL 440 specs 317 3- added precision qualifiers for GLSL builtins 318 4- removed mention of SAMPLE_ALPHA_TO_ONE 319 5- replaced mention of "color and texture coordinates" with more 320 generic language about fragment shader inputs. 321 6- removed mention of multisample enable. 322 7- added gl_SampleMaskIn from ARB_gpu_shader5 323 8- replace the term 'evaluated' with 'executed' (Issue 3) 324 9- removed mention of sizing gl_SampleMask[] (Issue 4) 325 10- added gl_MaxSamples shading language constant. 326 327 For historical issues, please see ARB_sample_shading and 328 ARB_gpu_shader5. 329 330 (1) OpenGL has a MULTISAMPLE enable that was not included in OpenGL ES. 331 Should we add it into this extension or base it purely on if the target 332 surface is multisample? 333 334 DISCUSSION: 335 GL (4.4) says: 336 "Multisample rasterization is enabled or disabled by calling Enable or 337 Disable with the symbolic constant MULTISAMPLE." 338 339 GL ES (3.0.2) says: 340 "Multisample rasterization cannot be enabled or disabled after a GL 341 context is created." 342 343 RESOLVED. Multisample rasterization should be based on the target 344 surface properties. Will not pick up the explicit multisample 345 enable, but the language for ES3.0.2 doesn't sound right either. 346 Bug 10690 tracks this and it should be fixed in later versions 347 of the ES3.0 specification. 348 349 (2) ES requires vec2s in a fragment shader to be declared with a precision 350 qualifiers, what precision should be used for gl_SamplePosition? 351 352 RESOLVED: mediump should be used since lowp might be implemented with 353 fixed point and be unable to exactly represent [0.5, 0.5]. 354 355 (3) Is it reasonable to run shaders per-sample when interpolation is still 356 per-fragment? 357 358 RESOLVED: Yes. This allows a useful way of interacting with 359 multi-sample resources so it is included. To avoid confusion between 360 between per-sample interpolation and per-sample execution, we'll 361 use the term "executed" instead of "evaluated". 362 363 (4) ARB_sample_shaders says that "gl_SampleMask[] must be sized either 364 implicitly or explicitly in the fragment shader to be the same size 365 described above." ES doesn't have implicitly sized arrays. 366 Does this need to be explicitly declared in a shader or should it be 367 predeclared by the implementation? If predeclared, should it be an 368 error to redeclare it in the shader? 369 370 RESOLVED: In practice, one couldn't detect a difference between an 371 implicitly sized array and one that is automatically sized correctly 372 by a builtin declaration. In ES it is considered to be declared 373 (correctly sized) by the implementation when necessary and thus no 374 specific statement is required. As with all built-ins it is an 375 error for a shader to redeclare it. 376 377 (5) How does one know the size of the gl_SampleMaskIn/gl_SampleMask 378 arrays? 379 380 RESOLVED: The GL spec states that the size of the arrays is 381 ceil(<s>/32) where <s> is the maximum number of color samples 382 in the implementation. <s> is thus the equivalent of MAX_SAMPLES 383 which is the upper bound on the number of supported sample 384 of any format. As a convenience we add the built-in shading 385 language constant gl_MaxSamples to mirror this API 386 constant in the shading language and the size of the arrays is 387 defined in terms of this constant. 388 389 (6) Should the shading language built-ins have OES suffixes? 390 391 RESOLVED: No. Per Bug 11637, the WG made a policy decision 392 that GLSL ES identifiers imported without semantic change 393 or subsetting as OES extensions from core GLSL do not carry 394 suffixes. The #extension mechanism must still be used to 395 enable the appropriate extension before the functionality can 396 be used. 397 398 399Revision History 400 401 Rev. Date Author Changes 402 ---- ---------- -------- ----------------------------------------- 403 10 2019-01-10 Jon Leech Clarify the requirements on gl_SampleMaskIn 404 (internal API issue #45). 405 9 2014-02-12 dkoch remove GLSL suffixes per Issue 6. 406 8 2014-01-30 dkoch rename to OES, clean editing notes 407 7 2013-12-11 dkoch correct names of interacting extensions 408 6 2013-10-24 dkoch add gl_MaxSampleOES builtin constant and Issue 5 409 5 2013-10-22 dkoch Clarifications from Ian Romanick 410 4 2013-10-03 dkoch Added dependency on texture_storage_multisample 411 3 2013-10-03 dkoch Resolved all issues. 412 Changed gl_SamplePosition to mediump. 413 Changed the term "evaluated" to "executed". 414 Removed language about sizing gl_SampleMask. 415 2 2013-09-08 dkoch Added interactions for SampleMaskIn, deps. 416 Misc small editorial updates. 417 Added issue 4, unresolved issue 3. 418 1 2013-09-03 gleese Extracted from OES_sample_shading and 419 OES_shader_multisample_interpolation 420 421