This section gives a high-level overview of what a vertex shader is. Vertex and fragment shaders are covered in depth in later chapters.

The vertex shader implements a general purpose programmable method for operating on vertices.

The inputs to the vertex shader consist of the following:

The outputs of the vertex shader are called varying variables. In the primitive rasterization stage, the varying values are calculated for each generated fragment and are passed in as inputs to the fragment shader. The mechanism used to generate a varying value for each fragment from the varying values assigned to each vertex of the primitive is called interpolation. The inputs and outputs of the vertex shader are diagramed in Figure 1-2.

Figure 1-2. OpenGL ES 2.0 Vertex Shader

Vertex shaders can be used for traditional vertex-based operations such as transforming the position by a matrix, computing the lighting equation to generate a per-vertex color, and generating or transforming texture coordinates. Alternately, because the vertex shader is specified by the application, vertex shaders can be used to do custom vertex transformations.

Example 1-1 shows a vertex shader written using the OpenGL ES shading language. We explain vertex shaders in significant detail later in the book. We show this shader now just to give you an idea of what a vertex shader looks like. The vertex shader in Example 1-1 takes a position and its associated color data as input attributes, transforms the position by a 4 × 4 matrix and outputs the transformed position and color.

1.  // uniforms used by the vertex shader
2.  uniform mat4   u_mvpMatrix; // matrix to convert P from model
3.                              // space to normalized device space.
4.
5.  // attributes input to the vertex shader
6.  attribute vec4   a_position; // position value
7.  attribute vec4   a_color;    // input vertex color
8.
9.  // varying variables - input to the fragment shader
10. varying vec4     v_color;    // output vertex color
11.
12. void
13. main()
14. {
15.     v_color = a_color;
16.     gl_Position = u_mvpMatrix * a_position;
17. }

Line 2 describes a uniform variable u_mvpMatrix that stores the combined model view and projection matrix. Lines 6 and 7 describe the inputs to the vertex shader and are referred to as vertex attributes. a_position is the input vertex position attribute and a_color is the input vertex color attribute. On line 10 we declare the varying v_color to store the output of the vertex shader that describes the per-vertex color. The built-in varying called gl_Position is declared automatically, and the shader must write the transformed position to this variable. A vertex or fragment shader has a single entry point called the main function. Lines 12-17 describe the vertex shader main function. In line 15, we read the vertex attribute input a_color and write it as the vertex output color v_color. In line 16, the transformed vertex position is output by writing it to gl_Position.

After the vertex shader, the next stage in the pipeline is primitive assembly. A primitive is a geometric object that can be drawn using appropriate drawing commands in OpenGL ES. These drawing commands specify a set of vertex attributes that describes the primitive’s geometry and a primitive type. Each vertex is described with a set of vertex attributes. These vertex attributes contain information that the vertex shader uses to calculate a position and other information that can be passed to the fragment shader such as its color and texture coordinates.

In the primitive assembly stage, the shaded vertices are assembled into individual geometric primitives that can be drawn such as a triangle, line, or point-sprite. For each primitive, it must be determined whether the primitive lies within the view frustum (the region of 3D space that is visible on the screen). If the primitive is not completely inside the view frustum, the primitive might need to be clipped to the view frustum. If the primitive is completely outside, it is discarded. After clipping, the vertex position is converted to screen coordinates. A culling operation can also be performed that discards primitives based on whether they face forward or backward. After clipping and culling, the primitive is ready to be passed to the next stage of the pipeline, which is the rasterization stage.

The next stage, shown in Figure 1-3, is the rasterization phase where the appropriate primitive (point-sprite, line, or triangle) is drawn. Rasterization is the process that converts primitives into a set of two-dimensional fragments, which are processed by the fragment shader. These two-dimensional fragments represent pixels that can be drawn on the screen.

Figure 1-3. OpenGL ES 2.0 Rasterization Stage

