OES_framebuffer_object

GL_OES_framebuffer_object

Aaftab Munshi (amunshi@ati.com)

Copyright (c) 2005-2013 The Khronos Group Inc. Copyright terms at
    http://www.khronos.org/registry/speccopyright.html

Khronos-approved extension specifications are updated in response to
issues and bugs prioritized by the Khronos OpenGL ES Working Group. For
extensions which have been promoted to a core Specification, fixes will
first appear in the latest version of that core Specification, and will
eventually be backported to the extension document. This policy is
described in more detail at
    https://www.khronos.org/registry/OpenGL/docs/update_policy.php

None.

Ratified by the Khronos BOP, July 22, 2005.

Last Modified Date: April 10, 2008

OpenGL ES Extension #10

OpenGL ES 1.0 is required.
OES_rgb8_rgba8 affects the definition of this extension.
OES_depth24 affects the definition of this extension.
OES_depth32 affects the definition of this extension.
OES_stencil1 affects the definition of this extension.
OES_stencil4 affects the definition of this extension.
OES_stencil8 affects the definition of this extension.

This extension defines a simple interface for drawing to rendering
destinations other than the buffers provided to the GL by the
window-system.  OES_framebuffer_object is a simplified version
of EXT_framebuffer_object with modifications to match the needs of 
OpenGL ES.

In this extension, these newly defined rendering destinations are
known collectively as "framebuffer-attachable images".  This
extension provides a mechanism for attaching framebuffer-attachable
images to the GL framebuffer as one of the standard GL logical
buffers: color, depth, and stencil.  When a framebuffer-attachable 
image is attached to the framebuffer, it is used as the source and
destination of fragment operations as described in Chapter 4.

By allowing the use of a framebuffer-attachable image as a rendering
destination, this extension enables a form of "offscreen" rendering.
Furthermore, "render to texture" is supported by allowing the images
of a texture to be used as framebuffer-attachable images.  A
particular image of a texture object is selected for use as a
framebuffer-attachable image by specifying the mipmap level, cube
map face (for a cube map texture) that identifies the image.  
The "render to texture" semantics of this extension are similar to 
performing traditional rendering to the framebuffer, followed 
immediately by a call to CopyTexSubImage.  However, by using this 
extension instead, an application can achieve the same effect, 
but with the advantage that the GL can usually eliminate the data copy 
that would have been incurred by calling CopyTexSubImage.

This extension also defines a new GL object type, called a
"renderbuffer", which encapsulates a single 2D pixel image.  The
image of renderbuffer can be used as a framebuffer-attachable image
for generalized offscreen rendering and it also provides a means to
support rendering to GL logical buffer types which have no
corresponding texture format (stencil, etc).  A renderbuffer
is similar to a texture in that both renderbuffers and textures can
be independently allocated and shared among multiple contexts.  The
framework defined by this extension is general enough that support
for attaching images from GL objects other than textures and
renderbuffers could be added by layered extensions.

To facilitate efficient switching between collections of
framebuffer-attachable images, this extension introduces another new
GL object, called a framebuffer object.  A framebuffer object
contains the state that defines the traditional GL framebuffer,
including its set of images.  Prior to this extension, it was the
window-system which defined and managed this collection of images,
traditionally by grouping them into a "drawable".  The window-system
APIs would also provide a function (i.e., eglMakeCurrent) to bind a 
drawable with a GL context.  In this extension, however, this 
functionality is subsumed by the GL and the GL provides the function 
BindFramebufferOES to bind a framebuffer object to the current context.  
Later, the context can bind back to the window-system-provided framebuffer 
in order to display rendered content.

Previous extensions that enabled rendering to a texture have been
much more complicated.  One example is the combination of
ARB_pbuffer and ARB_render_texture, both of which are window-system
extensions.  This combination requires calling MakeCurrent, an
operation that may be expensive, to switch between the window and
the pbuffer drawables.  An application must create one pbuffer per
renderable texture in order to portably use ARB_render_texture.  An
application must maintain at least one GL context per texture
format, because each context can only operate on a single
pixelformat or FBConfig.  All of these characteristics make
ARB_render_texture both inefficient and cumbersome to use.

OES_framebuffer_object, on the other hand, is both simpler to use
and more efficient than ARB_render_texture.  The
OES_framebuffer_object API is contained wholly within the GL API and
has no (non-portable) window-system components.  Under
OES_framebuffer_object, it is not necessary to create a second GL
context when rendering to a texture image whose format differs from
that of the window.  Finally, unlike the pbuffers of
ARB_render_texture, a single framebuffer object can facilitate
rendering to an unlimited number of texture objects.

Please refer to the EXT_framebuffer_object extension for a 
detailed explaination of how framebuffer objects are supposed to work,
the issues and their resolution.  This extension can be found at
http://oss.sgi.com/projects/ogl-sample/registry/EXT/framebuffer_object.txt

