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