The fragment shader implements a general-purpose programmable method for operating on fragments.

The fragment shader, as shown in Figure 1-4, is executed for each generated fragment by the rasterization stage and takes the following inputs:

Figure 1-4. OpenGL ES 2.0 Fragment Shader

The fragment shader can either discard the fragment or generate a color value referred to as gl_FragColor. The color, depth, stencil, and screen coordinate location (xw, yw) generated by the rasterization stage become inputs to the per-fragment operations stage of the OpenGL ES 2.0 pipeline.

Example 1-2 describes a very simple fragment shader that can be coupled with the vertex shader described in Example 1-1 to draw a gouraud shaded triangle. Again, we will go into much more detail on fragment shaders later in the book. We present this just to give you a basic idea of what a fragment shader looks like.

1. precision mediump float;
2.
3. varying vec4   v_color;  // input vertex color from vertex shader
4.
5.
6. void
7. main(void)
8. {
9.     gl_FragColor = v_color;
10.}

Line 1 sets the default precision qualifier, which is explained in detail in Chapter 4, “Shaders and Programs.” Line 3 describes the input to the fragment shader. The vertex shader must write the same set of varying variables that are read by the fragment shader. Lines 6-10 describe the fragment shader main function. Note that no output is declared in the fragment shader. This is because the only output variable is gl_FragColor, which in this example is set to input color to the fragment shader given by v_color in line 9.

After the fragment shader, the next stage is per-fragment operations. A fragment produced by rasterization with (xw, yw) screen coordinates can only modify the pixel at location (xw, yw) in the framebuffer. Figure 1-5 describes the OpenGL ES 2.0 per-fragment operations stage.

Figure 1-5. OpenGL ES 2.0 Per-Fragment Operations

The per-fragment operations stage performs the following functions (and tests) on each fragment, as shown in Figure 1-5:

At the end of the per-fragment stage, either the fragment is rejected or a fragment color, depth, or stencil value is written to the framebuffer at location (xw, yw). The fragment color, depth, and stencil values are written depending on whether the appropriate write masks are enabled or not. Write masks allow finer control over the color, depth, and stencil values written into the appropriate buffers. For example, the write mask for the color buffer could be set such that no red values get written into the color buffer.

In addition, OpenGL ES 2.0 also provides an interface to read back the pixels from the framebuffer. Note that only pixels can be read back from the color buffer. The depth and stencil values cannot be read back.

OpenGL ES 2.0 applications will need to link with the following libraries: the OpenGL ES 2.0 library named libGLESv2.lib and the EGL library named libEGL.lib.

OpenGL ES 2.0 applications will need to include the appropriate ES 2.0 and EGL header files. The following include files must be included by any OpenGL ES 2.0 application:

#include <EGL/egl.h>
#include <GLES2/gl2.h>
#include <GLES2/gl2ext.h>

egl.h is the EGL header file, gl2.h is the OpenGL ES 2.0 header file, and gl2ext.h is the header file that describes the list of Khronos-approved extensions for OpenGL ES 2.0.

The header file and library names are platform dependent. The OpenGL ES working group has tried to define the library and header names and how they should be organized but this might not be the case for all OpenGL ES platforms. Developers should, however, refer to the platform vendor’s documentation for information on how the libraries and include files are named and organized.

All EGL commands begin with the prefix egl and use an initial capital letter for each word making up the command name (e.g., eglCreateWindowSurface). Similarly, EGL data types also begin with the prefix EGL and use an initial capital letter for each word making up the type name except for EGLint and EGLenum.

Table 1-1 gives a brief description of EGL data types used.

All OpenGL ES commands begin with the prefix gl and use an initial capital letter for each word making up the command name (e.g., glBlendEquation). Similarly, OpenGL ES data types also begin with the prefix GL.

