EXT_discard_framebuffer

GL_EXT_discard_framebuffer

Benji Bowman, Imagination Technologies
John Rosasco, Apple
Richard Schreyer, Apple
Stuart Smith, Imagination Technologies
Michael Swift, Apple

Benj Lipchak, Apple (lipchak 'at' apple.com)

Complete

Last Modified Date: September 15, 2009
Revision: #7

OpenGL ES Extension #64

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.

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.

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.

void DiscardFramebufferEXT(enum target, 
                           sizei numAttachments, 
                           const enum *attachments);

Accepted in the <attachments> parameter of DiscardFramebufferEXT when the
default framebuffer is bound to <target>:

    COLOR_EXT                                0x1800
    DEPTH_EXT                                0x1801
    STENCIL_EXT                              0x1802

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."

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.

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.