A rendering context and a drawing surface need to be first created and made current before any OpenGL ES commands can be called by an application. The rendering context and the drawing surface are usually provided by the native windowing system through an API such as EGL. Chapter 3 describes how to create an EGL context and surface and how to attach them to a rendering thread. The rendering context contains appropriate state required for correct operation. The drawing surface provided by the native windowing system can be a surface that will be displayed on the screen, referred to as the window system provided framebuffer, or can be an off-screen surface, referred to as a pbuffer. The calls to create the EGL drawing surfaces let you specify the width and height of the surface in pixels, whether the surface uses color-, depth-, and stencil buffers, and bit depths of these buffers.

By default, OpenGL ES uses the window system provided framebuffer as the drawing surface. If the application is only drawing to an on-screen surface, the window system provided framebuffer is usually sufficient. However, many applications need to render to a texture, and for this using the window system provided framebuffer as your drawing surface is usually not an ideal option. Examples of where render to texture is useful are dynamic reflections and environment-mapping, multipass techniques for depth-of-field, motion blur effects, and post-processing effects.

There are two techniques that applications can use to render to a texture:

Neither of these two methods are ideal for rendering to a texture or other off-screen surface. What is needed are APIs that allow applications to directly render to a texture or the ability to create an off-screen surface within the OpenGL ES API and use it as a rendering target. Framebuffer objects and renderbuffer objects allow applications to do exactly this without requiring additional rendering contexts to be created. We no longer have to worry about the overhead of a context and drawable switch that can occur when using window system provided drawables. Framebuffer objects therefore provide a better and more efficient method for rendering to a texture or an off-screen surface.

The Framebuffer objects API supports the following operations:

We describe what a renderbuffer and a framebuffer object are, how they differ from window system provided drawables, and when to use a renderbuffer instead of a texture.

A renderbuffer object is a 2D image buffer allocated by the application. The renderbuffer can be used to allocate and store color, depth, or stencil values and can be used as a color, depth, or stencil attachment in a framebuffer object. A renderbuffer is similar to an off-screen window system provided drawable surface, such as a pbuffer. A renderbuffer, however, cannot be directly used as a GL texture.

A framebuffer object (often referred to as an FBO) is a collection of color, depth, and stencil buffer attachment points; state that describes properties such as the size and format of the color, depth, and stencil buffers attached to the FBO; and the names of the texture and renderbuffer objects attached to the FBO. Various 2D images can be attached to the color attachment point in the framebuffer object. These include a renderbuffer object that stores color values, a mip-level of a 2D texture or a cubemap face, or even a mip-level of a 2D slice in a 3D texture. Similarly, various 2D images containing depth values can be attached to the depth attachment point of an FBO. These can include a renderbuffer, a mip-level of a 2D texture or a cubemap face that stores depth values. The only 2D image that can be attached to the stencil attachment point of an FBO is a renderbuffer object that stores stencil values.

Figure 12-1 shows the relationship among framebuffer objects, renderbuffer objects, and textures. Note that there can only be one color, depth, and stencil attachment in a framebuffer object.

Figure 12-1. Framebuffer Objects, Renderbuffer Objects, and Textures

Creating framebuffer and renderbuffer objects is similar to how texture or vertex buffer objects are created in OpenGL ES 2.0.

The glGenRenderbuffers API call is used to allocate renderbuffer object names. This API is described next.

glGenRenderbuffers allocates n renderbuffer object names and returns them in renderbuffers. The renderbuffer object names returned by glGenRenderbuffers are unsigned integer numbers other than 0. The renderbuffer names returned are marked in use but do not have any state associated with them. The value 0 is reserved by OpenGL ES and does not refer to a renderbuffer object. Applications trying to modify or query buffer object state for renderbuffer object 0 will generate an appropriate error.

The glGenFramebuffers API call is used to allocate framebuffer object names. This API is described here.

glGenFramebuffers allocates n framebuffer object names and returns them in ids. The framebuffer object names returned by glGenFramebuffers are unsigned integer numbers other than 0. The framebuffer names returned are marked in use but do not have any state associated with them. The value 0 is reserved by OpenGL ES and refers to the window system provided framebuffer. Applications trying to modify or query buffer object state for framebuffer object 0 will generate an appropriate error.

In this section, we describe how to specify the data storage, format, and dimensions of the renderbuffer image. To specify this information for a specific renderbuffer object, we need to make this object the current renderbuffer object. The glBindRenderbuffer command is used to set the current renderbuffer object.

