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