1) This extension should fold in the language developed for the
   "full" OpenGL ES Specifications; the current difference form is
   somewhat confusing, particularly since the additional optional
   renderbuffer formats defined by layered extensions are not
   documented properly.

   The normal way of writing this would be to omit all mention of
   these formats from the base extension, and in the layered
   extensions, state that they are added to the appropriate table or
   section of the extension. Instead, they are listed as optional
   here, and the layered extensions are underspecified.

boolean IsRenderbufferOES(uint renderbuffer);
void BindRenderbufferOES(enum target, uint renderbuffer);
void DeleteRenderbuffersOES(sizei n, const uint *renderbuffers);
void GenRenderbuffersOES(sizei n, uint *renderbuffers);

void RenderbufferStorageOES(enum target, enum internalformat,
                            sizei width, sizei height);

void GetRenderbufferParameterivOES(enum target, enum pname, int* params);

boolean IsFramebufferOES(uint framebuffer);
void BindFramebufferOES(enum target, uint framebuffer);
void DeleteFramebuffersOES(sizei n, const uint *framebuffers);
void GenFramebuffersOES(sizei n, uint *framebuffers);

enum CheckFramebufferStatusOES(enum target);

void FramebufferTexture2DOES(enum target, enum attachment,
                             enum textarget, uint texture,
                             int level);

void FramebufferRenderbufferOES(enum target, enum attachment,
                                enum renderbuffertarget, uint renderbuffer);

void GetFramebufferAttachmentParameterivOES(enum target, enum attachment,
                                            enum pname, int *params);

void GenerateMipmapOES(enum target);

Accepted by the <target> parameter of BindFramebufferOES,
CheckFramebufferStatusOES, FramebufferTexture{2D|3D}OES,
FramebufferRenderbufferOES, and
GetFramebufferAttachmentParameterivOES:

    FRAMEBUFFER_OES                     0x8D40

Accepted by the <target> parameter of BindRenderbufferOES,
RenderbufferStorageOES, and GetRenderbufferParameterivOES, and
returned by GetFramebufferAttachmentParameterivOES:

    RENDERBUFFER_OES                    0x8D41

Accepted by the <internalformat> parameter of
RenderbufferStorageOES:

    DEPTH_COMPONENT16_OES               0x81A5
    RGBA4_OES                           0x8056
    RGB5_A1_OES                         0x8057
    RGB565_OES                          0x8D62
    STENCIL_INDEX1_OES                  0x8D46
    STENCIL_INDEX4_OES                  0x8D47
    STENCIL_INDEX8_OES                  0x8D48

Accepted by the <pname> parameter of GetRenderbufferParameterivOES:

    RENDERBUFFER_WIDTH_OES              0x8D42
    RENDERBUFFER_HEIGHT_OES             0x8D43
    RENDERBUFFER_INTERNAL_FORMAT_OES    0x8D44
    RENDERBUFFER_RED_SIZE_OES           0x8D50
    RENDERBUFFER_GREEN_SIZE_OES         0x8D51
    RENDERBUFFER_BLUE_SIZE_OES          0x8D52
    RENDERBUFFER_ALPHA_SIZE_OES         0x8D53
    RENDERBUFFER_DEPTH_SIZE_OES         0x8D54
    RENDERBUFFER_STENCIL_SIZE_OES       0x8D55

Accepted by the <pname> parameter of
GetFramebufferAttachmentParameterivOES:

    FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_OES            0x8CD0
    FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_OES            0x8CD1
    FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_OES          0x8CD2
    FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE_OES  0x8CD3
    FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_OES     0x8CD4

Accepted by the <attachment> parameter of
FramebufferTexture{2D|3D}OES, FramebufferRenderbufferOES, and
GetFramebufferAttachmentParameterivOES

    COLOR_ATTACHMENT0_OES                0x8CE0
    DEPTH_ATTACHMENT_OES                 0x8D00
    STENCIL_ATTACHMENT_OES               0x8D20

Returned by GetFramebufferAttachmentParameterivOES when the
<pname> parameter is FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_OES:

    GL_NONE_OES                          0

Returned by CheckFramebufferStatusOES():

    FRAMEBUFFER_COMPLETE_OES                          0x8CD5
    FRAMEBUFFER_INCOMPLETE_ATTACHMENT_OES             0x8CD6
    FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT_OES     0x8CD7
    FRAMEBUFFER_INCOMPLETE_DIMENSIONS_OES             0x8CD9
    FRAMEBUFFER_INCOMPLETE_FORMATS_OES                0x8CDA
    FRAMEBUFFER_INCOMPLETE_DRAW_BUFFER_OES            0x8CDB
    FRAMEBUFFER_INCOMPLETE_READ_BUFFER_OES            0x8CDC
    FRAMEBUFFER_UNSUPPORTED_OES                       0x8CDD

Accepted by GetIntegerv():

    FRAMEBUFFER_BINDING_OES             0x8CA6
    RENDERBUFFER_BINDING_OES            0x8CA7
    MAX_RENDERBUFFER_SIZE_OES           0x84E8

