1Name 2 3 NV_framebuffer_multisample 4 5Name Strings 6 7 GL_NV_framebuffer_multisample 8 9Contributors 10 11 Contributors to EXT_framebuffer_multisample 12 Contributors from ANGLE_framebuffer_multisample 13 14 Gregory Roth, NVIDIA 15 Mathias Heyer, NVIDIA 16 Xi Chen, NVIDIA 17 18Contacts 19 20 Mathias Heyer, NVIDIA (mheyer 'at' nvidia 'dot' com) 21 22Status 23 24 Complete 25 26Version 27 28 Last Modified Date: March 03, 2015 29 Author Revision: #5 30 31Number 32 33 OpenGL ES Extension #143 34 35Dependencies 36 37 Requires OpenGL ES 2.0. 38 39 Requires GL_NV_framebuffer_blit. 40 41 The extension is written against the OpenGL ES 2.0.25 42 (November 2, 2010) specification. 43 44 OES_texture_3D affects the definition of this extension. 45 NV_texture_array affects the definition of this extension. 46 47 This extension interacts with OpenGL ES 3.0 and later versions. 48 49Overview 50 51 This extension extends the framebuffer object framework to 52 enable multisample rendering. 53 54 The new operation RenderbufferStorageMultisampleNV() allocates 55 storage for a renderbuffer object that can be used as a multisample 56 buffer. A multisample render buffer image differs from a 57 single-sample render buffer image in that a multisample image has a 58 number of SAMPLES that is greater than zero. No method is provided 59 for creating multisample texture images. 60 61 All of the framebuffer-attachable images attached to a framebuffer 62 object must have the same number of SAMPLES or else the framebuffer 63 object is not "framebuffer complete". If a framebuffer object with 64 multisample attachments is "framebuffer complete", then the 65 framebuffer object behaves as if SAMPLE_BUFFERS is one. 66 67 A resolve operation is executed by calling 68 BlitFramebufferNV (provided by the NV_framebuffer_blit 69 extension) where the source is a multisample framebuffer object 70 and the destination is a single-sample framebuffer object. 71 Source and destination framebuffer may be either application-created 72 or window-system provided. 73 74New Procedures and Functions 75 76 void RenderbufferStorageMultisampleNV( 77 enum target, sizei samples, 78 enum internalformat, 79 sizei width, sizei height); 80 81New Tokens 82 83 Accepted by the <pname> parameter of GetRenderbufferParameteriv: 84 85 RENDERBUFFER_SAMPLES_NV 0x8CAB 86 87 Returned by CheckFramebufferStatus: 88 89 FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_NV 0x8D56 90 91 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 92 and GetFloatv: 93 94 MAX_SAMPLES_NV 0x8D57 95 96Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) 97 98 Add to the last paragraph of 3.7.2 (Alternate Texture Image Specification) 99 (as modified by NV_framebuffer_blit) the following: 100 101 "Calling CopyTexSubImage3DOES, CopyTexSubImage3DNV, 102 CopyTexImage2D or CopyTexSubImage2D will result in INVALID_OPERATION 103 being generated if the object bound to READ_FRAMEBUFFER_BINDING_NV 104 is "framebuffer complete" and the value of SAMPLE_BUFFERS is greater 105 than zero." 106 107Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment 108Operations and the Framebuffer) 109 110 Add to 4.3.1 (Reading Pixels), right before the subsection titled 111 "Obtaining Pixels from the Framebuffer": 112 113 "ReadPixels generates INVALID_OPERATION if READ_FRAMEBUFFER_BINDING_NV 114 (section 4.4) is non-zero, the read framebuffer is framebuffer 115 complete, and the value of SAMPLE_BUFFERS for the read framebuffer 116 is greater than zero." 117 118 In 4.3.2 (Copying Pixels), add to the section describing BlitFramebufferNV 119 that was added by NV_framebuffer_blit. 120 121 "If SAMPLE_BUFFERS for the read framebuffer is greater than zero and 122 SAMPLE_BUFFERS for the draw framebuffer is zero, the samples 123 corresponding to each pixel location in the source are converted to 124 a single sample before being written to the destination. 125 126 If SAMPLE_BUFFERS for the read framebuffer is zero and 127 SAMPLE_BUFFERS for the draw framebuffer is greater than zero, the 128 value of the source sample is replicated in each of the destination 129 samples. 130 131 If SAMPLE_BUFFERS for both the read and draw framebuffers are 132 greater than zero, and the values of SAMPLES for the read and draw 133 framebuffers are identical, the samples are copied without 134 modification from the read framebuffer to the draw framebuffer. 135 Otherwise, no copy is performed and an INVALID_OPERATION error is 136 generated. 137 138 If SAMPLE_BUFFERS for the read framebuffer is greater than zero and 139 the format of the read and draw framebuffers are not identical, no 140 copy is performed and an INVALID_OPERATION error is generated. 141 142 Furthermore, if SAMPLE_BUFFERS for either the read framebuffer or 143 draw framebuffer is greater than zero, no copy is performed and an 144 INVALID_OPERATION error is generated if the dimensions of the source 145 and destination rectangles provided to BlitFramebufferNV are not 146 identical, or if the formats of the read and draw framebuffers are 147 not identical. 148 149 Modification to 4.4.3 (Renderbuffer Objects) 150 151 Add, just above the definition of RenderbufferStorage: 152 153 "The command 154 155 void RenderbufferStorageMultisampleNV( 156 enum target, sizei samples, 157 enum internalformat, 158 sizei width, sizei height); 159 160 establishes the data storage, format, dimensions, and number of 161 samples of a renderbuffer object's image. <target> must be 162 RENDERBUFFER. <internalformat> must be one of the color-renderable, 163 depth-renderable, or stencil-renderable formats described in table 4.5. 164 <width> and <height> are the dimensions in pixels of the renderbuffer. If 165 either <width> or <height> is greater than the value of 166 MAX_RENDERBUFFER_SIZE, or if <samples> is greater than MAX_SAMPLES_NV, 167 then the error INVALID_VALUE is generated. If OpenGL ES is unable to 168 create a data store of the requested size, the error OUT_OF_MEMORY 169 is generated. 170 171 Upon success, RenderbufferStorageMultisampleNV deletes any existing 172 data store for the renderbuffer image and the contents of the data 173 store after calling RenderbufferStorageMultisampleNV are undefined. 174 RENDERBUFFER_WIDTH is set to <width>, RENDERBUFFER_HEIGHT is 175 set to <height>, and RENDERBUFFER_INTERNAL_FORMAT is set to 176 <internalformat>. 177 178 If <samples> is zero, then RENDERBUFFER_SAMPLES_NV is set to zero. 179 Otherwise <samples> represents a request for a desired minimum 180 number of samples. Since different implementations may support 181 different sample counts for multisampled rendering, the actual 182 number of samples allocated for the renderbuffer image is 183 implementation dependent. However, the resulting value for 184 RENDERBUFFER_SAMPLES_NV is guaranteed to be greater than or equal 185 to <samples> and no more than the next larger sample count supported 186 by the implementation. 187 188 An OpenGL ES implementation may vary its allocation of internal component 189 resolution based on any RenderbufferStorageMultisampleNV parameter (except 190 target), but the allocation and chosen internal format must not be a 191 function of any other state and cannot be changed once they are 192 established. The actual resolution in bits of each component of the 193 allocated image can be queried with GetRenderbufferParameteriv." 194 195 Modify the definiton of RenderbufferStorage as follows: 196 197 "The command 198 199 void RenderbufferStorage(enum target, enum internalformat, 200 sizei width, sizei height); 201 202 is equivalent to calling RenderbufferStorageMultisampleNV with 203 <samples> equal to zero." 204 205 In section 4.4.5 (Framebuffer Completeness) in the subsection 206 titled "Framebuffer Completeness" add an entry to the bullet list: 207 208 * The value of RENDERBUFFER_SAMPLES_NV is the same for all attached 209 images. 210 { FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_NV } 211 212 Also add a paragraph to the end of the section after the definition 213 of CheckFramebufferStatus: 214 215 "The values of SAMPLE_BUFFERS and SAMPLES are derived from the 216 attachments of the currently bound framebuffer object. If the 217 current DRAW_FRAMEBUFFER_BINDING_NV is not "framebuffer complete", 218 then both SAMPLE_BUFFERS and SAMPLES are undefined. Otherwise, 219 SAMPLES is equal to the value of RENDERBUFFER_SAMPLES_NV for the 220 attached images (which all must have the same value for 221 RENDERBUFFER_SAMPLES_NV). Further, SAMPLE_BUFFERS is one if 222 SAMPLES is non-zero. Otherwise, SAMPLE_BUFFERS is zero. 223 224Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State 225Requests) 226 227 In section 6.1.3 (Enumeraged Queries), modify the third paragraph 228 of the description of GetRenderbufferParameteriv as follows: 229 230 "Upon successful return from GetRenderbufferParameteriv, if 231 <pname> is RENDERBUFFER_WIDTH, RENDERBUFFER_HEIGHT, 232 RENDERBUFFER_INTERNAL_FORMAT, or RENDERBUFFER_SAMPLES_NV, then <params> 233 will contain the width in pixels, height in pixels, internal format, or 234 number of samples, respectively, of the image of the renderbuffer 235 currently bound to <target>." 236 237Dependencies on OpenGL ES 3.0 and later 238 239 If OpenGL ES 3.0 or later is supported, the described modifications to 240 language for BlitFramebufferNV also apply to BlitFramebuffer: 241 242 (Add to the end of the section describing BlitFramebuffer) 243 244 "If SAMPLE_BUFFERS for the read framebuffer is zero and 245 SAMPLE_BUFFERS for the draw framebuffer is greater than zero, the 246 value of the source sample is replicated in each of the destination 247 samples. 248 249 If SAMPLE_BUFFERS for both the read and draw framebuffers are 250 greater than zero, and the values of SAMPLES for the read and draw 251 framebuffers are identical, the samples are copied without 252 modification from the read framebuffer to the draw framebuffer. 253 Otherwise, no copy is performed and an INVALID_OPERATION error is 254 generated." 255 256 (In the error list for BlitFramebuffer, modify the item "An 257 INVALID_OPERATION error is generated if the draw framebuffer is 258 multisampled.") 259 260 * An INVALID_OPERATION error is generated if both the read and 261 draw buffers are multisampled, and SAMPLE_BUFFERS for the read and 262 draw buffers are not identical. 263 264 (In the error list for BlitFramebuffer, add to the list) 265 266 * An INVALID_OPERATION error is generated if either the read or draw 267 buffer is multisampled, and the formats of the read and draw 268 framebuffers are not identical. 269 270Dependencies on NV_framebuffer_blit 271 272 NV_framebuffer_blit is required. Technically, NV_framebuffer_blit 273 would not be required to support multisampled rendering, except for 274 the fact that it provides the only method of doing a multisample 275 resovle from a multisample renderbuffer. 276 277Dependencies on OES_texture_3D and NV_texture_array 278 279 On an OpenGL ES implementation, in the absense of OES_texture_3D or 280 NV_texture_array, omit references to CopyTexSubImage3DOES and 281 CopyTexSubImage3DNV, respectively. 282 283 284Errors 285 286 The error INVALID_OPERATION is generated if ReadPixels or 287 CopyTex{Sub}Image* is called while READ_FRAMEBUFFER_BINDING_NV 288 is non-zero, the read framebuffer is framebuffer complete, and the 289 value of SAMPLE_BUFFERS for the read framebuffer is greater than 290 zero. 291 292 If both the draw and read framebuffers are framebuffer complete and 293 both have a value of SAMPLE_BUFFERS that is greater than zero, then 294 the error INVALID_OPERATION is generated if BlitFramebufferNV is 295 called and the values of SAMPLES for the draw and read framebuffers 296 do not match. 297 298 If both the draw and read framebuffers are framebuffer complete and 299 either has a value of SAMPLE_BUFFERS that is greater than zero, then 300 the error INVALID_OPERATION is generated if BlitFramebufferNV is 301 called and the formats of the draw and read framebuffers are not 302 identical. 303 304 If either the draw or read framebuffer is framebuffer complete and 305 has a value of SAMPLE_BUFFERS that is greater than zero, then the 306 error INVALID_OPERATION is generated if BlitFramebufferNV is called 307 and the specified source and destination dimensions are not 308 identical. 309 310 If RenderbufferStorageMultisampleNV is called with <target> not 311 equal to RENDERBUFFER, the error INVALID_ENUM is generated. 312 313 If RenderbufferStorageMultisampleNV is called with an 314 <internalformat> that is not listed as one of the color-, depth- 315 or stencil-renderable formats in Table 4.5, then the error 316 INVALID_ENUM is generated. 317 318 If RenderbufferStorageMultisampleNV is called with <width> or 319 <height> greater than MAX_RENDERBUFFER_SIZE, then the error 320 INVALID_VALUE is generated. 321 322 If RenderbufferStorageMultisampleNV is called with a value of 323 <samples> that is greater than MAX_SAMPLES_NV or less than zero, 324 then the error INVALID_VALUE is generated. 325 326 The error OUT_OF_MEMORY is generated when 327 RenderbufferStorageMultisampleNV cannot create storage of the 328 specified size. 329 330New State 331 332 Add to table 6.23 (Renderbuffer State) 333 334 Get Value Type Get Command Initial Value Description Section 335 ------------------------------- ------ -------------------------- ------------- -------------------- ------- 336 RENDERBUFFER_SAMPLES_NV Z+ GetRenderbufferParameteriv 0 number of samples 4.4.3 337 338 339 Add to table 6.21 (Framebuffer Dependent Values) 340 the following new framebuffer dependent state. 341 342 Get Value Type Get Command Minimum Value Description Section 343 ----------------- ---- ----------- ------------- ------------------- ------- 344 MAX_SAMPLES_NV Z+ GetIntegerv 1 Maximum number of 4.4.3 345 samples supported 346 for multisampling 347 348 349 350Issues 351 352 Issues from EXT_framebuffer_multisample have been removed. 353 354 1) How is this extension different from Halti and ARB_framebuffer_object ? 355 - this extension offers the same MSAA functionality as in 356 ARB_framebuffer_object 357 - it is a superset of Halti in that: 358 a) SINGLE-->MSAA and MSAA-->MSAA blits are possible 359 b) the blit region may be relocated during the blit 360 361Revision History 362 Revision 5, 2015/03/03 363 - add interaction with OpenGL ES 3.0 and later 364 Revision 4, 2012/08/31 365 - add interaction with NV_texture_array 366 Revision 3, 2012/08/29 367 - consolidate contributors list 368 - be more explicit about the specification version the text is written against 369 Revision 2, 2012/08/15 370 - explicitly state that resolve blits from the window system provided framebuffer 371 are possible 372 - fix references to table 6.21 and table 6.23 373 Revision 1, 2012/05/15 374 - copied from revision 3 of ANGLE_framebuffer_multisample 375 - re-inserted missing functionality of EXT_framebuffer_blit 376 377