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

WebGL API createProgram()

Method createProgram() requires no parameters and returns an empty WebGLProgram object. Method getProgram() creates a program reference with a call to the WebGL API method createProgram(). The following listing demonstrates creating an empty WebGLProgram.

var p = gl.createProgram();

Listing 30: WebGL API createProgram()

WebGL API attachShader(WebGLProgram, WebGLShader)

Method attachShader() requires two parameters. The first parameter is a WebGLProgram. The second parameter is a WebGLShader.

The following listing demonstrates attaching the fragment shader, within getProgram(). The parameter p is a WebGLProgram.

gl.attachShader

(

p,

shaderF

);

Listing 31: Attach Fragment Shader

The following listing demonstrates attaching the vertex shader, within getProgram(). The parameter p is a WebGLProgram.

gl.attachShader

(

p,

shaderV

);

Listing 32: Attach Vertex Shader

WebGL API linkProgram(WebGLProgram)

WebGL API method linkProgram() returns nothing. The only parameter to linkProgram() is a WebGLProgram with two shaders attached. linkProgram() links the two shaders to the WebGLProgram. The following listing demonstrates linking the program.

gl.linkProgram

(

p

);

Listing 33: WebGL API linkProgram(WebGLProgram)

WebGL API useProgram(WebGLProgram)

WebGL API method useProgram() assigns the WebGLProgram for use. Future drawing operations access shaders linked to the assigned program. The following listing demonstrates calling useProgram(WebGLProgram) within method getProgram().

gl.useProgram

(

p

);

Listing 34: WebGL API useProgram(WebGLProgram)

Finally getProgram() returns the WebGLProgram or null. If the value returned from getProgram() is null, then the GLControl constructor displays an error message and exits. Otherwise the GLControl constructor retains a reference to the WebGLProgram in the property named program.

See the source code for method getProgram().

Compile Shaders

The method getShader(String, nType) called by getProgram(), returns either a WebGLShader or null. Method getShader(String, nType) first parameter is a String with the id of a script tag from the current Web page. The second parameter is one of two WebGL constants representing the type of shader to compile. The WebGL constants are either VERTEX_SHADER or FRAGMENT_SHADER.

Class GLControl was designed for our series of WebGL books. Some of the other books in the series declare unique shaders in separate Web pages. However WebGL Textures & Vertices: Beginner's Guide only uses the book's default shaders. Therefore eShader = document.getElementById(sID); always returns null for this book's example projects.

If the nType parameter is FRAGMENT_SHADER then the local variable sCode receives a prepared String of fragment shader code. If the nType parameter is VERTEX_SHADER then the local variable sCode receives a prepared String of vertex shader code. The section titled Shader Details discusses each line of the default shaders.

Once we have the shader code, we're ready to create and compile a shader.

WebGL API createShader(type)

The WebGL API method createShader(type) returns an empty WebGLShader object. Pass one of two WebGL constants to createShader(type). For vertex shaders the parameter should equal VERTEX_SHADER. For fragment shaders the parameter should equal FRAGMENT_SHADER.

The controller's method getShader(sID, nType) passes the shader's type through the parameter nType. Therefore nType equals either VERTEX_SHADER or FRAGMENT_SHADER. Method getShader(String, nType) calls the WebGL methodcreateShader(type) as follows.

shader = gl.createShader

(

nType

);

Listing 35: WebGL API createShader(type)

Shader Source Code

This book uses default shaders declared within GLControl.js. For vertex shaders, method getShader() assigns the following String to the local variable sCode.

sCode = "attribute vec4 a_position;"

+"attribute vec2 a_tex_coord0;"

+"varying vec2 v_tex_coord0;"

+"uniform mat4 um4_matrix;"

+"uniform mat4 um4_pmatrix;"

+"void main(void) {"

+ "gl_Position = um4_pmatrix * um4_matrix * a_position;"

+ "v_tex_coord0 = a_tex_coord0;"

+"}";

Listing 36: Assign the Default Vertex Shader

For fragment shaders, method getShader() assigns the following String to the local variable sCode.

sCode = "precision mediump float;"

+"uniform sampler2D u_sampler0;"

+"varying vec2 v_tex_coord0;"

+" void main(void) {"

+"gl_FragColor = texture2D(u_sampler0, v_tex_coord0);"

+"}";

Listing 37: Assign the Default Fragment Shader

WebGL API shaderSource(WebGLShader, String)

Call the WebGL API method shaderSource(WebGLShader,String) to assign a String of shader source code to an empty WebGLShader. The first parameter to shaderSource(WebGLShader, String) is our empty WebGLShader object named shader. The second parameter to shaderSource(WebGLShader, String) is our String of shader source code named sCode. The following listing demonstrates assigning shader source code to a WebGLShader.

gl.shaderSource

(

shader,

sCode

);

Listing 38: WebGL API shaderSource(WebGLShader,String)

WebGL API compileShader(WebGLShader)

Method getShader() compiles the shader with the WebGL API method compileShader(WebGLShader). The only parameter is our WebGLShader reference.

gl.compileShader

(

shader

);

Listing 39: WebGL API compileShader(WebGLShader)

WebGL API getShaderParameter(WebGLShader, COMPILE_STATUS)

It's often helpful to determine if the shader compiled correctly. If not, display some information to help understand what failed. The WebGL API method getShaderParameter(WebGLShader, COMPILE_STATUS) returns false if the shader compilation failed. If getShaderParameter(WebGLShader, COMPILE_STATUS) returns true, everything compiled fine so far.

The first parameter to getShaderParameter(WebGLShader, COMPILE_STATUS) is our shader reference. To obtain information regarding the compile, pass the WebGL constant COMPILE_STATUS as the second parameter. The following listing tests the shader compile status with an if block. If the compile failed, display reasons for the failure next.

if (!gl.getShaderParameter

(

shader,

gl.COMPILE_STATUS

))

{ ... }

Listing 40: WebGL API getShaderParameter(WebGLShader, COMPILE_STATUS)

WebGL API getShaderInfoLog(WebGLShader)

The WebGL API method getShaderInfoLog(WebGLShader) returns a String, with information regarding the specified shader. The following listing demonstrates calling getShaderInfoLog(WebGLShader), where shader is a WebGLShader. Read the String for more information regarding errors. Errors result from invalid vertex or fragment shader source code.

var sError = gl.getShaderInfoLog

(

shader

);

Listing 41: WebGL API getShaderInfoLog(WebGLShader)

If the shader compiled correctly, then getShader(String,nType) returns a valid WebGLShader. Otherwise getShader(String,nType) returns null. See the source code for method getShader().