| Name |
| |
| IMG_multisampled_render_to_texture |
| |
| Name Strings |
| |
| GL_IMG_multisampled_render_to_texture |
| |
| Contact |
| |
| Georg Kolling, Imagination Technologies (georg.kolling 'at' imgtec.com) |
| |
| Status |
| |
| Complete |
| |
| Version |
| |
| Last Modified Date: March 26, 2010 |
| Revision: 3 |
| |
| Number |
| |
| OpenGL ES Extension #74 |
| |
| Dependencies |
| |
| OpenGL ES 2.0 or OES_framebuffer_object are required. This |
| extension is written against the OpenGL ES 2.0 Specification. |
| |
| Overview |
| |
| This extension introduces functionality to perform multisampled |
| rendering to a color renderable texture, without requiring an |
| explicit resolve of multisample data. |
| |
| Some GPU architectures - such as tile-based renderers - are |
| capable of performing multisampled rendering by storing |
| multisample data in internal high-speed memory and downsampling the |
| data when writing out to external memory after rendering has |
| finished. Since per-sample data is never written out to external |
| memory, this approach saves bandwidth and storage space. In this |
| case multisample data gets discarded, however this is acceptable |
| in most cases. |
| |
| The extension provides a new command, FramebufferTexture2DMultisampleIMG, |
| which attaches a texture level to a framebuffer and enables |
| multisampled rendering to that texture level. |
| |
| When the texture level is used as a source or destination for any |
| operation other than drawing to it, an implicit resolve of |
| multisampled color data is performed. After such a resolve, the |
| multisampled color data is discarded. |
| |
| In order to allow the use of multisampled depth and stencil buffers |
| when performing multisampled rendering to a texture, the extension |
| also adds the command RenderbufferStorageMultisampleIMG. |
| |
| IP Status |
| |
| No known IP claims. |
| |
| New Procedures and Functions |
| |
| void RenderbufferStorageMultisampleIMG( |
| enum target, sizei samples, |
| enum internalformat, |
| sizei width, sizei height); |
| |
| void FramebufferTexture2DMultisampleIMG( |
| enum target, enum attachment, |
| enum textarget, uint texture, |
| int level, sizei samples); |
| |
| New Tokens |
| |
| Accepted by the <pname> parameter of GetRenderbufferParameteriv: |
| |
| RENDERBUFFER_SAMPLES_IMG 0x9133 |
| |
| Returned by CheckFramebufferStatus: |
| |
| FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_IMG 0x9134 |
| |
| Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, |
| GetFloatv, and GetDoublev: |
| |
| MAX_SAMPLES_IMG 0x9135 |
| |
| Accepted by the <pname> parameter of GetFramebufferAttachmentParameteriv: |
| |
| TEXTURE_SAMPLES_IMG 0x9136 |
| |
| |
| Additions to Section 4.4.3 of the OpenGL ES 2.0 Specification |
| (Renderbuffer Objects) |
| |
| Replace the paragraph describing the command RenderbufferStorage |
| with the following: |
| |
| The command |
| void RenderbufferStorageMultisampleIMG( 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 the value of MAX_SAMPLES_IMG, 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, RenderbufferStorageMultisampleIMG deletes any existing |
| data store for the renderbuffer image and the contents of the data |
| store after calling RenderbufferStorageMultisampleIMG 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_IMG 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_IMG 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 RenderbufferStorageMultisampleIMG |
| 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 command |
| void RenderbufferStorage( enum target, enum internalformat, |
| sizei width, sizei height ); |
| is equivalent to calling RenderbufferStorageMultisampleIMG with |
| samples equal to zero. |
| |
| Add the following after the paragraph describing FramebufferTexture2D: |
| |
| The command |
| void FramebufferTexture2DMultisampleIMG( enum target, |
| enum attachment, enum textarget, uint texture, |
| int level, sizei samples ); |
| enables multisampled rendering into the images of a texture object. |
| |
| target, textarget, texture, and level correspond to the same |
| parameters for FramebufferTexture2D and have the same restrictions. |
| attachment must be COLOR_ATTACHMENT0. If samples is greater than the |
| value of MAX_SAMPLES_IMG, then the error INVALID_VALUE is generated. |
| If samples is zero, then TEXTURE_SAMPLES_IMG is set to zero, and |
| FramebufferTexture2DMultisampleIMG behaves like FramebufferTexture2D. |
| |
| 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 image is implementation-dependent. However, the |
| resulting value for TEXTURE_SAMPLES_IMG is guaranteed to be greater |
| than or equal to samples and no more than the next larger sample count |
| supported by the implementation. |
| |
| The implementation allocates an implicit multisample buffer with |
| TEXTURE_SAMPLES_IMG samples and the same internalformat, width, and |
| height as the specified texture level. This buffer is used as the |
| target for rendering instead of the specified texture level. The |
| buffer is associated with the attachment and gets deleted |
| after the attachment is broken. |
| |
| When the texture level is used as a source or destination for any |
| operation, or when the attachment is broken, an implicit resolve |
| of multisample data from the multisample buffer to the texture level |
| is performed. After such a resolve, the contents of the multisample |
| buffer become undefined. |
| |
| The operations which cause a resolve include: |
| - Drawing with the texture bound to an active texture unit |
| - ReadPixels or CopyTex[Sub]Image* while the texture is |
| attached to the framebuffer |
| - CopyTex[Sub]Image*, Tex[Sub]Image*, |
| CompressedTex[Sub]Image* with the specified level as |
| destination |
| - GenerateMipmap |
| |
| Additions to section 4.4.5 of the OpenGL ES 2.0 Specification |
| (Framebuffer Completeness) |
| |
| Add the following bullet point after |
| * All attached images have the same width and height. |
| FRAMEBUFFER_INCOMPLETE_DIMENSIONS |
| on page 116: |
| |
| * The value of RENDERBUFFER_SAMPLES_IMG is the same for all |
| attached renderbuffers; the value of TEXTURE_SAMPLES_IMG |
| is the same for all texture attachments; and, if the attached |
| images are a mix of renderbuffers and textures, the value of |
| RENDERBUFFER_SAMPLES_IMG matches the value of TEXTURE_- |
| SAMPLES_IMG. |
| FRAMEBUFFER_INCOMPLETE_MULTISAMPLE |
| |
| Dependencies on GL and ES profiles, versions, and other extensions |
| |
| None |
| |
| Errors |
| |
| The error OUT_OF_MEMORY is generated when |
| RenderbufferStorageMultisampleIMG cannot create storage of the |
| specified size. |
| |
| If RenderbufferStorageMultisampleEXT is called with a value of |
| <samples> that is greater than MAX_SAMPLES_IMG, then the error |
| INVALID_VALUE is generated. |
| |
| The error INVALID_ENUM is generated if FramebufferTexture2DMultisampleIMG |
| is called with a <target> that is not FRAMEBUFFER. |
| |
| The error INVALID_ENUM is generated if FramebufferTexture2DMultisampleIMG |
| is called with an <attachment> that is not COLOR_ATTACHMENT0. |
| |
| The error INVALID_ENUM is generated if FramebufferTexture2DMultisampleIMG |
| is called with a <textarget> that is not TEXTURE_2D, |
| TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_POSITIVE_Y, |
| TEXTURE_CUBE_MAP_POSITIVE_Z, TEXTURE_CUBE_MAP_NEGATIVE_X, |
| TEXTURE_CUBE_MAP_NEGATIVE_Y, or TEXTURE_CUBE_MAP_NEGATIVE_Z. |
| |
| New State |
| |
| Changes to table 6.22, p. 154 (Renderbuffer State) |
| |
| Initial |
| Get Value Type Get Command Value Description Sec. |
| --------- ---- ---------------- ------- ------------ ----- |
| RENDERBUFFER_SAMPLES_IMG Z+ GetRenderbuffer- 0 Renderbuffer 4.4.3 |
| Parameteriv samples |
| |
| Changes to table 6.23, p. 155 (Framebuffer State) |
| |
| Initial |
| Get Value Type Get Command Value Description Sec. |
| --------- ------ --------------------- ------- --------------- ---- |
| TEXTURE_SAMPLES_IMG n * Z+ GetFramebuffer- 0 Framebuffer 4.4 |
| AttachmentParameteriv texture samples |
| |
| New Implementation Dependent State |
| |
| Changes to table 6.17, p. 149 (Implementation Dependent Values) |
| |
| Minimum |
| Get Value Type Get Command Value Description Sec. |
| --------- ---- ----------- ------- ----------- ---- |
| MAX_SAMPLES_IMG Z+ GetIntegerv 2 Max. # of 4.4 |
| samples. |
| |
| Sample Code |
| |
| GLsizei width = ...; |
| GLsizei height = ...; |
| GLint samples; |
| glGetIntegerv(GL_MAX_SAMPLES_IMG, &samples); |
| |
| /* Create multisampled depth renderbuffer */ |
| GLuint depthbuffer; |
| glGenRenderbuffers(1, &depthbuffer); |
| glBindRenderbuffer(GL_RENDERBUFFER, depthbuffer); |
| glRenderbufferStorageMultisampleIMG(GL_RENDERBUFFER, samples, |
| GL_DEPTH_COMPONENT16, width, height); |
| glBindRenderbuffer(GL_RENDERBUFFER, 0); |
| |
| /* Create RGBA texture with single mipmap level */ |
| GLuint texture; |
| glGenTextures(1, &texture); |
| glBindTexture(GL_TEXTURE_2D, texture); |
| glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, width, height, 0, GL_RGBA, |
| GL_UNSIGNED_SHORT_4_4_4_4, NULL); |
| glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); |
| glBindTexture(GL_TEXTURE_2D, 0); |
| |
| /* Create framebuffer object, attach texture and depth renderbuffer */ |
| GLuint framebuffer; |
| glGenFramebuffers(1, &framebuffer); |
| glBindFramebuffer(GL_FRAMEBUFFER, framebuffer); |
| glFramebufferRenderbuffer(GL_FRAMEBUFFER, GL_DEPTH_ATTACHMENT, |
| GL_RENDERBUFFER, depthbuffer); |
| glFramebufferTexture2DMultisampleIMG(GL_FRAMEBUFFER, |
| GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, texture, 0, samples); |
| |
| /* handle unsupported cases */ |
| if (glCheckFramebufferStatus(GL_FRAMEBUFFER) != |
| GL_FRAMEBUFFER_COMPLETE) |
| { |
| ... |
| } |
| |
| /* draw to the texture */ |
| glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); |
| ... |
| |
| /* Discard the depth renderbuffer contents if possible */ |
| if (extension_supported("GL_EXT_discard_framebuffer")) |
| { |
| GLenum discard_attachments[] = { GL_DEPTH_EXT }; |
| glDiscardFramebufferEXT(GL_FRAMEBUFFER, 1, |
| discard_attachments); |
| } |
| |
| /* Draw to the default framebuffer using the antialiased texture */ |
| /* Color data is implicitly resolved before the texture gets used */ |
| glBindFramebuffer(GL_FRAMEBUFFER, 0); |
| glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | |
| GL_STENCIL_BUFFER_BIT); |
| glBindTexture(GL_TEXTURE_2D, texture); |
| ... |
| |
| Conformance Tests |
| |
| No conformance test has been defined yet |
| |
| Issues |
| |
| |
| Revision History |
| |
| Revision 3, 2010/03/26 |
| - Set enums to undefined |
| |
| Revision 2, 2010/03/24 |
| - Removed error condition for glReadPixels and glCopyTexImage2D |
| |
| Revision 1, 2010/01/05 |
| - First draft of extension |