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