OpenGL ES supports three types of buffers, each of which stores different data for every pixel in the framebuffer:

The size of a buffer—commonly referred to as the “depth of the buffer” (but not to be confused with the depth buffer)—is measured by the number of bits that are available for storing information for a single pixel. The color buffer, for example, will have three components for storing the red, green, and blue color components, and optional storage for the alpha component. The depth of the color buffer is the sum of the number of bits for all of its components. For the depth and stencil buffers, on the other hand, a single value represents the bit depth of a pixel in those buffers. For example, a depth buffer might have 16 bits per pixel. The overall size of the buffer is the sum of the bit depths of all of the components. Common framebuffer depths include 16-bit RGB buffers, with five bits for red and blue, and six bits for green (the human visual system is more sensitive to green than red or blue), and 32 bits divided equally for an RGBA buffer.

Additionally, the color buffer may be double buffered, where it will contain two buffers: one that is displayed on the output device (usually a monitor or LCD display) named the “front” buffer; and another buffer that is hidden from the viewer, but used for constructing the next image to be displayed, and called the “back” buffer. In double-buffered applications, animation is accomplished by drawing into the back buffer, and then swapping the front and back buffers to display the new image. This swapping of buffers is usually synchronized with the refresh cycle of the display device, which will give the illusion of a continuously smooth animation. Recall that double buffering was discussed in Chapter 3, “An Introduction to EGL.”

Although every EGL configuration will have a color buffer, the depth and stencil buffers are optional. However, every EGL implementation must provide at least one configuration that contains all three of the buffers, with the depth buffer being at least 16 bits deep, and at least eight bits for the stencil buffer.

esCreateWindow(&esContext, "Application Name",
               window_width, window_height,
               ES_WINDOW_RGB | ES_WINDOW_DEPTH | ES_WINDOW_STENCIL);

The following sections describe the various tests that can be applied to a fragment in OpenGL ES. By default, all fragment tests and operations are disabled, and fragments become pixels as they are written to the framebuffer in the order in which they’re received. By enabling the various fragments, operational tests can be applied to choose which fragments become pixels and affect the final image.

Each fragment test is individually enabled by calling glEnable with the appropriate token listed in Table 11-1.

glStencilFunc(GL_EQUAL, 2, 0x7);

GLfloat vVertices[] =

 {
     -0.75f,  0.25f,  0.50f, // Quad #0
     -0.25f,  0.25f,  0.50f,
     -0.25f,  0.75f,  0.50f,
     -0.75f,  0.75f,  0.50f,
      0.25f,  0.25f,  0.90f, // Quad #1
      0.75f,  0.25f,  0.90f,
      0.75f,  0.75f,  0.90f,
      0.25f,  0.75f,  0.90f,
     -0.75f, -0.75f,  0.50f, // Quad #2
     -0.25f, -0.75f,  0.50f,
     -0.25f, -0.25f,  0.50f,
     -0.75f, -0.25f,  0.50f,
      0.25f, -0.75f,  0.50f, // Quad #3
      0.75f, -0.75f,  0.50f,
      0.75f, -0.25f,  0.50f,
      0.25f, -0.25f,  0.50f,
     -1.00f, -1.00f,  0.00f, // Big Quad
      1.00f, -1.00f,  0.00f,
      1.00f,  1.00f,  0.00f,
     -1.00f,  1.00f,  0.00f
 };
   GLubyte indices[][6] =
   {
       {  0,  1,  2,  0,  2,  3 }, // Quad #0
       {  4,  5,  6,  4,  6,  7 }, // Quad #1
       {  8,  9, 10,  8, 10, 11 }, // Quad #2
       { 12, 13, 14, 12, 14, 15 }, // Quad #3
       { 16, 17, 18, 16, 18, 19 }  // Big Quad
   };

