1Name 2 3 OES_framebuffer_object 4 5Name Strings 6 7 GL_OES_framebuffer_object 8 9Contact 10 11 Aaftab Munshi (amunshi@ati.com) 12 13Notice 14 15 Copyright (c) 2005-2013 The Khronos Group Inc. Copyright terms at 16 http://www.khronos.org/registry/speccopyright.html 17 18Specification Update Policy 19 20 Khronos-approved extension specifications are updated in response to 21 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 22 extensions which have been promoted to a core Specification, fixes will 23 first appear in the latest version of that core Specification, and will 24 eventually be backported to the extension document. This policy is 25 described in more detail at 26 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 27 28IP Status 29 30 None. 31 32Status 33 34 Ratified by the Khronos BOP, July 22, 2005. 35 36Version 37 38 Last Modified Date: April 10, 2008 39 40Number 41 42 OpenGL ES Extension #10 43 44Dependencies 45 46 OpenGL ES 1.0 is required. 47 OES_rgb8_rgba8 affects the definition of this extension. 48 OES_depth24 affects the definition of this extension. 49 OES_depth32 affects the definition of this extension. 50 OES_stencil1 affects the definition of this extension. 51 OES_stencil4 affects the definition of this extension. 52 OES_stencil8 affects the definition of this extension. 53 54Overview 55 56 This extension defines a simple interface for drawing to rendering 57 destinations other than the buffers provided to the GL by the 58 window-system. OES_framebuffer_object is a simplified version 59 of EXT_framebuffer_object with modifications to match the needs of 60 OpenGL ES. 61 62 In this extension, these newly defined rendering destinations are 63 known collectively as "framebuffer-attachable images". This 64 extension provides a mechanism for attaching framebuffer-attachable 65 images to the GL framebuffer as one of the standard GL logical 66 buffers: color, depth, and stencil. When a framebuffer-attachable 67 image is attached to the framebuffer, it is used as the source and 68 destination of fragment operations as described in Chapter 4. 69 70 By allowing the use of a framebuffer-attachable image as a rendering 71 destination, this extension enables a form of "offscreen" rendering. 72 Furthermore, "render to texture" is supported by allowing the images 73 of a texture to be used as framebuffer-attachable images. A 74 particular image of a texture object is selected for use as a 75 framebuffer-attachable image by specifying the mipmap level, cube 76 map face (for a cube map texture) that identifies the image. 77 The "render to texture" semantics of this extension are similar to 78 performing traditional rendering to the framebuffer, followed 79 immediately by a call to CopyTexSubImage. However, by using this 80 extension instead, an application can achieve the same effect, 81 but with the advantage that the GL can usually eliminate the data copy 82 that would have been incurred by calling CopyTexSubImage. 83 84 This extension also defines a new GL object type, called a 85 "renderbuffer", which encapsulates a single 2D pixel image. The 86 image of renderbuffer can be used as a framebuffer-attachable image 87 for generalized offscreen rendering and it also provides a means to 88 support rendering to GL logical buffer types which have no 89 corresponding texture format (stencil, etc). A renderbuffer 90 is similar to a texture in that both renderbuffers and textures can 91 be independently allocated and shared among multiple contexts. The 92 framework defined by this extension is general enough that support 93 for attaching images from GL objects other than textures and 94 renderbuffers could be added by layered extensions. 95 96 To facilitate efficient switching between collections of 97 framebuffer-attachable images, this extension introduces another new 98 GL object, called a framebuffer object. A framebuffer object 99 contains the state that defines the traditional GL framebuffer, 100 including its set of images. Prior to this extension, it was the 101 window-system which defined and managed this collection of images, 102 traditionally by grouping them into a "drawable". The window-system 103 APIs would also provide a function (i.e., eglMakeCurrent) to bind a 104 drawable with a GL context. In this extension, however, this 105 functionality is subsumed by the GL and the GL provides the function 106 BindFramebufferOES to bind a framebuffer object to the current context. 107 Later, the context can bind back to the window-system-provided framebuffer 108 in order to display rendered content. 109 110 Previous extensions that enabled rendering to a texture have been 111 much more complicated. One example is the combination of 112 ARB_pbuffer and ARB_render_texture, both of which are window-system 113 extensions. This combination requires calling MakeCurrent, an 114 operation that may be expensive, to switch between the window and 115 the pbuffer drawables. An application must create one pbuffer per 116 renderable texture in order to portably use ARB_render_texture. An 117 application must maintain at least one GL context per texture 118 format, because each context can only operate on a single 119 pixelformat or FBConfig. All of these characteristics make 120 ARB_render_texture both inefficient and cumbersome to use. 121 122 OES_framebuffer_object, on the other hand, is both simpler to use 123 and more efficient than ARB_render_texture. The 124 OES_framebuffer_object API is contained wholly within the GL API and 125 has no (non-portable) window-system components. Under 126 OES_framebuffer_object, it is not necessary to create a second GL 127 context when rendering to a texture image whose format differs from 128 that of the window. Finally, unlike the pbuffers of 129 ARB_render_texture, a single framebuffer object can facilitate 130 rendering to an unlimited number of texture objects. 131 132 Please refer to the EXT_framebuffer_object extension for a 133 detailed explaination of how framebuffer objects are supposed to work, 134 the issues and their resolution. This extension can be found at 135 http://oss.sgi.com/projects/ogl-sample/registry/EXT/framebuffer_object.txt 136 137Issues 138 139 1) This extension should fold in the language developed for the 140 "full" OpenGL ES Specifications; the current difference form is 141 somewhat confusing, particularly since the additional optional 142 renderbuffer formats defined by layered extensions are not 143 documented properly. 144 145 The normal way of writing this would be to omit all mention of 146 these formats from the base extension, and in the layered 147 extensions, state that they are added to the appropriate table or 148 section of the extension. Instead, they are listed as optional 149 here, and the layered extensions are underspecified. 150 151New Procedures and Functions 152 153 boolean IsRenderbufferOES(uint renderbuffer); 154 void BindRenderbufferOES(enum target, uint renderbuffer); 155 void DeleteRenderbuffersOES(sizei n, const uint *renderbuffers); 156 void GenRenderbuffersOES(sizei n, uint *renderbuffers); 157 158 void RenderbufferStorageOES(enum target, enum internalformat, 159 sizei width, sizei height); 160 161 void GetRenderbufferParameterivOES(enum target, enum pname, int* params); 162 163 boolean IsFramebufferOES(uint framebuffer); 164 void BindFramebufferOES(enum target, uint framebuffer); 165 void DeleteFramebuffersOES(sizei n, const uint *framebuffers); 166 void GenFramebuffersOES(sizei n, uint *framebuffers); 167 168 enum CheckFramebufferStatusOES(enum target); 169 170 void FramebufferTexture2DOES(enum target, enum attachment, 171 enum textarget, uint texture, 172 int level); 173 174 void FramebufferRenderbufferOES(enum target, enum attachment, 175 enum renderbuffertarget, uint renderbuffer); 176 177 void GetFramebufferAttachmentParameterivOES(enum target, enum attachment, 178 enum pname, int *params); 179 180 void GenerateMipmapOES(enum target); 181 182New Tokens 183 184 Accepted by the <target> parameter of BindFramebufferOES, 185 CheckFramebufferStatusOES, FramebufferTexture{2D|3D}OES, 186 FramebufferRenderbufferOES, and 187 GetFramebufferAttachmentParameterivOES: 188 189 FRAMEBUFFER_OES 0x8D40 190 191 Accepted by the <target> parameter of BindRenderbufferOES, 192 RenderbufferStorageOES, and GetRenderbufferParameterivOES, and 193 returned by GetFramebufferAttachmentParameterivOES: 194 195 RENDERBUFFER_OES 0x8D41 196 197 Accepted by the <internalformat> parameter of 198 RenderbufferStorageOES: 199 200 DEPTH_COMPONENT16_OES 0x81A5 201 RGBA4_OES 0x8056 202 RGB5_A1_OES 0x8057 203 RGB565_OES 0x8D62 204 STENCIL_INDEX1_OES 0x8D46 205 STENCIL_INDEX4_OES 0x8D47 206 STENCIL_INDEX8_OES 0x8D48 207 208 Accepted by the <pname> parameter of GetRenderbufferParameterivOES: 209 210 RENDERBUFFER_WIDTH_OES 0x8D42 211 RENDERBUFFER_HEIGHT_OES 0x8D43 212 RENDERBUFFER_INTERNAL_FORMAT_OES 0x8D44 213 RENDERBUFFER_RED_SIZE_OES 0x8D50 214 RENDERBUFFER_GREEN_SIZE_OES 0x8D51 215 RENDERBUFFER_BLUE_SIZE_OES 0x8D52 216 RENDERBUFFER_ALPHA_SIZE_OES 0x8D53 217 RENDERBUFFER_DEPTH_SIZE_OES 0x8D54 218 RENDERBUFFER_STENCIL_SIZE_OES 0x8D55 219 220 Accepted by the <pname> parameter of 221 GetFramebufferAttachmentParameterivOES: 222 223 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_OES 0x8CD0 224 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_OES 0x8CD1 225 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL_OES 0x8CD2 226 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_MAP_FACE_OES 0x8CD3 227 FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_OES 0x8CD4 228 229 Accepted by the <attachment> parameter of 230 FramebufferTexture{2D|3D}OES, FramebufferRenderbufferOES, and 231 GetFramebufferAttachmentParameterivOES 232 233 COLOR_ATTACHMENT0_OES 0x8CE0 234 DEPTH_ATTACHMENT_OES 0x8D00 235 STENCIL_ATTACHMENT_OES 0x8D20 236 237 Returned by GetFramebufferAttachmentParameterivOES when the 238 <pname> parameter is FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_OES: 239 240 GL_NONE_OES 0 241 242 Returned by CheckFramebufferStatusOES(): 243 244 FRAMEBUFFER_COMPLETE_OES 0x8CD5 245 FRAMEBUFFER_INCOMPLETE_ATTACHMENT_OES 0x8CD6 246 FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT_OES 0x8CD7 247 FRAMEBUFFER_INCOMPLETE_DIMENSIONS_OES 0x8CD9 248 FRAMEBUFFER_INCOMPLETE_FORMATS_OES 0x8CDA 249 FRAMEBUFFER_INCOMPLETE_DRAW_BUFFER_OES 0x8CDB 250 FRAMEBUFFER_INCOMPLETE_READ_BUFFER_OES 0x8CDC 251 FRAMEBUFFER_UNSUPPORTED_OES 0x8CDD 252 253 Accepted by GetIntegerv(): 254 255 FRAMEBUFFER_BINDING_OES 0x8CA6 256 RENDERBUFFER_BINDING_OES 0x8CA7 257 MAX_RENDERBUFFER_SIZE_OES 0x84E8 258 259 Returned by GetError(): 260 261 INVALID_FRAMEBUFFER_OPERATION_OES 0x0506 262 263OES_framebuffer_object implements the functionality defined by EXT_framebuffer_object 264with the following limitations: 265 266 - EXT versions of the entry points and tokens used by the desktop 267 extension are replaced with OES-suffixed versions, and GL_NONE is 268 replaced with GL_NONE_OES. 269 270 - there is no support for DrawBuffer{s}, ReadBuffer{s}, or multiple 271 color attachments; tokens COLOR_ATTACHMENT[1-15]_OES and 272 MAX_COLOR_ATTACHMENTS_OES are not supported. 273 274 - FramebufferTexture2DOES can be used to render 275 directly into the base level of a texture image only. Rendering to any 276 mip-level other than the base level is not supported. 277 278 - FramebufferTexture3DOES is optionally supported and is implemented only 279 if OES_texture_3D string is defined in the EXTENSIONS string returned by 280 OpenGL ES. 281 282 - section 4.4.2.1 of the EXT_framebuffer_object spec describes the function 283 RenderbufferStorageEXT. This function establishes the data storage, format, 284 and dimensions of a renderbuffer object's image. <target> must be 285 RENDERBUFFER_EXT. <internalformat> must be one of the internal formats 286 from table 3.16 or table 2.nnn which has a base internal format of RGB, RGBA, 287 DEPTH_COMPONENT, or STENCIL_INDEX. 288 289 The above paragraph is modified by OES_framebuffer_object and states thus: 290 291 "This function establishes the data storage, format, and 292 dimensions of a renderbuffer object's image. <target> must be RENDERBUFFER_OES. 293 <internalformat> must be one of the sized internal formats from the following 294 table which has a base internal format of RGB, RGBA, DEPTH_COMPONENT, 295 or STENCIL_INDEX" 296 297 The following formats are required: 298 299 Sized Base 300 Internal Format Internal format 301 --------------- --------------- 302 RGB565_OES RGB 303 RGBA4_OES RGBA 304 RGB5_A1_OES RGBA 305 DEPTH_COMPONENT16_OES DEPTH_COMPONENT 306 307 The following formats are optional: 308 309 Sized Base 310 Internal Format Internal format 311 --------------------- --------------- 312 RGBA8_OES RGBA 313 RGB8_OES RGB 314 DEPTH_COMPONENT24_OES DEPTH_COMPONENT 315 DEPTH_COMPONENT32_OES DEPTH_COMPONENT 316 STENCIL_INDEX1_OES STENCIL_INDEX 317 STENCIL_INDEX4_OES STENCIL_INDEX 318 STENCIL_INDEX8_OES STENCIL_INDEX 319 320Dependencies on OES_rgb8_rgba8 321 322 The RGB8_OES and RGBA8_OES <internalformat> parameters to 323 RenderbufferStorageOES are only valid if OES_rgb8_rgba8 is 324 supported. 325 326Dependencies on OES_depth24 327 328 The DEPTH_COMPONENT24_OES <internalformat> parameter to 329 RenderbufferStorageOES is only valid if OES_depth24 is supported. 330 331Dependencies on OES_depth32 332 333 The DEPTH_COMPONENT32_OES <internalformat> parameter to 334 RenderbufferStorageOES is only valid if OES_depth32 is supported. 335 336Dependencies on OES_stencil1 337 338 The STENCIL_INDEX1_OES <internalformat> parameter to 339 RenderbufferStorageOES is only valid if OES_stencil1 is supported. 340 341Dependencies on OES_stencil4 342 343 The STENCIL_INDEX4_OES <internalformat> parameter to 344 RenderbufferStorageOES is only valid if OES_stencil4 is supported. 345 346Dependencies on OES_stencil8 347 348 The STENCIL_INDEX8_OES <internalformat> parameter to 349 RenderbufferStorageOES is only valid if OES_stencil8 is supported. 350 351Errors 352 353 INVALID_ENUM is generated if RenderbufferStorageOES is called with 354 an unsupported <internalformat>. 355 356Revision History 357 358 02/25/2005 Aaftab Munshi First draft of extension 359 04/27/2005 Aaftab Munshi Added additional limitations to simplify 360 OES_framebuffer_object implementations 361 07/06/2005 Aaftab Munshi Added GetRenderbufferStorageFormatsOES 362 removed limitations that were added to OES 363 version of RenderbufferStorage, 364 and FramebufferTexture2DOES. 365 07/07/2005 Aaftab Munshi Removed GetRenderbufferStorageFormatsOES 366 after discussions with Jeremy Sandmel, 367 and added specific extensions for the 368 optional renderbuffer storage foramts 369 07/18/2005 Aaftab Munshi Added comment that optional formats can 370 be mandated by OpenGL ES APIs. 371 06/03/2006 Aaftab Munshi Sync to revision 118 of EXT_framebuffer_object 372 04/22/2007 Jon Leech Restore RGB565_OES to "New Tokens" section. 373 03/26/2008 Jon Leech Add NONE_OES to "New Tokens" and use it 374 instead of the non-existent (in ES 1.x) NONE. 375 04/01/2008 Ben Bowman, Remove COLOR_ATTACHMENT[1-15]_OES and 376 Jon Leech MAX_COLOR_ATTACHMENTS_OES to match the 377 latest headers. 378 04/10/2008 Jon Leech Add enum values and fix names for 379 RGBA4_OES, RGB5_A1_OES, and 380 DEPTH_COMPONENT16_OES. Add issues 381 list. Improve documentation of 382 interaction with document interactions 383 with optional optional layered 384 renderbuffer format extensions. 385