Returned by GetError():

    INVALID_FRAMEBUFFER_OPERATION_OES   0x0506

- EXT versions of the entry points and tokens used by the desktop
  extension are replaced with OES-suffixed versions, and GL_NONE is
  replaced with GL_NONE_OES.

- there is no support for DrawBuffer{s}, ReadBuffer{s}, or multiple
  color attachments; tokens COLOR_ATTACHMENT[1-15]_OES and
  MAX_COLOR_ATTACHMENTS_OES are not supported.

- FramebufferTexture2DOES can be used to render 
  directly into the base level of a texture image only.  Rendering to any 
  mip-level other than the base level is not supported.

- FramebufferTexture3DOES is optionally supported and is implemented only
  if OES_texture_3D string is defined in the EXTENSIONS string returned by 
  OpenGL ES.

- section 4.4.2.1 of the EXT_framebuffer_object spec describes the function
  RenderbufferStorageEXT.  This function establishes the data storage, format, 
  and dimensions of a renderbuffer object's image.  <target> must be 
  RENDERBUFFER_EXT. <internalformat> must be one of the internal formats 
  from table 3.16 or table 2.nnn which has a base internal format of RGB, RGBA, 
  DEPTH_COMPONENT, or STENCIL_INDEX.

  The above paragraph is modified by OES_framebuffer_object and states thus:

  "This function establishes the data storage, format, and 
  dimensions of a renderbuffer object's image.  <target> must be RENDERBUFFER_OES.
  <internalformat> must be one of the sized internal formats from the following 
  table which has a base internal format of RGB, RGBA, DEPTH_COMPONENT, 
  or STENCIL_INDEX"

   The following formats are required:

            Sized                 Base                  
            Internal Format       Internal format      
            ---------------       ---------------       
            RGB565_OES            RGB                
            RGBA4_OES             RGBA
            RGB5_A1_OES           RGBA
            DEPTH_COMPONENT16_OES DEPTH_COMPONENT

    The following formats are optional:

            Sized                 Base                  
            Internal Format       Internal format      
            --------------------- ---------------
            RGBA8_OES             RGBA
            RGB8_OES              RGB
            DEPTH_COMPONENT24_OES DEPTH_COMPONENT
            DEPTH_COMPONENT32_OES DEPTH_COMPONENT
            STENCIL_INDEX1_OES    STENCIL_INDEX      
            STENCIL_INDEX4_OES    STENCIL_INDEX      
            STENCIL_INDEX8_OES    STENCIL_INDEX      

The RGB8_OES and RGBA8_OES <internalformat> parameters to
RenderbufferStorageOES are only valid if OES_rgb8_rgba8 is
supported.

The DEPTH_COMPONENT24_OES <internalformat> parameter to
RenderbufferStorageOES is only valid if OES_depth24 is supported.

The DEPTH_COMPONENT32_OES <internalformat> parameter to
RenderbufferStorageOES is only valid if OES_depth32 is supported.

The STENCIL_INDEX1_OES <internalformat> parameter to
RenderbufferStorageOES is only valid if OES_stencil1 is supported.

The STENCIL_INDEX4_OES <internalformat> parameter to
RenderbufferStorageOES is only valid if OES_stencil4 is supported.

The STENCIL_INDEX8_OES <internalformat> parameter to
RenderbufferStorageOES is only valid if OES_stencil8 is supported.

INVALID_ENUM is generated if RenderbufferStorageOES is called with
an unsupported <internalformat>.

02/25/2005   Aaftab Munshi    First draft of extension
04/27/2005   Aaftab Munshi    Added additional limitations to simplify
                              OES_framebuffer_object implementations
07/06/2005   Aaftab Munshi    Added GetRenderbufferStorageFormatsOES
                              removed limitations that were added to OES
                              version of RenderbufferStorage,
                              and FramebufferTexture2DOES.
07/07/2005   Aaftab Munshi    Removed GetRenderbufferStorageFormatsOES
                              after discussions with Jeremy Sandmel,
                              and added specific extensions for the
                              optional renderbuffer storage foramts
07/18/2005   Aaftab Munshi    Added comment that optional formats can
                              be mandated by OpenGL ES APIs.
06/03/2006   Aaftab Munshi    Sync to revision 118 of EXT_framebuffer_object
04/22/2007   Jon Leech        Restore RGB565_OES to "New Tokens" section.
03/26/2008   Jon Leech        Add NONE_OES to "New Tokens" and use it
                              instead of the non-existent (in ES 1.x) NONE.
04/01/2008   Ben Bowman,      Remove COLOR_ATTACHMENT[1-15]_OES and
             Jon Leech        MAX_COLOR_ATTACHMENTS_OES to match the
                              latest headers.
04/10/2008   Jon Leech        Add enum values and fix names for
                              RGBA4_OES, RGB5_A1_OES, and
                              DEPTH_COMPONENT16_OES. Add issues
                              list. Improve documentation of
                              interaction with document interactions
                              with optional optional layered
                              renderbuffer format extensions.