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