mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-07 20:17:37 +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.
364 lines
15 KiB
Plaintext
364 lines
15 KiB
Plaintext
Name
|
|
|
|
ANGLE_framebuffer_multisample
|
|
|
|
Name Strings
|
|
|
|
GL_ANGLE_framebuffer_multisample
|
|
|
|
Contributors
|
|
|
|
Contributors to EXT_framebuffer_multisample
|
|
Daniel Koch, TransGaming Inc.
|
|
Shannon Woods, TransGaming Inc.
|
|
Kenneth Russell, Google Inc.
|
|
Vangelis Kokkevis, Google Inc.
|
|
|
|
Contacts
|
|
|
|
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 #84
|
|
|
|
Dependencies
|
|
|
|
Requires OpenGL ES 2.0.
|
|
|
|
Requires GL_ANGLE_framebuffer_blit (or equivalent functionality).
|
|
|
|
The extension is written against the OpenGL ES 2.0 specification.
|
|
|
|
OES_texture_3D affects the definition of this extension.
|
|
|
|
Overview
|
|
|
|
This extension extends the framebuffer object framework to
|
|
enable multisample rendering.
|
|
|
|
The new operation RenderbufferStorageMultisampleANGLE() allocates
|
|
storage for a renderbuffer object that can be used as a multisample
|
|
buffer. A multisample render buffer image differs from a
|
|
single-sample render buffer image in that a multisample image has a
|
|
number of SAMPLES that is greater than zero. No method is provided
|
|
for creating multisample texture images.
|
|
|
|
All of the framebuffer-attachable images attached to a framebuffer
|
|
object must have the same number of SAMPLES or else the framebuffer
|
|
object is not "framebuffer complete". If a framebuffer object with
|
|
multisample attachments is "framebuffer complete", then the
|
|
framebuffer object behaves as if SAMPLE_BUFFERS is one.
|
|
|
|
The resolve operation is affected by calling
|
|
BlitFramebufferANGLE (provided by the ANGLE_framebuffer_blit
|
|
extension) where the source is a multisample application-created
|
|
framebuffer object and the destination is a single-sample
|
|
framebuffer object (either application-created or window-system
|
|
provided).
|
|
|
|
New Procedures and Functions
|
|
|
|
void RenderbufferStorageMultisampleANGLE(
|
|
enum target, sizei samples,
|
|
enum internalformat,
|
|
sizei width, sizei height);
|
|
|
|
New Types
|
|
|
|
None.
|
|
|
|
New Tokens
|
|
|
|
Accepted by the <pname> parameter of GetRenderbufferParameteriv:
|
|
|
|
RENDERBUFFER_SAMPLES_ANGLE 0x8CAB
|
|
|
|
Returned by CheckFramebufferStatus:
|
|
|
|
FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_ANGLE 0x8D56
|
|
|
|
Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
|
|
and GetFloatv:
|
|
|
|
MAX_SAMPLES_ANGLE 0x8D57
|
|
|
|
Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation)
|
|
|
|
Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization)
|
|
|
|
Add to the last paragraph of 3.7.2 (Alternate Texture Image Specification)
|
|
(as modified by ANGLE_framebuffer_blit) the following:
|
|
|
|
"Calling CopyTexSubImage3DOES, CopyTexImage2D or CopyTexSubImage2D will
|
|
result in INVALID_OPERATION being generated if the object bound to
|
|
READ_FRAMEBUFFER_BINDING_ANGLE is "framebuffer complete" and the value
|
|
of SAMPLE_BUFFERS is greater than zero."
|
|
|
|
Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment
|
|
Operations and the Framebuffer)
|
|
|
|
Add to 4.3.1 (Reading Pixels), right before the subsection titled
|
|
"Obtaining Pixels from the Framebuffer":
|
|
|
|
"ReadPixels generates INVALID_OPERATION if READ_FRAMEBUFFER_BINDING_ANGLE
|
|
(section 4.4) is non-zero, the read framebuffer is framebuffer
|
|
complete, and the value of SAMPLE_BUFFERS for the read framebuffer
|
|
is greater than zero."
|
|
|
|
In 4.3.2 (Copying Pixels), add to the section describing BlitFramebuffer
|
|
that was added by ANGLE_framebuffer_blit.
|
|
|
|
"If SAMPLE_BUFFERS for the read framebuffer is greater than zero and
|
|
SAMPLE_BUFFERS for the draw framebuffer is zero, the samples
|
|
corresponding to each pixel location in the source are converted to
|
|
a single sample before being written to the destination.
|
|
|
|
If SAMPLE_BUFFERS for the draw framebuffer is greater than zero,
|
|
no copy is performed and an INVALID_OPERATION error is generated.
|
|
|
|
If SAMPLE_BUFFERS for the read framebuffer is greater than zero and
|
|
<mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT, no copy is
|
|
performed and an INVALID_OPERATION error is generated.
|
|
|
|
If SAMPLE_BUFFERS for the read framebuffer is greater than zero and
|
|
the format of the read and draw framebuffers are not identical, no
|
|
copy is performed and an INVALID_OPERATION error is generated.
|
|
|
|
If SAMPLE_BUFFERS for the read framebuffer is greater than zero, the
|
|
dimensions of the source and destination rectangles provided to
|
|
BlitFramebufferANGLE must be identical and must specify the complete
|
|
source and destination buffers, otherwise no copy is performed and
|
|
an INVALID_OPERATION error is generated."
|
|
|
|
Modification to 4.4.3 (Renderbuffer Objects)
|
|
|
|
Add, just above the definition of RenderbufferStorage:
|
|
|
|
"The command
|
|
|
|
void RenderbufferStorageMultisampleANGLE(
|
|
enum target, sizei samples,
|
|
enum internalformat,
|
|
sizei width, sizei height);
|
|
|
|
establishes the data storage, format, dimensions, and number of
|
|
samples of a renderbuffer object's image. <target> must be
|
|
RENDERBUFFER. <internalformat> must be one of the color-renderable,
|
|
depth-renderable, or stencil-renderable formats described in table 4.5.
|
|
<width> and <height> are the dimensions in pixels of the renderbuffer. If
|
|
either <width> or <height> is greater than the value of
|
|
MAX_RENDERBUFFER_SIZE, or if <samples> is greater than MAX_SAMPLES_ANGLE,
|
|
then the error INVALID_VALUE is generated. If OpenGL ES is unable to
|
|
create a data store of the requested size, the error OUT_OF_MEMORY
|
|
is generated.
|
|
|
|
Upon success, RenderbufferStorageMultisampleANGLE deletes any existing
|
|
data store for the renderbuffer image and the contents of the data
|
|
store after calling RenderbufferStorageMultisampleANGLE are undefined.
|
|
RENDERBUFFER_WIDTH is set to <width>, RENDERBUFFER_HEIGHT is
|
|
set to <height>, and RENDERBUFFER_INTERNAL_FORMAT is set to
|
|
<internalformat>.
|
|
|
|
If <samples> is zero, then RENDERBUFFER_SAMPLES_ANGLE is set to zero.
|
|
Otherwise <samples> represents a request for a desired minimum
|
|
number of samples. Since different implementations may support
|
|
different sample counts for multisampled rendering, the actual
|
|
number of samples allocated for the renderbuffer image is
|
|
implementation dependent. However, the resulting value for
|
|
RENDERBUFFER_SAMPLES_ANGLE is guaranteed to be greater than or equal
|
|
to <samples> and no more than the next larger sample count supported
|
|
by the implementation.
|
|
|
|
An OpenGL ES implementation may vary its allocation of internal component
|
|
resolution based on any RenderbufferStorageMultisampleANGLE parameter (except
|
|
target), but the allocation and chosen internal format must not be a
|
|
function of any other state and cannot be changed once they are
|
|
established. The actual resolution in bits of each component of the
|
|
allocated image can be queried with GetRenderbufferParameteriv."
|
|
|
|
Modify the definiton of RenderbufferStorage as follows:
|
|
|
|
"The command
|
|
|
|
void RenderbufferStorage(enum target, enum internalformat,
|
|
sizei width, sizei height);
|
|
|
|
is equivalent to calling RenderbufferStorageMultisampleANGLE with
|
|
<samples> equal to zero."
|
|
|
|
In section 4.4.5 (Framebuffer Completeness) in the subsection
|
|
titled "Framebuffer Completeness" add an entry to the bullet list:
|
|
|
|
* The value of RENDERBUFFER_SAMPLES_ANGLE is the same for all attached
|
|
images.
|
|
{ FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_ANGLE }
|
|
|
|
Also add a paragraph to the end of the section after the definition
|
|
of CheckFramebufferStatus:
|
|
|
|
"The values of SAMPLE_BUFFERS and SAMPLES are derived from the
|
|
attachments of the currently bound framebuffer object. If the
|
|
current DRAW_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer complete",
|
|
then both SAMPLE_BUFFERS and SAMPLES are undefined. Otherwise,
|
|
SAMPLES is equal to the value of RENDERBUFFER_SAMPLES_ANGLE for the
|
|
attached images (which all must have the same value for
|
|
RENDERBUFFER_SAMPLES_ANGLE). Further, SAMPLE_BUFFERS is one if
|
|
SAMPLES is non-zero. Otherwise, SAMPLE_BUFFERS is zero.
|
|
|
|
Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special Functions)
|
|
|
|
|
|
Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State
|
|
Requests)
|
|
|
|
In section 6.1.3 (Enumeraged Queries), modify the third paragraph
|
|
of the description of GetRenderbufferParameteriv as follows:
|
|
|
|
"Upon successful return from GetRenderbufferParameteriv, if
|
|
<pname> is RENDERBUFFER_WIDTH, RENDERBUFFER_HEIGHT,
|
|
RENDERBUFFER_INTERNAL_FORMAT, or RENDERBUFFER_SAMPLES_ANGLE, then <params>
|
|
will contain the width in pixels, height in pixels, internal format, or
|
|
number of samples, respectively, of the image of the renderbuffer
|
|
currently bound to <target>."
|
|
|
|
|
|
Dependencies on ANGLE_framebuffer_blit
|
|
|
|
ANGLE_framebuffer_blit is required. Technically, ANGLE_framebuffer_blit
|
|
would not be required to support multisampled rendering, except for
|
|
the fact that it provides the only method of doing a multisample
|
|
resovle from a multisample renderbuffer.
|
|
|
|
Dependencies on OES_texture_3D
|
|
|
|
On an OpenGL ES implementation, in the absense of OES_texture_3D,
|
|
omit references to CopyTexSubImage3DOES.
|
|
|
|
Errors
|
|
|
|
The error INVALID_OPERATION is generated if ReadPixels or
|
|
CopyTex{Sub}Image* is called while READ_FRAMEBUFFER_BINDING_ANGLE
|
|
is non-zero, the read framebuffer is framebuffer complete, and the
|
|
value of SAMPLE_BUFFERS for the read framebuffer is greater than
|
|
zero.
|
|
|
|
If both the draw and read framebuffers are framebuffer complete and
|
|
the draw framebuffer has a value of SAMPLE_BUFFERS that is greater
|
|
than zero, then the error INVALID_OPERATION is generated if
|
|
BlitFramebufferANGLE is called.
|
|
|
|
If both the draw and read framebuffers are framebuffer complete and
|
|
the read framebuffer has a value of SAMPLE_BUFFERS that is greater
|
|
than zero, the error INVALID_OPERATION is generated if
|
|
BlitFramebufferANGLE is called and any of the following conditions
|
|
are true:
|
|
- <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT.
|
|
- the source or destination rectangles do not specify the entire
|
|
source or destination buffer.
|
|
|
|
If both the draw and read framebuffers are framebuffer complete and
|
|
either has a value of SAMPLE_BUFFERS that is greater than zero, then
|
|
the error INVALID_OPERATION is generated if BlitFramebufferANGLE is
|
|
called and the formats of the draw and read framebuffers are not
|
|
identical.
|
|
|
|
If either the draw or read framebuffer is framebuffer complete and
|
|
has a value of SAMPLE_BUFFERS that is greater than zero, then the
|
|
error INVALID_OPERATION is generated if BlitFramebufferANGLE is called
|
|
and the specified source and destination dimensions are not
|
|
identical.
|
|
|
|
If RenderbufferStorageMultisampleANGLE is called with <target> not
|
|
equal to RENDERBUFFER, the error INVALID_ENUM is generated.
|
|
|
|
If RenderbufferStorageMultisampleANGLE is called with an
|
|
<internalformat> that is not listed as one of the color-, depth-
|
|
or stencil-renderable formats in Table 4.5, then the error
|
|
INVALID_ENUM is generated.
|
|
|
|
If RenderbufferStorageMultisampleANGLE is called with <width> or
|
|
<height> greater than MAX_RENDERBUFFER_SIZE, then the error
|
|
INVALID_VALUE is generated.
|
|
|
|
If RenderbufferStorageMultisampleANGLE is called with a value of
|
|
<samples> that is greater than MAX_SAMPLES_ANGLE or less than zero,
|
|
then the error INVALID_VALUE is generated.
|
|
|
|
The error OUT_OF_MEMORY is generated when
|
|
RenderbufferStorageMultisampleANGLE cannot create storage of the
|
|
specified size.
|
|
|
|
New State
|
|
|
|
Add to table 6.22 (Renderbuffer State)
|
|
|
|
Get Value Type Get Command Initial Value Description Section
|
|
------------------------------- ------ -------------------------- ------------- -------------------- -------
|
|
RENDERBUFFER_SAMPLES_ANGLE Z+ GetRenderbufferParameteriv 0 number of samples 4.4.3
|
|
|
|
|
|
Add to table 6.yy (Framebuffer Dependent Vaues) (added by
|
|
ANGLE_framebuffer_blit), the following new framebuffer dependent state.
|
|
|
|
Get Value Type Get Command Minimum Value Description Section
|
|
----------------- ---- ----------- ------------- ------------------- -------
|
|
MAX_SAMPLES_ANGLE Z+ GetIntegerv 1 Maximum number of 4.4.3
|
|
samples supported
|
|
for multisampling
|
|
|
|
|
|
|
|
Issues
|
|
|
|
Issues from EXT_framebuffer_multisample have been removed.
|
|
|
|
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_mulitsample
|
|
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) How does this extension differ from EXT_framebuffer_multisample?
|
|
|
|
This is designed to be a proper subset of EXT_framebuffer_multisample
|
|
functionality as applicable to OpenGL ES 2.0.
|
|
|
|
Functionality that is unchanged:
|
|
- creation of multisample renderbuffers.
|
|
- whole buffer multi-sample->single-sample resolve.
|
|
- no format conversions, stretching or flipping supported on multisample blits.
|
|
|
|
Additional restrictions on BlitFramebufferANGLE:
|
|
- multisample resolve is only supported on color buffers.
|
|
- no blits to multisample destinations (no single->multi or multi-multi).
|
|
- only entire buffers can be resolved.
|
|
|
|
Revision History
|
|
|
|
Revision 1, 2010/07/08
|
|
- copied from revision 7 of EXT_framebuffer_multisample
|
|
- removed language that was not relevant to ES2
|
|
- rebase changes against the Open GL ES 2.0 specification
|
|
- added ANGLE-specific restrictions
|
|
Revision 2, 2010/07/19
|
|
- fix missing error code
|
|
Revision 3, 2010/08/06
|
|
- add additional contributors, update implementation status
|
|
- disallow negative samples
|