OpenGL ES 3.0 Cookbook

There are two types of processors in the OpenGL ES 3.0 processing pipeline to execute vertex shader and fragment shader executables; it is called programmable processing unit:

Here are the sample codes for vertex and fragment shaders:

Like most of the languages, the shader program also starts its control from the main() function. In both shader programs, the first line, #version 300 es, specifies the GLES shading language version number, which is 3.0 in the present case. The vertex shader receives a per-vertex input variable VertexPosition. The data type of this variable is vec4, which is one of the inbuilt data types provided by OpenGL ES Shading Language. The in keyword in the beginning of the variable specifies that it is an incoming variable and it receives some data outside the scope of our current shader program. Similarly, the out keyword specifies that the variable is used to send some data value to the next stage of the shader. Similarly, the color information data is received in VertexColor. This color information is passed to TriangleColor, which sends this information to the fragment shader, and is the next stage of the processing pipeline.

The RadianAngle is a uniform type of variable that contains the rotation angle. This angle is used to calculate rotation matrix into rotation. Refer to following See also section to get reference for the per-vertex attribute and uniform variables.

The input values received by VertexPosition are multiplied using the rotation matrix, which will rotate the geometry of our triangle. This value is assigned to gl_Position. The gl_Position is an inbuilt variable of the vertex shader. This variable is supposed to write the vertex position in the homogeneous form. This value can be used by any of the fixed functionality stages, such as primitive assembly, rasterization, culling, and so on. Refer to the The fixed function and programmable pipeline architecture recipe in Appendix, Supplementary Information on OpenGL ES 3.0, for more information on the fixed stages.

In the fragment shader, the precision keyword specifies the default precision of all floating types (and aggregates, such as mat4 and vec4) to be mediump. The acceptable values of such declared types need to fall within the range specified by the declared precision. OpenGL ES Shading Language supports three types of the precision: lowp, mediump and highp. Specifying the precision in the fragment shader is compulsory. However, for vertex, if the precision is not specified, it is consider to be highest (highp).

FragColor is an out variable, which sends the calculated color values for each fragment to the next stage. It accepts the value in the RGBA color format.

As mentioned there are three types of precision qualifiers, the following table describes these:

The range and precision of these precision qualifiers are shown here:

The preceding image is taken from page 48 of https://www.khronos.org/registry/gles/specs/3.0/GLSL_ES_Specification_3.00.3.pdf.

Compiling and linking a shader is necessary so that these programs are understandable and executable by the underlying graphics hardware/platform (that is, the vertex and fragment processors).

The following figure provides an overview of the complete process of creating a shader executable. The different number labels help us understand the order of flow in the build process. Each stage within the build process is marked with the respective OpenGL ES APIs responsible for it.

In order to load and compile the shader source, use the following steps:

The loadAndCompileShader function first creates an empty shader object. This empty object is referenced by the shader variable. This object is bound with the source code of the corresponding shader. The source code is compiled through a shader object using the glCompileShader API. If the compilation is successful, the shader object handle is returned successfully. Otherwise, the shader object returns 0 and needs to be deleted explicitly using glDeleteShader. The status of the compilation can be checked using glGetShaderiv with GL_COMPILE_STATUS.

In order to differentiate among various versions of OpenGL ES and GL Shading Language, it is useful to get this information from the current driver of your device. This will be helpful to make the program robust and manageable by avoiding errors caused by version upgrade or application being installed on older versions of OpenGL ES and GLSL. The other vital information can be queried from the current driver, such as the vendor, renderer, and available extensions supported by the device driver. This information can be queried using the glGetString API. This API accepts a symbolic constant and returns the queried system metrics in the string form. The printGLString wrapper function in our program helps in printing device metrics:

