This chapter links to the course’s interactive demos and uses MathJax for its formulas. Read it through the course website (or download the file and open it in a browser); a Canvas inline preview will reach neither the demos nor the math. All chapters.

Shaders in GLSL (three.js): ShaderMaterial, Uniforms, Varyings, and the Normal Matrix

GLSL, the OpenGL Shading Language, arrived with OpenGL 2.0 in 2004; WebGL shaders are written in its OpenGL ES dialect. Khronos Group, OpenGL 2.0 specification, 2004

A shader is a small program that the graphics card runs once per vertex or once per pixel, in parallel, with no memory of the other vertices or pixels. three.js writes the shaders for its built-in materials; a ShaderMaterial lets you write your own in GLSL, the shading language of OpenGL and WebGL, while three.js still supplies the matrices, the mesh’s attributes and the colour conversion. Everything the illumination and texture chapters compute per pixel is written here, which is why the homework’s lit sphere (HW5) is a shader. This chapter covers the language as far as the course needs it and the contract between three.js and your code; it leaves out three.js’s node-based materials, compute shaders and WebGPU.

1 · Where shaders sit in the pipeline

For each mesh, the graphics card runs the vertex shader once per vertex. It reads that vertex’s attributes and must write gl_Position, the clip-space position of the viewing chapter (\(P\,V\,M\,\mathbf{p}\), before the divide by \(w\)). The fixed-function stages then clip, divide, map to the viewport and rasterize each triangle into pixels, interpolating whatever else the vertex shader wrote, perspective-correctly (the rasterization chapter). The fragment shader runs once per covered pixel, reads the interpolated values and writes a colour; the depth test and blending decide what reaches the framebuffer.

2 · A ShaderMaterial, end to end

A ShaderMaterial is two strings of GLSL and an object of uniforms. The smallest useful one paints a mesh a single colour:

const material = new THREE.ShaderMaterial({
  uniforms: { uTint: { value: new THREE.Color(0.2, 0.6, 1.0) } },
  vertexShader: VERTEX,
  fragmentShader: FRAGMENT,
});
scene.add(new THREE.Mesh(new THREE.SphereGeometry(1, 32, 16), material));

// VERTEX: position is the attribute; the three matrices are declared by three.js
void main() {
  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}

// FRAGMENT: the uniform's name and type match the JavaScript key
uniform vec3 uTint;
void main() {
  gl_FragColor = vec4(uTint, 1.0);
  #include <colorspace_fragment>
}

vec4(position, 1.0) makes the point homogeneous (\(w = 1\)) and the product is the clip position. The uniform is declared in GLSL and given a value in JavaScript; three.js matches them by name each time it draws. The #include line asks three.js to paste in its output colour conversion (Section 7). Nothing else is needed: the attribute position and the matrices are declared by three.js (Section 4).

The strings are usually written in the same JavaScript file as template literals, between backquotes, often tagged with a /* glsl */ comment so an editor highlights them. three.js compiles them the first time the mesh is drawn, and recompiles only when the strings or the material’s defines change; changing a uniform’s value costs nothing.

3 · GLSL for this course

GLSL looks like C with vectors. The parts the course uses fit in one table.

three.js compiles a ShaderMaterial as GLSL ES 3.00 but lets you write in the older GLSL ES 1.00 spelling: it adds #define lines so that attribute, varying, texture2D and gl_FragColor mean their 3.00 equivalents (in, out, texture, an output variable). This chapter uses the older spelling throughout, as three.js’s own shaders do.

4 · What three.js declares for you

Before compiling a ShaderMaterial, three.js prepends a block of declarations to each string. The ones a course shader uses are these:

So a world-space lighting shader has \(M\), \(V\), \(P\) and the eye position for free; what it lacks is a normal matrix for world space, since three.js’s normalMatrix is built from \(VM\). Section 6 supplies one.

The raw form is what a WebGL program without three.js would contain, and nothing is hidden in it:

attribute vec3 position;
uniform mat4 modelViewMatrix;
uniform mat4 projectionMatrix;
void main() {
  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}

precision highp float;
uniform vec3 uTint;
void main() {
  gl_FragColor = vec4(uTint, 1.0);
}

5 · Uniforms from JavaScript

Each entry of uniforms is an object with a value; three.js uploads the value to the GLSL uniform of the same name at every draw. The JavaScript type decides the GLSL type it can fill:

// once per frame, or whenever the value changes; no needsUpdate, no recompile
material.uniforms.uLightWorld.value.copy(lamp.position);
material.uniforms.uTime.value = t / 1000;

6 · Lighting in the shader, and the normal