Note that glGenRenderbuffers is not required to assign a renderbuffer object name before it is bound using glBindRenderbuffer. Although it is a good practice to call glGenRenderbuffers, there are lots of applications that specify compile-time constants for their buffers. An application can specify an unused renderbuffer object name to glBindRenderbuffer. However, we do recommend that OpenGL ES applications call glGenRenderbuffers and use renderbuffer object names returned by glGenRenderbuffers instead of specifying their own buffer object names.

The first time the renderbuffer object name is bound by calling glBindRenderbuffer, the renderbuffer object is allocated with the appropriate default state and if the allocation is successful, this allocated object will become the newly bound renderbuffer object.

The following state and default values are associated with a renderbuffer object:

glBindRenderbuffer can also be used to bind to an existing renderbuffer object (i.e., an object that has been assigned and used before and therefore has valid state associated with it). No changes to the state of the newly bound renderbuffer object are made by the bind command.

Once a renderbuffer object is bound, we can specify the dimensions and format of the image stored in the renderbuffer. The glRenderbufferStorage command can be used to specify this information.

glRenderbufferStorage looks very similar to glTexImage2D except that no image data is supplied. The width and height of the renderbuffer is specified in pixels and must be values that are smaller than the maximum renderbuffer size supported by the implementation. The minimum size value that must be supported by all OpenGL ES implementations is 1. The actual maximum size supported by the implementation can be queried using the following code example.

GLint maxRenderbufferSize;
glGetIntegerv(GL_MAX_RENDERBUFFER_SIZE, &maxRenderbufferSize);

The internalformat argument specifies the format that the application would like to use to store pixels in the renderbuffer object.

The renderbuffer object can be attached to the color, depth, or stencil attachment of the framebuffer object without the renderbuffer’s storage format and dimensions specified. The renderbuffer’s storage format and dimensions can be specified before or after the renderbuffer object has been attached to the framebuffer object. This information will, however, need to be correctly specified before the framebuffer object and renderbuffer attachment can be used for rendering.

We describe how to use framebuffer objects to render to an off-screen buffer (i.e., renderbuffer) or to render to a texture. Before we can use a framebuffer object and specify its attachments, we need to make it the current framebuffer object. The glBindFramebuffer command is used to set the current framebuffer object.

Note that glGenFramebuffers is not required to assign a framebuffer object name before it is bound using glBindFramebuffer. An application can specify an unused framebuffer object name to glBindFramebuffer. However, we do recommend that OpenGL ES applications call glGenFramebuffers and use framebuffer object names returned by glGenFramebuffers instead of specifying their own buffer object names.

The first time a framebuffer object name is bound by calling glBindFramebuffer, the framebuffer object is allocated with appropriate default state, and if the allocation is successful, this allocated object is bound as the current framebuffer object for the rendering context.

The following state is associated with a framebuffer object:

For each attachment point, the following information is specified:

glBindFramebuffer can also be used to bind to an existing framebuffer object (i.e., an object that has been assigned and used before and therefore has valid state associated with it). No changes are made to the state of the newly bound framebuffer object.

Once a framebuffer object has been bound, the color, depth, and stencil attachments of the currently bound framebuffer object can be set to a renderbuffer object or a texture. As shown in Figure 12-1, the color attachment can be set to a renderbuffer that stores color values, or to a mip-level of a 2D texture or a cubemap face, or to a mip-level of a 2D slice in a 3D texture. The depth attachment can be set to a renderbuffer that stores depth values, to a mip-level of a 2D depth texture, or to a depth cubemap face. The stencil attachment must be set to a renderbuffer that stores stencil values.

After the application is done using renderbuffer objects, they can be deleted. Deleting renderbuffer and framebuffer objects is very similar to deleting texture objects.

Renderbuffer objects are deleted using the glDeleteRenderbuffers API.

glDeleteRenderbuffers deletes the renderbuffer objects specified in renderbuffers. Once a renderbuffer object is deleted, it has no state associated with it and is marked as unused and can later be reused as a new renderbuffer object. When deleting a renderbuffer object that is also the currently bound renderbuffer object, the renderbuffer object is deleted and the current renderbuffer binding is reset to zero. If renderbuffer object names specified in renderbuffers are invalid or zero, they are ignored (i.e., no error will be generated). Further if the renderbuffer is attached to the currently bound framebuffer object, it is first detached from the framebuffer and then deleted.

Framebuffer objects are deleted using the glDeleteFramebuffers API.

