WebGL Textures & Vertices: Beginner's Guide (2015)

Entity Summary

The GLEntity class prepares a texture and matrix for use with WebGL. The section titled Default Matrix for Each Entity discusses the GLEntity matrix property. This section detailed texture initialization. A set of GLEntitymay share one texture, or each entity may retain a unique texture. A set of GLEntity may share shader variables, or each entity can use a unique set of shader variables. The GLEntity property uSampler maintains the location of a uniform sampler2D. The aTexCoord property saves the location of an attribute for processing texture coordinates.

This section discussed GLEntity methods getImageVariables(), setImage(), setActiveTexture(), setMinMagFilters(), and last setWrapToEdges(). Method getImageVariables() saves the location of shader variables associated with the entity's texture. Method setImage() activates and creates a WebGLTexture for the entity. Method setMinMagFilters() assigns minification and magnification filters for the active texture. Method setWrapToEdges() assigns wrapping types for the active texture.

GLEntity follows the sequence listed below, to prepare a texture for processing in the shader.

1. Assign a texture unit to a sampler with WebGL method uniform1i().

2. Create a texture with WebGL method createTexture().

3. Activate a texture unit with WebGL method activeTexture().

4. Bind the texture to a target with WebGL method bindTexture().

5. Tell the GPU how to store pixel data with WebGL method pixelStorei().

6. Upload image data with WebGL method texImage2D().

7. Assign wrapping modes with WebGL method texParameteri().

8. Assign minification and magnification filters with WebGL method texParameteri().

WebGL API methods covered include getUniformLocation(), getAttribLocation(), vertexAttribPointer(), enableVertexAttribArray(), uniformi(), createTexture(), texParameteri(), activeTexture(), bindTexture(),pixelStorei(), and texImage2D().

Finalize then Display the Mesh

The GLEntity method setImage(EventObject ev) tracks the number of image's downloaded. For every image loaded, increment the controller's nImagesLoaded property. The following line demonstrates tracking the number of images downloaded.

controller.nImagesLoaded++;

When every image has loaded, then finalize the program and show the first frame of the animation. GLEntity calls the controller's method setProgramVariables(), when all images have downloaded.

if (controller.nImagesToLoad <= controller.nImagesLoaded){

controller.setProgramVariables(controller);

}

Listing 78: Call setProgramVariables(controller)

The method setProgramVariables(controller) part of the GLControl class, finalizes values for the WebGLProgram and draws one frame of the scene. The last statement in setProgramVariables(controller) calls animOne(ev). Method animOne(ev) displays one frame of the animation.

setProgramVariables(controller) calls three WebGL methods. First verify the program functionality with a call to validateProgram(WebGLProgram). If the WebGLProgram doesn't validate, then call WebGL methodsgetProgramParameter(WebGLProgram, Number), getProgramInfoLog(WebGLProgram), and deleteProgram(WebGLProgram). For invalid programs terminate processing. Otherwise the controller renders a frame to the canvas.

Validate the Program or Read Error Messages

Often we learn the most when something goes wrong. Here we demonstrate the short sequence to retrieve error messages regarding the shaders and program. First call the WebGL API method validateProgram(WebGLProgram).Second call the WebGL API method getProgramParameter(WebGLProgram, Number). Third call the WebGL API method getProgramInfoLog(WebGLProgram), to obtain information about the program in text format. Fourth call the WebGL API method deleteProgram(WebGLProgram) to free program related resources.

WebGL API validateProgram(WebGLProgram)

The WebGL API method validateProgram(WebGLProgram) verifies accuracy of the program with linked shaders. We call validateProgram(WebGLProgram) after images load. Some browsers only properly validate programs after textures have uploaded to the GPU. The only parameter to validateProgram(WebGLProgram) is a compiled and linked program object. The following listing demonstrates calling validateProgram(WebGLProgram). The programparameter is a reference to the controller's WebGLProgram.

gl.validateProgram

(

program

);

Listing 79: WebGL API validateProgram(WebGLProgram)

WebGL API getProgramParameter(WebGLProgram, Number)

Call the WebGL API method getProgramParameter(WebGLProgram, Number) with two parameters. The first parameter to getProgramParameter(WebGLProgram, Number) is our program object. The second parameter is a WebGL constant VALIDATE_STATUS. Method getProgramParameter(WebGLProgram, Number) returns true if the program validates and false if a problem exists. The following listing demonstrates how to test the validity of the program with getProgramParameter(WebGLProgram, Number).

if (!gl.getProgramParameter

(

program,

gl.VALIDATE_STATUS

))

{

// The program failed.

}

Listing 80: WebGL API getProgramParameter(WebGLProgram,Number)

WebGL API getProgramInfoLog(WebGLProgram)

The WebGL API method getProgramInfoLog(WebGLProgram) returns program information in String format. If the program failed validation, obtain information regarding the failure. The following listing demonstrates saving the error message in a String for later display.

var validateError = gl.getProgramInfoLog

(

program

);

WebGL API getProgramInfoLog(WebGLProgram)

To view the error message call the GLControl method named viewError(String,GLControl). Method viewError(String,GLControl) displays the error to the eDebug HTML element on the Web page. The template Web page includes a div element with id eDebug.

Sometimes the log messages seem cryptic. They might point to invalid or missing names for variables in the shaders. They might suggest invalid types. They might include errors defined with numbers. If the solution isn't obvious, a search online often provides answers. Don't forget to look at OpenGL ES topics on the Web. WebGL shaders use OpenGL ES constructs.

WebGL API deleteProgram(WebGLProgram)

The WebGL API method deleteProgram(WebGLProgram) detaches any attached shaders and assigns the program for deletion.

Successful Program

If the program validation was successful then call any final initialization sequence required for the specific project. If an example project requires unique settings before rendering, then the project implements a method named init(controller). The parameter to init(controller) is a reference to GLControl. The Display Repeating Graphic project implements an init(controller) method. Other books in the series implement special features to initialize before rendering. We demonstrate the call to init(controller) in the first book, as a foundation for future projects. The following listing calls init(controller) if it's defined. The glDemo variable generically references any project in the series.

if (glDemo.init != null){

glDemo.init(controller);

}

Listing 81: Unique Initialization For a Project

Everything's ready to render the scene. See the source code for method setProgramVariables().