In addition, some commands might take arguments in different flavors. The flavors or types vary by the number of arguments taken (one to four arguments), the data type of the arguments used (byte [b], unsigned byte [ub], short [s], unsigned short [us], int [i], fixed [x], and float [f]), and whether the arguments are passed as a vector (v) or not. A few examples of command flavors allowed in OpenGL ES follow.

The following two commands are equivalent except one specifies the uniform value as floats and the other as integers.

glUniform2f(location, 1.0f, 0.0f);
glUniform2i(location, 1, 0)

The following lines describe commands that are also equivalent but one passes command arguments as a vector and the other does not.

GLfloat   coord[4] = { 1.0f, 0.75f, 0.25f, 0.0f };
glUniform4fv(location, coord);
glUniform4f(location, coord[0], coord[1], coord[2], coord[3]);

Table 1-2 gives a description of the command suffixes and argument data types used in OpenGL ES.

Finally, OpenGL ES defines the type GLvoid. This is used for OpenGL ES commands that accept pointers.

In the rest of this book, OpenGL ES commands are referred to by their base names only and an asterisk is used to indicate that this refers to multiple flavors of the command name. For example, glUniform*() stands for all variations of the command you use to specify uniforms and glUniform*v() refers to all the vector versions of the command you use to specify uniforms. If a particular version of a command needs to be discussed, we use the full command name with the appropriate suffixes.

OpenGL ES commands incorrectly used by applications generate an error code. This error code is recorded and can be queried using glGetError. No other errors will be recorded until the application has queried the first error code using glGetError. Once the error code has been queried, the current error code is reset to GL_NO_ERROR. The command that generated the error is ignored and does not affect the OpenGL ES state except for the GL_OUT_OF_MEMORY error described later in this section.

The glGetError command is described next.

Table 1-3 lists the basic error codes and their description. There are other error codes besides the basic error codes listed in Table 1-3 that are described in the chapters that cover OpenGL ES commands that generate these specific errors.

The OpenGL ES 2.0 API inherits the OpenGL client-server model. The application, or client, issues commands, and these commands are processed by the OpenGL ES implementation or server. In OpenGL, the client and server can reside on different machines over a network. OpenGL ES also allows the client and server to reside on different machines but because OpenGL ES targets handheld and embedded platforms, the client and server will typically be on the same device.

In the client-server model, the commands issued by the client do not necessarily get sent to the server immediately. If the client and server are over a network, it will be very inefficient to send individual commands over the network. Instead, the commands can be buffered on the client side and then issued to the server at a later point in time. As a result, there needs to be a mechanism that lets the client know when the server has completed execution of previously submitted commands. Consider another example where multiple OpenGL ES contexts (each current to a different thread) are sharing objects. To synchronize correctly between these contexts, it is important that commands from context A be issued to the server before context B that depends on OpenGL ES state modified by context A. The glFlush command is used to flush any pending commands in the current OpenGL ES context and issue them to the server. Note that glFlush only issues the commands to the server and does not wait for them to complete. If the client requires that the commands be completed, the glFinish command should be used. We, however, do not recommend using glFinish unless absolutely necessary. Because glFinish does not return until all queued commands in the context have been completely processed by the server, calling glFinish can adversely impact performance by forcing the client and server to synchronize their operations.

void  glFlush(void)
void  glFinish(void)

Figure 1-1 showed the various pipeline stages in OpenGL ES 2.0. Each pipeline stage has state that can be enabled or disabled and appropriate state values that are maintained per context. Examples of state are blending enable, blend factors, cull enable, and cull face. This state is initialized with default values when an OpenGL ES context (EGLcontext) is initialized. The state enables can be set using the glEnable and glDisable commands.

The chapters that follow will describe the specific state enables for each pipeline stage shown in Figure 1-1. You can also check if a state is currently enabled or disabled by using the glIsEnabled command.

Specific state values such as blend factor, depth test values, and so on can also be queried using appropriate glGet*** commands. These commands are described in detail in Chapter 14, “State Queries.”