glDeleteFramebuffers deletes the framebuffer objects specified in framebuffers. Once a framebuffer object is deleted, it has no state associated with it and is marked as unused and can later be reused as a new framebuffer object. When deleting a framebuffer object that is also the currently bound framebuffer object, the framebuffer object is deleted and the current framebuffer binding is reset to zero. If framebuffer object names specified in framebuffers are invalid or zero, they are ignored and no error will be generated.

Let’s now look at some examples that demonstrate how to use framebuffer objects. Example 12-1 demonstrates how to render to texture using framebuffer objects. In this example we draw to a texture using a framebuffer object. We then use this texture to draw a quad to the window system provided framebuffer (i.e., the screen). Figure 12-2 shows the generated image.

GLuint   framebuffer;
GLuint   depthRenderbuffer;
GLuint   texture;
GLint    texWidth = 256, texHeight = 256;
GLint    maxRenderbufferSize;

glGetIntegerv(GL_MAX_RENDERBUFFER_SIZE, &maxRenderbufferSize);

// check if GL_MAX_RENDERBUFFER_SIZE is >= texWidth and texHeight
if((maxRenderbufferSize <= texWidth) ||
   (maxRenderbufferSize <= texHeight))
{
   // cannot use framebuffer objects as we need to create
   // a depth buffer as a renderbuffer object
   // return with appropriate error
}

// generate the framebuffer, renderbuffer, and texture object names
glGenFramebuffers(1, &framebuffer);
glGenRenderbuffers(1, &depthRenderbuffer);
glGenTextures(1, &texture);

// bind texture and load the texture mip-level 0
// texels are RGB565
// no texels need to be specified as we are going to draw into
// the texture
glBindTexture(GL_TEXTURE_2D, texture);
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB, texWidth, texHeight,
             0, GL_RGB, GL_UNSIGNED_SHORT_5_6_5, NULL);

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);

// bind renderbuffer and create a 16-bit depth buffer
// width and height of renderbuffer = width and height of
// the texture
glBindRenderbuffer(GL_RENDERBUFFER, depthRenderbuffer);
glRenderbufferStorage(GL_RENDERBUFFER, GL_DEPTH_COMPONENT16,
                      texWidth, texHeight);

// bind the framebuffer
glBindFramebuffer(GL_FRAMEBUFFER, framebuffer);

// specify texture as color attachment
glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0,
                       GL_TEXTURE_2D, texture, 0);

// specify depth_renderbufer as depth attachment
glFramebufferRenderbuffer(GL_FRAMEBUFFER, GL_DEPTH_ATTACHMENT,
                          GL_RENDERBUFFER, depthRenderbuffer);

// check for framebuffer complete
status = glCheckFramebufferStatus(GL_FRAMEBUFFER);
if(status == GL_FRAMEBUFFER_COMPLETE)
{
   // render to texture using FBO
   // clear color and depth buffer
   glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
   glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

   // load uniforms for vertex and fragment shader
   // used to render to FBO. The vertex shader is the
   // ES 1.1 vertex shader described as Example 8-8 in
   // Chapter 8. The fragment shader outputs the color
   // computed by vertex shader as fragment color and
   // is described as Example 1-2 in Chapter 1.
   set_fbo_texture_shader_and_uniforms();

   // drawing commands to the framebuffer object
   draw_teapot();

   // render to window system provided framebuffer
   glBindFramebuffer(GL_FRAMEBUFFER, 0);
   // Use texture to draw to window system provided framebuffer
   // We draw a quad that is the size of the viewport.
   //
   // The vertex shader outputs the vertex position and texture
   // coordinates passed as inputs.
   //
   // The fragment shader uses the texture coordinate to sample
   // the texture and uses this as the per-fragment color value.
   set_screen_shader_and_uniforms();
   draw_screen_quad();
}

// cleanup
glDeleteRenderbuffers(1, &depthRenderbuffer);
glDeleteFramebuffers(1, &framebuffer);
glDeleteTextures(1, &texture);

Figure 12-2. Render to Color Texture

In Example 12-1 we create the framebuffer, texture, and depthRenderbuffer objects using appropriate glGen*** commands. framebuffer uses a color attachment that is a texture object (texture) and a depth attachment that is a renderbuffer object (depthRenderbuffer).

Before we create these objects, we query the maximum renderbuffer size (GL_MAX_RENDERBUFFER_SIZE) to make sure that the maximum renderbuffer size supported by the implementation is less than or equal to the width and height of texture that will be used as a color attachment. This is to ensure that we can create a depth renderbuffer successfully and use it as the depth attachment in framebuffer.