#define NumTests  4
   GLfloat  colors[NumTests][4] =
   {
       { 1.0f, 0.0f, 0.0f, 1.0f },
       { 0.0f, 1.0f, 0.0f, 1.0f },
       { 0.0f, 0.0f, 1.0f, 1.0f },
       { 1.0f, 1.0f, 0.0f, 0.0f }
   };

   GLint    numStencilBits;
   GLuint  stencilValues[NumTests] =
   {
      0x7, // Result of test 0
      0x0, // Result of test 1
      0x2, // Result of test 2
      0xff // Result of test 3. We need to fill this
           // value in a run-time
   };

   // Set the viewport
   glViewport(0, 0, esContext->width, esContext->height);

   // Clear the color, depth, and stencil buffers. At this
   // point, the stencil buffer will be 0x1 for all pixels
   glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT |
           GL_STENCIL_BUFFER_BIT);

   // Use the program object
   glUseProgram(userData->programObject);

   // Load the vertex position
   glVertexAttribPointer(userData->positionLoc, 3, GL_FLOAT,
                         GL_FALSE, 0, vVertices);

   glEnableVertexAttribArray(userData->positionLoc);

   // Test 0:
   //
   // Initialize upper-left region. In this case, the stencil-
   // buffer values will be replaced because the stencil test
   // for the rendered pixels will fail the stencil test, which is
   //
   //        ref   mask    stencil  mask
   //      ( 0x7 & 0x3 ) < ( 0x1 & 0x7 )
   //
   // The value in the stencil buffer for these pixels will
   // be 0x7.
   //
   glStencilFunc(GL_LESS, 0x7, 0x3);
   glStencilOp(GL_REPLACE, GL_DECR, GL_DECR);
   glDrawElements(GL_TRIANGLES, 6, GL_UNSIGNED_BYTE, indices[0]);

   // Test 1:
   //
   // Initialize the upper right region. Here, we'll decrement
   // the stencil-buffer values where the stencil test passes
   // but the depth test fails. The stencil test is
   //
   //        ref  mask     stencil  mask
   //       ( 0x3 & 0x3 ) > ( 0x1 & 0x3 )
   //
   //    but where the geometry fails the depth test.  The
   //    stencil values for these pixels will be 0x0.
   //
   glStencilFunc(GL_GREATER, 0x3, 0x3);
   glStencilOp(GL_KEEP, GL_DECR, GL_KEEP);
   glDrawElements(GL_TRIANGLES, 6, GL_UNSIGNED_BYTE, indices[1]);

   // Test 2:
   //
   // Initialize the lower left region. Here we'll increment
   // (with saturation) the stencil value where both the
   // stencil and depth tests pass. The stencil test for
   // these pixels will be
   //
   //        ref  mask      stencil  mask
   //      ( 0x1 & 0x3 ) == ( 0x1 & 0x3 )
   //
   // The stencil values for these pixels will be 0x2.
   //
   glStencilFunc(GL_EQUAL, 0x1, 0x3);
   glStencilOp(GL_KEEP, GL_INCR, GL_INCR);
   glDrawElements(GL_TRIANGLES, 6, GL_UNSIGNED_BYTE, indices[2]);

   // Test 3:
   //
   // Finally, initialize the lower right region. We'll invert
   // the stencil value where the stencil tests fails. The
   // stencil test for these pixels will be
   //
   //        ref   mask    stencil  mask
   //      ( 0x2 & 0x1 ) == ( 0x1 & 0x1 )
   //
   // The stencil value here will be set to ~((2^s-1) & 0x1),
   // (with the 0x1 being from the stencil clear value),
   // where 's' is the number of bits in the stencil buffer
   //
   glStencilFunc(GL_EQUAL, 0x2, 0x1);
   glStencilOp(GL_INVERT, GL_KEEP, GL_KEEP);
   glDrawElements(GL_TRIANGLES, 6, GL_UNSIGNED_BYTE, indices[3]);

   // As we don't know at compile time how many stencil bits are
   // present, we'll query, and update the correct value in the
   // stencilValues arrays for the fourth tests. We'll use this
   // value later in rendering.
   glGetIntegerv(GL_STENCIL_BITS, &numStencilBits);

   stencilValues[3] = ~(((1 << numStencilBits) - 1) & 0x1) & 0xff;

   // Use the stencil buffer for controlling where rendering will
   // occur. We disable writing to the stencil buffer so we can
   // test against them without modifying the values we generated.
   glStencilMask(0x0);

   for(i = 0; i < NumTests; ++i)
   {
      glStencilFunc(GL_EQUAL, stencilValues[i], 0xff);
      glUniform4fv(userData->colorLoc, 1, colors[i]);
      glDrawElements(GL_TRIANGLES, 6, GL_UNSIGNED_BYTE, indices[4]);
   }

In this section, we discuss blending pixel colors. Once a fragment passes all of the enabled fragment tests, its color can be combined with the color that’s already present in the fragment’s pixel location. Before the two colors are combined, they’re multiplied by a scaling factor and combined using the specified blending operator. The blending equation is

C_final = f_source C_source op f_destingation C_destination

where f_source and C_source are the incoming fragment’s scaling factor and color, respectively. Likewise, f_destingation and C_destination are the pixel’s scaling factor and color. op is the mathematical operator for combining the scaled values.

The scaling factors are specified by calling either glBlendFunc or glBlendFuncSeparate.

The possible values for the blending coefficients are shown in Table 11-3.

In Table 11-3 (R_s, G_s, B_s, A_s) are the color components associated with the incoming fragment color, (R_d, G_d, B_d, A_d) are the components associated with the pixel color already in the color buffer, and (R_c, G_c, B_c, A_c) represent a constant color that you set by calling glBlendColor. In the case of GL_SRC_ALHPA_SATURATE, the minimum value that’s computed is applied to the source color only.

Once the incoming fragment and pixel color have been multiplied by their respective scaling factors, they’re combined using the operator specified by glBlendEquation or glBlendEquationSeparate. By default, blended colors are accumulated using the GL_FUNC_ADD operator. The GL_FUNC_SUBTRACT operator subtracts the scaled color from the framebuffer from the incoming fragment’s value. Likewise, the GL_FUNC_REVERSE_SUBTRACT reverses the blending equation such that the incoming fragment colors are subtracted from the current pixel value.

