1Name 2 3 OES_shader_multisample_interpolation 4 5Name Strings 6 7 GL_OES_shader_multisample_interpolation 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 Members of the OpenGL ES working group 20 21Notice 22 23 Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at 24 http://www.khronos.org/registry/speccopyright.html 25 26Specification Update Policy 27 28 Khronos-approved extension specifications are updated in response to 29 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 30 extensions which have been promoted to a core Specification, fixes will 31 first appear in the latest version of that core Specification, and will 32 eventually be backported to the extension document. This policy is 33 described in more detail at 34 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 35 36Status 37 38 Complete. 39 Ratified by the Khronos Board of Promoters on 2014/03/14. 40 41Version 42 43 Last Modified Date: February 11, 2014 44 Revision: 10 45 46Number 47 48 OpenGL ES Extension #172 49 50Dependencies 51 52 OpenGL ES 3.0 and GLSL ES 3.00 required. 53 54 This extension is written against the OpenGL ES 3.0.2 (April 8, 2013) 55 and the OpenGL ES Shading Language Specification Revision 4 56 (March 6, 2013) specifications. 57 58 This extension requires OES_sample_variables. 59 60 This extension interacts with OES_sample_shading. 61 62Overview 63 64 In standard multisample rendering, an implementation is allowed to 65 assign the same sets of fragment shader input values to each sample. 66 This can cause aliasing where the fragment shader input values are 67 used to generate a result that doesn't antialias itself, for example 68 with alpha-tested transparency. 69 70 This extension adds the "sample" qualifier that can be used on vertex 71 outputs and fragment inputs. When the "sample" qualifier is used, the 72 fragment shader is invoked separately for each covered sample and 73 all such qualified interpolants must be evaluated at the corresponding 74 sample point. 75 76 This extension provides built-in fragment shader functions to provide 77 fine-grained control over interpolation, including interpolating a 78 fragment shader input at a programmable offset relative to the pixel 79 center, a specific sample number, or at the centroid. 80 81IP Status 82 83 No known IP claims. 84 85New Procedures and Functions 86 87 None 88 89New Tokens 90 91 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, 92 and GetInteger64v: 93 94 MIN_FRAGMENT_INTERPOLATION_OFFSET_OES 0x8E5B 95 MAX_FRAGMENT_INTERPOLATION_OFFSET_OES 0x8E5C 96 FRAGMENT_INTERPOLATION_OFFSET_BITS_OES 0x8E5D 97 98Additions to Chapter 2 of the OpenGL ES 3.0 Specification 99(OpenGL Operation) 100 101 None 102 103Additions to Chapter 3 of the OpenGL ES 3.0 Specification 104(Rasterization) 105 106 Modify Section 3.3, Multisampling, p. 95 107 108 (add new paragraph as the second-last paragraph, at the end of the 109 section, p. 96) 110 111 If the value of SAMPLE_BUFFERS is one and the current program object 112 includes a fragment shader with one or more input variables qualified with 113 "sample in", the data associated with those variables will be assigned 114 independently. The values for each sample must be evaluated at the 115 location of the sample. The data associated with any other variables not 116 qualified with "sample in" need not be evaluated independently for each 117 sample. 118 119 120 Modify Section 3.9.1, Shader Variables, p. 161 121 122 (modify the second last paragraph of the section to be as follows, p. 161) 123 124 When interpolating input variables, the default 125 screen-space location at which these variables are sampled is defined in 126 previous rasterization sections. The default location may be overriden by 127 interpolation qualifiers. When interpolating variables declared using 128 "centroid in", the variable is sampled at a location within the pixel 129 covered by the primitive generating the fragment. When interpolating 130 variables declared using "sample in" when the value of SAMPLE_BUFFERS is 131 one, the fragment shader will be invoked separately for each covered sample 132 and the variable will be sampled at the corresponding sample point. 133 134 (add the following paragraph immediately after the above, p. 161) 135 136 Additionally, built-in fragment shader functions provide further 137 fine-grained control over interpolation. The built-in functions 138 interpolateAtCentroid() and interpolateAtSample() will sample variables as 139 though they were declared with the "centroid" or "sample" qualifiers, 140 respectively. The built-in function interpolateAtOffset() will sample 141 variables at a specified (x,y) offset relative to the center of the pixel. 142 The range and granularity of offsets supported by this function is 143 implementation-dependent. If either component of the specified offset is 144 less than MIN_FRAGMENT_INTERPOLATION_OFFSET_OES or greater than 145 MAX_FRAGMENT_INTERPOLATION_OFFSET_OES, the position used to interpolate the 146 variable is undefined. Not all values of <offset> may be supported; x and 147 y offsets may be rounded to fixed-point values with the number of fraction 148 bits given by the implementation-dependent constant 149 FRAGMENT_INTERPOLATION_OFFSET_BITS_OES. 150 151Additions to Chapter 4 of the OpenGL ES 3.0 Specification 152(Per-Fragment Operations and the Framebuffer) 153 154 None. 155 156Additions to Chapter 5 of the OpenGL ES 3.0 Specification 157(Special Functions) 158 159 None. 160 161Additions to Chapter 6 of the OpenGL ES 3.0 Specification 162(State and State Requests) 163 164 None. 165 166Additions to Appendix A of the OpenGL ES 3.0 (Compatibility Profile) 167Specification (Invariance) 168 169 None. 170 171Additions to the EGL Specifications 172 173 None. 174 175Modifications to The OpenGL ES Shading Language Specification, Version 3.00.04 176 177 Including the following line in a shader can be used to control the 178 language features described in this extension: 179 180 #extension GL_OES_shader_multisample_interpolation : <behavior> 181 182 where <behavior> is as specified in section 3.3. 183 184 New preprocessor #defines are added to the OpenGL ES Shading Language: 185 186 #define GL_OES_shader_multisample_interpolation 1 187 188 189 Modify Section 3.7, Keywords, p. 15 190 191 (add to the keyword list) 192 193 sample 194 195 (remove from the reserved keywords list) 196 197 sample 198 199 Modify Section 4.3, Storage Qualifiers, p. 33 200 201 (add to first table on the page) 202 203 Qualifier Meaning 204 -------------- ---------------------------------------- 205 sample in linkage with per-sample interpolation 206 sample out linkage with per-sample interpolation 207 208 (modify third paragraph, p. 33) These interpolation qualifiers may only 209 precede the qualifiers in, centroid in, sample in, out, centroid out, or 210 sample out in a declaration. ... 211 212 213 Modify Section 4.3.4, Input Variables, p. 35 214 215 (modify first paragraph of section) Shader input variables are declared 216 with the in, centroid in, or sample in storage qualifiers. ... Variables 217 declared as in, centroid in, or sample in may not be written to during 218 shader execution. ... 219 220 (modify the last paragraph, p. 35) ... It is an error to use "centroid in", 221 "sample in" or the interpolation qualifiers in a vertex shader input. ... 222 223 (modify third paragraph, p. 36) ... Fragment shader inputs get 224 per-fragment values, typically interpolated from a previous stage's 225 outputs. They are declared in fragment shaders with the in, centroid in, 226 or sample in storage qualifiers. ... 227 228 (add to examples immediately below) 229 230 sample in vec4 perSampleColor; 231 232 (replace the last paragraph of section, specifying that "sample" only need 233 be used in the fragment shader) The output of the vertex shader and the 234 input of the fragment shader form an interface. For this interface, 235 vertex shader output variables and fragment shader input variables of the 236 same name must match in type and qualification, with a few exceptions: 237 The storage qualifiers must, of course, differ (one is in and one is 238 out). Also, the "sample" qualifier may differ. When the "sample" 239 qualifier does not match, the qualifier declared (if any) in the vertex 240 shader is ignored. 241 242 Modify Section 4.3.6, Output Variables, p. 37 243 244 (modify first paragraph of section) Shader output variables are declared 245 with the out, centroid out, or sample out storage qualifiers. ... 246 247 (modify third paragraph of section) Vertex output variables 248 output per-vertex data and are declared using the out, centroid out, or 249 sample out storage qualifiers. ... 250 251 (add to examples immediately below) 252 253 sample out vec4 perSampleColor; 254 255 (modify last paragraph, p. 37) Fragment outputs output per-fragment data 256 and are declared using the out storage qualifier. It is an error to use 257 "centroid out" or "sample out" in a fragment shader. ... 258 259 260 Modify Section 4.3.9, Interpolation, p. 44 261 262 (modify first paragraph of section, add reference to sample in/out) The 263 presence of and type of interpolation is controlled by the storage 264 qualifiers centroid in, sample in, centroid out, and sample out, by the 265 optional interpolation qualifiers smooth, and flat. When no interpolation 266 qualifier is present, smooth interpolation is used. ... 267 268 (modify second paragraph) ... A variable may be qualified as flat centroid 269 or flat sample, which will mean the same thing as qualifying it only as 270 flat. 271 272 (replace last paragraph, p. 44) 273 274 When single-sampling, or for fragment shader input 275 variables qualified with neither "centroid in" nor "sample in", the value 276 is interpolated to the pixel's center and 277 a single value may be assigned to each sample within the pixel, to the 278 extent permitted by the OpenGL ES Specification. 279 280 When multisampling, "centroid" and "sample" may be 281 used to control the location and frequency of the sampling of the 282 qualified fragment shader input. If a fragment shader input is qualified 283 with "centroid", a single value may be assigned to that variable for all 284 samples in the pixel, but that value must be interpolated at a location 285 that lies in both the pixel and in the primitive being rendered, including 286 any of the pixel's samples covered by the primitive. Because the location 287 at which the variable is interpolated may be different in neighboring pixels, 288 and derivatives may be computed by computing differences in neighboring pixels, 289 derivatives of centroid-sampled inputs may be less accurate than those for 290 non-centroid interpolated variables. If a fragment shader input is 291 qualified with "sample", a separate value must be assigned to that 292 variable for each covered sample in the pixel, and that value must be 293 sampled at the location of the individual sample. 294 295 296 Modify Section 8.9, Fragment Processing Functions, p. 99 297 298 (add new functions to the end of section, p. 101) 299 300 Built-in interpolation functions are available to compute an interpolated 301 value of a fragment shader input variable at a shader-specified (x,y) 302 location. A separate (x,y) location may be used for each invocation of 303 the built-in function, and those locations may differ from the default 304 (x,y) location used to produce the default value of the input. 305 For the interpolateAt* functions, the call will return a precision 306 qualification matching the precision of the "interpolant" argument to 307 the function call. 308 309 float interpolateAtCentroid(float interpolant); 310 vec2 interpolateAtCentroid(vec2 interpolant); 311 vec3 interpolateAtCentroid(vec3 interpolant); 312 vec4 interpolateAtCentroid(vec4 interpolant); 313 314 float interpolateAtSample(float interpolant, int sample); 315 vec2 interpolateAtSample(vec2 interpolant, int sample); 316 vec3 interpolateAtSample(vec3 interpolant, int sample); 317 vec4 interpolateAtSample(vec4 interpolant, int sample); 318 319 float interpolateAtOffset(float interpolant, vec2 offset); 320 vec2 interpolateAtOffset(vec2 interpolant, vec2 offset); 321 vec3 interpolateAtOffset(vec3 interpolant, vec2 offset); 322 vec4 interpolateAtOffset(vec4 interpolant, vec2 offset); 323 324 The function interpolateAtCentroid() will return the value of the input 325 <interpolant> sampled at a location inside the both the pixel and 326 the primitive being processed. The value obtained would be the same value 327 assigned to the input variable if declared with the "centroid" qualifier. 328 329 The function interpolateAtSample() will return the value of the input 330 <interpolant> variable at the location of the sample numbered <sample>. If 331 multisample buffers are not available, the input varying will be evaluated 332 at the center of the pixel. If sample <sample> does 333 not exist, the position used to interpolate the input varying is 334 undefined. 335 336 The function interpolateAtOffset() will return the value of the input 337 <interpolant> variable sampled at an offset from the center of the pixel 338 specified by <offset>. The two floating-point components of <offset> 339 give the offset in pixels in the x and y directions, respectively. 340 An offset of (0,0) identifies the center of the pixel. The range and 341 granularity of offsets supported by this function is 342 implementation-dependent. 343 344 For all of the interpolation functions, <interpolant> must be an input 345 variable or an element of an input variable declared as an array. 346 Component selection operators (e.g., ".xy") may not be used when 347 specifying <interpolant>. If <interpolant> is declared with a "flat" 348 qualifier, the interpolated value will have the same value everywhere for 349 a single primitive, so the location used for the interpolation has no 350 effect and the functions just return that same value. If <interpolant> 351 is declared with the "centroid" qualifier, the value returned by 352 interpolateAtSample() and interpolateAtOffset() will be evaluated 353 at the specified location, ignoring the location normally used with the 354 "centroid" qualifier. 355 356 357 Modify Section 9, Shading Language Grammar, p. 92 358 359 !!! TBD !!! 360 361Dependencies on OES_sample_shading 362 363 This extension builds upon the per-sample shading support provided by 364 OES_sample_shading to provide a new "sample" qualifier on a fragment 365 shader input that forces per-sample shading, and specifies that the value 366 of the input be evaluated per-sample. 367 368 There is no interaction between the extensions, except that shaders using 369 the features of this extension seem likely to use features from 370 OES_sample_shading as well. 371 372Errors 373 374 None. 375 376New State 377 378 None. 379 380New Implementation Dependent State 381 382 Add to table 6.28 (Implementation Dependent Values) 383 384 Min. 385 Get Value Type Get Command Value Description Sec. 386 ---------------------- ---- ----------- ----- -------------------------- ----- 387 MIN_FRAGMENT_INTERP- R GetFloatv -0.5 furthest negative offset 3.9.1 388 OLATION_OFFSET_OES for interpolateAtOffset() 389 MAX_FRAGMENT_INTERP- R GetFloatv +0.5 furthest positive offset 3.9.1 390 OLATION_OFFSET_OES for interpolateAtOffset() 391 FRAGMENT_INTERPOLATION_ Z+ GetIntegerv 4 subpixel bits for 3.9.1 392 OFFSET_BITS_OES interpolateAtOffset() 393 394Issues 395 396 (0) This extension is based on parts of ARB_gpu_shader5. What are the 397 major differences? 398 399 1- rebased to ES 3.0 400 2- edits for consistency with GL 4.4/GLSL 440 specs 401 3- removed mention of 'noperspective' interpolation qualifier 402 4- removed mention of multisample enable 403 5- retained tighter interpolation requirements from ES3.0 404 6- moved gl_SampleMaskIn to OES_sample_variables 405 7- added precision statement for the interpolateAt* functions. 406 407 For historical issues, please see Issues 1, 2, 9, 11, and 12 in 408 ARB_gpu_shader5. 409 410 (1) What should we call this extension? 411 412 RESOLVED: It will be called OES_shader_multisample_interpolation 413 since it allows the shader to explicitly control the interpolation 414 used for multisample interpolation. 415 416 (2) "sample" and "centroid" have been split out as "Auxiliary Storage 417 Qualifiers" in GLSL 4.xx specs. Should we follow the way the 418 extension spec was written, or modify it to be more like GLSL 4.40? 419 420 RESOLVED. Leave it as the original extension was written. The changes 421 in the core spec are related to spec re-ordering which it makes no 422 sense to try to replicate via an extension. 423 424 (3) For Section 4.9.3 when multisample is disabled the ES 300 spec says 425 "the value is interpolated at the pixel's center", however GLSL 440 426 says "the value may be interpolated anywhere within the pixel. Which 427 behaviour do we want to incorporate? 428 429 RESOLVED. We retain the tighter ES 300 requirement which specifies 430 that the pixel's center must be used. 431 432 (4) What to do with the MULTISAMPLE enable language? 433 434 RESOLVED. OpenGL ES does not support MULTISAMPLE enable. This is 435 determined by the buffer properties, aka the value of SAMPLE_BUFFERS. 436 437 (5) Do we need precision qualifiers on the interpolatAt* functions? 438 439 RESOLVED. Yes. A statement was added for the interpolateAt* functions 440 to clarify that the the precision is taken to from the 'interpolant' 441 argument to the functions. 442 443 (6) Should the shading language built-ins have OES suffixes? 444 445 RESOLVED: No. Per Bug 11637, the WG made a policy decision 446 that GLSL ES identifiers imported without semantic change 447 or subsetting as OES extensions from core GLSL do not carry 448 suffixes. The #extension mechanism must still be used to 449 enable the appropriate extension before the functionality can 450 be used. 451 452Revision History 453 454 Rev. Date Author Changes 455 ---- ---------- -------- ----------------------------------------- 456 10 2014-02-12 dkoch remove GLSL suffixes per Issue 6. 457 9 2014-01-31 pbrown Add language explicitly not requiring that 458 "sample" qualifier match between stages (bug 459 11189), where the fragment qualifier wins. 460 8 2014-01-30 dkoch rename to OES, clean editing notes 461 7 2013-10-03 dkoch rewrote overview and dependecies 462 6 2013-09-16 dkoch renamed to shader_multisample_interpolation 463 5 2013-09-10 dkoch Mark issue 5 as resolved. 464 4 2013-09-09 dkoch Require OES_sample_variables 465 Move gl_SampleMaskIn interaction base extension. 466 Add precision statement for interpolateAt fn's. 467 Add a couple new edits for ESSL spec. 468 3 2013-09-03 gleese Moved sample variables to OES_sample_variables 469 2 2013-08-26 dkoch resolved issues 2-4 & supporting edits. 470 1 2013-08-13 dkoch port to ES 3.0 471 0 2013-08-07 dkoch reduced ARB_gpu_shader5 to sample-related features 472