1Name 2 3 EXT_raster_multisample 4 5Name Strings 6 7 GL_EXT_raster_multisample 8 9Contact 10 11 Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com) 12 13Contributors 14 15 Pat Brown, NVIDIA 16 Mathias Heyer, NVIDIA 17 18Status 19 20 Shipping 21 22Version 23 24 Last Modified Date: March 27, 2015 25 Revision: 2 26 27Number 28 29 OpenGL Extension #462 30 OpenGL ES Extension #226 31 32Dependencies 33 34 This extension is written against the OpenGL 4.3 (Compatibility Profile) 35 specification. 36 37 This extension requires OpenGL ES 3.0.3 (December 18, 2013) in an 38 OpenGL ES implementation. 39 40 This extension interacts with NV_fragment_coverage_to_color. 41 42 This extension interacts with EXT_depth_bounds_test. 43 44 This extension interacts with OES_sample_shading. 45 46 This extension interacts with OES_sample_variables. 47 48Overview 49 50 This extension allows rendering to a non-multisample color buffer while 51 rasterizing with more than one sample. The result of rasterization 52 (coverage) is available in the gl_SampleMaskIn[] fragment shader input, 53 multisample rasterization is enabled for all primitives, and several per- 54 fragment operations operate at the raster sample rate. 55 56 When using the functionality provided by this extension, depth, stencil, 57 and depth bounds tests must be disabled, and a multisample draw 58 framebuffer must not be used. 59 60 A fragment's "coverage", or "effective raster samples" is considered to 61 have "N bits" (as opposed to "one bit" corresponding to the single color 62 sample) through the fragment shader, in the sample mask output, through 63 the multisample fragment operations and occlusion query, until the coverage 64 is finally "reduced" to a single bit in a new "Coverage Reduction" stage 65 that occurs before blending. 66 67New Procedures and Functions 68 69 void RasterSamplesEXT(uint samples, boolean fixedsamplelocations); 70 71New Tokens 72 73 Accepted by the <cap> parameter of Enable, Disable, IsEnabled: 74 75 RASTER_MULTISAMPLE_EXT 0x9327 76 77 Accepted by the <pname> parameter of GetBooleanv, GetDoublev, 78 GetIntegerv, and GetFloatv: 79 80 RASTER_SAMPLES_EXT 0x9328 81 MAX_RASTER_SAMPLES_EXT 0x9329 82 RASTER_FIXED_SAMPLE_LOCATIONS_EXT 0x932A 83 MULTISAMPLE_RASTERIZATION_ALLOWED_EXT 0x932B 84 EFFECTIVE_RASTER_SAMPLES_EXT 0x932C 85 86Additions to Chapter 14 of the OpenGL 4.3 (Compatibility Profile) Specification 87(Rasterization) 88 89 Modify Section 14.3.1 (Multisampling), p. 477 90 91 (replace the introductory language at the beginning of the section to 92 account for the new ability to use multisample rasterization without 93 having multisample storage) 94 95 Multisampling is a mechanism to antialias all GL primitives: points, 96 lines, polygons, bitmaps, and images. The technique is to sample all 97 primitives multiple times at each pixel. The color sample values are 98 resolved to a single, displayable color. For window system-provided 99 framebuffers, this occurs each time a pixel is updated, so the 100 antialiasing appears to be automatic at the application level. For 101 application-created framebuffers, this must be requested by calling 102 the BlitFramebuffer command (see section 18.3.1). Because each sample 103 includes color, depth, and stencil information, the color (including 104 texture operation), depth, and stencil functions perform 105 equivalently to the single-sample mode. 106 107 When the framebuffer includes a multisample buffer, separate color, depth, 108 and stencil values are stored in this buffer for each sample location. 109 Samples contain separate color values for each fragment color. 110 Framebuffers including a multisample buffer do not include non-multisample 111 depth or stencil buffers, even if the multisample buffer does not store 112 depth or stencil values. Color buffers do coexist with the multisample 113 buffer, however. 114 115 The color sample values are resolved to a single, displayable color each 116 time a pixel is updated, so the antialiasing appears to be automatic at 117 the application level. Because each sample includes color, depth, and 118 stencil information, the color (including texture operation), depth, and 119 stencil functions perform equivalently to the single-sample mode. 120 121 Multisample antialiasing is most valuable for rendering polygons, because 122 it requires no sorting for hidden surface elimination, and it correctly 123 handles adjacent polygons, object silhouettes, and even intersecting 124 polygons. If only points or lines are being rendered, the "smooth" 125 antialiasing mechanism provided by the base GL may result in a higher 126 quality image. This mechanism is designed to allow multisample and smooth 127 antialiasing techniques to be alternated during the rendering of a single 128 scene. 129 130 If the value of MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is TRUE, the 131 rasterization of all primitives is changed, and is referred to as 132 multisample rasterization. Otherwise, primitive rasterization is 133 referred to as single-sample rasterization. The value of MULTISAMPLE- 134 _RASTERIZATION_ALLOWED_EXT is queried by calling GetIntegerv 135 with pname set to MULTISAMPLE_RASTERIZATION_ALLOWED_EXT. 136 137 During multisample rendering the contents of a pixel fragment are changed 138 in two ways. First, each fragment includes a coverage value with 139 EFFECTIVE_RASTER_SAMPLES_EXT bits. The value of EFFECTIVE_RASTER_- 140 SAMPLES_EXT is an implementation-dependent constant, and 141 is queried by calling GetIntegerv with pname set to EFFECTIVE_RASTER- 142 _SAMPLES_EXT. 143 144 145 --- 146 147 Multisample rasterization may also be enabled without introducing 148 additional storage for the multisample buffer, by calling Enable with a 149 <target> of RASTER_MULTISAMPLE_EXT. The command: 150 151 void RasterSamplesEXT(uint samples, boolean fixedsamplelocations); 152 153 selects the number of samples to be used for rasterization. <samples> 154 represents a request for a desired minimum number of samples. Since 155 different implementations may support different sample counts, the actual 156 sample pattern used is implementation-dependent. However, the resulting 157 value for RASTER_SAMPLES_EXT is guaranteed to be greater than or equal to 158 <samples> and no more than the next larger sample count supported by the 159 implementation. If <fixedsamplelocations> is TRUE, identical sample 160 locations will be used for all pixels. The sample locations chosen are a 161 function of only the parameters to RasterSamplesEXT and not of any other 162 state. 163 164 If RASTER_MULTISAMPLE_EXT is enabled, then the sample pattern chosen by 165 RasterSamplesEXT will be used instead of sampling at the center of the 166 pixel. The sample locations can be queried with GetMultisamplefv with a 167 <pname> of SAMPLE_POSITION, similar to normal multisample sample locations. 168 169 The value MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is TRUE if SAMPLE_BUFFERS 170 is one or if RASTER_MULTISAMPLE_EXT is enabled. The value 171 EFFECTIVE_RASTER_SAMPLES_EXT is equal to RASTER_SAMPLES_EXT if 172 RASTER_MULTISAMPLE_EXT is enabled, otherwise is equal to SAMPLES. 173 174 Explicit multisample rasterization can not be used in conjunction with 175 depth, stencil, or depth bounds tests, multisample framebuffers, or if 176 RASTER_SAMPLES_EXT is zero. If RASTER_MULTISAMPLE_EXT is enabled, the 177 error INVALID_OPERATION will be generated by Draw commands if 178 179 - the value of RASTER_SAMPLES_EXT is zero 180 - the depth, stencil, or depth bounds test is enabled 181 - a multisample draw framebuffer is bound (SAMPLE_BUFFERS is one) 182 183 Errors 184 185 - An INVALID_VALUE error is generated if <samples> is greater than the 186 value of MAX_RASTER_SAMPLES_EXT (the implementation-dependent maximum 187 number of samples). 188 189 190 Add to the end of Section 14.3.1.1 (Sample Shading), p. 479 191 192 If RASTER_MULTISAMPLE_EXT is enabled, the number of unique samples to 193 process is implementation-dependent and need not be more than one. 194 195 Modify Section 14.4.3 (Point Multisample Rasterization) 196 197 If MULTISAMPLE is enabled and MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is 198 TRUE, then points are rasterized using the following algorithm, regardless 199 of whether point antialiasing (POINT_SMOOTH) is enabled or disabled. 200 201 Modify Section 14.5.4 (Line Multisample Rasterization) 202 203 If MULTISAMPLE is enabled and MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is 204 TRUE, then lines are rasterized using the following algorithm, regardless 205 of whether line antialiasing (LINE_SMOOTH) is enabled or disabled. 206 207 Modify Section 14.6.6 (Polygon Multisample Rasterization) 208 209 If MULTISAMPLE is enabled and MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is 210 TRUE, then polygons are rasterized using the following algorithm, 211 regardless of whether polygon antialiasing (POLYGON_SMOOTH) is enabled or 212 disabled. 213 214 Modify Section 14.8.0.1 (Bitmap Multisample Rasterization) 215 216 If MULTISAMPLE is enabled and MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is 217 TRUE, then bitmaps are rasterized using the following algorithm. 218 219Additions to Chapter 15 of the OpenGL 4.3 (Compatibility Profile) Specification 220(Programmable Fragment Processing) 221 222 Modify Section 15.2.2 (Shader Inputs), p. 512 223 224 The built-in variable gl_SampleMaskIn is an integer array holding bitfields 225 indicating the set of fragment samples covered by the primitive 226 corresponding to the fragment shader invocation. The number of elements in 227 the array is 228 229 ceil(s/32), 230 231 where <s> is the maximum number of color or raster samples supported by the 232 implementation. Bit <n> of element <w> in the array is set if and only if 233 the raster sample numbered 32<w> + <n> is considered covered for this 234 fragment shader invocation. 235 236 Modify Section 15.2.3 (Shader Outputs), p. 513 237 238 The built-in integer array gl_SampleMask can be used to change the sample 239 coverage for a fragment from within the shader. The number of elements in 240 the array is 241 242 ceil(s/32), 243 244 where <s> is the maximum number of color or raster samples supported by the 245 implementation. 246 247Additions to Chapter 17 of the OpenGL 4.3 (Compatibility Profile) Specification 248(Writing Fragments and Samples to the Framebuffer) 249 250 Modify Figure 17.1 (Per-fragment operations) 251 252 Add a new stage called "Coverage Reduction" between "Occlusion Query" and 253 "Blending". 254 255 (note: If NV_fragment_coverage_to_color is supported, the "Coverage 256 Reduction" stage is after the "Fragment coverage to color" stage.) 257 258 259 Modify Section 17.3.3 (Multisample Fragment Operations) 260 261 First paragraph: 262 ...No changes to the fragment alpha or coverage values are made at this 263 step if MULTISAMPLE is disabled or MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is 264 FALSE. 265 266 ... 267 268 If SAMPLE_ALPHA_TO_COVERAGE is enabled, a temporary coverage value is 269 generated where each bit is determined by the alpha value at the 270 corresponding sample location. The coverage value has 271 EFFECTIVE_RASTER_SAMPLES_EXT bits. 272 273 274 Modify Section 17.3.7 (Occlusion Queries), p.538 275 276 When an occlusion query is started with target SAMPLES_PASSED, the samples- 277 passed count maintained by the GL is set to zero. When an occlusion query 278 is active, the samples-passed count is incremented for each fragment that 279 passes the depth test. If MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is FALSE, 280 then the samples-passed count is incremented by 1 for each fragment. If 281 MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is TRUE, then the samples-passed 282 count is incremented by the number of samples whose coverage bit is set. 283 However, implementations, at their discretion, may instead increase the 284 samples-passed count by the value of EFFECTIVE_RASTER_SAMPLES_EXT if any 285 sample in the fragment is covered. Additionally, if 286 RASTER_MULTISAMPLE_EXT is enabled, implementations may instead increase 287 the samples-passed count by one for the entire fragment if any sample 288 is covered. 289 290 291 Add a new Section 17.3.Y (Coverage Reduction) after 17.3.7. 292 293 If RASTER_MULTISAMPLE_EXT is enabled, a fragment's coverage is reduced 294 from RASTER_SAMPLES_EXT bits to a single bit, where the new "color 295 coverage" is 1 if any bit in the fragment's coverage is on, and 0 296 otherwise. If the color coverage is 0, then blending and writing to the 297 framebuffer are not performed for that sample. 298 299 300Additions to Chapter 18 of the OpenGL 4.3 (Compatibility Profile) Specification 301(Drawing, Reading, and Copying Pixels) 302 303 Modify Section 18.1.3 (Pixel Rectangle Multisample Rasterization) 304 305 If MULTISAMPLE is enabled and MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is TRUE, 306 then pixel rectangles are rasterized using the following algorithm. 307 308New Implementation Dependent State 309 310 Minimum 311 Get Value Type Get Command Value Description Sec. 312 --------- ------- ----------- ------- ------------------------ ------ 313 MAX_RASTER_SAMPLES_EXT Z+ GetIntegerv 2 Maximum number of raster 14.3.1 314 samples 315 316New State 317 318 Get Value Get Command Type Initial Value Description Sec. Attribute 319 --------- ----------- ---- ------------- ----------- ---- --------- 320 RASTER_MULTISAMPLE_EXT IsEnabled B FALSE Multisample Rasterization 14.3.1 enable/multisample 321 without multiple color 322 samples 323 RASTER_SAMPLES_EXT GetIntegerv Z+ 0 Number of raster samples 14.3.1 multisample 324 325 RASTER_FIXED_SAMPLE_- GetBooleanv B FALSE Require same sample 14.3.1 multisample 326 LOCATIONS_EXT locations 327 MULTISAMPLE_RASTERIZATION_- GetBooleanv B FALSE Whether multisample 14.3.1 - 328 ALLOWED_EXT rasterization can be used 329 EFFECTIVE_RASTER_SAMPLES_EXT GetIntegerv Z+ 0 How many samples are used 14.3.1 - 330 for rasterization and 331 fragment operations 332 333Additions to the AGL/GLX/WGL Specifications 334 335 None. 336 337GLX Protocol 338 339 None. 340 341Modifications to the OpenGL Shading Language Specification, Version 4.30 342 343 Modify Section 7.1 (Built-In Language Variables), p. 118 344 345 For both the input array gl_SampleMaskIn[] and the output array 346 gl_SampleMask[], bit B of mask M (gl_SampleMaskIn[M] or gl_SampleMask[M]) 347 corresponds to sample 32*M+B. These arrays have ceil(s/32) elements, where 348 s is the maximum number of color or raster samples supported by the 349 implementation. 350 351 352Interactions with OpenGL ES 3.0 353 354 For OpenGL ES, remove references to images, bitmaps and GetDoublev. 355 Disregard references to POINT_SMOOTH, LINE_SMOOTH and POLYGON_SMOOTH. 356 357 Omit changes to Section 14.8.0.1 (Bitmap Multisample Rasterization). 358 Also, omit changes to Section 18.1.3 (Pixel Rectangle Multisample Rasterization). 359 360 Since OpenGL ES does not support enabling/disabling MULTISAMPLE rasterization 361 via MULTISAMPLE, read all occurrences of MULTISAMPLE as if it was enabled. 362 363 364Dependencies on OES_sample_shading 365 366 If this extension is implemented on OpenGL ES and OES_sample_shading 367 is not supported, omit changes to Section 3.3.1 (Sample Shading). 368 369 370Dependencies on OES_sample_variables 371 If this extension is implemented on OpenGL ES and OES_sample_variables 372 is not supported, omit changes to Section 3.9.2 (Shader Inputs; 373 Shader Outputs). 374 375 376Dependencies on EXT_depth_bounds_test 377 378 If EXT_depth_bounds_test is not supported, remove the error check for the 379 depth bounds test enable. 380 381Errors 382 383 INVALID_OPERATION is generated by Draw commands if RASTER_MULTISAMPLE_EXT 384 is enabled and any of the following is true: 385 386 - the value of RASTER_SAMPLES_EXT is zero 387 - the depth, stencil, or depth bounds test is enabled 388 - a multisample draw framebuffer is bound (SAMPLE_BUFFERS is one) 389 390 INVALID_VALUE is generated by RasterSamplesEXT if <samples> is greater 391 than the value of MAX_RASTER_SAMPLES_EXT. 392 393Issues 394 395 (1) What is the interaction with sample shading? 396 397 RESOLVED: Sample shading requires "max(ceil(mss * samples), 1)" shader 398 invocations. Since <samples> must be one when using this feature, an 399 implementation is still only required to shade once. However, in case this 400 functionality were supported with more than one color sample, we don't 401 require shading at more than one sample. 402 403 (2) Where are attributes sampled? 404 405 RESOLVED: They are sampled as if normal multisampling were in effect with 406 the same sample pattern. i.e. attributes can be sampled at the center or 407 at the centroid, depending on what the shader requests. 408 409 (3) During multisample rasterization, what are the values of the GLSL 410 built-in variables gl_SampleMaskIn[], gl_SampleMask[], gl_SampleID, 411 gl_NumSamples, gl_SamplePosition? 412 413 RESOLVED: There are RASTER_SAMPLES_EXT bits in gl_SampleMaskIn and 414 gl_SampleMask. gl_SampleID and gl_NumSamples continue to reflect the 415 number of samples in the framebuffer. 416 417 gl_SamplePosition is intended to reflect the location of the fragment being 418 shaded when MIN_SAMPLE_SHADING is enabled. However, since we don't require 419 MIN_SAMPLE_SHADING to work in conjunction with this extension, 420 gl_SamplePosition may just contain the location of the pixel center. 421 422 (4) How does multisample rasterization operate? 423 424 RESOLVED: Point shape, point anti-aliasing, line smooth, etc. will operate 425 the same when RASTER_MULTISAMPLE is enabled as they do when SAMPLE_BUFFERS 426 is one in the absence of this extension. 427 428 (5) When using both NV_fragment_coverage_to_color and EXT_raster_multisample 429 or NV_framebuffer_mixed_samples, how do these features interact? 430 431 RESOLVED: Both may be used simultaneously, and the coverage_to_color 432 functionality is applied before coverage reduction in the pipeline. This 433 means the full raster sample mask will be written to the color buffer, not 434 the reduced color sample mask. 435 436 437Revision History 438 439 Revision 2, 2015/03/27 440 - Add ES interactions 441 442 Revision 1, September 12, 2014 (jbolz, pbrown, mheyer) 443 444 Internal spec development. 445