xref: /third_party/openGLES/extensions/ANGLE/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.