static void printGLString(const char *name, GLenum s) {
    printf("GL %s = %s\n", name, (const char *) glGetString(s));
}
// Print the OpenGL ES system metrics
void printOpenGLESInfo(){
   printGLString("Version",    GL_VERSION);
   printGLString("Vendor",    GL_VENDOR);
   printGLString("Renderer",    GL_RENDERER);
   printGLString("Extensions",    GL_EXTENSIONS);
   printGLString("GLSL version",  GL_SHADING_LANGUAGE_VERSION);
}

The following instructions provides a step-by-step procedure to link as shader:

The linkShader wrapper function links the shader. It accepts two parameters: vertShaderID and fragShaderID. They are identifiers of the compiled shader objects. The createProgram function creates a program object. It is another OpenGL ES object to which shader objects are attached using glAttachShader. The shader objects can be detached from the program object if they are no longer in need. The program object is responsible for creating the executable program that runs on the programmable processor. A program in OpenGL ES is an executable in the OpenGL ES 3.0 pipeline that runs on the vertex and fragment processors.

The program object is linked using glLinkShader. If the linking fails, the program object must be deleted using glDeleteProgram. When a program object is deleted it automatically detached the shader objects associated with it. The shader objects need to be deleted explicitly. If a program object is requested for deletion, it will only be deleted until it's not being used by some other rendering context in the current OpenGL ES state.

If the program's object link successfully, then one or more executable will be created, depending on the number of shaders attached with the program. The executable can be used at runtime with the help of the glUseProgram API. It makes the executable a part of the current OpenGL ES state.

OpenGL ES 3.0 allows us to check the error using a simple routine called getGlError. The following wrapper function prints all the error messages occurred in the programming:

static void checkGlError(const char* op) {
     for(GLint error = glGetError(); error; error= glGetError()){
        printf("after %s() glError (0x%x)\n", op, error);
     }
}

The getGlError returns an error code. The following table describes these errors:

Syntax:

GLenum glGetError(void);

Here are few examples of code that produce OpenGL ES errors:

// Gives a GL_INVALID_ENUM error
glEnable(GL_TRIANGLES);

// Gives a GL_INVALID_VALUE
// when attribID >= GL_MAX_VERTEX_ATTRIBS
glEnableVertexAttribArray(attribID);

When OpenGL ES detects an error, it records the error into an error flag. Each error has a unique numeric code and symbolic name. OpenGL ES does not track each time an error has occurred. Due to performance reasons, detecting errors may degrade the rendering performance therefore, the error flag is not set until the glGetError routine is called. If there is no error detected, this routine will always return GL_NO_ERRORS. In distributed environment, there may be several error flags, therefore, it is advisable to call the glGetError routine in the loop, as this routine can record multiple error flags.

The vertex shader in the Programming shaders in GL shading language 3.0 recipe contains two per-vertex attributes named VertexPosition and VertexColor:

// Incoming vertex info from program to vertex shader
in vec4  VertexPosition;
in vec4  VertexColor;

The VertexPosition contains the 3D coordinates of the triangle that defines the shape of the object that we intend to draw on the screen. The VertexColor contains the color information on each vertex of this geometry.

In the vertex shader, a non-negative attribute location ID uniquely identifies each vertex attribute. This attribute location is assigned at the compile time if not specified in the vertex shader program. For more information on specifying the ID, refer to the See also section of this recipe.

Basically, the logic of sending data to their shader is very simple. It's a two-step process:

Follow this procedure to send data to a shader using the per-vertex attribute:

The per-vertex attribute variables VertexPosition and VertexColor defined in the vertex shader are the lifelines of the vertex shader. These lifelines constantly provide the data information form the client side (OpenGL ES program or CPU) to server side (GPU). Each per-vertex attribute has a unique attribute location available in the shader that can be queried using glGetAttribLocation. The per-vertex queried attribute locations are stored in positionAttribHandle; colorAttribHandle must be bound with the data using attribute location with glVertexAttribPointer. This API establishes a logical connection between client and server side. Now, the data is ready to flow from our data structures to the shader. The last important thing is the enabling of the attribute on the shader side for optimization purposes. By default, all the attribute are disabled. Therefore, even if the data is supplied for the client side, it is not visible at the server side. The glEnableVertexAttribArray API allows us to enable the per-vertex attributes on the shader side.

