blob: 6ad8f8986a1ce3d31f9e8ee2d60703129a3143e6 [file] [log] [blame]
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 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.