On a system where the number of colors available in the framebuffer is limited due to the number of bits per component in the framebuffer, we can simulate greater color depth using dithering. Dithering algorithms arrange colors in such ways that the image appears to have more available colors than are really present. OpenGL ES 2.0 doesn’t specify which dithering algorithm is to be used in supporting its dithering stage; the technique is very implementation dependent.

The only control your application has over dithering is whether it is applied to the final pixels or not, which is entirely controlled by calling glEnable or glDisable to specify dithering’s use in the pipeline.

Antialiasing is an important technique for improving the quality of generated images by trying to reduce the visual artifacts of rendering into discrete pixels. The geometric primitives that OpenGL ES 2.0 renders get rasterized onto a grid, and their edges may become deformed in that process. We’ve all seen that staircase effect that happens to lines drawn diagonally across a monitor.

There are various techniques for trying to reduce those aliasing effects, and OpenGL ES 2.0 supports a variant called multisampling. Multisampling divides every pixel into a set of samples, each of which is treated like a “mini-pixel” during rasterization. That is, when a geometric primitive is rendered, it’s like rendering into a framebuffer that has many more pixels than the real display surface. Each sample has its own color, depth, and stencil value, and those values are preserved until the image is ready for display. When it’s time to compose the final image, the samples are resolved into the final pixel color. What makes this process special is that in addition to using every sample’s color information, OpenGL ES 2.0 also has additional information about how many samples for a particular pixel were occupied during rasterization. Each sample for a pixel is assigned a bit in the sample coverage mask. Using that coverage mask, we can control how the final pixels are resolved. Every rendering surface created for an OpenGL ES 2.0 application will be configured for multisampling, even if there’s only a single sample per pixel.

Multisampling has multiple options that can be turned on and off (using glEnable and glDisable) to control the usage of sample coverage value. First, you can specify that the sample’s alpha value should be used to determine the coverage value by enabling GL_SAMPLE_ALPHA_TO_COVERAGE. In this mode, if the geometric primitive covers a sample, the alpha value of incoming fragment is used to determine an additional sample coverage mask computed that is bitwise AND’ed into the coverage mask that is computed using the samples of the fragment. This newly computed coverage value replaces the original one generated directly from the sample coverage calculation. These sample computations are implementation dependent.

Additionally you can specify GL_SAMPLE_COVERAGE, which uses the fragment’s (potentially modified by previous operations listed earlier) coverage value, and computes the bitwise-and of that value with one specified using the glSampleCoverage function. The value specified with glSampleCoverage is used to generate an implementation-specific coverage mask, and includes an inversion flag, invert, that inverts the bits in the generated mask. Using this inversion flag, it is possible to create two transparency masks that don’t use entirely distinct sets of samples.

Although multisampling helps reduce aliasing in scenes, it is also prone to artifacts that may be visually displeasing. This usually occurs due to the sample locations with a pixel. This problem can be rectified by using centroid sampling, which is unfortunately not a feature that OpenGL ES 2.0 supports at the time of this writing.

If you would like to preserve your rendered image for posterity’s sake, you can read the pixel values back from the color buffer, but not from the depth or stencil buffers. By calling glReadPixels, the pixels in the color buffer are returned to your application in an array that has been previously allocated.

Aside from the fixed format (GL_RGB), and type (GL_UNSIGNED_BYTE), you’ll notice there are implementation-dependent values that should return the best format and type combination for the implementation you’re using. The implementation-specific values can be queried as follows:

GLenum    readType, readFormat;
GLubyte  *pixels;

glGetIntegerv(GL_IMPLEMENTATION_COLOR_READ_TYPE, &readType);
glGetIntegerv(GL_IMPLEMENTATION_COLOR_READ_FORMAT, &readFormat);

unsigned int  bytesPerPixel = 0;

switch(readType)
{
     case GL_UNSIGNED_BYTE:
         switch(readFormat)
         {
             case GL_RGBA:
                 bytesPerPixel = 4;
                 break;
             case GL_RGB:
                 bytesPerPixel = 3;
                 break;

             case GL_LUMINANCE_ALPHA:
                 bytesPerPixel = 2;
                 break;

             case GL_ALPHA:
             case GL_LUMINANCE:
                 bytesPerPixel = 1;
                 break;
         }
         break;

     case GL_UNSIGNED_SHORT_4444:   // GL_RGBA format
     case GL_UNSIGNED_SHORT_555_1:  // GL_RGBA format
     case GL_UNSIGNED_SHORT_565:    // GL_RGB  format
         bytesPerPixel = 2;
         break;
}

pixels = (GLubyte*) malloc(width * height * bytesPerPixel);

glReadPixels(0, 0, windowWidth, windowHeight, readFormat,
             readType, pixels );

You can read pixels from any currently bound framebuffer, whether it’s one allocated by the windowing system, or from a framebuffer object. Because each buffer can have a different layout, you’ll probably need to query the type and format for each buffer you want to read.

OpenGL ES 2.0 doesn’t have a function to directly copy a block of pixels into the framebuffer. Instead, the available method is to create a texture map from the block of pixels, and use the texture-mapping technique described in Chapter 9, “Texturing,” to initiate writing the pixels.