The vertex shader we programmed in the Programming shaders in OpenGL ES shading language 3.0 recipe contains a uniform variable RadianAngle. This variable is used to rotate the rendered triangle:

// Uniform variable for rotating triangle
uniform float  RadianAngle;

This variable will be updated on the client side (CPU) and send to the shader at server side (GPU) using special OpenGL ES 3.0 APIs. Similar to per-vertex attributes for uniform variables, we need to query and bind data in order to make it available in the shader.

Follow these steps to send data to a shader using uniform variables:

The uniform variable RadianAngle defined in the vertex shader is used to apply rotation transformation on the incoming per-vertex attribute VertexPosition. On the client side, this uniform variable is queried using glGetUniformLocation. This API returns the index of the uniform variable and stores it in radianAngle. This index will be used to bind the updated data information that is stored the radian with the glUniform1f OpenGL ES 3.0 API. Finally, the updated data reaches the vertex shader executable, where the general form of the Euler rotation is calculated:

mat2 rotation = mat2(cos(RadianAngle),sin(RadianAngle),
              -sin(RadianAngle),cos(RadianAngle));

The rotation transformation is calculated in the form of 2 x 2 matrix rotation, which is later promoted to a 4 x 4 matrix when multiplied by VertexPosition. The resultant vertices cause to rotate the triangle in a 2D space.

OpenGL ES requires a physical size (pixels) to define a 2D rendering surface called a viewport. This is used to define the OpenGL ES Framebuffer size.

A buffer in OpenGL ES is a 2D array in the memory that represents pixels in the viewport region. OpenGL ES has three types of buffers: color buffer, depth buffer, and stencil buffer. These buffers are collectively known as a framebuffer. All the drawings commands effect the information in the framebuffer.

The life cycle of this recipe is broadly divided into three states:

In our recipe, these states are represented by the GraphicsInit(), GraphicsResize(), and GraphicsRender() functions.

Follow these steps to program this recipe:

When the application starts, the control begins with GraphicsInit, where the system metrics are printed out to make sure that the device supports OpenGL ES 3.0. The OpenGL ES programmable pipeline requires vertex shader and fragment shader program executables in the rendering pipeline. The program object contains one or more executables after attaching the compiled shader objects and linking them to program. In the createProgramExec function the vertex and fragment shaders are compiled and linked, in order to generate the program object.

The GraphicsResize function generates the viewport of the given dimension. This is used internally by OpenGL ES 3.0 to maintain the framebuffer. In our current application, it is used to manage color buffer. Refer to the There's more … section for more information on other available buffers in OpenGL ES 3.0.

Finally, the rendering of the scene is performed by GraphicsRender, this function clears the color buffer with black background and renders the triangle on the screen. It uses a shader object program and sets it as the current rendering state using the glUseProgram API.

Each time a frame is rendered, data is sent from the client side (CPU) to the shader executable on the server side (GPU) using glVertexAttribPointer. This function uses the queried generic vertex attribute to bind the data with OpenGL ES pipeline.

There are other buffers also available in OpenGL ES 3.0:

The OpenGL ES API allows us to control each buffer separately. These buffers can be enabled and disabled as per the requirement of the rendering. The OpenGL ES can use any of these buffers (including color buffer) directly to act differently. These buffers can be set via preset values by using OpenGL ES APIs, such as glClearColor, glClearDepthf, and glClearStencil.

JNI creates a bridge between Java and native code via JNI interfaces. The Android NDK provides all the necessary tools such as libraries, source files, and compilers to help in building native code. It is believed that the development of the native code is faster, compared to Java code. Therefore, native development is better for memory management, performance, and cross-platform development.

