• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    IMG_multisampled_render_to_texture
4
5Name Strings
6
7    GL_IMG_multisampled_render_to_texture
8
9Contact
10
11    Georg Kolling, Imagination Technologies (georg.kolling 'at' imgtec.com)
12
13Status
14
15    Complete
16
17Version
18
19    Last Modified Date: March 26, 2010
20    Revision: 3
21
22Number
23
24    OpenGL ES Extension #74
25
26Dependencies
27
28    OpenGL ES 2.0 or OES_framebuffer_object are required. This
29    extension is written against the OpenGL ES 2.0 Specification.
30
31Overview
32
33    This extension introduces functionality to perform multisampled
34	rendering to a color renderable texture, without requiring an
35	explicit resolve of multisample data.
36
37	Some GPU architectures - such as tile-based renderers - are
38	capable of performing multisampled rendering by storing
39	multisample data in internal high-speed memory and downsampling the
40	data when writing out to external memory after rendering has
41	finished. Since per-sample data is never written out to external
42	memory, this approach saves bandwidth and storage space. In this
43	case multisample data gets discarded, however this is acceptable
44	in most cases.
45
46	The extension provides a new command, FramebufferTexture2DMultisampleIMG,
47	which attaches a texture level to a framebuffer and enables
48	multisampled rendering to that texture level.
49
50	When the texture level is used as a source or destination for any
51	operation other than drawing to it, an implicit resolve of
52	multisampled color data is performed. After such a resolve, the
53	multisampled color data is discarded.
54
55	In order to allow the use of multisampled depth and stencil buffers
56	when performing	multisampled rendering to a texture, the extension
57	also adds the command RenderbufferStorageMultisampleIMG.
58
59IP Status
60
61    No known IP claims.
62
63New Procedures and Functions
64
65    void RenderbufferStorageMultisampleIMG(
66            enum target, sizei samples,
67            enum internalformat,
68            sizei width, sizei height);
69
70    void FramebufferTexture2DMultisampleIMG(
71            enum target, enum attachment,
72            enum textarget, uint texture,
73            int level, sizei samples);
74
75New Tokens
76
77    Accepted by the <pname> parameter of GetRenderbufferParameteriv:
78
79        RENDERBUFFER_SAMPLES_IMG                0x9133
80
81    Returned by CheckFramebufferStatus:
82
83        FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_IMG  0x9134
84
85    Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
86    GetFloatv, and GetDoublev:
87
88        MAX_SAMPLES_IMG                         0x9135
89
90    Accepted by the <pname> parameter of GetFramebufferAttachmentParameteriv:
91
92        TEXTURE_SAMPLES_IMG                     0x9136
93
94
95Additions to Section 4.4.3 of the OpenGL ES 2.0 Specification
96(Renderbuffer Objects)
97
98	Replace the paragraph describing the command RenderbufferStorage
99	with the following:
100
101		The command
102			void RenderbufferStorageMultisampleIMG( enum target,
103			sizei samples, enum internalformat, sizei width,
104			sizei height );
105		establishes the data storage, format, dimensions, and number of
106		samples of a renderbuffer object's image. target must be RENDERBUFFER.
107		internalformat must be one of the color-renderable, depth-renderable,
108		or stencil-renderable formats described in table 4.5. width and height
109		are the dimensions in pixels of the renderbuffer. If either width or
110		height is greater than the value of MAX_RENDERBUFFER_SIZE, or if
111		samples is greater than the value of MAX_SAMPLES_IMG, then the error
112		INVALID_VALUE is generated. If OpenGL ES is unable to create a data
113		store of the requested size, the error OUT_OF_MEMORY is generated.
114		Upon success, RenderbufferStorageMultisampleIMG deletes any existing
115		data store for the renderbuffer image and the contents of the data
116		store after calling RenderbufferStorageMultisampleIMG are undefined.
117		RENDERBUFFER_WIDTH is set to width, RENDERBUFFER_HEIGHT is set to
118		height, and RENDERBUFFER_INTERNAL_FORMAT is set to internalformat.
119		If samples is zero, then RENDERBUFFER_SAMPLES_IMG is set to zero.
120		Otherwise samples represents a request for a desired minimum number
121		of samples. Since different implementations may support different
122		sample counts for multisampled rendering, the actual number of samples
123		allocated for the renderbuffer image is implementation-dependent.
124		However, the resulting value for RENDERBUFFER_SAMPLES_IMG is
125		guaranteed to be greater than or equal to samples and no more than the
126		next larger sample count supported by the implementation.
127
128		An OpenGL ES implementation may vary its allocation of internal
129		component resolution based on any RenderbufferStorageMultisampleIMG
130		parameter (except target), but the allocation and chosen internal format
131		must not be a function of any other state and cannot be changed once
132		they are established.
133
134		The command
135			void RenderbufferStorage( enum target, enum internalformat,
136			sizei width, sizei height );
137		is equivalent to calling RenderbufferStorageMultisampleIMG with
138		samples equal to zero.
139
140	Add the following after the paragraph describing FramebufferTexture2D:
141
142		The command
143		    void FramebufferTexture2DMultisampleIMG( enum target,
144			enum attachment, enum textarget, uint texture,
145			int level, sizei samples );
146		enables multisampled rendering into the images of a texture object.
147
148		target, textarget, texture, and level correspond to the same
149		parameters for FramebufferTexture2D and have the same restrictions.
150		attachment must be COLOR_ATTACHMENT0. If samples is greater than the
151		value of MAX_SAMPLES_IMG, then the error INVALID_VALUE is generated.
152		If samples is zero, then TEXTURE_SAMPLES_IMG is set to zero, and
153		FramebufferTexture2DMultisampleIMG behaves like FramebufferTexture2D.
154
155		Otherwise samples represents a request for a desired minimum number
156		of samples. Since different implementations may support different
157		sample counts for multisampled rendering, the actual number of samples
158		allocated for the image is implementation-dependent. However, the
159		resulting value for TEXTURE_SAMPLES_IMG is guaranteed to be greater
160		than or equal to samples and no more than the next larger sample count
161		supported by the implementation.
162
163		The implementation allocates an implicit multisample buffer with
164		TEXTURE_SAMPLES_IMG samples and the	same internalformat, width, and
165		height as the specified texture level. This buffer is used as the
166		target for rendering instead of the specified texture level. The
167		buffer is associated with the attachment and gets deleted
168		after the attachment is broken.
169
170		When the texture level is used as a source or destination for any
171		operation, or when the attachment is broken, an implicit resolve
172		of multisample data from the multisample buffer to the texture level
173		is performed. After such a resolve, the contents of the multisample
174		buffer become undefined.
175
176		The operations which cause a resolve include:
177			- Drawing with the texture bound to an active texture unit
178			- ReadPixels or CopyTex[Sub]Image* while the texture is
179			  attached to the framebuffer
180			- CopyTex[Sub]Image*, Tex[Sub]Image*,
181			  CompressedTex[Sub]Image* with the specified level as
182			  destination
183			- GenerateMipmap
184
185Additions to section 4.4.5 of the OpenGL ES 2.0 Specification
186(Framebuffer Completeness)
187
188	Add the following bullet point after
189		* All attached images have the same width and height.
190		  FRAMEBUFFER_INCOMPLETE_DIMENSIONS
191	on page 116:
192
193		* The value of RENDERBUFFER_SAMPLES_IMG is the same for all
194		  attached renderbuffers; the value of TEXTURE_SAMPLES_IMG
195		  is the same for all texture attachments; and, if the attached
196		  images are a mix of renderbuffers and textures, the value of
197		  RENDERBUFFER_SAMPLES_IMG matches the value of TEXTURE_-
198		  SAMPLES_IMG.
199          FRAMEBUFFER_INCOMPLETE_MULTISAMPLE
200
201Dependencies on GL and ES profiles, versions, and other extensions
202
203	None
204
205Errors
206
207    The error OUT_OF_MEMORY is generated when
208    RenderbufferStorageMultisampleIMG cannot create storage of the
209    specified size.
210
211    If RenderbufferStorageMultisampleEXT is called with a value of
212    <samples> that is greater than MAX_SAMPLES_IMG, then the error
213    INVALID_VALUE is generated.
214
215    The error INVALID_ENUM is generated if FramebufferTexture2DMultisampleIMG
216    is called with a <target> that is not FRAMEBUFFER.
217
218    The error INVALID_ENUM is generated if FramebufferTexture2DMultisampleIMG
219    is called with an <attachment> that is not COLOR_ATTACHMENT0.
220
221    The error INVALID_ENUM is generated if FramebufferTexture2DMultisampleIMG
222    is called with a <textarget> that is not TEXTURE_2D,
223	TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_POSITIVE_Y,
224	TEXTURE_CUBE_MAP_POSITIVE_Z, TEXTURE_CUBE_MAP_NEGATIVE_X,
225	TEXTURE_CUBE_MAP_NEGATIVE_Y, or TEXTURE_CUBE_MAP_NEGATIVE_Z.
226
227New State
228
229	Changes to table 6.22, p. 154 (Renderbuffer State)
230
231                                                     Initial
232    Get Value                 Type  Get Command      Value   Description  Sec.
233    ---------                 ----  ---------------- ------- ------------ -----
234    RENDERBUFFER_SAMPLES_IMG  Z+    GetRenderbuffer- 0       Renderbuffer 4.4.3
235                                    Parameteriv              samples
236
237	Changes to table 6.23, p. 155 (Framebuffer State)
238
239                                                       Initial
240    Get Value            Type    Get Command           Value   Description     Sec.
241    ---------            ------  --------------------- ------- --------------- ----
242    TEXTURE_SAMPLES_IMG  n * Z+  GetFramebuffer-       0       Framebuffer     4.4
243                                 AttachmentParameteriv         texture samples
244
245New Implementation Dependent State
246
247    Changes to table 6.17, p. 149 (Implementation Dependent Values)
248
249                                          Minimum
250    Get Value         Type    Get Command Value   Description Sec.
251    ---------         ----    ----------- ------- ----------- ----
252    MAX_SAMPLES_IMG   Z+      GetIntegerv 2       Max. # of   4.4
253                                                  samples.
254
255Sample Code
256
257	GLsizei width  = ...;
258	GLsizei height = ...;
259	GLint samples;
260	glGetIntegerv(GL_MAX_SAMPLES_IMG, &samples);
261
262	/* Create multisampled depth renderbuffer */
263	GLuint depthbuffer;
264	glGenRenderbuffers(1, &depthbuffer);
265	glBindRenderbuffer(GL_RENDERBUFFER, depthbuffer);
266	glRenderbufferStorageMultisampleIMG(GL_RENDERBUFFER, samples,
267		GL_DEPTH_COMPONENT16, width, height);
268	glBindRenderbuffer(GL_RENDERBUFFER, 0);
269
270	/* Create RGBA texture with single mipmap level */
271	GLuint texture;
272	glGenTextures(1, &texture);
273	glBindTexture(GL_TEXTURE_2D, texture);
274	glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, width, height, 0, GL_RGBA,
275		GL_UNSIGNED_SHORT_4_4_4_4, NULL);
276	glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
277	glBindTexture(GL_TEXTURE_2D, 0);
278
279	/* Create framebuffer object, attach texture and depth renderbuffer */
280	GLuint framebuffer;
281	glGenFramebuffers(1, &framebuffer);
282	glBindFramebuffer(GL_FRAMEBUFFER, framebuffer);
283	glFramebufferRenderbuffer(GL_FRAMEBUFFER, GL_DEPTH_ATTACHMENT,
284		GL_RENDERBUFFER, depthbuffer);
285	glFramebufferTexture2DMultisampleIMG(GL_FRAMEBUFFER,
286		GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, texture, 0, samples);
287
288	/* handle unsupported cases */
289	if (glCheckFramebufferStatus(GL_FRAMEBUFFER) !=
290			GL_FRAMEBUFFER_COMPLETE)
291	{
292		...
293	}
294
295	/* draw to the texture */
296	glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
297	...
298
299	/* Discard the depth renderbuffer contents if possible */
300	if (extension_supported("GL_EXT_discard_framebuffer"))
301	{
302		GLenum discard_attachments[] = { GL_DEPTH_EXT };
303		glDiscardFramebufferEXT(GL_FRAMEBUFFER, 1,
304			discard_attachments);
305	}
306
307	/* Draw to the default framebuffer using the antialiased texture */
308	/* Color data is implicitly resolved before the texture gets used */
309	glBindFramebuffer(GL_FRAMEBUFFER, 0);
310	glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT |
311		GL_STENCIL_BUFFER_BIT);
312	glBindTexture(GL_TEXTURE_2D, texture);
313	...
314
315Conformance Tests
316
317    No conformance test has been defined yet
318
319Issues
320
321
322Revision History
323
324    Revision 3, 2010/03/26
325      - Set enums to undefined
326
327    Revision 2, 2010/03/24
328      - Removed error condition for glReadPixels and glCopyTexImage2D
329
330    Revision 1, 2010/01/05
331      - First draft of extension
332