Per-pixel lighting needs, at each pixel, the surface point, the surface normal and the light’s position in one space. World space is the natural choice: the light’s position comes from the scene, and cameraPosition is the eye. The vertex shader carries the world position and the world normal as varyings; the fragment shader builds \(\mathbf{L}\), clamps \(\mathbf{N}\cdot\mathbf{L}\) and multiplies. It is the illumination chapter’s diffuse term:

uniform mat3 uNormalWorld;      // inverse transpose of mat3(modelMatrix), set from JavaScript
varying vec3 vWorldPos;
varying vec3 vWorldNormal;
void main() {
  vec4 world   = modelMatrix * vec4(position, 1.0);   // the point, in world space
  vWorldPos    = world.xyz;
  vWorldNormal = uNormalWorld * normal;               // the normal, in world space
  gl_Position  = projectionMatrix * viewMatrix * world;
}

uniform vec3 uLightWorld;       // the light's position, world space
uniform vec3 uAlbedo;           // diffuse reflectance, linear
varying vec3 vWorldPos;
varying vec3 vWorldNormal;
void main() {
  vec3 n = normalize(vWorldNormal);                // interpolation shortens it
  vec3 l = normalize(uLightWorld - vWorldPos);     // direction to the light, per pixel
  vec3 c = uAlbedo * max(dot(n, l), 0.0);          // max(0, N·L)
  gl_FragColor = vec4(c, 1.0);
  #include <colorspace_fragment>
}

// JavaScript: the world normal matrix, refreshed before each draw
uniforms.uNormalWorld = { value: new THREE.Matrix3() };
mesh.onBeforeRender = () => material.uniforms.uNormalWorld.value.getNormalMatrix(mesh.matrixWorld);

getNormalMatrix(m) computes \(\big((M_{3\times3})^{-1}\big)^{\top}\) on the CPU, once per draw. The alternative, transpose(inverse(mat3(modelMatrix))) * normal in the vertex shader, gives the same vector and inverts the same matrix once per vertex. The normal is renormalized in the fragment shader because interpolating two unit vectors gives a shorter one in between.

The specular term of the illumination chapter is a few more lines in the fragment shader: the direction to the eye from cameraPosition and the world position, the mirror direction with reflect, and the clamped cosine raised to the shininess with pow. An ambient term is a constant added before the output. Every one of them is computed per pixel from interpolated vectors, which is Phong shading in the sense of the meshes chapter; computing the colour in the vertex shader and interpolating it would be Gouraud shading.

7 · Linear light and the output colour space

Lighting adds and multiplies light, so it must run on linear values (the colour chapter); screens expect sRGB-encoded values (the transfer function). three.js keeps the two apart for you on the way in and asks you to opt in on the way out:

• In. A THREE.Color stores linear components (new THREE.Color(0x808080) holds 0.2159), and a texture marked colorSpace = THREE.SRGBColorSpace is decoded to linear by the graphics card when it is sampled. A plain Vector3 uniform is passed as it is.
• Out. #include <colorspace_fragment>, as the last line of main, expands to gl_FragColor = linearToOutputTexel( gl_FragColor );, which encodes to the renderer’s outputColorSpace (sRGB by default). Without the line, the shader’s number is written to the screen as the code value.

Either convention is consistent if its inputs are chosen for it: linear inputs with the output conversion, or values meant as screen codes with none. The error is the mix, linear inputs without the conversion, which makes every mid-tone too dark, or screen codes with the conversion, which makes them too light.

<!doctype html>
<script type="module">
import * as THREE from './lib/vendor/three.module.js';
const renderer = new THREE.WebGLRenderer();
renderer.setSize(64, 64);
document.body.appendChild(renderer.domElement);
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 10);
camera.position.z = 3;
const mat = new THREE.ShaderMaterial({
  uniforms: {
    uLightWorld: { value: new THREE.Vector3(0, 1.732, 1) },
    uAlbedo: { value: new THREE.Vector3(1, 1, 1) },
  },
  vertexShader: `
    varying vec3 vWorldPos;
    void main() {
      vec4 world = modelMatrix * vec4(position, 1.0);
      vWorldPos = world.xyz;
      gl_Position = projectionMatrix * viewMatrix * world;
    }`,
  fragmentShader: `
    uniform vec3 uLightWorld;
    uniform vec3 uAlbedo;
    varying vec3 vWorldPos;
    void main() {
      vec3 n = vec3(0.0, 0.0, 1.0);
      vec3 l = normalize(uLightWorld - vWorldPos);
      gl_FragColor = vec4(uAlbedo * max(dot(n, l), 0.0), 1.0);
      #include <colorspace_fragment>
    }`,
});
scene.add(new THREE.Mesh(new THREE.PlaneGeometry(2, 2), mat));
renderer.render(scene, camera);
const gl = renderer.getContext();
const px = new Uint8Array(4);
gl.readPixels(32, 32, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, px);
console.log('centre pixel', px.join(', '));
</script>

