The Tor Browser: comparison gfx/angle/extensions/ANGLE_framebuffer

--1:000000000000
+:e40648da6cdc
+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

The Tor Browser / file comparison

comparison: gfx/angle/extensions/ANGLE_framebuffer_multisample.txt

gfx/angle/extensions/ANGLE_framebuffer_multisample.txt