| Name |
| |
| EXT_discard_framebuffer |
| |
| Name Strings |
| |
| GL_EXT_discard_framebuffer |
| |
| Contributors |
| |
| Benji Bowman, Imagination Technologies |
| John Rosasco, Apple |
| Richard Schreyer, Apple |
| Stuart Smith, Imagination Technologies |
| Michael Swift, Apple |
| |
| Contacts |
| |
| Benj Lipchak, Apple (lipchak 'at' apple.com) |
| |
| Status |
| |
| Complete |
| |
| Version |
| |
| Last Modified Date: September 15, 2009 |
| Revision: #7 |
| |
| Number |
| |
| OpenGL ES Extension #64 |
| |
| Dependencies |
| |
| OpenGL ES 1.0 is required. |
| |
| Written based on the wording of the OpenGL ES 2.0 specification. |
| |
| Requires OES_framebuffer_object or OpenGL ES 2.0. |
| |
| Overview |
| |
| This extension provides a new command, DiscardFramebufferEXT, which |
| causes the contents of the named framebuffer attachable images to become |
| undefined. The contents of the specified buffers are undefined until a |
| subsequent operation modifies the content, and only the modified region |
| is guaranteed to hold valid content. Effective usage of this command |
| may provide an implementation with new optimization opportunities. |
| |
| Some OpenGL ES implementations cache framebuffer images in a small pool |
| of fast memory. Before rendering, these implementations must load the |
| existing contents of one or more of the logical buffers (color, depth, |
| stencil, etc.) into this memory. After rendering, some or all of these |
| buffers are likewise stored back to external memory so their contents can |
| be used again in the future. In many applications, some or all of the |
| logical buffers are cleared at the start of rendering. If so, the |
| effort to load or store those buffers is wasted. |
| |
| Even without this extension, if a frame of rendering begins with a full- |
| screen Clear, an OpenGL ES implementation may optimize away the loading |
| of framebuffer contents prior to rendering the frame. With this extension, |
| an application can use DiscardFramebufferEXT to signal that framebuffer |
| contents will no longer be needed. In this case an OpenGL ES |
| implementation may also optimize away the storing back of framebuffer |
| contents after rendering the frame. |
| |
| Issues |
| |
| 1) Should DiscardFramebufferEXT's argument be a list of COLOR_ATTACHMENTx |
| enums, or should it use the same bitfield from Clear and BlitFramebuffer? |
| |
| RESOLVED: We'll use a sized list of framebuffer attachments. This |
| will give us some future-proofing for when MRTs and multisampled |
| FBOs are supported. |
| |
| 2) What happens if the app discards only one of the depth and stencil |
| attachments, but those are backed by the same packed_depth_stencil buffer? |
| |
| a) Generate an error |
| b) Both images become undefined |
| c) Neither image becomes undefined |
| d) Only one of the images becomes undefined |
| |
| RESOLVED: (b) which sort of falls out of Issue 4. |
| |
| 3) How should DiscardFramebufferEXT interact with the default framebuffer? |
| |
| a) Generate an error |
| b) Ignore the hint silently |
| c) The contents of the specified attachments become undefined |
| |
| RESOLVED: (c), with appropriate wording to map FBO attachments to |
| the corresponding default framebuffer's logical buffers |
| |
| 4) What happens when you discard an attachment that doesn't exist? This is |
| the case where a framebuffer is complete but doesn't have, for example, a |
| stencil attachment, yet the app tries to discard the stencil attachment. |
| |
| a) Generate an error |
| b) Ignore the hint silently |
| |
| RESOLVED: (b) for two reasons. First, this is just a hint anyway, and |
| if we required error detection, then suddenly an implementation can't |
| trivially ignore it. Second, this is consistent with Clear, which |
| ignores specified buffers that aren't present. |
| |
| New Procedures and Functions |
| |
| void DiscardFramebufferEXT(enum target, |
| sizei numAttachments, |
| const enum *attachments); |
| |
| New Tokens |
| |
| Accepted in the <attachments> parameter of DiscardFramebufferEXT when the |
| default framebuffer is bound to <target>: |
| |
| COLOR_EXT 0x1800 |
| DEPTH_EXT 0x1801 |
| STENCIL_EXT 0x1802 |
| |
| Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment |
| Operations and the Framebuffer) |
| |
| Introduce new section 4.5: |
| |
| "4.5 Discarding Framebuffer Contents |
| |
| The GL provides a means for discarding portions of every pixel in a |
| particular buffer, effectively leaving its contents undefined. The |
| command |
| |
| void DiscardFramebufferEXT(enum target, |
| sizei numAttachments, |
| const enum *attachments); |
| |
| effectively signals to the GL that it need not preserve all contents of |
| a bound framebuffer object. <numAttachments> indicates how many |
| attachments are supplied in the <attachments> list. If an attachment is |
| specified that does not exist in the framebuffer bound to <target>, it is |
| ignored. <target> must be FRAMEBUFFER. |
| |
| If a framebuffer object is bound to <target>, then <attachments> may |
| contain COLOR_ATTACHMENT0, DEPTH_ATTACHMENT, and/or STENCIL_ATTACHMENT. If |
| the framebuffer object is not complete, DiscardFramebufferEXT may be |
| ignored. |
| |
| If the default framebuffer is bound to <target>, then <attachment> may |
| contain COLOR, identifying the color buffer; DEPTH, identifying the depth |
| buffer; or STENCIL, identifying the stencil buffer." |
| |
| Errors |
| |
| The error INVALID_ENUM is generated if DiscardFramebufferEXT is called |
| with a <target> that is not FRAMEBUFFER. |
| |
| The error INVALID_ENUM is generated if DiscardFramebufferEXT is called with |
| a token other than COLOR_ATTACHMENT0, DEPTH_ATTACHMENT, or |
| STENCIL_ATTACHMENT in its <attachments> list when a framebuffer object is |
| bound to <target>. |
| |
| The error INVALID_ENUM is generated if DiscardFramebufferEXT is called with |
| a token other than COLOR_EXT, DEPTH_EXT, or STENCIL_EXT in its |
| <attachments> list when the default framebuffer is bound to <target>. |
| |
| The error INVALID_VALUE is generated if DiscardFramebufferEXT is called |
| with <numAttachments> less than zero. |
| |
| Revision History |
| |
| 09/15/2009 Benj Lipchak |
| Make attachments argument const enum*. |
| |
| 09/07/2009 Benj Lipchak |
| Minor clarification to overview text. |
| |
| 08/18/2009 Benj Lipchak |
| Replace null-terminated list with sized list, loosen error checking, |
| and use separate attachment tokens for default framebuffers. |
| |
| 07/15/2009 Benj Lipchak |
| Minor changes to overview, change GLenum to enum, whitespace fixes. |
| |
| 07/14/2009 Benj Lipchak |
| Rename entrypoint to DiscardFramebufferEXT to follow verb/object naming |
| style, and rename entire extension to match. Replace bitfield with |
| null-terminated attachment list. Add actual spec diffs. Update |
| overview, issues list, and errors. |
| |
| 04/30/2009 Richard Schreyer |
| General revision, removed the combined resolve-and-discard feature. |
| |
| 04/30/2008 Michael Swift |
| First draft of extension. |
| |
| TODO: |
| - provide examples of intended usage |