The Tor Browser / file comparison
comparison: gfx/angle/extensions/ANGLE_framebuffer_blit.txt
gfx/angle/extensions/ANGLE_framebuffer_blit.txt
- changeset 0
- 6474c204b198
equal
deleted
inserted
replaced
| -1:000000000000 | 0:9c8d37187867 |
|---|---|
| 1 Name | |
| 2 | |
| 3 ANGLE_framebuffer_blit | |
| 4 | |
| 5 Name Strings | |
| 6 | |
| 7 GL_ANGLE_framebuffer_blit | |
| 8 | |
| 9 Contributors | |
| 10 | |
| 11 Contributors to EXT_framebuffer_blit | |
| 12 Daniel Koch, TransGaming Inc. | |
| 13 Shannon Woods, TransGaming Inc. | |
| 14 Kenneth Russell, Google Inc. | |
| 15 Vangelis Kokkevis, Google Inc. | |
| 16 | |
| 17 Contact | |
| 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: Sept 22, 2012 | |
| 28 Author Revision: 4 | |
| 29 | |
| 30 Number | |
| 31 | |
| 32 OpenGL ES Extension #83 | |
| 33 | |
| 34 Dependencies | |
| 35 | |
| 36 OpenGL ES 2.0 is required. | |
| 37 | |
| 38 The extension is written against the OpenGL ES 2.0 specification. | |
| 39 | |
| 40 OES_texture_3D affects the definition of this extension. | |
| 41 | |
| 42 Overview | |
| 43 | |
| 44 This extension modifies framebuffer objects by splitting the | |
| 45 framebuffer object binding point into separate DRAW and READ | |
| 46 bindings. This allows copying directly from one framebuffer to | |
| 47 another. In addition, a new high performance blit function is | |
| 48 added to facilitate these blits and perform some data conversion | |
| 49 where allowed. | |
| 50 | |
| 51 IP Status | |
| 52 | |
| 53 No known IP claims. | |
| 54 | |
| 55 New Procedures and Functions | |
| 56 | |
| 57 void BlitFramebufferANGLE(int srcX0, int srcY0, int srcX1, int srcY1, | |
| 58 int dstX0, int dstY0, int dstX1, int dstY1, | |
| 59 bitfield mask, enum filter); | |
| 60 | |
| 61 New Tokens | |
| 62 | |
| 63 Accepted by the <target> parameter of BindFramebuffer, | |
| 64 CheckFramebufferStatus, FramebufferTexture2D, FramebufferTexture3DOES, | |
| 65 FramebufferRenderbuffer, and | |
| 66 GetFramebufferAttachmentParameteriv: | |
| 67 | |
| 68 // (reusing the tokens from EXT_framebuffer_blit) | |
| 69 READ_FRAMEBUFFER_ANGLE 0x8CA8 | |
| 70 DRAW_FRAMEBUFFER_ANGLE 0x8CA9 | |
| 71 | |
| 72 Accepted by the <pname> parameters of GetIntegerv and GetFloatv: | |
| 73 | |
| 74 // (reusing the tokens from EXT_framebuffer_blit) | |
| 75 DRAW_FRAMEBUFFER_BINDING_ANGLE 0x8CA6 // alias FRAMEBUFFER_BINDING | |
| 76 READ_FRAMEBUFFER_BINDING_ANGLE 0x8CAA | |
| 77 | |
| 78 | |
| 79 Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) | |
| 80 | |
| 81 Change the last paragraph of section 3.7.2 (Alternate Texture Image | |
| 82 Specification Commands) to: | |
| 83 | |
| 84 "Calling CopyTexSubImage3DOES, CopyTexImage2D or CopyTexSubImage2D will | |
| 85 result in an INVALID_FRAMEBUFFER_OPERATION error if the object bound | |
| 86 to READ_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer complete" | |
| 87 (section 4.4.4.2)." | |
| 88 | |
| 89 Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment | |
| 90 Operations and the Framebuffer) | |
| 91 | |
| 92 Change the first word of Chapter 4 from "The" to "A". | |
| 93 | |
| 94 Append to the introduction of Chapter 4: | |
| 95 | |
| 96 "Conceptually, the GL has two active framebuffers; the draw | |
| 97 framebuffer is the destination for rendering operations, and the | |
| 98 read framebuffer is the source for readback operations. The same | |
| 99 framebuffer may be used for both drawing and reading. Section | |
| 100 4.4.1 describes the mechanism for controlling framebuffer usage." | |
| 101 | |
| 102 Modify the first sentence of the last paragraph of section 4.1.1 as follows: | |
| 103 | |
| 104 "While an application-created framebuffer object is bound to | |
| 105 DRAW_FRAMEBUFFER_ANGLE, the pixel ownership test always passes." | |
| 106 | |
| 107 Add to 4.3.1 (Reading Pixels), right before the subsection titled | |
| 108 "Obtaining Pixels from the Framebuffer": | |
| 109 | |
| 110 "Calling ReadPixels generates INVALID_FRAMEBUFFER_OPERATION if | |
| 111 the object bound to READ_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer | |
| 112 complete" (section 4.4.4.2). GetIntegerv generates an INVALID_OPERATION | |
| 113 error if the object bound to READ_FRAMEBUFFER_BINDING_ANGLE is not | |
| 114 framebuffer complete, or if the GL is using a framebuffer object | |
| 115 (i.e. READ_FRAMEBUFFER_BINDING_ANGLE is non-zero) and there is no color | |
| 116 attachment." | |
| 117 | |
| 118 Insert a new section 4.3.2 titled "Copying Pixels" and renumber the | |
| 119 subsequent sections. Add the following text: | |
| 120 | |
| 121 "BlitFramebufferANGLE transfers a rectangle of pixel values from one | |
| 122 region of the read framebuffer to another in the draw framebuffer. | |
| 123 | |
| 124 BlitFramebufferANGLE(int srcX0, int srcY0, int srcX1, int srcY1, | |
| 125 int dstX0, int dstY0, int dstX1, int dstY1, | |
| 126 bitfield mask, enum filter); | |
| 127 | |
| 128 <mask> is the bitwise OR of a number of values indicating which | |
| 129 buffers are to be copied. The values are COLOR_BUFFER_BIT, | |
| 130 DEPTH_BUFFER_BIT, and STENCIL_BUFFER_BIT, which are described in | |
| 131 section 4.2.3. The pixels corresponding to these buffers are | |
| 132 copied from the source rectangle, bound by the locations (srcX0, | |
| 133 srcY0) and (srcX1, srcY1), to the destination rectangle, bound by | |
| 134 the locations (dstX0, dstY0) and (dstX1, dstY1). The lower bounds | |
| 135 of the rectangle are inclusive, while the upper bounds are | |
| 136 exclusive. | |
| 137 | |
| 138 The actual region taken from the read framebuffer is limited to the | |
| 139 intersection of the source buffers being transferred, which may include | |
| 140 the color buffer, the depth buffer, and/or the stencil buffer depending on | |
| 141 <mask>. The actual region written to the draw framebuffer is limited to the | |
| 142 intersection of the destination buffers being written, which may include | |
| 143 the color buffer, the depth buffer, and/or the stencil buffer | |
| 144 depending on <mask>. Whether or not the source or destination regions are | |
| 145 altered due to these limits, the offset applied to pixels being transferred | |
| 146 is performed as though no such limits were present. | |
| 147 | |
| 148 Stretching and scaling during a copy are not supported. If the source | |
| 149 and destination rectangle dimensions do not match, no copy is | |
| 150 performed and an INVALID_OPERATION error is generated. | |
| 151 Because stretching is not supported, <filter> must be NEAREST and | |
| 152 no filtering is applied. | |
| 153 | |
| 154 Flipping during a copy is not supported. If either the source or | |
| 155 destination rectangle specifies a negative dimension, the error | |
| 156 INVALID_OPERATION is generated. If both the source and | |
| 157 destination rectangles specify a negative dimension for the same | |
| 158 direction, no reversal is required and the operation is supported. | |
| 159 | |
| 160 If the source and destination buffers are identical, and the | |
| 161 source and destination rectangles overlap, the result of the blit | |
| 162 operation is undefined. | |
| 163 | |
| 164 The pixel copy bypasses the fragment pipeline. The only fragment | |
| 165 operations which affect the blit are the pixel ownership test and | |
| 166 the scissor test. | |
| 167 | |
| 168 If a buffer is specified in <mask> and does not exist in both the | |
| 169 read and draw framebuffers, the corresponding bit is silently | |
| 170 ignored. | |
| 171 | |
| 172 Calling BlitFramebufferANGLE will result in an | |
| 173 INVALID_FRAMEBUFFER_OPERATION error if the objects bound to | |
| 174 DRAW_FRAMEBUFFER_BINDING_ANGLE and READ_FRAMEBUFFER_BINDING_ANGLE are | |
| 175 not "framebuffer complete" (section 4.4.4.2)." | |
| 176 | |
| 177 Calling BlitFramebufferANGLE will result in an INVALID_OPERATION | |
| 178 error if <mask> includes COLOR_BUFFER_BIT and the source and | |
| 179 destination color formats to not match. | |
| 180 | |
| 181 Calling BlitFramebufferANGLE will result in an INVALID_OPERATION | |
| 182 error if <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT | |
| 183 and the source and destination depth and stencil buffer formats do | |
| 184 not match. | |
| 185 | |
| 186 If <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT, only | |
| 187 complete buffers can be copied. If the source rectangle does not | |
| 188 specify the complete source buffer or the destination rectangle | |
| 189 (after factoring the scissor region, if applicable) does not specify | |
| 190 the complete destination buffer, an INVALID_OPERATION | |
| 191 error is generated. | |
| 192 | |
| 193 Modify the beginning of section 4.4.1 as follows: | |
| 194 | |
| 195 "The default framebuffer for rendering and readback operations is | |
| 196 provided by the windowing system. In addition, named framebuffer | |
| 197 objects can be created and operated upon. The namespace for | |
| 198 framebuffer objects is the unsigned integers, with zero reserved | |
| 199 by the GL for the default framebuffer. | |
| 200 | |
| 201 A framebuffer object is created by binding an unused name to | |
| 202 DRAW_FRAMEBUFFER_ANGLE or READ_FRAMEBUFFER_ANGLE. The binding is | |
| 203 effected by calling | |
| 204 | |
| 205 void BindFramebuffer(enum target, uint framebuffer); | |
| 206 | |
| 207 with <target> set to the desired framebuffer target and | |
| 208 <framebuffer> set to the unused name. The resulting framebuffer | |
| 209 object is a new state vector, comprising one set of the state values | |
| 210 listed in table 6.23 for each attachment point of the | |
| 211 framebuffer, set to the same initial values. There is one | |
| 212 color attachment point, plus one each | |
| 213 for the depth and stencil attachment points. | |
| 214 | |
| 215 BindFramebuffer may also be used to bind an existing | |
| 216 framebuffer object to DRAW_FRAMEBUFFER_ANGLE or | |
| 217 READ_FRAMEBUFFER_ANGLE. If the bind is successful no change is made | |
| 218 to the state of the bound framebuffer object, and any previous | |
| 219 binding to <target> is broken. | |
| 220 | |
| 221 If a framebuffer object is bound to DRAW_FRAMEBUFFER_ANGLE or | |
| 222 READ_FRAMEBUFFER_ANGLE, it becomes the target for rendering or | |
| 223 readback operations, respectively, until it is deleted or another | |
| 224 framebuffer is bound to the corresponding bind point. Calling | |
| 225 BindFramebuffer with <target> set to FRAMEBUFFER binds the | |
| 226 framebuffer to both DRAW_FRAMEBUFFER_ANGLE and READ_FRAMEBUFFER_ANGLE. | |
| 227 | |
| 228 While a framebuffer object is bound, GL operations on the target | |
| 229 to which it is bound affect the images attached to the bound | |
| 230 framebuffer object, and queries of the target to which it is bound | |
| 231 return state from the bound object. Queries of the values | |
| 232 specified in table 6.20 (Implementation Dependent Pixel Depths) | |
| 233 and table 6.yy (Framebuffer Dependent Values) are | |
| 234 derived from the framebuffer object bound to DRAW_FRAMEBUFFER_ANGLE. | |
| 235 | |
| 236 The initial state of DRAW_FRAMEBUFFER_ANGLE and READ_FRAMEBUFFER_ANGLE | |
| 237 refers to the default framebuffer provided by the windowing | |
| 238 system. In order that access to the default framebuffer is not | |
| 239 lost, it is treated as a framebuffer object with the name of 0. | |
| 240 The default framebuffer is therefore rendered to and read from | |
| 241 while 0 is bound to the corresponding targets. On some | |
| 242 implementations, the properties of the default framebuffer can | |
| 243 change over time (e.g., in response to windowing system events | |
| 244 such as attaching the context to a new windowing system drawable.)" | |
| 245 | |
| 246 Change the description of DeleteFramebuffers as follows: | |
| 247 | |
| 248 "<framebuffers> contains <n> names of framebuffer objects to be | |
| 249 deleted. After a framebuffer object is deleted, it has no | |
| 250 attachments, and its name is again unused. If a framebuffer that | |
| 251 is currently bound to one or more of the targets | |
| 252 DRAW_FRAMEBUFFER_ANGLE or READ_FRAMEBUFFER_ANGLE is deleted, it is as | |
| 253 though BindFramebuffer had been executed with the corresponding | |
| 254 <target> and <framebuffer> zero. Unused names in <framebuffers> | |
| 255 are silently ignored, as is the value zero." | |
| 256 | |
| 257 | |
| 258 In section 4.4.3 (Renderbuffer Objects), modify the first two sentences | |
| 259 of the description of FramebufferRenderbuffer as follows: | |
| 260 | |
| 261 "<target> must be DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE, or | |
| 262 FRAMEBUFFER. If <target> is FRAMEBUFFER, it behaves as | |
| 263 though DRAW_FRAMEBUFFER_ANGLE was specified. The INVALID_OPERATION | |
| 264 error is generated if the value of the corresponding binding is zero." | |
| 265 | |
| 266 In section 4.4.3 (Renderbuffer Objects), modify the first two sentences | |
| 267 of the description of FramebufferTexture2D as follows: | |
| 268 | |
| 269 "<target> must be DRAW_FRAMEBUFFER_ANGLE, | |
| 270 READ_FRAMEBUFFER_ANGLE, or FRAMEBUFFER. If <target> is | |
| 271 FRAMEBUFFER, it behaves as though DRAW_FRAMEBUFFER_ANGLE was | |
| 272 specified. The INVALID_OPERATION error is generated if the value of the | |
| 273 corresponding binding is zero." | |
| 274 | |
| 275 In section 4.4.5 (Framebuffer Completeness), modify the first sentence | |
| 276 of the description of CheckFramebufferStatus as follows: | |
| 277 | |
| 278 "If <target> is not DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or | |
| 279 FRAMEBUFFER, the error INVALID_ENUM is generated. If <target> is | |
| 280 FRAMEBUFFER, it behaves as though DRAW_FRAMEBUFFER_ANGLE was | |
| 281 specified." | |
| 282 | |
| 283 Modify the first sentence of the subsection titled "Effects of Framebuffer | |
| 284 Completeness on Framebuffer Operations" to be: | |
| 285 | |
| 286 "Attempting to render to or read from a framebuffer which is not | |
| 287 framebuffer complete will generate an | |
| 288 INVALID_FRAMEBUFFER_OPERATION error." | |
| 289 | |
| 290 | |
| 291 | |
| 292 Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State | |
| 293 Requests) | |
| 294 | |
| 295 In section 6.1.3, modify the first sentence of the description of | |
| 296 GetFramebufferAttachmentParameteriv as follows: | |
| 297 | |
| 298 "<target> must be DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or | |
| 299 FRAMEBUFFER. If <target> is FRAMEBUFFER, it behaves as | |
| 300 though DRAW_FRAMEBUFFER_ANGLE was specified." | |
| 301 | |
| 302 Modify the title of Table 6.23 (Framebuffer State) to be "Framebuffer | |
| 303 (state per attachment point)". | |
| 304 | |
| 305 | |
| 306 Dependencies on OES_texture_3D | |
| 307 | |
| 308 On an OpenGL ES implementation, in the absense of OES_texture_3D, | |
| 309 omit references to FramebufferTexture3DOES and CopyTexSubImage3DOES. | |
| 310 | |
| 311 Errors | |
| 312 | |
| 313 The error INVALID_FRAMEBUFFER_OPERATION is generated if | |
| 314 BlitFramebufferANGLE is called while the | |
| 315 draw framebuffer is not framebuffer complete. | |
| 316 | |
| 317 The error INVALID_FRAMEBUFFER_OPERATION is generated if | |
| 318 BlitFramebufferANGLE, ReadPixels, CopyTex{Sub}Image*, is called while the | |
| 319 read framebuffer is not framebuffer complete. | |
| 320 | |
| 321 The error INVALID_OPERATION is generated if GetIntegerv is called | |
| 322 while the read framebuffer is not framebuffer complete, or if there | |
| 323 is no color attachment present on the read framebuffer object. | |
| 324 | |
| 325 The error INVALID_VALUE is generated by BlitFramebufferANGLE if | |
| 326 <mask> has any bits set other than those named by | |
| 327 COLOR_BUFFER_BIT, DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT. | |
| 328 | |
| 329 The error INVALID_OPERATION is generated if BlitFramebufferANGLE is | |
| 330 called and <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT | |
| 331 and the source and destination depth or stencil buffer formats do | |
| 332 not match. | |
| 333 | |
| 334 The error INVALID_OPERATION is generated if BlitFramebufferANGLE is | |
| 335 called and any of the following conditions are true: | |
| 336 - the source and destination rectangle dimensions do not match | |
| 337 (ie scaling or flipping is required). | |
| 338 - <mask> includes COLOR_BUFFER_BIT and the source and destination | |
| 339 buffer formats do not match. | |
| 340 - <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT and the | |
| 341 source or destination rectangles do not specify the entire source | |
| 342 or destination buffer (after applying any scissor region). | |
| 343 | |
| 344 The error INVALID_ENUM is generated by BlitFramebufferANGLE if | |
| 345 <filter> is not NEAREST. | |
| 346 | |
| 347 The error INVALID_ENUM is generated if BindFramebuffer, | |
| 348 CheckFramebufferStatus, FramebufferTexture{2D|3DOES}, | |
| 349 FramebufferRenderbuffer, or | |
| 350 GetFramebufferAttachmentParameteriv is called and <target> is | |
| 351 not DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or FRAMEBUFFER. | |
| 352 | |
| 353 New State | |
| 354 | |
| 355 (Add a new table 6.xx, "Framebuffer (state per framebuffer target binding point)") | |
| 356 | |
| 357 Get Value Type Get Command Initial Value Description Section | |
| 358 ------------------------------ ---- ----------- -------------- ------------------- ------------ | |
| 359 DRAW_FRAMEBUFFER_BINDING_ANGLE Z+ GetIntegerv 0 framebuffer object bound 4.4.1 | |
| 360 to DRAW_FRAMEBUFFER_ANGLE | |
| 361 READ_FRAMEBUFFER_BINDING_ANGLE Z+ GetIntegerv 0 framebuffer object 4.4.1 | |
| 362 to READ_FRAMEBUFFER_ANGLE | |
| 363 | |
| 364 Remove reference to FRAMEBUFFER_BINDING from Table 6.23. | |
| 365 | |
| 366 (Add a new table 6.yy, "Framebuffer Dependent Values") | |
| 367 | |
| 368 Get Value Type Get Command Initial Value Description Section | |
| 369 ---------------------------- ---- ----------- -------------- ------------------- ------------ | |
| 370 SAMPLE_BUFFERS Z+ GetIntegerv 0 Number of multisample 3.2 | |
| 371 buffers | |
| 372 SAMPLES Z+ GetIntegerv 0 Coverage mask size 3.2 | |
| 373 | |
| 374 Remove the references to SAMPLE_BUFFERS and SAMPLES from Table 6.17. | |
| 375 | |
| 376 | |
| 377 Issues | |
| 378 | |
| 379 1) What should we call this extension? | |
| 380 | |
| 381 Resolved: ANGLE_framebuffer_blit. | |
| 382 | |
| 383 This extension is a result of a collaboration between Google and | |
| 384 TransGaming for the open-source ANGLE project. Typically one would | |
| 385 label a multi-vendor extension as EXT, but EXT_framebuffer_blit | |
| 386 is already the name for this on Desktop GL. Additionally this | |
| 387 isn't truely a multi-vendor extension because there is only one | |
| 388 implementation of this. We'll follow the example of the open-source | |
| 389 MESA project which uses the project name for the vendor suffix. | |
| 390 | |
| 391 2) Why is this done as a separate extension instead of just supporting | |
| 392 EXT_framebuffer_blit? | |
| 393 | |
| 394 To date, EXT_framebuffer_blit has not had interactions with OpenGL ES | |
| 395 specified and, as far as we know, it has not previously been exposed on | |
| 396 an ES 1.1 or ES 2.0 implementation. Because there are enough | |
| 397 differences between Desktop GL and OpenGL ES, and since OpenGL ES 2.0 | |
| 398 has already subsumed the EXT_framebuffer_object functionality (with | |
| 399 some changes) it was deemed a worthwhile exercise to fully specify the | |
| 400 interactions. Additionally, some of the choices in exactly which | |
| 401 functionality is supported by BlitFramebufferANGLE is dictated by | |
| 402 what is reasonable to support on a implementation which is | |
| 403 layered on Direct3D9. It is not expected that other implementations | |
| 404 will necessary have the same set of restrictions or requirements. | |
| 405 | |
| 406 3) How does this extension differ from EXT_framebuffer_blit? | |
| 407 | |
| 408 This extension is designed to be a pure subset of the | |
| 409 EXT_framebuffer_blit functionality as applicable to OpenGL ES 2.0. | |
| 410 | |
| 411 Functionality that is unchanged: | |
| 412 - the split DRAW and READ framebuffer attachment points and related sematics. | |
| 413 - the token values for the DRAW/READ_FRAMEBUFFER and DRAW/READ_FRAMBUFFER_BINDING | |
| 414 - the signature of the BlitFramebuffer entry-point. | |
| 415 | |
| 416 Additional restrictions imposed by BlitFramebufferANGLE: | |
| 417 - no color conversions are supported | |
| 418 - no scaling, stretching or flipping are supported | |
| 419 - no filtering is supported (a consequence of no stretching) | |
| 420 - only whole depth and/or stencil buffers can be copied | |
| 421 | |
| 422 Revision History | |
| 423 | |
| 424 Revision 1, 2010/07/06 | |
| 425 - copied from revision 15 of EXT_framebuffer_object | |
| 426 - removed language that was clearly not relevant to ES2 | |
| 427 - rebased changes against the OpenGL ES 2.0 specification | |
| 428 - added ANGLE-specific restrictions | |
| 429 Revision 2, 2010/07/15 | |
| 430 - clarifications of implicit clamping to buffer sizes (from ARB_fbo) | |
| 431 - clarify that D/S restricts apply after the scissor is applied | |
| 432 - improve some error language | |
| 433 Revision 3, 2010/08/06 | |
| 434 - add additional contributors, update implementation status | |
| 435 Revision 4, 2012/09/22 | |
| 436 - document errors for GetIntegerv. | |
| 437 |
