This is a continuation from WebGL Fundamentals. WebGL sometimes appears complicated to learn because most lessons go over everything all at once. I'll try to avoid that where possible and break it down into smaller pieces.
One of things that makes WebGL seem complicated is that you have these 2 tiny functions, a vertex shader and a fragment shader. Those two functions run on your GPU which is where all the speed comes from. That's also why they are written in a custom language, a language that matches what a GPU can do. Those 2 functions need to be compiled and linked. That process is, 99% of the time, the same in every WebGL program.
Here's the boilerplate code for compiling a shader.
/**
* Creates and compiles a shader.
*
* @param {!WebGLRenderingContext} gl The WebGL Context.
* @param {string} shaderSource The GLSL source code for the shader.
* @param {number} shaderType The type of shader, VERTEX_SHADER or
* FRAGMENT_SHADER.
* @return {!WebGLShader} The shader.
*/
function compileShader(gl, shaderSource, shaderType) {
// Create the shader object
var shader = gl.createShader(shaderType);
// Set the shader source code.
gl.shaderSource(shader, shaderSource);
// Compile the shader
gl.compileShader(shader);
// Check if it compiled
var success = gl.getShaderParameter(shader, gl.COMPILE_STATUS);
if (!success) {
// Something went wrong during compilation; get the error
throw ("could not compile shader:" + gl.getShaderInfoLog(shader));
}
return shader;
}
And the boilerplate code for linking 2 shaders into a program
/**
* Creates a program from 2 shaders.
*
* @param {!WebGLRenderingContext) gl The WebGL context.
* @param {!WebGLShader} vertexShader A vertex shader.
* @param {!WebGLShader} fragmentShader A fragment shader.
* @return {!WebGLProgram} A program.
*/
function createProgram(gl, vertexShader, fragmentShader) {
// create a program.
var program = gl.createProgram();
// attach the shaders.
gl.attachShader(program, vertexShader);
gl.attachShader(program, fragmentShader);
// link the program.
gl.linkProgram(program);
// Check if it linked.
var success = gl.getProgramParameter(program, gl.LINK_STATUS);
if (!success) {
// something went wrong with the link; get the error
throw ("program failed to link:" + gl.getProgramInfoLog(program));
}
return program;
};
Of course how you decide to handle errors might be different. Throwing exceptions might not be the best way to handle things. Still, those few lines of code are pretty much the same in nearly every WebGL program.
Now that multiline template literals are supported in all modern browsers it's my preferred way of storing shaders. I can just do something like
var vertexShaderSource = `#version 300 es
in vec4 a_position;
uniform mat4 u_matrix;
void main() {
gl_Position = u_matrix * a_position;
}
`;
And have an easy to edit shader. Some older browsers like IE won't like this but first of I'm using WebGL so I don't really care about IE. If I did care and had a non WebGL fallback I'd use some build step with something like Babel to convert the code above into something that IE understands.
In the past I liked to store my shaders in non javascript <script> tags. It also makes them easy to edit so I'd use code like this.
/**
* Creates a shader from the content of a script tag.
*
* @param {!WebGLRenderingContext} gl The WebGL Context.
* @param {string} scriptId The id of the script tag.
* @param {string} opt_shaderType. The type of shader to create.
* If not passed in will use the type attribute from the
* script tag.
* @return {!WebGLShader} A shader.
*/
function createShaderFromScript(gl, scriptId, opt_shaderType) {
// look up the script tag by id.
var shaderScript = document.getElementById(scriptId);
if (!shaderScript) {
throw("*** Error: unknown script element" + scriptId);
}
// extract the contents of the script tag.
var shaderSource = shaderScript.text;
// If we didn't pass in a type, use the 'type' from
// the script tag.
if (!opt_shaderType) {
if (shaderScript.type == "x-shader/x-vertex") {
opt_shaderType = gl.VERTEX_SHADER;
} else if (shaderScript.type == "x-shader/x-fragment") {
opt_shaderType = gl.FRAGMENT_SHADER;
} else if (!opt_shaderType) {
throw("*** Error: shader type not set");
}
}
return compileShader(gl, shaderSource, opt_shaderType);
};
Now to compile a shader I can just do
var shader = compileShaderFromScript(gl, "someScriptTagId");
I'll usually go one step further and make a function to compile two shaders from script tags, attach them to a program and link them.
/**
* Creates a program from 2 script tags.
*
* @param {!WebGLRenderingContext} gl The WebGL Context.
* @param {string} vertexShaderId The id of the vertex shader script tag.
* @param {string} fragmentShaderId The id of the fragment shader script tag.
* @return {!WebGLProgram} A program
*/
function createProgramFromScripts(
gl, vertexShaderId, fragmentShaderId) {
var vertexShader = createShaderFromScriptTag(gl, vertexShaderId, gl.VERTEX_SHADER);
var fragmentShader = createShaderFromScriptTag(gl, fragmentShaderId, gl.FRAGMENT_SHADER);
return createProgram(gl, vertexShader, fragmentShader);
}
The other piece of code I use in almost every WebGL program is something to resize the canvas. You can see how that function is implemented here.
In the case of all the samples these 2 functions are included with
<script src="resources/webgl-utils.js"></script>
and used like this
var program = webglUtils.createProgramFromScripts(
gl, [idOfVertexShaderScript, idOfFragmentShaderScript]);
...
webglUtils.resizeCanvasToMatchDisplaySize(canvas);
It seems best not to clutter all the samples with many lines of the same code as they just get in the way of what that specific example is about.
The actual boilerplate API used in most of these samples is
/**
* Creates a program from 2 sources.
*
* @param {WebGLRenderingContext} gl The WebGLRenderingContext
* to use.
* @param {string[]} shaderSources Array of sources for the
* shaders. The first is assumed to be the vertex shader,
* the second the fragment shader.
* @param {string[]} [opt_attribs] An array of attribs names.
* Locations will be assigned by index if not passed in
* @param {number[]} [opt_locations] The locations for the attribs.
* A parallel array to opt_attribs letting you assign locations.
* @param {module:webgl-utils.ErrorCallback} opt_errorCallback callback for errors.
* By default it just prints an error to the console
* on error. If you want something else pass an callback.
* It's passed an error message.
* @return {WebGLProgram} The created program.
* @memberOf module:webgl-utils
*/
function createProgramFromSources(gl,
shaderSources,
opt_attribs,
opt_locations,
opt_errorCallback)
where shaderSources is an array of strings containing the GLSL source code.
The first string in the array is the vertex shader source. The second is
the fragment shader source.
That's most of my minimum set of WebGL boilerplate code.
You can find webgl-utils.js code here.
If you want something slightly more organized check out TWGL.js.
The rest of what makes WebGL look complicated is setting up all the inputs to your shaders. See how it works.
I'd also suggest you read up on less code more fun and check out TWGL.
Note while we're add it there are several more scripts for similar reasons
This provides code to setup sliders that have a visible value that updates when you drag the slider. Again I didn't want to clutter all the files with this code so it's in one place.
This script is not needed except on webgl2fundamentals.org. It helps print error messages to the screen when used inside the live editor among other things.
This is a bunch of 2d math functions. They get created started with the first article about matrix math and as they are created they are inline but eventually they're just too much clutter so after few example they are used by including this script.
This is a bunch of 3d math functions. They get created started with the first article about 3d and as they are created they are inline but eventually they're just too much clutter so after the 2nd article on 3d they are used by including this script.