1Name
2
3    EXT_discard_framebuffer
4
5Name Strings
6
7    GL_EXT_discard_framebuffer
8
9Contributors
10
11    Benji Bowman, Imagination Technologies
12    John Rosasco, Apple
13    Richard Schreyer, Apple
14    Stuart Smith, Imagination Technologies
15    Michael Swift, Apple
16    
17Contacts
18
19    Benj Lipchak, Apple (lipchak 'at' apple.com)
20
21Status
22
23    Complete
24
25Version
26
27    Last Modified Date: September 15, 2009
28    Revision: #7
29
30Number
31
32    OpenGL ES Extension #64
33
34Dependencies
35
36    OpenGL ES 1.0 is required.
37    
38    Written based on the wording of the OpenGL ES 2.0 specification.
39
40    Requires OES_framebuffer_object or OpenGL ES 2.0.
41
42Overview
43
44    This extension provides a new command, DiscardFramebufferEXT, which 
45    causes the contents of the named framebuffer attachable images to become 
46    undefined.  The contents of the specified buffers are undefined until a 
47    subsequent operation modifies the content, and only the modified region 
48    is guaranteed to hold valid content.  Effective usage of this command 
49    may provide an implementation with new optimization opportunities.
50
51    Some OpenGL ES implementations cache framebuffer images in a small pool 
52    of fast memory.  Before rendering, these implementations must load the
53    existing contents of one or more of the logical buffers (color, depth, 
54    stencil, etc.) into this memory.  After rendering, some or all of these 
55    buffers are likewise stored back to external memory so their contents can
56    be used again in the future.  In many applications, some or all of the 
57    logical buffers  are cleared at the start of rendering.  If so, the 
58    effort to load or store those buffers is wasted.
59
60    Even without this extension, if a frame of rendering begins with a full-
61    screen Clear, an OpenGL ES implementation may optimize away the loading
62    of framebuffer contents prior to rendering the frame.  With this extension, 
63    an application can use DiscardFramebufferEXT to signal that framebuffer 
64    contents will no longer be needed.  In this case an OpenGL ES 
65    implementation may also optimize away the storing back of framebuffer 
66    contents after rendering the frame.
67
68Issues
69
70    1) Should DiscardFramebufferEXT's argument be a list of COLOR_ATTACHMENTx 
71    enums, or should it use the same bitfield from Clear and BlitFramebuffer?
72        
73        RESOLVED: We'll use a sized list of framebuffer attachments.  This
74        will give us some future-proofing for when MRTs and multisampled
75        FBOs are supported.
76        
77    2) What happens if the app discards only one of the depth and stencil
78    attachments, but those are backed by the same packed_depth_stencil buffer?
79    
80        a) Generate an error
81        b) Both images become undefined
82        c) Neither image becomes undefined
83        d) Only one of the images becomes undefined
84        
85        RESOLVED: (b) which sort of falls out of Issue 4.
86        
87    3) How should DiscardFramebufferEXT interact with the default framebuffer?
88
89        a) Generate an error
90        b) Ignore the hint silently
91        c) The contents of the specified attachments become undefined
92
93        RESOLVED: (c), with appropriate wording to map FBO attachments to
94        the corresponding default framebuffer's logical buffers
95
96    4) What happens when you discard an attachment that doesn't exist?  This is 
97    the case where a framebuffer is complete but doesn't have, for example, a
98    stencil attachment, yet the app tries to discard the stencil attachment.
99
100        a) Generate an error
101        b) Ignore the hint silently
102
103        RESOLVED: (b) for two reasons.  First, this is just a hint anyway, and
104        if we required error detection, then suddenly an implementation can't
105        trivially ignore it.  Second, this is consistent with Clear, which 
106        ignores specified buffers that aren't present.
107    
108New Procedures and Functions
109
110    void DiscardFramebufferEXT(enum target, 
111                               sizei numAttachments, 
112                               const enum *attachments);
113
114New Tokens
115
116    Accepted in the <attachments> parameter of DiscardFramebufferEXT when the
117    default framebuffer is bound to <target>:
118
119        COLOR_EXT                                0x1800
120        DEPTH_EXT                                0x1801
121        STENCIL_EXT                              0x1802
122
123Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment 
124Operations and the Framebuffer)
125    
126    Introduce new section 4.5:
127
128    "4.5 Discarding Framebuffer Contents
129
130    The GL provides a means for discarding portions of every pixel in a 
131    particular buffer, effectively leaving its contents undefined.  The 
132    command
133
134        void DiscardFramebufferEXT(enum target, 
135                                   sizei numAttachments, 
136                                   const enum *attachments);
137
138    effectively signals to the GL that it need not preserve all contents of
139    a bound framebuffer object.  <numAttachments> indicates how many 
140    attachments are supplied in the <attachments> list.  If an attachment is 
141    specified that does not exist in the framebuffer bound to <target>, it is 
142    ignored.  <target> must be FRAMEBUFFER.  
143    
144    If a framebuffer object is bound to <target>, then <attachments> may 
145    contain COLOR_ATTACHMENT0, DEPTH_ATTACHMENT, and/or STENCIL_ATTACHMENT.  If
146    the framebuffer object is not complete, DiscardFramebufferEXT may be 
147    ignored.
148
149    If the default framebuffer is bound to <target>, then <attachment> may 
150    contain COLOR, identifying the color buffer; DEPTH, identifying the depth 
151    buffer; or STENCIL, identifying the stencil buffer."
152
153Errors
154
155    The error INVALID_ENUM is generated if DiscardFramebufferEXT is called
156    with a <target> that is not FRAMEBUFFER.
157    
158    The error INVALID_ENUM is generated if DiscardFramebufferEXT is called with
159    a token other than COLOR_ATTACHMENT0, DEPTH_ATTACHMENT, or 
160    STENCIL_ATTACHMENT in its <attachments> list when a framebuffer object is
161    bound to <target>.
162
163    The error INVALID_ENUM is generated if DiscardFramebufferEXT is called with
164    a token other than COLOR_EXT, DEPTH_EXT, or STENCIL_EXT in its 
165    <attachments> list when the default framebuffer is bound to <target>.
166
167    The error INVALID_VALUE is generated if DiscardFramebufferEXT is called 
168    with <numAttachments> less than zero.
169
170Revision History
171
172    09/15/2009  Benj Lipchak
173        Make attachments argument const enum*.
174        
175    09/07/2009  Benj Lipchak
176        Minor clarification to overview text.
177        
178    08/18/2009  Benj Lipchak
179        Replace null-terminated list with sized list, loosen error checking,
180        and use separate attachment tokens for default framebuffers.
181
182    07/15/2009  Benj Lipchak
183        Minor changes to overview, change GLenum to enum, whitespace fixes.
184
185    07/14/2009  Benj Lipchak
186        Rename entrypoint to DiscardFramebufferEXT to follow verb/object naming
187        style, and rename entire extension to match.  Replace bitfield with
188        null-terminated attachment list.  Add actual spec diffs.  Update
189        overview, issues list, and errors.
190
191    04/30/2009  Richard Schreyer
192        General revision, removed the combined resolve-and-discard feature.
193        
194    04/30/2008  Michael Swift
195        First draft of extension.
196
197TODO:
198- provide examples of intended usage
199