| Name |
| |
| ANGLE_framebuffer_blit |
| |
| Name Strings |
| |
| GL_ANGLE_framebuffer_blit |
| |
| Contributors |
| |
| Contributors to EXT_framebuffer_blit |
| Daniel Koch, TransGaming Inc. |
| Shannon Woods, TransGaming Inc. |
| Kenneth Russell, Google Inc. |
| Vangelis Kokkevis, Google Inc. |
| |
| Contact |
| |
| Daniel Koch, TransGaming Inc. (daniel 'at' transgaming 'dot' com) |
| |
| Status |
| |
| Implemented in ANGLE ES2 |
| |
| Version |
| |
| Last Modified Date: Sept 22, 2012 |
| Author Revision: 4 |
| |
| Number |
| |
| OpenGL ES Extension #83 |
| |
| Dependencies |
| |
| OpenGL ES 2.0 is required. |
| |
| The extension is written against the OpenGL ES 2.0 specification. |
| |
| OES_texture_3D affects the definition of this extension. |
| |
| Overview |
| |
| This extension modifies framebuffer objects by splitting the |
| framebuffer object binding point into separate DRAW and READ |
| bindings. This allows copying directly from one framebuffer to |
| another. In addition, a new high performance blit function is |
| added to facilitate these blits and perform some data conversion |
| where allowed. |
| |
| IP Status |
| |
| No known IP claims. |
| |
| New Procedures and Functions |
| |
| void BlitFramebufferANGLE(int srcX0, int srcY0, int srcX1, int srcY1, |
| int dstX0, int dstY0, int dstX1, int dstY1, |
| bitfield mask, enum filter); |
| |
| New Tokens |
| |
| Accepted by the <target> parameter of BindFramebuffer, |
| CheckFramebufferStatus, FramebufferTexture2D, FramebufferTexture3DOES, |
| FramebufferRenderbuffer, and |
| GetFramebufferAttachmentParameteriv: |
| |
| // (reusing the tokens from EXT_framebuffer_blit) |
| READ_FRAMEBUFFER_ANGLE 0x8CA8 |
| DRAW_FRAMEBUFFER_ANGLE 0x8CA9 |
| |
| Accepted by the <pname> parameters of GetIntegerv and GetFloatv: |
| |
| // (reusing the tokens from EXT_framebuffer_blit) |
| DRAW_FRAMEBUFFER_BINDING_ANGLE 0x8CA6 // alias FRAMEBUFFER_BINDING |
| READ_FRAMEBUFFER_BINDING_ANGLE 0x8CAA |
| |
| |
| Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) |
| |
| Change the last paragraph of section 3.7.2 (Alternate Texture Image |
| Specification Commands) to: |
| |
| "Calling CopyTexSubImage3DOES, CopyTexImage2D or CopyTexSubImage2D will |
| result in an INVALID_FRAMEBUFFER_OPERATION error if the object bound |
| to READ_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer complete" |
| (section 4.4.4.2)." |
| |
| Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment |
| Operations and the Framebuffer) |
| |
| Change the first word of Chapter 4 from "The" to "A". |
| |
| Append to the introduction of Chapter 4: |
| |
| "Conceptually, the GL has two active framebuffers; the draw |
| framebuffer is the destination for rendering operations, and the |
| read framebuffer is the source for readback operations. The same |
| framebuffer may be used for both drawing and reading. Section |
| 4.4.1 describes the mechanism for controlling framebuffer usage." |
| |
| Modify the first sentence of the last paragraph of section 4.1.1 as follows: |
| |
| "While an application-created framebuffer object is bound to |
| DRAW_FRAMEBUFFER_ANGLE, the pixel ownership test always passes." |
| |
| Add to 4.3.1 (Reading Pixels), right before the subsection titled |
| "Obtaining Pixels from the Framebuffer": |
| |
| "Calling ReadPixels generates INVALID_FRAMEBUFFER_OPERATION if |
| the object bound to READ_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer |
| complete" (section 4.4.4.2). GetIntegerv generates an INVALID_OPERATION |
| error if the object bound to READ_FRAMEBUFFER_BINDING_ANGLE is not |
| framebuffer complete, or if the GL is using a framebuffer object |
| (i.e. READ_FRAMEBUFFER_BINDING_ANGLE is non-zero) and there is no color |
| attachment." |
| |
| Insert a new section 4.3.2 titled "Copying Pixels" and renumber the |
| subsequent sections. Add the following text: |
| |
| "BlitFramebufferANGLE transfers a rectangle of pixel values from one |
| region of the read framebuffer to another in the draw framebuffer. |
| |
| BlitFramebufferANGLE(int srcX0, int srcY0, int srcX1, int srcY1, |
| int dstX0, int dstY0, int dstX1, int dstY1, |
| bitfield mask, enum filter); |
| |
| <mask> is the bitwise OR of a number of values indicating which |
| buffers are to be copied. The values are COLOR_BUFFER_BIT, |
| DEPTH_BUFFER_BIT, and STENCIL_BUFFER_BIT, which are described in |
| section 4.2.3. The pixels corresponding to these buffers are |
| copied from the source rectangle, bound by the locations (srcX0, |
| srcY0) and (srcX1, srcY1), to the destination rectangle, bound by |
| the locations (dstX0, dstY0) and (dstX1, dstY1). The lower bounds |
| of the rectangle are inclusive, while the upper bounds are |
| exclusive. |
| |
| The actual region taken from the read framebuffer is limited to the |
| intersection of the source buffers being transferred, which may include |
| the color buffer, the depth buffer, and/or the stencil buffer depending on |
| <mask>. The actual region written to the draw framebuffer is limited to the |
| intersection of the destination buffers being written, which may include |
| the color buffer, the depth buffer, and/or the stencil buffer |
| depending on <mask>. Whether or not the source or destination regions are |
| altered due to these limits, the offset applied to pixels being transferred |
| is performed as though no such limits were present. |
| |
| Stretching and scaling during a copy are not supported. If the source |
| and destination rectangle dimensions do not match, no copy is |
| performed and an INVALID_OPERATION error is generated. |
| Because stretching is not supported, <filter> must be NEAREST and |
| no filtering is applied. |
| |
| Flipping during a copy is not supported. If either the source or |
| destination rectangle specifies a negative dimension, the error |
| INVALID_OPERATION is generated. If both the source and |
| destination rectangles specify a negative dimension for the same |
| direction, no reversal is required and the operation is supported. |
| |
| If the source and destination buffers are identical, and the |
| source and destination rectangles overlap, the result of the blit |
| operation is undefined. |
| |
| The pixel copy bypasses the fragment pipeline. The only fragment |
| operations which affect the blit are the pixel ownership test and |
| the scissor test. |
| |
| If a buffer is specified in <mask> and does not exist in both the |
| read and draw framebuffers, the corresponding bit is silently |
| ignored. |
| |
| Calling BlitFramebufferANGLE will result in an |
| INVALID_FRAMEBUFFER_OPERATION error if the objects bound to |
| DRAW_FRAMEBUFFER_BINDING_ANGLE and READ_FRAMEBUFFER_BINDING_ANGLE are |
| not "framebuffer complete" (section 4.4.4.2)." |
| |
| Calling BlitFramebufferANGLE will result in an INVALID_OPERATION |
| error if <mask> includes COLOR_BUFFER_BIT and the source and |
| destination color formats to not match. |
| |
| Calling BlitFramebufferANGLE will result in an INVALID_OPERATION |
| error if <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT |
| and the source and destination depth and stencil buffer formats do |
| not match. |
| |
| If <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT, only |
| complete buffers can be copied. If the source rectangle does not |
| specify the complete source buffer or the destination rectangle |
| (after factoring the scissor region, if applicable) does not specify |
| the complete destination buffer, an INVALID_OPERATION |
| error is generated. |
| |
| Modify the beginning of section 4.4.1 as follows: |
| |
| "The default framebuffer for rendering and readback operations is |
| provided by the windowing system. In addition, named framebuffer |
| objects can be created and operated upon. The namespace for |
| framebuffer objects is the unsigned integers, with zero reserved |
| by the GL for the default framebuffer. |
| |
| A framebuffer object is created by binding an unused name to |
| DRAW_FRAMEBUFFER_ANGLE or READ_FRAMEBUFFER_ANGLE. The binding is |
| effected by calling |
| |
| void BindFramebuffer(enum target, uint framebuffer); |
| |
| with <target> set to the desired framebuffer target and |
| <framebuffer> set to the unused name. The resulting framebuffer |
| object is a new state vector, comprising one set of the state values |
| listed in table 6.23 for each attachment point of the |
| framebuffer, set to the same initial values. There is one |
| color attachment point, plus one each |
| for the depth and stencil attachment points. |
| |
| BindFramebuffer may also be used to bind an existing |
| framebuffer object to DRAW_FRAMEBUFFER_ANGLE or |
| READ_FRAMEBUFFER_ANGLE. If the bind is successful no change is made |
| to the state of the bound framebuffer object, and any previous |
| binding to <target> is broken. |
| |
| If a framebuffer object is bound to DRAW_FRAMEBUFFER_ANGLE or |
| READ_FRAMEBUFFER_ANGLE, it becomes the target for rendering or |
| readback operations, respectively, until it is deleted or another |
| framebuffer is bound to the corresponding bind point. Calling |
| BindFramebuffer with <target> set to FRAMEBUFFER binds the |
| framebuffer to both DRAW_FRAMEBUFFER_ANGLE and READ_FRAMEBUFFER_ANGLE. |
| |
| While a framebuffer object is bound, GL operations on the target |
| to which it is bound affect the images attached to the bound |
| framebuffer object, and queries of the target to which it is bound |
| return state from the bound object. Queries of the values |
| specified in table 6.20 (Implementation Dependent Pixel Depths) |
| and table 6.yy (Framebuffer Dependent Values) are |
| derived from the framebuffer object bound to DRAW_FRAMEBUFFER_ANGLE. |
| |
| The initial state of DRAW_FRAMEBUFFER_ANGLE and READ_FRAMEBUFFER_ANGLE |
| refers to the default framebuffer provided by the windowing |
| system. In order that access to the default framebuffer is not |
| lost, it is treated as a framebuffer object with the name of 0. |
| The default framebuffer is therefore rendered to and read from |
| while 0 is bound to the corresponding targets. On some |
| implementations, the properties of the default framebuffer can |
| change over time (e.g., in response to windowing system events |
| such as attaching the context to a new windowing system drawable.)" |
| |
| Change the description of DeleteFramebuffers as follows: |
| |
| "<framebuffers> contains <n> names of framebuffer objects to be |
| deleted. After a framebuffer object is deleted, it has no |
| attachments, and its name is again unused. If a framebuffer that |
| is currently bound to one or more of the targets |
| DRAW_FRAMEBUFFER_ANGLE or READ_FRAMEBUFFER_ANGLE is deleted, it is as |
| though BindFramebuffer had been executed with the corresponding |
| <target> and <framebuffer> zero. Unused names in <framebuffers> |
| are silently ignored, as is the value zero." |
| |
| |
| In section 4.4.3 (Renderbuffer Objects), modify the first two sentences |
| of the description of FramebufferRenderbuffer as follows: |
| |
| "<target> must be DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE, or |
| FRAMEBUFFER. If <target> is FRAMEBUFFER, it behaves as |
| though DRAW_FRAMEBUFFER_ANGLE was specified. The INVALID_OPERATION |
| error is generated if the value of the corresponding binding is zero." |
| |
| In section 4.4.3 (Renderbuffer Objects), modify the first two sentences |
| of the description of FramebufferTexture2D as follows: |
| |
| "<target> must be DRAW_FRAMEBUFFER_ANGLE, |
| READ_FRAMEBUFFER_ANGLE, or FRAMEBUFFER. If <target> is |
| FRAMEBUFFER, it behaves as though DRAW_FRAMEBUFFER_ANGLE was |
| specified. The INVALID_OPERATION error is generated if the value of the |
| corresponding binding is zero." |
| |
| In section 4.4.5 (Framebuffer Completeness), modify the first sentence |
| of the description of CheckFramebufferStatus as follows: |
| |
| "If <target> is not DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or |
| FRAMEBUFFER, the error INVALID_ENUM is generated. If <target> is |
| FRAMEBUFFER, it behaves as though DRAW_FRAMEBUFFER_ANGLE was |
| specified." |
| |
| Modify the first sentence of the subsection titled "Effects of Framebuffer |
| Completeness on Framebuffer Operations" to be: |
| |
| "Attempting to render to or read from a framebuffer which is not |
| framebuffer complete will generate an |
| INVALID_FRAMEBUFFER_OPERATION error." |
| |
| |
| |
| Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State |
| Requests) |
| |
| In section 6.1.3, modify the first sentence of the description of |
| GetFramebufferAttachmentParameteriv as follows: |
| |
| "<target> must be DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or |
| FRAMEBUFFER. If <target> is FRAMEBUFFER, it behaves as |
| though DRAW_FRAMEBUFFER_ANGLE was specified." |
| |
| Modify the title of Table 6.23 (Framebuffer State) to be "Framebuffer |
| (state per attachment point)". |
| |
| |
| Dependencies on OES_texture_3D |
| |
| On an OpenGL ES implementation, in the absense of OES_texture_3D, |
| omit references to FramebufferTexture3DOES and CopyTexSubImage3DOES. |
| |
| Errors |
| |
| The error INVALID_FRAMEBUFFER_OPERATION is generated if |
| BlitFramebufferANGLE is called while the |
| draw framebuffer is not framebuffer complete. |
| |
| The error INVALID_FRAMEBUFFER_OPERATION is generated if |
| BlitFramebufferANGLE, ReadPixels, CopyTex{Sub}Image*, is called while the |
| read framebuffer is not framebuffer complete. |
| |
| The error INVALID_OPERATION is generated if GetIntegerv is called |
| while the read framebuffer is not framebuffer complete, or if there |
| is no color attachment present on the read framebuffer object. |
| |
| The error INVALID_VALUE is generated by BlitFramebufferANGLE if |
| <mask> has any bits set other than those named by |
| COLOR_BUFFER_BIT, DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT. |
| |
| The error INVALID_OPERATION is generated if BlitFramebufferANGLE is |
| called and <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT |
| and the source and destination depth or stencil buffer formats do |
| not match. |
| |
| The error INVALID_OPERATION is generated if BlitFramebufferANGLE is |
| called and any of the following conditions are true: |
| - the source and destination rectangle dimensions do not match |
| (ie scaling or flipping is required). |
| - <mask> includes COLOR_BUFFER_BIT and the source and destination |
| buffer formats do not match. |
| - <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT and the |
| source or destination rectangles do not specify the entire source |
| or destination buffer (after applying any scissor region). |
| |
| The error INVALID_ENUM is generated by BlitFramebufferANGLE if |
| <filter> is not NEAREST. |
| |
| The error INVALID_ENUM is generated if BindFramebuffer, |
| CheckFramebufferStatus, FramebufferTexture{2D|3DOES}, |
| FramebufferRenderbuffer, or |
| GetFramebufferAttachmentParameteriv is called and <target> is |
| not DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or FRAMEBUFFER. |
| |
| New State |
| |
| (Add a new table 6.xx, "Framebuffer (state per framebuffer target binding point)") |
| |
| Get Value Type Get Command Initial Value Description Section |
| ------------------------------ ---- ----------- -------------- ------------------- ------------ |
| DRAW_FRAMEBUFFER_BINDING_ANGLE Z+ GetIntegerv 0 framebuffer object bound 4.4.1 |
| to DRAW_FRAMEBUFFER_ANGLE |
| READ_FRAMEBUFFER_BINDING_ANGLE Z+ GetIntegerv 0 framebuffer object 4.4.1 |
| to READ_FRAMEBUFFER_ANGLE |
| |
| Remove reference to FRAMEBUFFER_BINDING from Table 6.23. |
| |
| (Add a new table 6.yy, "Framebuffer Dependent Values") |
| |
| Get Value Type Get Command Initial Value Description Section |
| ---------------------------- ---- ----------- -------------- ------------------- ------------ |
| SAMPLE_BUFFERS Z+ GetIntegerv 0 Number of multisample 3.2 |
| buffers |
| SAMPLES Z+ GetIntegerv 0 Coverage mask size 3.2 |
| |
| Remove the references to SAMPLE_BUFFERS and SAMPLES from Table 6.17. |
| |
| |
| Issues |
| |
| 1) What should we call this extension? |
| |
| Resolved: ANGLE_framebuffer_blit. |
| |
| This extension is a result of a collaboration between Google and |
| TransGaming for the open-source ANGLE project. Typically one would |
| label a multi-vendor extension as EXT, but EXT_framebuffer_blit |
| is already the name for this on Desktop GL. Additionally this |
| isn't truely a multi-vendor extension because there is only one |
| implementation of this. We'll follow the example of the open-source |
| MESA project which uses the project name for the vendor suffix. |
| |
| 2) Why is this done as a separate extension instead of just supporting |
| EXT_framebuffer_blit? |
| |
| To date, EXT_framebuffer_blit has not had interactions with OpenGL ES |
| specified and, as far as we know, it has not previously been exposed on |
| an ES 1.1 or ES 2.0 implementation. Because there are enough |
| differences between Desktop GL and OpenGL ES, and since OpenGL ES 2.0 |
| has already subsumed the EXT_framebuffer_object functionality (with |
| some changes) it was deemed a worthwhile exercise to fully specify the |
| interactions. Additionally, some of the choices in exactly which |
| functionality is supported by BlitFramebufferANGLE is dictated by |
| what is reasonable to support on a implementation which is |
| layered on Direct3D9. It is not expected that other implementations |
| will necessary have the same set of restrictions or requirements. |
| |
| 3) How does this extension differ from EXT_framebuffer_blit? |
| |
| This extension is designed to be a pure subset of the |
| EXT_framebuffer_blit functionality as applicable to OpenGL ES 2.0. |
| |
| Functionality that is unchanged: |
| - the split DRAW and READ framebuffer attachment points and related sematics. |
| - the token values for the DRAW/READ_FRAMEBUFFER and DRAW/READ_FRAMBUFFER_BINDING |
| - the signature of the BlitFramebuffer entry-point. |
| |
| Additional restrictions imposed by BlitFramebufferANGLE: |
| - no color conversions are supported |
| - no scaling, stretching or flipping are supported |
| - no filtering is supported (a consequence of no stretching) |
| - only whole depth and/or stencil buffers can be copied |
| |
| Revision History |
| |
| Revision 1, 2010/07/06 |
| - copied from revision 15 of EXT_framebuffer_object |
| - removed language that was clearly not relevant to ES2 |
| - rebased changes against the OpenGL ES 2.0 specification |
| - added ANGLE-specific restrictions |
| Revision 2, 2010/07/15 |
| - clarifications of implicit clamping to buffer sizes (from ARB_fbo) |
| - clarify that D/S restricts apply after the scissor is applied |
| - improve some error language |
| Revision 3, 2010/08/06 |
| - add additional contributors, update implementation status |
| Revision 4, 2012/09/22 |
| - document errors for GetIntegerv. |
| |
