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 parameter of BindFramebufferOES, CheckFramebufferStatusOES, FramebufferTexture{2D|3D}OES, FramebufferRenderbufferOES, and GetFramebufferAttachmentParameterivOES: FRAMEBUFFER_OES 0x8D40 Accepted by the parameter of BindRenderbufferOES, RenderbufferStorageOES, and GetRenderbufferParameterivOES, and returned by GetFramebufferAttachmentParameterivOES: RENDERBUFFER_OES 0x8D41 Accepted by the 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 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 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 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 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. must be RENDERBUFFER_EXT. 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. must be RENDERBUFFER_OES. 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 parameters to RenderbufferStorageOES are only valid if OES_rgb8_rgba8 is supported. Dependencies on OES_depth24 The DEPTH_COMPONENT24_OES parameter to RenderbufferStorageOES is only valid if OES_depth24 is supported. Dependencies on OES_depth32 The DEPTH_COMPONENT32_OES parameter to RenderbufferStorageOES is only valid if OES_depth32 is supported. Dependencies on OES_stencil1 The STENCIL_INDEX1_OES parameter to RenderbufferStorageOES is only valid if OES_stencil1 is supported. Dependencies on OES_stencil4 The STENCIL_INDEX4_OES parameter to RenderbufferStorageOES is only valid if OES_stencil4 is supported. Dependencies on OES_stencil8 The STENCIL_INDEX8_OES parameter to RenderbufferStorageOES is only valid if OES_stencil8 is supported. Errors INVALID_ENUM is generated if RenderbufferStorageOES is called with an unsupported . 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.