daniel@transgaming.com | 559f51c | 2011-04-06 18:45:47 +0000 | [diff] [blame] | 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 |