The Tor Browser / file revision

 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.