8 · Textures and samplers

A texture reaches a shader as a sampler2D uniform, and texture2D(sampler, uv) returns the filtered colour at a texture coordinate, \((0, 0)\) at the bottom-left of the image and \((1, 1)\) at the top-right. The geometry’s uv attribute is passed through as a varying:

varying vec2 vUv;
void main() {
  vUv = uv;
  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}

uniform sampler2D uMap;
uniform mat3 uPlace;            // a 2D placement: scale, rotate, offset, as in the texture chapter
varying vec2 vUv;
void main() {
  vec2 st = (uPlace * vec3(vUv, 1.0)).xy;         // homogeneous 2D: the third component is 1
  gl_FragColor = texture2D(uMap, st);
  #include <colorspace_fragment>
}

const tex = new THREE.TextureLoader().load('checker.png');
tex.colorSpace = THREE.SRGBColorSpace;            // an image of colours: decode to linear when sampled
tex.wrapS = tex.wrapT = THREE.RepeatWrapping;     // the default is ClampToEdgeWrapping
material.uniforms.uMap = { value: tex };

The placement matrix is the texture chapter’s \(3\times3\) homogeneous transform of the plane, applied to the coordinate before the lookup; the library’s uvMat3 builds one, and Matrix3.fromArray carries it to the uniform. The sampling options are properties of the texture, not of the shader: wrapS and wrapT (ClampToEdgeWrapping by default, RepeatWrapping, MirroredRepeatWrapping), magFilter (LinearFilter by default, or NearestFilter) and minFilter (LinearMipmapLinearFilter by default, trilinear filtering over the mipmaps of the minification section). anisotropy is 1 by default; raise it for a floor seen at a grazing angle. Data textures (normal maps, heights) keep the default colour space, since their numbers are not colours.

9 · Render state: culling, depth, blending

What happens to a fragment after the shader is set on the material, not in GLSL. The defaults of a ShaderMaterial draw opaque front faces with the depth test and depth writes on.

A fragment shader can also refuse a pixel with discard;, which writes neither colour nor depth: a cut-out leaf from an alpha texture, or a clipping plane. Sorting is per object, not per triangle, so two interpenetrating transparent meshes, or one concave transparent mesh, can still blend in the wrong order.

10 · Debugging a shader

A shader cannot print. Two techniques replace console.log: read the compiler’s message when it fails, and paint the value you doubt as a colour when it runs.

uniform vec3 uTint;
void main() {
  vec3 c = uTint * 0.5;
  gl_FragColor = c;
}

THREE.WebGLProgram: Shader Error 0 - VALIDATE_STATUS false

Material Name:
Material Type: ShaderMaterial

Program Info Log: Fragment shader is not compiled.

FRAGMENT

ERROR: 0:60: '=' : dimension mismatch
ERROR: 0:60: 'assign' : cannot convert from 'highp 3-component vector of float' to 'out highp 4-component vector of float'

  55: }
  56:
  57: uniform vec3 uTint;
  58: void main() {
  59:   vec3 c = uTint * 0.5;
> 60:   gl_FragColor = c;
  61: }

When the shader compiles but the picture is wrong, replace the output with the quantity in doubt, mapped into \([0, 1]\):

varying vec3 vWorldPos;
varying vec3 vWorldNormal;
void main() {
  vec3 n = normalize(vWorldNormal);
  gl_FragColor = vec4(0.5 * n + 0.5, 1.0);        // a unit vector, components -1..1, as a colour
}

• Normals as colour. On a sphere in world space, the side facing \(+x\) is pink-red \((1, 0.5, 0.5)\), the top light green, the side facing the viewer at \(+z\) lavender. A face that shows the wrong hue has the wrong normal; a hue that changes as the camera orbits is a normal in view space.
• A scalar as grey. gl_FragColor = vec4(vec3(max(dot(n, l), 0.0)), 1.0); shows \(\mathbf{N}\cdot\mathbf{L}\) alone. Black where you expect light is a light in the wrong place or a normal pointing in.
• A position as colour. fract(vWorldPos) draws a grid that should stay fixed to the world as the camera moves.
• A solid colour. gl_FragColor = vec4(1.0, 0.0, 1.0, 1.0);: if the mesh is not magenta, the problem is upstream of the fragment shader (the mesh is not in the scene, is culled, or is outside the frustum).

11 · Exercises