diff -r 000000000000 -r 6474c204b198 gfx/angle/extensions/ANGLE_framebuffer_multisample.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/gfx/angle/extensions/ANGLE_framebuffer_multisample.txt Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,363 @@ +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 parameter of GetRenderbufferParameteriv: + + RENDERBUFFER_SAMPLES_ANGLE 0x8CAB + + Returned by CheckFramebufferStatus: + + FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_ANGLE 0x8D56 + + Accepted by the 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 + 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. must be + RENDERBUFFER. must be one of the color-renderable, + depth-renderable, or stencil-renderable formats described in table 4.5. + and are the dimensions in pixels of the renderbuffer. If + either or is greater than the value of + MAX_RENDERBUFFER_SIZE, or if 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 , RENDERBUFFER_HEIGHT is + set to , and RENDERBUFFER_INTERNAL_FORMAT is set to + . + + If is zero, then RENDERBUFFER_SAMPLES_ANGLE is set to zero. + Otherwise 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 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 + 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 + is RENDERBUFFER_WIDTH, RENDERBUFFER_HEIGHT, + RENDERBUFFER_INTERNAL_FORMAT, or RENDERBUFFER_SAMPLES_ANGLE, then + 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 ." + + +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: + - 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 not + equal to RENDERBUFFER, the error INVALID_ENUM is generated. + + If RenderbufferStorageMultisampleANGLE is called with an + 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 or + greater than MAX_RENDERBUFFER_SIZE, then the error + INVALID_VALUE is generated. + + If RenderbufferStorageMultisampleANGLE is called with a value of + 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