In our first recipe, you will learn to program C/C++ code in the Android Java application. In this recipe, we will create a UI TextView control in the Android framework and display its contents as a string message sent from the C/C++ code. Java communicates with C/C++ through static/shared libraries, the NDK uses JNI and provides a means to develop these libraries under a Java environment.

As a prerequisite for NDK development, you must add Android NDK into the PATH environment variable, so that the NDK APIs are directly accessible from the command-line terminal.

Follow these steps to create an Android application with JNI support:

The regular Java code needs to know how to call the native C code. This is done by declaring functions in Java files where each function's signature is prefixed with a native keyword. The definition of these functions is defined in C/C++ source files. These functions need to redeclare in the header files, which must be located in the JNI folder. These declarations are in a special syntax rule that the ndk build understands. The functions are finally made available to Java in the form of shared or static libraries. You need to call this shared/static library within the Java code to use these exported functions.

In this recipe, you learned the convention to produce the JNI function's native method signatures. While working on large projects, sometimes, it is cumbersome to make such changes as the code could be significantly large. Additionally, the chances of human errors are also substantially high.

Alternately, the javah tool can be used to automate this process. It generates the C header and source files that are needed to implement native methods. It reads a Java class file and creates a C-language header file in the current working directory. The generated header and source files are used by C programs to reference an object's instance variables from the native source code. A detailed description of the usage of this tool is beyond the scope of this book. However, I highly recommend that you refer to the See also section for more information on this.

For our first Android OpenGL ES 3.0 recipe, we advise you to locate the sample AndroidHelloWorldTriangle recipe with this chapter. It will be helpful to import the contents to quickly build the application. To import recipes, refer to the Opening a sample project in Android ADT and iOS recipe in Appendix, Supplementary Information on OpenGL ES 3.0.

Here is the step-by-step procedure to program our first OpenGL ES 3.0 application in Android:

The first Android recipe for OpenGL ES 3.0 contains two OpenGL ES classes:

When the Android OpenGL ES framework launches an activity, it first checks the available EGL configurations on device and chooses the one best suited to our requirements. This configuration is used to create OpenGL ES rendering context. Finally, rendering is performed by GLSurfaceRenderer, where it calls the native OpenGL ES code with the help of the GLESNativeLib class.

The OpenGL ES rendering source is coded in NativeTemplate.cpp, which is exposed to the Android framework via the libglNative.so static library. This library is compiled from the NDK using the ndk-build command and is automatically stored under the folder AndroidBlueTriangle | libs | armeabi | libglNative.so.

You can explore more about the official Android OpenGL ES and its framework classes at http://developer.android.com/reference/android/opengl/package-summary.html.

Make sure that you should have iOS 7 support in your Xcode IDE. For more information, refer to the Software requirements for OpenGL ES 3.0 – Android ADT recipe in Appendix, Supplementary Information on OpenGL ES 3.0. It's advisable to import the sample recipe iOSHelloWorldTriangle in the Xcode. This will be helpful in understanding the theory quickly.

Here are the step-by-step descriptions of the first iOS OpenGL ES 3.0 application:

The program handles reference counting by itself. Therefore, it is advised that you disable the automatic reference count (ARC) to build the program. Otherwise, the compilation may fail. Follow these steps to disable the ARC:

The Xcode provides an app wizard to the build the applications for iOS 7.0. The OpenGL ES development uses GLKit, which was introduced in iOS 5.0. The GLKit is an OpenGL ES development framework in objective C/C++. It is used to develop 3D graphics applications for programmable pipeline architecture. Since we are developing a portable application that works across platforms, this kit might not be fully helpful for us (GLKit is in Objective C/C++) in that direction. We will create our custom graphics development framework, which will be helpful for portable applications across Android and iOS. We will use GLKit to build the bridge between our graphics development framework kit and iOS. We will introduce this framework in Chapter 2, OpenGL ES 3.0 Essentials.

