xref: /third_party/openGLES/extensions/OES/OES_framebuffer_object.txt

Name

    OES_framebuffer_object

Name Strings

    GL_OES_framebuffer_object

Contact

    Aaftab Munshi (amunshi@ati.com)

Notice

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

Specification Update Policy

    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

IP Status

    None.

Status

    Ratified by the Khronos BOP, July 22, 2005.

Version

    Last Modified Date: April 10, 2008

Number

    OpenGL ES Extension #10

Dependencies

    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.

Overview

    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

Issues

    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.

New Procedures and Functions

    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);

New Tokens

    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

OES_framebuffer_object implements the functionality defined by EXT_framebuffer_object 
with the following limitations:

    - 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      

Dependencies on OES_rgb8_rgba8

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

Dependencies on OES_depth24

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

Dependencies on OES_depth32

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

Dependencies on OES_stencil1

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

Dependencies on OES_stencil4

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

Dependencies on OES_stencil8

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

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

Revision History

    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.