Edit
kc3-lang/angle/extensions/ANGLE_framebuffer_blit.txt
shannon.woods@transgaming.com
- extensions/ANGLE_framebuffer_blit.txt
-
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.