WebGL Textures & Vertices

Beginner's Guide

Page Seventy Nine

Validate the Program

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 program parameter 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 sample 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.

WebGL Beginner's Guide Introduction WebGL Beginner's Guide
Copyright © 2015 Seven Thunder Software. All Rights Reserved.