зеркало из https://github.com/mozilla/gecko-dev.git
364 строки
15 KiB
Plaintext
364 строки
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
|