1Name
2
3    ANGLE_framebuffer_blit
4
5Name Strings
6
7    GL_ANGLE_framebuffer_blit
8
9Contributors
10
11    Contributors to EXT_framebuffer_blit
12    Daniel Koch, TransGaming Inc.
13    Shannon Woods, TransGaming Inc.
14    Kenneth Russell, Google Inc.
15    Vangelis Kokkevis, Google Inc.
16
17Contact
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: Sept 22, 2012
28    Author Revision: 4
29
30Number
31
32    OpenGL ES Extension #83
33
34Dependencies
35
36    OpenGL ES 2.0 is required.
37
38    The extension is written against the OpenGL ES 2.0 specification.
39
40    OES_texture_3D affects the definition of this extension.
41
42Overview
43
44    This extension modifies framebuffer objects by splitting the
45    framebuffer object binding point into separate DRAW and READ
46    bindings.  This allows copying directly from one framebuffer to
47    another.  In addition, a new high performance blit function is
48    added to facilitate these blits and perform some data conversion
49    where allowed.
50
51IP Status
52
53    No known IP claims.
54
55New Procedures and Functions
56
57    void BlitFramebufferANGLE(int srcX0, int srcY0, int srcX1, int srcY1,
58                              int dstX0, int dstY0, int dstX1, int dstY1,
59                              bitfield mask, enum filter);
60
61New Tokens
62
63    Accepted by the <target> parameter of BindFramebuffer,
64    CheckFramebufferStatus, FramebufferTexture2D, FramebufferTexture3DOES,
65    FramebufferRenderbuffer, and
66    GetFramebufferAttachmentParameteriv:
67
68    // (reusing the tokens from EXT_framebuffer_blit)
69    READ_FRAMEBUFFER_ANGLE                0x8CA8
70    DRAW_FRAMEBUFFER_ANGLE                0x8CA9
71
72    Accepted by the <pname> parameters of GetIntegerv and GetFloatv:
73
74    // (reusing the tokens from EXT_framebuffer_blit)
75    DRAW_FRAMEBUFFER_BINDING_ANGLE        0x8CA6 // alias FRAMEBUFFER_BINDING
76    READ_FRAMEBUFFER_BINDING_ANGLE        0x8CAA
77
78
79Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization)
80
81    Change the last paragraph of section 3.7.2 (Alternate Texture Image
82    Specification Commands) to:
83
84    "Calling CopyTexSubImage3DOES, CopyTexImage2D or CopyTexSubImage2D will
85    result in an INVALID_FRAMEBUFFER_OPERATION error if the object bound
86    to READ_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer complete"
87    (section 4.4.4.2)."
88
89Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment
90Operations and the Framebuffer)
91
92    Change the first word of Chapter 4 from "The" to "A".
93
94    Append to the introduction of Chapter 4:
95
96    "Conceptually, the GL has two active framebuffers; the draw
97    framebuffer is the destination for rendering operations, and the
98    read framebuffer is the source for readback operations.  The same
99    framebuffer may be used for both drawing and reading.  Section
100    4.4.1 describes the mechanism for controlling framebuffer usage."
101
102    Modify the first sentence of the last paragraph of section 4.1.1 as follows:
103
104    "While an application-created framebuffer object is bound to
105    DRAW_FRAMEBUFFER_ANGLE, the pixel ownership test always passes."
106
107    Add to 4.3.1 (Reading Pixels), right before the subsection titled
108    "Obtaining Pixels from the Framebuffer":
109
110    "Calling ReadPixels generates INVALID_FRAMEBUFFER_OPERATION if
111    the object bound to READ_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer
112    complete" (section 4.4.4.2). GetIntegerv generates an INVALID_OPERATION
113    error if the object bound to READ_FRAMEBUFFER_BINDING_ANGLE is not
114    framebuffer complete, or if the GL is using a framebuffer object 
115    (i.e. READ_FRAMEBUFFER_BINDING_ANGLE is non-zero) and there is no color
116    attachment."
117
118    Insert a new section 4.3.2 titled "Copying Pixels" and renumber the
119    subsequent sections.  Add the following text:
120
121    "BlitFramebufferANGLE transfers a rectangle of pixel values from one
122    region of the read framebuffer to another in the draw framebuffer.
123
124    BlitFramebufferANGLE(int srcX0, int srcY0, int srcX1, int srcY1,
125                         int dstX0, int dstY0, int dstX1, int dstY1,
126                         bitfield mask, enum filter);
127
128    <mask> is the bitwise OR of a number of values indicating which
129    buffers are to be copied. The values are COLOR_BUFFER_BIT,
130    DEPTH_BUFFER_BIT, and STENCIL_BUFFER_BIT, which are described in
131    section 4.2.3.  The pixels corresponding to these buffers are
132    copied from the source rectangle, bound by the locations (srcX0,
133    srcY0) and (srcX1, srcY1), to the destination rectangle, bound by
134    the locations (dstX0, dstY0) and (dstX1, dstY1).  The lower bounds
135    of the rectangle are inclusive, while the upper bounds are
136    exclusive.
137
138    The actual region taken from the read framebuffer is limited to the
139    intersection of the source buffers being transferred, which may include
140    the color buffer, the depth buffer, and/or the stencil buffer depending on
141    <mask>. The actual region written to the draw framebuffer is limited to the
142    intersection of the destination buffers being written, which may include
143    the color buffer, the depth buffer, and/or the stencil buffer
144    depending on <mask>. Whether or not the source or destination regions are
145    altered due to these limits, the offset applied to pixels being transferred
146    is performed as though no such limits were present.
147
148    Stretching and scaling during a copy are not supported. If the source
149    and destination rectangle dimensions do not match, no copy is
150    performed and an INVALID_OPERATION error is generated.
151    Because stretching is not supported, <filter> must be NEAREST and
152    no filtering is applied. 
153
154    Flipping during a copy is not supported. If either the source or 
155    destination rectangle specifies a negative dimension, the error 
156    INVALID_OPERATION is generated. If both the source and 
157    destination rectangles specify a negative dimension for the same 
158    direction, no reversal is required and the operation is supported.
159
160    If the source and destination buffers are identical, and the
161    source and destination rectangles overlap, the result of the blit
162    operation is undefined.
163
164    The pixel copy bypasses the fragment pipeline.  The only fragment
165    operations which affect the blit are the pixel ownership test and
166    the scissor test.
167
168    If a buffer is specified in <mask> and does not exist in both the
169    read and draw framebuffers, the corresponding bit is silently
170    ignored.
171
172    Calling BlitFramebufferANGLE will result in an
173    INVALID_FRAMEBUFFER_OPERATION error if the objects bound to
174    DRAW_FRAMEBUFFER_BINDING_ANGLE and READ_FRAMEBUFFER_BINDING_ANGLE are
175    not "framebuffer complete" (section 4.4.4.2)."
176
177    Calling BlitFramebufferANGLE will result in an INVALID_OPERATION
178    error if <mask> includes COLOR_BUFFER_BIT and the source and 
179    destination color formats to not match.
180
181    Calling BlitFramebufferANGLE will result in an INVALID_OPERATION
182    error if <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT
183    and the source and destination depth and stencil buffer formats do
184    not match.
185
186    If <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT, only 
187    complete buffers can be copied.  If the source rectangle does not 
188    specify the complete source buffer or the destination rectangle 
189    (after factoring the scissor region, if applicable) does not specify 
190    the complete destination buffer, an INVALID_OPERATION
191    error is generated.
192
193    Modify the beginning of section 4.4.1 as follows:
194
195    "The default framebuffer for rendering and readback operations is
196    provided by the windowing system.  In addition, named framebuffer
197    objects can be created and operated upon.  The namespace for
198    framebuffer objects is the unsigned integers, with zero reserved
199    by the GL for the default framebuffer.
200
201    A framebuffer object is created by binding an unused name to
202    DRAW_FRAMEBUFFER_ANGLE or READ_FRAMEBUFFER_ANGLE.  The binding is
203    effected by calling
204
205        void BindFramebuffer(enum target, uint framebuffer);
206
207    with <target> set to the desired framebuffer target and
208    <framebuffer> set to the unused name.  The resulting framebuffer
209    object is a new state vector, comprising one set of the state values
210    listed in table 6.23 for each attachment point of the
211    framebuffer, set to the same initial values.  There is one
212    color attachment point, plus one each
213    for the depth and stencil attachment points.
214
215    BindFramebuffer may also be used to bind an existing
216    framebuffer object to DRAW_FRAMEBUFFER_ANGLE or
217    READ_FRAMEBUFFER_ANGLE.  If the bind is successful no change is made
218    to the state of the bound framebuffer object, and any previous
219    binding to <target> is broken.
220
221    If a framebuffer object is bound to DRAW_FRAMEBUFFER_ANGLE or
222    READ_FRAMEBUFFER_ANGLE, it becomes the target for rendering or
223    readback operations, respectively, until it is deleted or another
224    framebuffer is bound to the corresponding bind point.  Calling
225    BindFramebuffer with <target> set to FRAMEBUFFER binds the
226    framebuffer to both DRAW_FRAMEBUFFER_ANGLE and READ_FRAMEBUFFER_ANGLE.
227
228    While a framebuffer object is bound, GL operations on the target
229    to which it is bound affect the images attached to the bound
230    framebuffer object, and queries of the target to which it is bound
231    return state from the bound object.  Queries of the values
232    specified in table 6.20 (Implementation Dependent Pixel Depths)
233    and table 6.yy (Framebuffer Dependent Values) are
234    derived from the framebuffer object bound to DRAW_FRAMEBUFFER_ANGLE.
235
236    The initial state of DRAW_FRAMEBUFFER_ANGLE and READ_FRAMEBUFFER_ANGLE
237    refers to the default framebuffer provided by the windowing
238    system.  In order that access to the default framebuffer is not
239    lost, it is treated as a framebuffer object with the name of 0.
240    The default framebuffer is therefore rendered to and read from
241    while 0 is bound to the corresponding targets.  On some
242    implementations, the properties of the default framebuffer can
243    change over time (e.g., in response to windowing system events
244    such as attaching the context to a new windowing system drawable.)"
245
246    Change the description of DeleteFramebuffers as follows:
247
248    "<framebuffers> contains <n> names of framebuffer objects to be
249    deleted.  After a framebuffer object is deleted, it has no
250    attachments, and its name is again unused.  If a framebuffer that
251    is currently bound to one or more of the targets
252    DRAW_FRAMEBUFFER_ANGLE or READ_FRAMEBUFFER_ANGLE is deleted, it is as
253    though BindFramebuffer had been executed with the corresponding
254    <target> and <framebuffer> zero.  Unused names in <framebuffers>
255    are silently ignored, as is the value zero."
256
257
258    In section 4.4.3 (Renderbuffer Objects), modify the first two sentences
259    of the description of FramebufferRenderbuffer as follows:
260
261    "<target> must be DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE, or
262    FRAMEBUFFER.  If <target> is FRAMEBUFFER, it behaves as
263    though DRAW_FRAMEBUFFER_ANGLE was specified.  The INVALID_OPERATION 
264    error is generated if the value of the corresponding binding is zero."
265
266    In section 4.4.3 (Renderbuffer Objects), modify the first two sentences
267    of the description of FramebufferTexture2D as follows:
268
269    "<target> must be DRAW_FRAMEBUFFER_ANGLE,
270    READ_FRAMEBUFFER_ANGLE, or FRAMEBUFFER.  If <target> is
271    FRAMEBUFFER, it behaves as though DRAW_FRAMEBUFFER_ANGLE was
272    specified.  The INVALID_OPERATION error is generated if the value of the
273    corresponding binding is zero."
274
275    In section 4.4.5 (Framebuffer Completeness), modify the first sentence 
276    of the description of CheckFramebufferStatus as follows:
277
278    "If <target> is not DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or
279    FRAMEBUFFER, the error INVALID_ENUM is generated.  If <target> is
280    FRAMEBUFFER, it behaves as though DRAW_FRAMEBUFFER_ANGLE was
281    specified."
282
283    Modify the first sentence of the subsection titled "Effects of Framebuffer
284    Completeness on Framebuffer Operations" to be:
285
286    "Attempting to render to or read from a framebuffer which is not
287    framebuffer complete will generate an
288    INVALID_FRAMEBUFFER_OPERATION error."
289    
290
291
292Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State
293Requests)
294
295    In section 6.1.3, modify the first sentence of the description of
296    GetFramebufferAttachmentParameteriv as follows:
297
298    "<target> must be DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or
299    FRAMEBUFFER.  If <target> is FRAMEBUFFER, it behaves as
300    though DRAW_FRAMEBUFFER_ANGLE was specified."
301
302    Modify the title of Table 6.23 (Framebuffer State) to be "Framebuffer 
303    (state per attachment point)". 
304
305
306Dependencies on OES_texture_3D
307
308    On an OpenGL ES implementation, in the absense of OES_texture_3D,
309    omit references to FramebufferTexture3DOES and CopyTexSubImage3DOES.
310
311Errors
312
313    The error INVALID_FRAMEBUFFER_OPERATION is generated if
314    BlitFramebufferANGLE is called while the
315    draw framebuffer is not framebuffer complete.
316
317    The error INVALID_FRAMEBUFFER_OPERATION is generated if
318    BlitFramebufferANGLE, ReadPixels, CopyTex{Sub}Image*, is called while the
319    read framebuffer is not framebuffer complete.
320
321    The error INVALID_OPERATION is generated if GetIntegerv is called
322    while the read framebuffer is not framebuffer complete, or if there
323    is no color attachment present on the read framebuffer object.
324
325    The error INVALID_VALUE is generated by BlitFramebufferANGLE if
326    <mask> has any bits set other than those named by
327    COLOR_BUFFER_BIT, DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT.
328
329    The error INVALID_OPERATION is generated if BlitFramebufferANGLE is
330    called and <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT
331    and the source and destination depth or stencil buffer formats do
332    not match.
333
334    The error INVALID_OPERATION is generated if BlitFramebufferANGLE is 
335    called and any of the following conditions are true:
336     - the source and destination rectangle dimensions do not match
337       (ie scaling or flipping is required).
338     - <mask> includes COLOR_BUFFER_BIT and the source and destination 
339       buffer formats do not match.
340     - <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT and the
341       source or destination rectangles do not specify the entire source
342       or destination buffer (after applying any scissor region).
343
344    The error INVALID_ENUM is generated by BlitFramebufferANGLE if
345    <filter> is not NEAREST.
346
347    The error INVALID_ENUM is generated if BindFramebuffer,
348    CheckFramebufferStatus, FramebufferTexture{2D|3DOES},
349    FramebufferRenderbuffer, or
350    GetFramebufferAttachmentParameteriv is called and <target> is
351    not DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or FRAMEBUFFER.
352
353New State
354
355    (Add a new table 6.xx, "Framebuffer (state per framebuffer target binding point)")
356
357    Get Value                     Type   Get Command   Initial Value    Description               Section
358    ------------------------------  ----   -----------   --------------   -------------------       ------------
359    DRAW_FRAMEBUFFER_BINDING_ANGLE   Z+    GetIntegerv   0                framebuffer object bound  4.4.1
360                                                                          to DRAW_FRAMEBUFFER_ANGLE
361    READ_FRAMEBUFFER_BINDING_ANGLE   Z+    GetIntegerv   0                framebuffer object        4.4.1
362                                                                          to READ_FRAMEBUFFER_ANGLE
363
364    Remove reference to FRAMEBUFFER_BINDING from Table 6.23.
365
366    (Add a new table 6.yy, "Framebuffer Dependent Values") 
367
368    Get Value                     Type   Get Command   Initial Value    Description               Section
369    ----------------------------  ----   -----------   --------------   -------------------       ------------
370    SAMPLE_BUFFERS                 Z+    GetIntegerv   0                Number of multisample     3.2
371                                                                        buffers
372    SAMPLES                        Z+    GetIntegerv   0                Coverage mask size        3.2
373
374    Remove the references to SAMPLE_BUFFERS and SAMPLES from Table 6.17.
375
376
377Issues
378
379    1) What should we call this extension?
380  
381       Resolved: ANGLE_framebuffer_blit.  
382
383       This extension is a result of a collaboration between Google and 
384       TransGaming for the open-source ANGLE project. Typically one would
385       label a multi-vendor extension as EXT, but EXT_framebuffer_blit 
386       is already the name for this on Desktop GL.  Additionally this
387       isn't truely a multi-vendor extension because there is only one
388       implementation of this.  We'll follow the example of the open-source
389       MESA project which uses the project name for the vendor suffix.
390
391    2) Why is this done as a separate extension instead of just supporting
392       EXT_framebuffer_blit?
393
394       To date, EXT_framebuffer_blit has not had interactions with OpenGL ES
395       specified and, as far as we know, it has not previously been exposed on 
396       an ES 1.1 or ES 2.0 implementation. Because there are enough 
397       differences between Desktop GL and OpenGL ES, and since OpenGL ES 2.0 
398       has already subsumed the EXT_framebuffer_object functionality (with 
399       some changes) it was deemed a worthwhile exercise to fully specify the
400       interactions.  Additionally, some of the choices in exactly which 
401       functionality is supported by BlitFramebufferANGLE is dictated by
402       what is reasonable to support on a implementation which is 
403       layered on Direct3D9.  It is not expected that other implementations 
404       will necessary have the same set of restrictions or requirements. 
405
406    3) How does this extension differ from EXT_framebuffer_blit?
407
408       This extension is designed to be a pure subset of the 
409       EXT_framebuffer_blit functionality as applicable to OpenGL ES 2.0.
410
411       Functionality that is unchanged:
412        - the split DRAW and READ framebuffer attachment points and related sematics.
413        - the token values for the DRAW/READ_FRAMEBUFFER and DRAW/READ_FRAMBUFFER_BINDING
414        - the signature of the BlitFramebuffer entry-point.
415       
416       Additional restrictions imposed by BlitFramebufferANGLE:
417        - no color conversions are supported
418        - no scaling, stretching or flipping are supported
419        - no filtering is supported (a consequence of no stretching)
420        - only whole depth and/or stencil buffers can be copied
421
422Revision History
423
424    Revision 1, 2010/07/06
425      - copied from revision 15 of EXT_framebuffer_object
426      - removed language that was clearly not relevant to ES2
427      - rebased changes against the OpenGL ES 2.0 specification
428      - added ANGLE-specific restrictions
429    Revision 2, 2010/07/15
430      - clarifications of implicit clamping to buffer sizes (from ARB_fbo)
431      - clarify that D/S restricts apply after the scissor is applied
432      - improve some error language
433    Revision 3, 2010/08/06
434      - add additional contributors, update implementation status
435    Revision 4, 2012/09/22
436      - document errors for GetIntegerv.
437
438