The app wizard creates two classes for us, AppDelegate and ViewController. These classes are described here:

When iOS launches an application, it creates an instance of UIResponder, which basically creates the application object. This application object is a service for the application to provide a physical space in the screen window. This windowing is provided by the object of UIWindow, which will be created during the construction of UIApplication. This window object contains the desired view to display something on screen. In our case, this view should be some OpenGL rendering surface, which is provided by GLKitController to display. When the class object of GLKitController is created, it automatically creates the view associated with it. This helps the application to provide the necessary OpenGL rendering surface:

// AppDelegate.m
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
self.window = [[[UIWindow alloc] initWithFrame:[[UIScreen mainScreen]  bounds]] autorelease];
// Override point for customization after application launch.
self.viewController = [[[ViewController alloc] initWithNibName:@"ViewController" bundle:nil] autorelease];
self.window.rootViewController = self.viewController;
[self.window makeKeyAndVisible];
return YES;
}

The didFinishLaunchingWithOptions interface from UIApplicationDelete informs the event status of the application that it has completed loading. Within this event, we created the window and set the ViewController.

When a subclass from GLKitController is extended, it's very important that we override the viewDidLoad and viewDidUnload methods:

//  ViewController.mm
- (void)viewDidLoad
{
  [super viewDidLoad];
    
  self.context = [[[EAGLContext alloc] initWithAPI:kEAGLRenderingAPIOpenGLES3] autorelease];
  if (!self.context) {
    NSLog(@"Failed to create ES context");
  }
    
  GLKView *view = (GLKView *)self.view;
  view.context = self.context;
  view.drawableDepthFormat = GLKViewDrawableDepthFormat24;
  
  [self setupGL];
}

The viewDidLoad method helps create the rendering context and set up all its drawable properties for an appropriate configuration. To create an OpenGL ES 3.0 render context, we use initWithAPI. It accepts kEAGLRenderingAPIOpenGLES3 as an argument. This argument makes sure that the rendering context is meant for OpenGL ES 3.0 version.

We can modify the rendering context properties to configure the format of the drawable frame buffer object, such as drawableColorFormat, drawableDepthFormat, drawableStencilFormat and drawableMultisample.

This method is also a good place for initialization and other resource allocations. The last line is calling the setupGL function[self setupGL] in the objective C++ language syntax. Therefore, it is equivalent to this setupGL() in C++:

//  ViewController.mm
- (void)setupGL
{
  [EAGLContext setCurrentContext:self.context];
  GLint defaultFBO, defaultRBO;

  glGetIntegerv(GL_FRAMEBUFFER_BINDING &defaultFBO);
  glGetIntegerv(GL_RENDERBUFFER_BINDING, &defaultRBO);
  glBindFramebuffer( GL_FRAMEBUFFER, defaultFBO );
  glBindRenderbuffer( GL_RENDERBUFFER, defaultRBO );
    
  setupGraphics(self.view.bounds.size.width,
  self.view.bounds.size.height);

}

The setupGL function sets the current context with the one we created in viewDidApplication. This is very important to make the OpenGL ES APIs work. The glBindFramebuffer and glBindRenderbuffer APIs help the other APIs to know which target framebuffer to render on. In OpenGLES, the data is rendered in a rectangular array of information buffer container called a framebuffer. A framebuffer comprises many other helping buffers, such as color, depth, and stencil buffer, to accomplish rendering on the screen window. Sometimes, there could be cases where we may lose framebuffer or the render buffer. In such cases, it is advisable to bind these buffers with these two functions before you call any OpenGL ES3.0 API.

In order to render our application, we must override the drawRect method:

//  ViewController.mm
- (void)glkView:(GLKView *)view drawInRect:(CGRect)rect
{
    renderFrame();
}

The renderFrame function contains all the necessary code to render blue triangle.