IMG_multisampled_render_to_texture

GL_IMG_multisampled_render_to_texture

Georg Kolling, Imagination Technologies (georg.kolling 'at' imgtec.com)

Complete

Last Modified Date: March 26, 2010
Revision: 3

OpenGL ES Extension #74

OpenGL ES 2.0 or OES_framebuffer_object are required. This 
extension is written against the OpenGL ES 2.0 Specification.

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.

No known IP claims.

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

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

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

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

None

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.

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

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.

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);
...

No conformance test has been defined yet

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