After the objects have been created, we call glBindTexture(texture) to make the texture the currently bound texture object. The texture mip-level is then specified using glTexImage2D. Note that the pixels argument is NULL. This is because we are rendering to the entire texture region and therefore there is no reason to specify any input data as it will get overwritten.

The depthRenderbuffer object is bound using glBindRenderbuffer and glRenderbufferStorage is called to allocate storage for a 16-bit depth buffer.

The framebuffer object is bound using glBindFramebuffer. texture is attached as a color attachment to framebuffer and depthRenderbuffer is attached as a depth attachment to framebuffer.

We now check if the framebuffer status is complete before we begin drawing into framebuffer. Once framebuffer rendering is complete, we reset the currently bound framebuffer to the window system provided framebuffer by calling glBindFramebuffer(GL_FRAMEBUFFER, 0). We can now use texture that was used as a render target in framebuffer to draw to the window system provided framebuffer.

In Example 12-1, the depth buffer attachment to framebuffer was a renderbuffer object. In Example 12-2 we look at how to use a depth texture as a depth buffer attachment to framebuffer. This feature is available if the OES_depth_texture extension is supported by the implementation. Applications can render to the depth texture used as a framebuffer attachment from the light source. The rendered depth texture can then be used as a shadow map to calculate the percentage in shadow for each fragment. Figure 12-3 shows the generated image.

#define COLOR_TEXTURE    0
#define DEPTH_TEXTURE    1

GLuint   framebuffer;
GLuint   textures[2];
GLint    texWidth = 256, texHeight = 256;

// generate the framebuffer, & texture object names
glGenFramebuffers(1, &framebuffer);
glGenTextures(2, textures);

// bind  color texture and load the texture mip-level 0
// texels are RGB565
// no texels need to specified as we are going to draw into
// the texture
glBindTexture(GL_TEXTURE_2D, textures[COLOR_TEXTURE]);
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB, texWidth, texHeight,
             0, GL_RGB, GL_UNSIGNED_SHORT_5_6_5, NULL);

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);

// bind  depth texture and load the texture mip-level 0
// no texels need to specified as we are going to draw into
// the texture
glBindTexture(GL_TEXTURE_2D, textures[DEPTH_TEXTURE]);
glTexImage2D(GL_TEXTURE_2D, 0, GL_DEPTH_COMPONENT, texWidth,
             texHeight, 0, GL_DEPTH_COMPONENT, GL_UNSIGNED_SHORT,
             NULL);

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST);



// bind the framebuffer
glBindFramebuffer(GL_FRAMEBUFFER, framebuffer);

// specify texture as color attachment
glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0,
                       GL_TEXTURE_2D, textures[COLOR_TEXTURE], 0);

// specify texture as depth attachment
glFramebufferTexture2D(GL_FRAMEBUFFER, GL_DEPTH_ATTACHMENT,
                       GL_TEXTURE_2D, textures[DEPTH_TEXTURE], 0);

// check for framebuffer complete
status = glCheckFramebufferStatus(GL_FRAMEBUFFER);
if (status == GL_FRAMEBUFFER_COMPLETE)
{
   // render to color & depth textures using FBO
   // clear color & depth buffer
   glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
   glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

   // load uniforms for vertex and fragment shader
   // used to render to FBO. The vertex shader is the
   // ES 1.1 vertex shader described as Example 8-8 in
   // Chapter 8. The fragment shader outputs the color
   // computed by vertex shader as fragment color and
   // is described as Example 1-2 in Chapter 1.
   set_fbo_texture_shader_and_uniforms();

   // drawing commands to the framebuffer object
   draw_teapot();

   // render to window system provided framebuffer
   glBindFramebuffer(GL_FRAMEBUFFER, 0);

   // Use depth texture to draw to window system framebuffer
   // We draw a quad that is the size of the viewport.
   //
   // The vertex shader outputs the vertex position and texture
   // coordinates passed as inputs.
   //
   // The fragment shader uses the texture coordinate to sample
   // the texture and uses this as the per-fragment color value.
   set_screen_shader_and_uniforms();
   draw_screen_quad();
}

// cleanup
glDeleteRenderbuffers(1, &depthRenderbuffer);
glDeleteFramebuffers(1, &framebuffer);
glDeleteTextures(1, &texture);

Figure 12-3. Render to Depth Texture

Here we discuss some performance tips that developers should carefully consider when using framebuffer objects.