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