| 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 |