1Name 2 3 ARB_sample_shading 4 5Name Strings 6 7 GL_ARB_sample_shading 8 9Contact 10 11 Eric Werness, NVIDIA Corporation (ewerness 'at' nvidia.com) 12 Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com) 13 14Contributors 15 16 Murat Balci, AMD 17 Pierre Boudier, AMD 18 Pat Brown, NVIDIA 19 Greg Roth, NVIDIA 20 Graham Sellers, AMD 21 Eric Werness, NVIDIA 22 23Notice 24 25 Copyright (c) 2009-2013 The Khronos Group Inc. Copyright terms at 26 http://www.khronos.org/registry/speccopyright.html 27 28Specification Update Policy 29 30 Khronos-approved extension specifications are updated in response to 31 issues and bugs prioritized by the Khronos OpenGL Working Group. For 32 extensions which have been promoted to a core Specification, fixes will 33 first appear in the latest version of that core Specification, and will 34 eventually be backported to the extension document. This policy is 35 described in more detail at 36 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 37 38Status 39 40 Complete. Approved by the ARB on July 3, 2009. 41 42Version 43 44 Last Modified Date: 02/02/2010 45 Revision: 8 46 47Number 48 49 ARB Extension #70 50 51Dependencies 52 53 OpenGL 2.0 is required. 54 55 OpenGL Shading Language 1.30 is required 56 57 This extension is written against the OpenGL 2.0 specification and 58 version 1.30 of the OpenGL Shading Language Specification. 59 60Overview 61 62 In standard multisample rendering, an implementation is allowed to 63 assign the same color and texture coordinate values to each sample, 64 which then allows the optimization where the shader is only 65 evaluated once and then distributed to the samples that have been 66 determined to be covered by the primitive currently being 67 rasterized. This can cause aliasing where the input color and 68 texture coordinates are used to generate a result that doesn't 69 antialias itself, for example with alpha-tested transparency. 70 71 This extension adds the ability to explicitly request that an 72 implementation use a minimum number of unique set of fragment 73 computation inputs when multisampling a pixel. Specifying such a 74 requirement can reduce aliasing that results from evaluating the 75 fragment computations too few times per pixel. 76 77 This extension adds new global state that controls the minimum 78 number of samples for which attribute data is independently 79 interpolated. When enabled, all operations that were traditionally 80 executed per-fragment operate independently on each sample. 81 82 This also extends the shading language to allow control over the 83 sample being processed. This includes built-in fragment input 84 variables identifying the sample number and position being processed 85 when executing fragment shaders per sample. 86 87New Procedures and Functions 88 89 void MinSampleShadingARB(clampf value); 90 91New Tokens 92 93 Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, 94 and by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, 95 and GetDoublev: 96 97 SAMPLE_SHADING_ARB 0x8C36 98 99 Accepted by the <pname> parameter of GetBooleanv, GetDoublev, 100 GetIntegerv, and GetFloatv: 101 102 MIN_SAMPLE_SHADING_VALUE_ARB 0x8C37 103 104Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) 105 106 None. 107 108Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 109 110 Modify Section 3.2.1 Multisampling p. 93 111 112 (add a new paragraph at the end of the section, p. 95) 113 114 Sample shading can be used to specify a minimum number of unique samples 115 to process for each fragment. Sample shading is controlled by by calling 116 Enable or Disable with the symbolic constant SAMPLE_SHADING_ARB. 117 118 If MULTISAMPLE or SAMPLE_SHADING_ARB is disabled, sample shading has no 119 effect. Otherwise, an implementation must provide a minimum of 120 121 max(ceil(MIN_SAMPLE_SHADING_VALUE_ARB*SAMPLES),1) 122 123 unique color values and sets of texture coordinates for each 124 fragment. These are associated with the samples in an 125 implementation-dependent manner. The value of 126 MIN_SAMPLE_SHADING_VALUE_ARB is specified by calling 127 128 void MinSampleShadingARB(clampf value); 129 130 with <value> set to the desired minimum sample shading fraction. <value> 131 is clamped to [0,1] when specified. The sample shading fraction may be 132 queried by calling GetFloatv with pname set to 133 MIN_SAMPLE_SHADING_VALUE_ARB. 134 135 When the sample shading fraction is 1.0, a separate set of colors and 136 other associated data are evaluated for each sample, each set of values 137 are evaluated at the sample location. 138 139 140 Modify section 3.11, Fragment Shaders, p. 193 141 142 Add the following paragraph to the section Shader Inputs, p. 196 143 144 The built-in read-only variable gl_SampleID is filled with the 145 sample number of the sample currently being processed. This variable 146 is in the range 0 to gl_NumSamples-1, where gl_NumSamples is the total 147 number of samples in the framebuffer, or one if rendering to a 148 non-multisample framebuffer. Using this variable in a fragment shader 149 causes the entire shader to be evaluated per-sample. When rendering to a 150 non-multisample buffer, or if multisample rasterization is disabled, 151 gl_SampleID will always be zero. gl_NumSamples is the sample count 152 of the framebuffer regardless of whether multisample rasterization 153 is enabled or not. 154 155 The built-in read-only variable gl_SamplePosition contains the 156 position of the current sample within the multi-sample draw buffer. 157 The x and y components of gl_SamplePosition contain the sub-pixel 158 coordinate of the current sample and will have values in the range 159 zero to one. The sub-pixel coordinate of the center of the pixel is 160 always (0.5, 0.5). Using this variable in a fragment shader 161 causes the entire shader to be evaluated per-sample. When rendering to a 162 non-multisample buffer, or if multisample rasterization is disabled, 163 gl_SamplePosition will always be (0.5, 0.5). 164 165 Add the following paragraph to the section Shader Outputs, p. 196 166 167 The built-in integer array gl_SampleMask[] can be used to change the 168 sample coverage for a fragment from within the shader. The number 169 of elements in the array is ceil(<s>/32), where <s> is the 170 maximum number of color samples supported by the implementation. 171 If bit <n> of element <w> in the array is set to zero, sample 172 <w>*32+<n> should be considered uncovered for the purposes of 173 multisample fragment operations (Section 4.1.3). Modifying the 174 sample mask in this way may exclude covered samples from being 175 processed further at a per-fragment granularity. However, setting 176 sample mask bits to one will never enable samples not covered by the 177 original primitive. If the fragment shader is being evaluated at 178 any frequency other than per-framgent, bits of the sample mask not 179 corresponding to the current fragment shader invocation are ignored. 180 181 Add the following prototypes to the list of built-in variables 182 accessible from a fragment shader: 183 184 in int gl_SampleID; 185 in vec2 gl_SamplePosition; 186 out int gl_SampleMask[]; 187 188 Add the following prototype to the list of built-in uniforms 189 accessible from a fragment shader: 190 191 uniform int gl_NumSamples; 192 193 194Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment 195Operations and the Frame Buffer) 196 197 Modify Section 4.1.3, Multisample Fragment Operations, p. 200 198 199 (modify first paragraph of section) This step modifies fragment alpha and 200 coverage values based on the values of SAMPLE_ALPHA_TO_COVERAGE, 201 SAMPLE_ALPHA_TO_ONE, SAMPLE_COVERAGE, SAMPLE_COVERAGE_VALUE, 202 SAMPLE_COVERAGE_INVERT, and an output sample mask optionally written by 203 the fragment shader. No changes to the fragment alpha or coverage values 204 are made at this step if MULTISAMPLE is disabled, or if the value of 205 SAMPLE_BUFFERS is not one. 206 207 (insert new paragraph after second paragraph, p. 201) 208 209 Next, if a fragment shader is active and statically assigns to the 210 built-in output variable gl_SampleMask, the fragment coverage is ANDed 211 with the bits of the sample mask. If such a fragment shader did not 212 assign a value to gl_SampleMask due to flow control, the value ANDed with 213 the fragment coverage is undefined. If no fragment shader is active, or 214 if the active fragment shader does not statically assign values to 215 gl_SampleMask, the fragment coverage is not modified. 216 217 218Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) 219 220 None. 221 222Additions to Chapter 6 of the OpenGL 2.0 Specification (State and 223State Requests) 224 225 None. 226 227Additions to the AGL/GLX/WGL Specifications 228 229 None 230 231GLX Protocol 232 233 TBD 234 235Errors 236 237 None. 238 239New State 240 241 Get Value Get Command Type Initial Value Attribute 242 --------- ----------- ---- ------------- --------- 243 SAMPLE_SHADING_ARB IsEnabled B FALSE multisample/enable 244 MIN_SAMPLE_SHADING_VALUE_ARB GetFloatv R+ 0 multisample 245 246New Implementation Dependent State 247 248 None. 249 250Modifications to The OpenGL Shading Language Specification, Version 1.10.59 251 252 Including the following line in a shader can be used to control the 253 language features described in this extension: 254 255 #extension GL_ARB_sample_shading 256 257 A new preprocessor #define is added to the OpenGL Shading Language: 258 259 #define GL_ARB_sample_shading 1 260 261 Add to section 7.2 "Fragment Shader Special Variables" 262 263 264 The built-in output array gl_SampleMask[] sets the sample mask for 265 the fragment being processed. Coverage for the current fragment is 266 ANDed with the value of gl_SampleMask. Bit B of mask 267 gl_SampleMask[M] corresponds to sample 32*M+B. This array must be 268 sized in the fragment shader either implicitly or explicitly to be 269 the same size as the implementation dependent maximum sample mask 270 words determined by the maximum number of samples. If the fragment 271 shader statically assigns a value to gl_SampleMask[], the sample 272 mask will be undefined for any array elements of any fragment shader 273 invocations that fails to assign a value. If a shader does not 274 statically assign a value to gl_SampleMask, the sample mask has no 275 effect on the processing of a fragment. 276 277 The built-in read-only variable gl_SampleID is filled with the 278 sample number of the sample currently being processed. This 279 variable is in the range 0 to gl_NumSamples-1, where gl_NumSamples is 280 the total number of samples in the framebuffer, or one if rendering to 281 a non-multisample framebuffer. Using this variable in a fragment shader 282 causes the entire shader to be evaluated per-sample. 283 284 The built-in read-only variable gl_SamplePosition contains the 285 position of the current sample within the multi-sample draw 286 buffer. The x and y components of gl_SamplePosition contain the 287 sub-pixel coordinate of the current sample and will have values in 288 the range zero to one. Using this variable in a fragment shader 289 causes the entire shader to be evaluated per-sample. 290 291 ... 292 293 The built-in variables that are accessible from a fragment shader are 294 intrinsically given types as follows: 295 296 int gl_SampleID; 297 vec2 gl_SamplePosition; 298 int gl_SampleMask[]; 299 300 301Issues 302 303 304 1) Do we need both an enable and state? 305 306 RESOLVED. Yes - that's just the way GL rolls 307 308 2) How many times is the fragment shader run? 309 310 RESOLVED. The shader must be run at least once for each unique 311 set of texture coordinates and colors, so 312 max(MIN_SAMPLE_SHADING_VALUE_ARB*SAMPLES,1) times. 313 314 3) What cases can benefit from enabling this? 315 316 RESOLVED. Something like alpha-tested rendering using textures 317 don't benefit from multisampling right now - using this extension 318 to run the fragment shader or fixed-function texturing multiple 319 times per pixel can significantly improve quality. 320 321 4) What do KIL and discard do? 322 323 RESOLVED. They terminate a single invocation of the shader, so a 324 single fragment may have some threads that discard and some that 325 don't. 326 327 5) Should there be an option to specify that all fragment shader inputs 328 be interpolated at per-sample frequency? If so, how? 329 330 RESOLVED: Yes. Via the enable 331 332 6) Should the ability to specify per-sample or per-fragment 333 interpolation on a per-varying basis be added via the language? 334 335 RESOLVED: Not in this extension. 336 337 7) Does gl_SampleMask belong here? 338 339 RESOLVED: Yes, it's sample related and conteporary with the 340 hardware required for the rest of this extension. Thematically it 341 might match better with ARB_texture_multisample, but that 342 extension targets hardware that cannot support gl_sampleMask. 343 344 8) How should gl_SampleMask mask samples above the first 32? 345 346 RESOLVED: By being an array with enough entries to encompass all 347 the implementation-dependent maximum number of samples. 348 349 9) Is per-sample shading ever triggered by properties of the fragment 350 shader? 351 352 RESOLVED: Yes. The variables "gl_SampleID" and "gl_SamplePosition" 353 can be used to read properties of the current sample, which wouldn't 354 make much sense if the fragment shader were run at a lower frequency 355 than per-sample. 356 357 10) Does gl_SamplePosition need to support layout() qualifiers such as 358 "pixel_center_integer" in GLSL 1.50? 359 360 RESOLVED: Not in this extension. "pixel_center_integer" was added in 361 part for compatibility with shaders originally targeting Direct3D 362 version 9.0 or earlier, where pixel centers were specified to be (X.0, 363 Y.0) instead of OpenGL's (X.5, Y.5). However, Direct3D 9.0 doesn't 364 support anything like "gl_SamplePosition", and Direct3D versions that do 365 support this functionality have adopted OpenGL's (X.5, Y.5) conventions. 366 367 368Revision History 369 370 Rev. Date Author Changes 371 ---- -------- -------- ----------------------------------------- 372 8 02/02/2010 pbrown Clarify that use of gl_SamplePosition 373 triggers per-sample shading (bug 5911). 374 375 7 01/20/2010 Jon Leech Add rounding rule for computing number of 376 samples used depending on min sample 377 shading setting. 378 379 6 10/22/2009 pdaniell Specify that gl_NumSamples should return 380 the sample count for the framebuffer 381 regardless of whether MULTISAMPLE is enabled 382 or not. This matches the API-level queries. 383 384 5 09/17/2009 pbrown Clean up some language on MinSampleShading. 385 Add a clarification requiring variables to 386 be sampled at sample locations when doing 387 full per-sample shading. Add some more 388 details on the gl_SampleMask array and its 389 operation in the multisample fragment ops. 390 Rename gl_MaxSampleId to gl_NumSamples and 391 adjust language. 392 393 4 08/02/2009 Jon Leech Reformat to 80 columns and assign 394 ARB extension number 395 396 3 06/25/2009 groth Restore missing explanations of 397 MIN_SAMPLE_SHADING_VALUE_ARB 398 399 2 05/15/2009 groth Restore gl_sampleMask as an array 400 401 1 05/13/2009 groth Merge from NV_sample_shading_control, 402 NV_gpu_shader4_1, and AMD_sample_rate_shader 403