1Name 2 3 NV_framebuffer_multisample_coverage 4 5Name Strings 6 7 GL_NV_framebuffer_multisample_coverage 8 9Contact 10 11 Mike Strauss, NVIDIA Corporation (mstrauss 'at' nvidia.com) 12 13Status 14 15 Shipping in NVIDIA Release 95 drivers (November 2006) 16 17 Functionality supported by GeForce 8800 18 19Version 20 21 Last Modified Date: May 31, 2008 22 Revision #9 23 24Number 25 26 336 27 28Dependencies 29 30 Requires GL_EXT_framebuffer_object. 31 32 Requires GL_EXT_framebuffer_blit. 33 34 Requires GL_EXT_framebuffer_multisample. 35 36 Written based on the wording of the OpenGL 1.5 specification. 37 38Overview 39 40 This extension extends the EXT_framebuffer_multisample 41 specification by providing a new function, 42 RenderBufferStorageMultisampleCoverageNV, that distinguishes 43 between color samples and coverage samples. 44 45 EXT_framebuffer_multisample introduced the function 46 RenderbufferStorageMultisampleEXT as a method of defining the 47 storage parameters for a multisample render buffer. This function 48 takes a <samples> parameter. Using rules provided by the 49 specification, the <samples> parameter is resolved to an actual 50 number of samples that is supported by the underlying hardware. 51 EXT_framebuffer_multisample does not specify whether <samples> 52 refers to coverage samples or color samples. 53 54 This extension adds the function 55 RenderbufferStorageMultisamplCoverageNV, which takes a 56 <coverageSamples> parameter as well as a <colorSamples> parameter. 57 These two parameters give developers more fine grained control over 58 the quality of multisampled images. 59 60IP Status 61 62 No known IP issues. 63 64New Procedures and Functions 65 66 void RenderbufferStorageMultisampleCoverageNV( 67 enum target, sizei coverageSamples, 68 sizei colorSamples, enum internalformat, 69 sizei width, sizei height); 70 71New Tokens 72 73 Accepted by the <pname> parameter of GetRenderbufferParameterivEXT: 74 75 RENDERBUFFER_COVERAGE_SAMPLES_NV 0x8CAB 76 RENDERBUFFER_COLOR_SAMPLES_NV 0x8E10 77 78 79 Accepted by the <pname> parameter of GetIntegerv: 80 81 MAX_MULTISAMPLE_COVERAGE_MODES_NV 0x8E11 82 MULTISAMPLE_COVERAGE_MODES_NV 0x8E12 83 84Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) 85 86 None. 87 88Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 89 90 None. 91 92Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment 93Operations and the Frame Buffer) 94 95 Modification to 4.4.2.1 (Renderbuffer Objects) 96 97 Add, just above the definition of RenderbufferStorageMultisampleEXT: 98 99 "The command 100 101 void RenderbufferStorageMultisampleCoverageNV( 102 enum target, sizei coverageSamples, 103 sizei colorSamples, enum internalformat, 104 sizei width, sizei height); 105 106 establishes the data storage, format, dimensions, number of coverage 107 samples, and number of color samples of a renderbuffer object's 108 image. <target> must be RENDERBUFFER_EXT. <internalformat> must be 109 RGB, RGBA, DEPTH_COMPONENT, STENCIL_INDEX, or one of the internal 110 formats from table 3.16 or table 2.nnn that has a base internal 111 format of RGB, RGBA, DEPTH_COMPONENT, or STENCIL_INDEX. <width> 112 and <height> are the dimensions in pixels of the renderbuffer. If 113 either <width> or <height> is greater than 114 MAX_RENDERBUFFER_SIZE_EXT, the error INVALID_VALUE is generated. If 115 the GL is unable to create a data store of the requested size, the 116 error OUT_OF_MEMORY is generated. 117 118 Upon success, RenderbufferStorageMultisampleCoverageNV deletes any 119 existing data store for the renderbuffer image and the contents of 120 the data store after calling 121 RenderbufferStorageMultisampleCoverageNV are undefined. 122 RENDERBUFFER_WIDTH_EXT is set to <width>, RENDERBUFFER_HEIGHT_EXT 123 is set to <height>, and RENDERBUFFER_INTERNAL_FORMAT_EXT is set to 124 <internalformat>. 125 126 If <coverageSamples> is zero, then RENDERBUFFER_COVERAGE_SAMPLES_NV 127 is set to zero. Otherwise <coverageSamples> represents a request 128 for a desired minimum number of coverage samples. Since different 129 implementations may support different coverage sample counts for 130 multisampled rendering, the actual number of coverage samples 131 allocated for the renderbuffer image is implementation dependent. 132 However, the resulting value for RENDERBUFFER_COVERAGE_SAMPLES_NV is 133 guaranteed to be greater than or equal to <coverageSamples> and no 134 more than the next larger coverage sample count supported by the 135 implementation. 136 137 If <colorSamples> is zero then RENDERBUFFER_COLOR_SAMPLES_NV is set 138 to zero. Otherwise, <colorSamples> represents a request for a 139 desired minimum number of colors samples. Since different 140 implementations may support different color sample counts for 141 multisampled rendering, the actual number of color samples 142 allocated for the renderbuffer image is implementation dependent. 143 Furthermore, a given implementation may support different color 144 sample counts for each supported coverage sample count. The 145 resulting value for RENDERBUFFER_COLOR_SAMPLES_NV is determined 146 after resolving the value for RENDERBUFFER_COVERAGE_SAMPLES_NV. 147 If the requested color sample count exceeds the maximum number of 148 color samples supported by the implementation given the value of 149 RENDERBUFFER_COVERAGE_SAMPLES_NV, the implementation will set 150 RENDERBUFFER_COLOR_SAMPLES_NV to the highest supported value. 151 Otherwise, the resulting value for RENDERBUFFER_COLOR_SAMPLES_NV is 152 guaranteed to be greater than or equal to <colorSamples> and no 153 more than the next larger color sample count supported by the 154 implementation given the value of RENDERBUFFER_COVERAGE_SAMPLES_NV. 155 156 If <colorSamples> is greater than <coverageSamples>, the error 157 INVALID_VALUE is generated. 158 159 If <coverageSamples> or <colorSamples> is greater than 160 MAX_SAMPLES_EXT, the error INVALID_VALUE is generated. 161 162 If <coverageSamples> is greater than zero, and <colorSamples> is 163 zero, RENDERBUFFER_COLOR_SAMPLES_NV is set to an implementation 164 dependent value based on RENDERBUFFER_COVERAGE_SAMPLES_NV. 165 166 An implementation may only support a subset of the possible 167 combinations of coverage samples and color samples. Requests for 168 combinations not supported by the implementation are resolved to 169 a supported combination using the rules above. The number of 170 supported combinations is MAX_MULTISAMPLE_COVERAGE_MODES_NV. 171 MULTISAMPLE_COVERAGE_MODES_NV is an array of 172 MAX_MULTISAMPLE_COVERAGE_MODES_NV pairs of integers representing 173 the combinations of coverage samples and color samples supported 174 by the implementation. The first integer in each pair corresponds 175 to coverage samples, while the second corresponds to color samples. 176 177 Modify the definition of RenderbufferStorageMultisampleEXT as 178 follows: 179 180 "The command 181 182 void RenderbufferStorageMultisampleEXT( 183 enum target, sizei samples, 184 enum internalformat, 185 sizei width, sizei height); 186 187 is equivalent to calling 188 189 RenderbufferStorageMultisampleCoverageNV(target, samples, 0, 190 internalforamt, width, height). 191 192 Modification to 4.4.4.2 (Framebuffer Completeness) 193 194 Modify the RENDERBUFFER_SAMPLES_EXT entry in the bullet list: 195 196 * The value of RENDERBUFFER_COVERAGE_SAMPLES_NV is the same for all 197 attached images. 198 { FRAMEBUFFER_INCOMPLETE_MULTISAMPLE } 199 200 Add an entry to the bullet list: 201 202 * The value of RENDERBUFFER_COLOR_SAMPLES_NV is the same for all 203 attached images. 204 { FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_EXT } 205 206Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) 207 208 None. 209 210Additions to Chapter 6 of the OpenGL 2.0 Specification (State and 211State Requests) 212 213 None. 214 215Additions to Appendix A of the OpenGL 2.0 Specification (Invariance) 216 217 None. 218 219Errors 220 221 The error INVALID_OPERATION is generated if 222 RenderbufferStorageMultisampleCoverageNV is called and 223 <colorSamples> is greater than <coverageSamples> 224 225 The error INVALID_VALUE is generated if 226 RenderbufferStorageMultisampleCoverageNV is called and 227 <coverageSamples> is greater than MAX_SAMPLES_EXT. 228 229 The error INVALID_VALUE is generated if 230 RenderbufferStorageMultisampleCoverageNV is called and 231 <colorSamples> is greater than MAX_SAMPLES_EXT. 232 233New State 234 235(add to table 8.nnn, "Renderbuffers (state per renderbuffer object)") 236 237 Initial 238 Get Value Type Get Command Value Description Section Attribute 239 -------------------------------- ---- ----------------------------- ------- ------------------- ------------ --------- 240 RENDERBUFFER_COVERAGE_SAMPLES_NV Z+ GetRenderbufferParameterivEXT 0 Number of coverage 4.4.2.1 - 241 samples used by the 242 renderbuffer 243 RENDERBUFFER_COLOR_SAMPLES_NV Z+ GetRenderbufferParameterivEXT 0 Number of color 4.4.2.1 - 244 samples used by the 245 renderbuffer 246 247(modify RENDERBUFFER_SAMPLES_EXT entry in table 8.nnn) 248 249 Initial 250 Get Value Type Get Command Value Description Section Attribute 251 ------------------------ ---- ----------------------------- ------ ------------------- ------------ --------- 252 RENDERBUFFER_SAMPLES_EXT Z+ GetRenderbufferParameterivEXT 0 Alias for 4.4.2.1 - 253 RENDERBUFFER_- 254 COVERAGE_SAMPLES_NV 255 256New Implementation Dependent State 257 258 Minimum 259 Get Value Type Get Command Value Description Section Attribute 260 --------------------------------- --------- ----------- ------- ------------------------------------ ------- --------- 261 MAX_MULTISAMPLE_COVERAGE_MODES_NV Z+ GetIntegerv 0 Number of unique combinations of 4.4.2.1 - 262 <coverageSamples> and <colorSamples> 263 supported by the implementation. 264 MULTISAMPLE_COVERAGE_MODES_NV n * 2 x Z+ GetIntegerv - MAX_MULTISAMPLE_COVERAGE_MODES_NV (n) 4.4.2.1 - 265 pairs of integers. Each pair is 266 a unique combination of 267 <coverageSamples> and <colorSamples> 268 supported by the implementation. 269 270Issues 271 272 (1) How should RenderbufferStorageMultisampleEXT be layered on top 273 of RenderbufferStorageMultisampleCoverageNV? 274 275 RESOLVED. NVIDIA will expose this extension at the same time 276 that EXT_framebuffer_multisample is exposed, so there will not 277 be any issues with backward compatibility. However, some 278 developers choose not to use vendor specific extensions. These 279 developers should be able to make use of current and future 280 hardware that differentiates between color and coverage 281 samples. Since color samples are a subset of coverage samples, 282 the <samples> parameter to RenderbufferStorageMultisampleEXT 283 should be treated as a request for coverage samples. The 284 implementation is free to choose the number of color samples 285 used by the renderbuffer. 286 287 (2) <coverageSamples> is rounded up to the next highest 288 number of samples supported by the implementation. How 289 should <colorSamples> be rounded given that an implementation 290 may not support all combinations of <coverageSamples> and 291 <colorSamples>? 292 293 RESOLVED: It is a requirement that <coverageSamples> be 294 compatible with the <samples> parameter to 295 RenderbufferStorageMultisampleEXT. While it is desirable for 296 <colorSamples> to resolve the same way as <coverageSamples>, 297 this may not always be possible. An implementation may support 298 a different maximum number of color samples for each coverage 299 sample count. It would be confusing to set an error when 300 <colorSamples> exceeds the maximum supported number of color 301 samples for a given coverage sample count, because there 302 is no mechanism to query or predict this behavior. Therefore, 303 the implementation should round <colorSamples> down when it 304 exceeds the maximum number of color samples supported with the 305 given coverage sample count. Otherwise, <colorSamples> is 306 rounded up to the next highest number of color samples 307 supported by the implementation. 308 309 (3) EXT_framebuffer_multisample provides a way to query the maximum 310 number of samples supported by an implementation. Should a new 311 query mechanism be added so that an application can determine 312 the maximum number of color samples supported with a given 313 number of coverage samples? 314 315 RESOLVED: Yes. An application can use GetIntegerv to query 316 MAX_MULTISAMPLE_COVERAGE_MODES_NV. The result is the number of 317 unique combinations of <coverageSamples> and <colorSamples> that 318 are supported by the implementation. GetIntegerv can be used 319 with MULTISAMPLE_COVERAGE_MODES_NV to query these combinations. 320 The integer array is populated with 321 MAX_MULTISAMPLE_COVERAGE_MODES_NV pairs of integers, where each 322 pair describes a unique multisample coverage mode. The first 323 integer in each pair is the number of coverage samples and the 324 second integer is the number of color samples. An example is 325 below: 326 327 // Get the number of unique multisample coverage modes 328 glGetIntegerv(GL_MAX_MULTISAMPLE_COVERAGE_MODES_NV, &numModes); 329 330 // Allocate enough memory to store the array of modes 331 GLint *modes = (GLint*)malloc(2*numModes*sizeof(GLint)); 332 333 // Get the list of modes 334 glGetIntegerv(GL_MULTISAMPLE_COVERAGE_MODES_NV, modes); 335 336 // Print out all of the modes 337 for (i = 0; i < numModes; i++) { 338 printf("%d coverage samples, %d color samples\n", 339 modes[i*2+0], // coverage samples for mode i 340 modes[i*2+1]); // color samples for mode i 341 } 342 343Revision History 344 345 Rev. Date Author Changes 346 ---- -------- -------- -------------------------------------------- 347 7-9 05/31/08 mjk Miscellaneous typo fixes. 348 349 6 mstrauss Internal spec development. 350