1 Name 2 3 ANGLE_framebuffer_multisample 4 5 Name Strings 6 7 GL_ANGLE_framebuffer_multisample 8 9 Contributors 10 11 Contributors to EXT_framebuffer_multisample 12 Daniel Koch, TransGaming Inc. 13 Shannon Woods, TransGaming Inc. 14 Kenneth Russell, Google Inc. 15 Vangelis Kokkevis, Google Inc. 16 17 Contacts 18 19 Daniel Koch, TransGaming Inc. (daniel 'at' transgaming 'dot' com) 20 21 Status 22 23 Implemented in ANGLE ES2 24 25 Version 26 27 Last Modified Date: Aug 6, 2010 28 Author Revision: #3 29 30 Number 31 32 OpenGL ES Extension #84 33 34 Dependencies 35 36 Requires OpenGL ES 2.0. 37 38 Requires GL_ANGLE_framebuffer_blit (or equivalent functionality). 39 40 The extension is written against the OpenGL ES 2.0 specification. 41 42 OES_texture_3D affects the definition of this extension. 43 44 Overview 45 46 This extension extends the framebuffer object framework to 47 enable multisample rendering. 48 49 The new operation RenderbufferStorageMultisampleANGLE() allocates 50 storage for a renderbuffer object that can be used as a multisample 51 buffer. A multisample render buffer image differs from a 52 single-sample render buffer image in that a multisample image has a 53 number of SAMPLES that is greater than zero. No method is provided 54 for creating multisample texture images. 55 56 All of the framebuffer-attachable images attached to a framebuffer 57 object must have the same number of SAMPLES or else the framebuffer 58 object is not "framebuffer complete". If a framebuffer object with 59 multisample attachments is "framebuffer complete", then the 60 framebuffer object behaves as if SAMPLE_BUFFERS is one. 61 62 The resolve operation is affected by calling 63 BlitFramebufferANGLE (provided by the ANGLE_framebuffer_blit 64 extension) where the source is a multisample application-created 65 framebuffer object and the destination is a single-sample 66 framebuffer object (either application-created or window-system 67 provided). 68 69 New Procedures and Functions 70 71 void RenderbufferStorageMultisampleANGLE( 72 enum target, sizei samples, 73 enum internalformat, 74 sizei width, sizei height); 75 76 New Types 77 78 None. 79 80 New Tokens 81 82 Accepted by the <pname> parameter of GetRenderbufferParameteriv: 83 84 RENDERBUFFER_SAMPLES_ANGLE 0x8CAB 85 86 Returned by CheckFramebufferStatus: 87 88 FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_ANGLE 0x8D56 89 90 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 91 and GetFloatv: 92 93 MAX_SAMPLES_ANGLE 0x8D57 94 95 Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation) 96 97 Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) 98 99 Add to the last paragraph of 3.7.2 (Alternate Texture Image Specification) 100 (as modified by ANGLE_framebuffer_blit) the following: 101 102 "Calling CopyTexSubImage3DOES, CopyTexImage2D or CopyTexSubImage2D will 103 result in INVALID_OPERATION being generated if the object bound to 104 READ_FRAMEBUFFER_BINDING_ANGLE is "framebuffer complete" and the value 105 of SAMPLE_BUFFERS is greater than zero." 106 107 Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment 108 Operations 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_ANGLE 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 BlitFramebuffer 119 that was added by ANGLE_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 draw framebuffer is greater than zero, 127 no copy is performed and an INVALID_OPERATION error is generated. 128 129 If SAMPLE_BUFFERS for the read framebuffer is greater than zero and 130 <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT, no copy is 131 performed and an INVALID_OPERATION error is generated. 132 133 If SAMPLE_BUFFERS for the read framebuffer is greater than zero and 134 the format of the read and draw framebuffers are not identical, no 135 copy is performed and an INVALID_OPERATION error is generated. 136 137 If SAMPLE_BUFFERS for the read framebuffer is greater than zero, the 138 dimensions of the source and destination rectangles provided to 139 BlitFramebufferANGLE must be identical and must specify the complete 140 source and destination buffers, otherwise no copy is performed and 141 an INVALID_OPERATION error is generated." 142 143 Modification to 4.4.3 (Renderbuffer Objects) 144 145 Add, just above the definition of RenderbufferStorage: 146 147 "The command 148 149 void RenderbufferStorageMultisampleANGLE( 150 enum target, sizei samples, 151 enum internalformat, 152 sizei width, sizei height); 153 154 establishes the data storage, format, dimensions, and number of 155 samples of a renderbuffer object's image. <target> must be 156 RENDERBUFFER. <internalformat> must be one of the color-renderable, 157 depth-renderable, or stencil-renderable formats described in table 4.5. 158 <width> and <height> are the dimensions in pixels of the renderbuffer. If 159 either <width> or <height> is greater than the value of 160 MAX_RENDERBUFFER_SIZE, or if <samples> is greater than MAX_SAMPLES_ANGLE, 161 then the error INVALID_VALUE is generated. If OpenGL ES is unable to 162 create a data store of the requested size, the error OUT_OF_MEMORY 163 is generated. 164 165 Upon success, RenderbufferStorageMultisampleANGLE deletes any existing 166 data store for the renderbuffer image and the contents of the data 167 store after calling RenderbufferStorageMultisampleANGLE are undefined. 168 RENDERBUFFER_WIDTH is set to <width>, RENDERBUFFER_HEIGHT is 169 set to <height>, and RENDERBUFFER_INTERNAL_FORMAT is set to 170 <internalformat>. 171 172 If <samples> is zero, then RENDERBUFFER_SAMPLES_ANGLE is set to zero. 173 Otherwise <samples> represents a request for a desired minimum 174 number of samples. Since different implementations may support 175 different sample counts for multisampled rendering, the actual 176 number of samples allocated for the renderbuffer image is 177 implementation dependent. However, the resulting value for 178 RENDERBUFFER_SAMPLES_ANGLE is guaranteed to be greater than or equal 179 to <samples> and no more than the next larger sample count supported 180 by the implementation. 181 182 An OpenGL ES implementation may vary its allocation of internal component 183 resolution based on any RenderbufferStorageMultisampleANGLE parameter (except 184 target), but the allocation and chosen internal format must not be a 185 function of any other state and cannot be changed once they are 186 established. The actual resolution in bits of each component of the 187 allocated image can be queried with GetRenderbufferParameteriv." 188 189 Modify the definiton of RenderbufferStorage as follows: 190 191 "The command 192 193 void RenderbufferStorage(enum target, enum internalformat, 194 sizei width, sizei height); 195 196 is equivalent to calling RenderbufferStorageMultisampleANGLE with 197 <samples> equal to zero." 198 199 In section 4.4.5 (Framebuffer Completeness) in the subsection 200 titled "Framebuffer Completeness" add an entry to the bullet list: 201 202 * The value of RENDERBUFFER_SAMPLES_ANGLE is the same for all attached 203 images. 204 { FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_ANGLE } 205 206 Also add a paragraph to the end of the section after the definition 207 of CheckFramebufferStatus: 208 209 "The values of SAMPLE_BUFFERS and SAMPLES are derived from the 210 attachments of the currently bound framebuffer object. If the 211 current DRAW_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer complete", 212 then both SAMPLE_BUFFERS and SAMPLES are undefined. Otherwise, 213 SAMPLES is equal to the value of RENDERBUFFER_SAMPLES_ANGLE for the 214 attached images (which all must have the same value for 215 RENDERBUFFER_SAMPLES_ANGLE). Further, SAMPLE_BUFFERS is one if 216 SAMPLES is non-zero. Otherwise, SAMPLE_BUFFERS is zero. 217 218 Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special Functions) 219 220 221 Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State 222 Requests) 223 224 In section 6.1.3 (Enumeraged Queries), modify the third paragraph 225 of the description of GetRenderbufferParameteriv as follows: 226 227 "Upon successful return from GetRenderbufferParameteriv, if 228 <pname> is RENDERBUFFER_WIDTH, RENDERBUFFER_HEIGHT, 229 RENDERBUFFER_INTERNAL_FORMAT, or RENDERBUFFER_SAMPLES_ANGLE, then <params> 230 will contain the width in pixels, height in pixels, internal format, or 231 number of samples, respectively, of the image of the renderbuffer 232 currently bound to <target>." 233 234 235 Dependencies on ANGLE_framebuffer_blit 236 237 ANGLE_framebuffer_blit is required. Technically, ANGLE_framebuffer_blit 238 would not be required to support multisampled rendering, except for 239 the fact that it provides the only method of doing a multisample 240 resovle from a multisample renderbuffer. 241 242 Dependencies on OES_texture_3D 243 244 On an OpenGL ES implementation, in the absense of OES_texture_3D, 245 omit references to CopyTexSubImage3DOES. 246 247 Errors 248 249 The error INVALID_OPERATION is generated if ReadPixels or 250 CopyTex{Sub}Image* is called while READ_FRAMEBUFFER_BINDING_ANGLE 251 is non-zero, the read framebuffer is framebuffer complete, and the 252 value of SAMPLE_BUFFERS for the read framebuffer is greater than 253 zero. 254 255 If both the draw and read framebuffers are framebuffer complete and 256 the draw framebuffer has a value of SAMPLE_BUFFERS that is greater 257 than zero, then the error INVALID_OPERATION is generated if 258 BlitFramebufferANGLE is called. 259 260 If both the draw and read framebuffers are framebuffer complete and 261 the read framebuffer has a value of SAMPLE_BUFFERS that is greater 262 than zero, the error INVALID_OPERATION is generated if 263 BlitFramebufferANGLE is called and any of the following conditions 264 are true: 265 - <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT. 266 - the source or destination rectangles do not specify the entire 267 source or destination buffer. 268 269 If both the draw and read framebuffers are framebuffer complete and 270 either has a value of SAMPLE_BUFFERS that is greater than zero, then 271 the error INVALID_OPERATION is generated if BlitFramebufferANGLE is 272 called and the formats of the draw and read framebuffers are not 273 identical. 274 275 If either the draw or read framebuffer is framebuffer complete and 276 has a value of SAMPLE_BUFFERS that is greater than zero, then the 277 error INVALID_OPERATION is generated if BlitFramebufferANGLE is called 278 and the specified source and destination dimensions are not 279 identical. 280 281 If RenderbufferStorageMultisampleANGLE is called with <target> not 282 equal to RENDERBUFFER, the error INVALID_ENUM is generated. 283 284 If RenderbufferStorageMultisampleANGLE is called with an 285 <internalformat> that is not listed as one of the color-, depth- 286 or stencil-renderable formats in Table 4.5, then the error 287 INVALID_ENUM is generated. 288 289 If RenderbufferStorageMultisampleANGLE is called with <width> or 290 <height> greater than MAX_RENDERBUFFER_SIZE, then the error 291 INVALID_VALUE is generated. 292 293 If RenderbufferStorageMultisampleANGLE is called with a value of 294 <samples> that is greater than MAX_SAMPLES_ANGLE or less than zero, 295 then the error INVALID_VALUE is generated. 296 297 The error OUT_OF_MEMORY is generated when 298 RenderbufferStorageMultisampleANGLE cannot create storage of the 299 specified size. 300 301 New State 302 303 Add to table 6.22 (Renderbuffer State) 304 305 Get Value Type Get Command Initial Value Description Section 306 ------------------------------- ------ -------------------------- ------------- -------------------- ------- 307 RENDERBUFFER_SAMPLES_ANGLE Z+ GetRenderbufferParameteriv 0 number of samples 4.4.3 308 309 310 Add to table 6.yy (Framebuffer Dependent Vaues) (added by 311 ANGLE_framebuffer_blit), the following new framebuffer dependent state. 312 313 Get Value Type Get Command Minimum Value Description Section 314 ----------------- ---- ----------- ------------- ------------------- ------- 315 MAX_SAMPLES_ANGLE Z+ GetIntegerv 1 Maximum number of 4.4.3 316 samples supported 317 for multisampling 318 319 320 321 Issues 322 323 Issues from EXT_framebuffer_multisample have been removed. 324 325 1) What should we call this extension? 326 327 Resolved: ANGLE_framebuffer_blit. 328 329 This extension is a result of a collaboration between Google and 330 TransGaming for the open-source ANGLE project. Typically one would 331 label a multi-vendor extension as EXT, but EXT_framebuffer_mulitsample 332 is already the name for this on Desktop GL. Additionally this 333 isn't truely a multi-vendor extension because there is only one 334 implementation of this. We'll follow the example of the open-source 335 MESA project which uses the project name for the vendor suffix. 336 337 2) How does this extension differ from EXT_framebuffer_multisample? 338 339 This is designed to be a proper subset of EXT_framebuffer_multisample 340 functionality as applicable to OpenGL ES 2.0. 341 342 Functionality that is unchanged: 343 - creation of multisample renderbuffers. 344 - whole buffer multi-sample->single-sample resolve. 345 - no format conversions, stretching or flipping supported on multisample blits. 346 347 Additional restrictions on BlitFramebufferANGLE: 348 - multisample resolve is only supported on color buffers. 349 - no blits to multisample destinations (no single->multi or multi-multi). 350 - only entire buffers can be resolved. 351 352 Revision History 353 354 Revision 1, 2010/07/08 355 - copied from revision 7 of EXT_framebuffer_multisample 356 - removed language that was not relevant to ES2 357 - rebase changes against the Open GL ES 2.0 specification 358 - added ANGLE-specific restrictions 359 Revision 2, 2010/07/19 360 - fix missing error code 361 Revision 3, 2010/08/06 362 - add additional contributors, update implementation status 363 - disallow negative samples 364
