mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-02 15:15:23 +00:00
9ebd896e48
This ANGLE update fixes bugs, brings large performance improvements, and adds major new features that web devs are looking forward to: vertex shader texture lookup and float textures. http://code.google.com/p/angleproject/ This update is also needed because the version we're currently using is the chrome_m10 branch and that's no longer maintained. This update will make it much easier to apply security fixes if needed.
428 lines
18 KiB
Plaintext
428 lines
18 KiB
Plaintext
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
|
|
|