1Name
2
3    ANGLE_framebuffer_multisample
4
5Name Strings
6
7    GL_ANGLE_framebuffer_multisample
8
9Contributors
10
11    Contributors to EXT_framebuffer_multisample
12    Daniel Koch, TransGaming Inc.
13    Shannon Woods, TransGaming Inc.
14    Kenneth Russell, Google Inc.
15    Vangelis Kokkevis, Google Inc.
16
17Contacts
18
19    Daniel Koch, TransGaming Inc. (daniel 'at' transgaming 'dot' com)
20
21Status
22
23    Implemented in ANGLE ES2
24
25Version
26
27    Last Modified Date: Aug 6, 2010 
28    Author Revision: #3
29
30Number
31
32    OpenGL ES Extension #84
33
34Dependencies
35
36    Requires OpenGL ES 2.0.
37
38    Requires GL_ANGLE_framebuffer_blit (or equivalent functionality).
39
40    The extension is written against the OpenGL ES 2.0 specification. 
41
42    OES_texture_3D affects the definition of this extension.
43
44Overview
45
46    This extension extends the framebuffer object framework to
47    enable multisample rendering.
48
49    The new operation RenderbufferStorageMultisampleANGLE() allocates
50    storage for a renderbuffer object that can be used as a multisample
51    buffer.  A multisample render buffer image differs from a
52    single-sample render buffer image in that a multisample image has a
53    number of SAMPLES that is greater than zero.  No method is provided
54    for creating multisample texture images.
55
56    All of the framebuffer-attachable images attached to a framebuffer
57    object must have the same number of SAMPLES or else the framebuffer
58    object is not "framebuffer complete".  If a framebuffer object with
59    multisample attachments is "framebuffer complete", then the
60    framebuffer object behaves as if SAMPLE_BUFFERS is one.
61
62    The resolve operation is affected by calling 
63    BlitFramebufferANGLE (provided by the ANGLE_framebuffer_blit
64    extension) where the source is a multisample application-created
65    framebuffer object and the destination is a single-sample
66    framebuffer object (either application-created or window-system
67    provided).
68
69New Procedures and Functions
70
71    void RenderbufferStorageMultisampleANGLE(
72            enum target, sizei samples,
73            enum internalformat,
74            sizei width, sizei height);
75
76New Types
77
78    None.
79
80New Tokens
81
82    Accepted by the <pname> parameter of GetRenderbufferParameteriv:
83
84        RENDERBUFFER_SAMPLES_ANGLE                  0x8CAB
85
86    Returned by CheckFramebufferStatus:
87
88        FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_ANGLE    0x8D56
89
90    Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
91    and GetFloatv:
92
93        MAX_SAMPLES_ANGLE                           0x8D57
94
95Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation)
96
97Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization)
98
99    Add to the last paragraph of 3.7.2 (Alternate Texture Image Specification)
100    (as modified by ANGLE_framebuffer_blit) the following:
101
102    "Calling CopyTexSubImage3DOES, CopyTexImage2D or CopyTexSubImage2D will
103    result in INVALID_OPERATION being generated if the object bound to
104    READ_FRAMEBUFFER_BINDING_ANGLE is "framebuffer complete" and the value
105    of SAMPLE_BUFFERS is greater than zero."
106
107Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment
108Operations and the Framebuffer)
109
110    Add to 4.3.1 (Reading Pixels), right before the subsection titled
111    "Obtaining Pixels from the Framebuffer":
112
113    "ReadPixels generates INVALID_OPERATION if READ_FRAMEBUFFER_BINDING_ANGLE
114    (section 4.4) is non-zero, the read framebuffer is framebuffer
115    complete, and the value of SAMPLE_BUFFERS for the read framebuffer
116    is greater than zero."
117
118    In 4.3.2 (Copying Pixels), add to the section describing BlitFramebuffer
119    that was added by ANGLE_framebuffer_blit.
120
121    "If SAMPLE_BUFFERS for the read framebuffer is greater than zero and
122    SAMPLE_BUFFERS for the draw framebuffer is zero, the samples
123    corresponding to each pixel location in the source are converted to
124    a single sample before being written to the destination.
125
126    If SAMPLE_BUFFERS for the draw framebuffer is greater than zero, 
127    no copy is performed and an INVALID_OPERATION error is generated.
128
129    If SAMPLE_BUFFERS for the read framebuffer is greater than zero and
130    <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT, no copy is 
131    performed and an INVALID_OPERATION error is generated.
132
133    If SAMPLE_BUFFERS for the read framebuffer is greater than zero and 
134    the format of the read and draw framebuffers are not identical, no
135    copy is performed and an INVALID_OPERATION error is generated.
136
137    If SAMPLE_BUFFERS for the read framebuffer is greater than zero, the
138    dimensions of the source and destination rectangles provided to 
139    BlitFramebufferANGLE must be identical and must specify the complete 
140    source and destination buffers, otherwise no copy is performed and 
141    an INVALID_OPERATION error is generated."
142
143    Modification to 4.4.3 (Renderbuffer Objects)
144
145    Add, just above the definition of RenderbufferStorage:
146
147    "The command
148
149        void RenderbufferStorageMultisampleANGLE(
150            enum target, sizei samples,
151            enum internalformat,
152            sizei width, sizei height);
153
154    establishes the data storage, format, dimensions, and number of
155    samples of a renderbuffer object's image.  <target> must be
156    RENDERBUFFER.  <internalformat> must be one of the color-renderable,
157    depth-renderable, or stencil-renderable formats described in table 4.5.
158    <width> and <height> are the dimensions in pixels of the renderbuffer.  If
159    either <width> or <height> is greater than the value of 
160    MAX_RENDERBUFFER_SIZE, or if <samples> is greater than MAX_SAMPLES_ANGLE, 
161    then the error INVALID_VALUE is generated. If OpenGL ES is unable to 
162    create a data store of the requested size, the error OUT_OF_MEMORY 
163    is generated.
164
165    Upon success, RenderbufferStorageMultisampleANGLE deletes any existing
166    data store for the renderbuffer image and the contents of the data
167    store after calling RenderbufferStorageMultisampleANGLE are undefined.
168    RENDERBUFFER_WIDTH is set to <width>, RENDERBUFFER_HEIGHT is
169    set to <height>, and RENDERBUFFER_INTERNAL_FORMAT is set to
170    <internalformat>.
171
172    If <samples> is zero, then RENDERBUFFER_SAMPLES_ANGLE is set to zero.
173    Otherwise <samples> represents a request for a desired minimum
174    number of samples. Since different implementations may support
175    different sample counts for multisampled rendering, the actual
176    number of samples allocated for the renderbuffer image is
177    implementation dependent.  However, the resulting value for
178    RENDERBUFFER_SAMPLES_ANGLE is guaranteed to be greater than or equal
179    to <samples> and no more than the next larger sample count supported
180    by the implementation.
181
182    An OpenGL ES implementation may vary its allocation of internal component
183    resolution based on any RenderbufferStorageMultisampleANGLE parameter (except
184    target), but the allocation and chosen internal format must not be a
185    function of any other state and cannot be changed once they are
186    established. The actual resolution in bits of each component of the 
187    allocated image can be queried with GetRenderbufferParameteriv."
188
189    Modify the definiton of RenderbufferStorage as follows:
190
191    "The command
192
193        void RenderbufferStorage(enum target, enum internalformat,
194                                    sizei width, sizei height);
195
196     is equivalent to calling RenderbufferStorageMultisampleANGLE with
197     <samples> equal to zero."
198
199    In section 4.4.5 (Framebuffer Completeness) in the subsection
200    titled "Framebuffer Completeness" add an entry to the bullet list:
201
202    * The value of RENDERBUFFER_SAMPLES_ANGLE is the same for all attached
203      images.
204      { FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_ANGLE }
205
206    Also add a paragraph to the end of the section after the definition
207    of CheckFramebufferStatus:
208
209    "The values of SAMPLE_BUFFERS and SAMPLES are derived from the
210    attachments of the currently bound framebuffer object.  If the
211    current DRAW_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer complete",
212    then both SAMPLE_BUFFERS and SAMPLES are undefined.  Otherwise,
213    SAMPLES is equal to the value of RENDERBUFFER_SAMPLES_ANGLE for the
214    attached images (which all must have the same value for
215    RENDERBUFFER_SAMPLES_ANGLE).  Further, SAMPLE_BUFFERS is one if
216    SAMPLES is non-zero.  Otherwise, SAMPLE_BUFFERS is zero.
217
218Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special Functions)
219
220
221Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State
222Requests)
223
224    In section 6.1.3 (Enumeraged Queries), modify the third paragraph 
225    of the description of GetRenderbufferParameteriv as follows:
226
227    "Upon successful return from GetRenderbufferParameteriv, if
228    <pname> is RENDERBUFFER_WIDTH, RENDERBUFFER_HEIGHT,
229    RENDERBUFFER_INTERNAL_FORMAT, or RENDERBUFFER_SAMPLES_ANGLE, then <params> 
230    will contain the width in pixels, height in pixels, internal format, or 
231    number of samples, respectively, of the image of the renderbuffer 
232    currently bound to <target>."
233
234
235Dependencies on ANGLE_framebuffer_blit    
236
237    ANGLE_framebuffer_blit is required.  Technically, ANGLE_framebuffer_blit
238    would not be required to support multisampled rendering, except for
239    the fact that it provides the only method of doing a multisample
240    resovle from a multisample renderbuffer.
241
242Dependencies on OES_texture_3D
243
244    On an OpenGL ES implementation, in the absense of OES_texture_3D,
245    omit references to CopyTexSubImage3DOES.
246
247Errors
248
249    The error INVALID_OPERATION is generated if ReadPixels or 
250    CopyTex{Sub}Image* is called while READ_FRAMEBUFFER_BINDING_ANGLE
251    is non-zero, the read framebuffer is framebuffer complete, and the
252    value of SAMPLE_BUFFERS for the read framebuffer is greater than
253    zero.
254
255    If both the draw and read framebuffers are framebuffer complete and
256    the draw framebuffer has a value of SAMPLE_BUFFERS that is greater 
257    than zero, then the error INVALID_OPERATION is generated if 
258    BlitFramebufferANGLE is called.
259
260    If both the draw and read framebuffers are framebuffer complete and
261    the read framebuffer has a value of SAMPLE_BUFFERS that is greater
262    than zero, the error INVALID_OPERATION is generated if 
263    BlitFramebufferANGLE is called and any of the following conditions
264    are true:
265     - <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT.
266     - the source or destination rectangles do not specify the entire
267       source or destination buffer.
268
269    If both the draw and read framebuffers are framebuffer complete and
270    either has a value of SAMPLE_BUFFERS that is greater than zero, then
271    the error INVALID_OPERATION is generated if BlitFramebufferANGLE is
272    called and the formats of the draw and read framebuffers are not
273    identical.
274
275    If either the draw or read framebuffer is framebuffer complete and
276    has a value of SAMPLE_BUFFERS that is greater than zero, then the
277    error INVALID_OPERATION is generated if BlitFramebufferANGLE is called
278    and the specified source and destination dimensions are not
279    identical.
280
281    If RenderbufferStorageMultisampleANGLE is called with <target> not
282    equal to RENDERBUFFER, the error INVALID_ENUM is generated.
283
284    If RenderbufferStorageMultisampleANGLE is called with an 
285    <internalformat> that is not listed as one of the color-, depth- 
286    or stencil-renderable formats in Table 4.5, then the error
287    INVALID_ENUM is generated.
288
289    If RenderbufferStorageMultisampleANGLE is called with <width> or 
290    <height> greater than MAX_RENDERBUFFER_SIZE, then the error 
291    INVALID_VALUE is generated.
292
293    If RenderbufferStorageMultisampleANGLE is called with a value of
294    <samples> that is greater than MAX_SAMPLES_ANGLE or less than zero,
295    then the error INVALID_VALUE is generated.
296
297    The error OUT_OF_MEMORY is generated when
298    RenderbufferStorageMultisampleANGLE cannot create storage of the
299    specified size.
300
301New State
302
303    Add to table 6.22 (Renderbuffer State)
304
305    Get Value                          Type    Get Command                 Initial Value  Description             Section
306    -------------------------------    ------  --------------------------  -------------  --------------------    -------
307    RENDERBUFFER_SAMPLES_ANGLE         Z+      GetRenderbufferParameteriv  0              number of samples       4.4.3
308
309
310    Add to table 6.yy (Framebuffer Dependent Vaues) (added by 
311    ANGLE_framebuffer_blit), the following new framebuffer dependent state.
312
313    Get Value          Type  Get Command     Minimum Value    Description             Section
314    -----------------  ----  -----------     -------------    -------------------     -------
315    MAX_SAMPLES_ANGLE  Z+    GetIntegerv     1                Maximum number of       4.4.3
316                                                              samples supported
317                                                              for multisampling
318                                                            
319
320
321Issues
322    
323    Issues from EXT_framebuffer_multisample have been removed.
324 
325    1) What should we call this extension?
326
327       Resolved: ANGLE_framebuffer_blit.  
328
329       This extension is a result of a collaboration between Google and 
330       TransGaming for the open-source ANGLE project. Typically one would
331       label a multi-vendor extension as EXT, but EXT_framebuffer_mulitsample 
332       is already the name for this on Desktop GL.  Additionally this
333       isn't truely a multi-vendor extension because there is only one
334       implementation of this.  We'll follow the example of the open-source
335       MESA project which uses the project name for the vendor suffix.
336 
337    2) How does this extension differ from EXT_framebuffer_multisample?
338
339       This is designed to be a proper subset of EXT_framebuffer_multisample
340       functionality as applicable to OpenGL ES 2.0.
341
342       Functionality that is unchanged: 
343        - creation of multisample renderbuffers.
344        - whole buffer multi-sample->single-sample resolve.
345        - no format conversions, stretching or flipping supported on multisample blits.
346
347       Additional restrictions on BlitFramebufferANGLE:
348        - multisample resolve is only supported on color buffers.
349        - no blits to multisample destinations (no single->multi or multi-multi).
350        - only entire buffers can be resolved.
351         
352Revision History
353
354    Revision 1, 2010/07/08
355      - copied from revision 7 of EXT_framebuffer_multisample
356      - removed language that was not relevant to ES2 
357      - rebase changes against the Open GL ES 2.0 specification
358      - added ANGLE-specific restrictions
359    Revision 2, 2010/07/19
360      - fix missing error code
361    Revision 3, 2010/08/06
362      - add additional contributors, update implementation status
363      - disallow negative samples 
364