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: Aug 6, 2010
Author Revision: 3
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)."
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_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
