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.

WebGL and three.js for This Course: the Server, the Scene Graph, and the Course Library

The Khronos Group released the WebGL 1.0 specification in March 2011, bringing GPU rendering to the browser without plug-ins. Khronos Group, WebGL 1.0 specification, 2011

Each homework (HW1 to HW6) can be done in either of two tracks, Unity or WebGL, and HW7 and HW8 in JavaScript or Python. The Unity chapter serves the first track; this chapter serves the second. The WebGL track runs in a browser on the course’s own JavaScript library, the same code behind every demo in this text, drawn with three.js, a widely used library over the browser’s WebGL interface. There is nothing to install beyond a browser and Python. The price is that a browser is a stricter host than an editor: a page must be served, modules must be imported by exact relative paths, and errors appear in a console rather than a window. The chapter covers that ground first, then the four things a graphics course needs from three.js (the transform hierarchy, the frame loop, the matrix type and its storage, and the difference between its conventions and the text’s), then the course library and the homework runner. It is not a three.js tutorial: lights, shadows, post-processing and loaders are left out.

1 · Serving the course: one folder, one server

Clone or download the homework starter repository, the folder that holds index.html, lib/ and homework/ (git names it UWB-CSS-551-AU26-homework; this chapter calls it css551/), and, in a terminal, start a static web server in it:

cd css551
python3 -m http.server 8000

Then open http://localhost:8000/ for the list of released homework, or http://localhost:8000/homework/run.html?hw=hw01 for the first homework. The server does nothing but hand files to the browser; stop it with Ctrl-C. Any port works, but every page of the course uses relative paths, so the server must be started in css551/ itself, not in a subfolder, or the pages will not find the library.

Access to script at 'file:///…/css551/lib/skeletons/runner.js' from origin 'null' has been
blocked by CORS policy: Cross origin requests are only supported for protocol schemes: chrome,
chrome-untrusted, data, http, https.

2 · ES modules and import paths

Every file of the course library is an ES module: it says what it shares with export and what it needs with import. A page starts the chain with <script type="module">.

// lib/skeletons/hw01.js, the file you edit in HW1
import { dot, cross, normalize, sub } from '../core/xform.js';

export function advance(p, velocity, dt) { /* yours */ }

The browser caches modules aggressively. After editing a file, reload with the cache bypassed (Shift-reload, or Cmd-Shift-R on a Mac, Ctrl-Shift-R elsewhere), or keep the developer tools open with “Disable cache” checked in the Network tab. The homework runner adds a fresh query string to your file’s URL on every load, so your own file is never stale; the library files can be.

3 · The browser’s developer tools

Open them with F12, or Cmd-Option-I on a Mac. Three panels do almost all the work.

• Console shows console.log output, warnings and every uncaught error with its file and line (click the link to jump there). It is also a live JavaScript prompt in the page’s context: after the homework runner loads, window.__hwResults holds the check rows.
• Sources (Chrome) or Debugger (Firefox) shows the loaded files. Click a line number to set a breakpoint; reload or trigger the code, and execution stops there with every local variable inspectable. A debugger; statement in your file does the same from code.
• Network shows every request. A red 404 for xform.js is a wrong import path; a module that never appears was never imported.

for (let r = 0; r < 4; r++) console.log([0, 1, 2, 3].map((c) => m.elements[4 * c + r].toFixed(3)));

4 · three.js’s object model, against Unity’s

The largest difference from Unity is that nothing runs by itself. There is no editor, no Play button and no script lifecycle: your code creates the scene, adds objects, and calls render when the picture should change. The course’s demos are built that way, and so is every homework view.

5 · The render loop and the clock

An animation in a browser is a function that asks to be called before the next screen refresh, does one frame’s work, and asks again. requestAnimationFrame(f) calls f once, with a timestamp in milliseconds; the loop is the function scheduling itself. It is the rasterization chapter’s loop, written by hand:

let last = 0;
function frame(t) {                       // t: milliseconds since the page loaded
  const dt = last ? (t - last) / 1000 : 0;  // the frame's length in seconds
  last = t;
  cube.position.x += 3 * dt;              // 3 units per second, at any frame rate
  renderer.render(scene, camera);
  requestAnimationFrame(frame);           // ask for the next frame
}
requestAnimationFrame(frame);

There is no FixedUpdate. A simulation that needs a constant step, such as the cloth and fluid of the animation chapter, runs the accumulator of the interactive-systems chapter inside frame: add dt to a bank and take fixed steps while the bank holds one. Two browser behaviors matter. A hidden tab gets no animation frames at all, so the first dt after returning can be seconds long and should be clamped. And a page that calls requestAnimationFrame forever keeps the graphics card busy even when nothing changes; the course’s demos render on demand instead, running the loop only while a key is held and drawing once per slider change.

6 · Object3D: local, world, parent

node -e "import('./lib/vendor/three.module.js').then(T=>{const p=new T.Object3D();p.position.set(2,0,0);p.rotation.y=Math.PI/2;const c=new T.Object3D();c.position.set(1,0,0);p.add(c);const g=new T.Object3D();g.position.set(0,1,0);c.add(g);p.updateMatrixWorld(true);console.log(g.getWorldPosition(new T.Vector3()).toArray().map(v=>+v.toFixed(3)))})"
[ 2, 1, -1 ]

7 · Conventions, against the text’s

three.js agrees with the text on more than Unity does: right-handed, \(y\) up, \(+z\) toward the viewer, column vectors, and matrices stored column by column. A picture drawn from the text matches the screen without mirroring. Three conventions still need naming.

node -e "Promise.all([import('./lib/vendor/three.module.js'),import('./lib/core/xform.js')]).then(([T,X])=>{const m=X.makeTRS(2,0.5,-1,0,30,0,2,2,2);const good=new T.Matrix4().fromArray(m),bad=new T.Matrix4().set(...m);const p=()=>new T.Vector3(1,0,0);console.log(p().applyMatrix4(good).toArray().map(v=>+v.toFixed(3)));console.log(p().applyMatrix4(bad).toArray().map(v=>+v.toFixed(3)))})"
[ 3.732, 0.5, -2 ]
[ 0.577, 0, 0.333 ]

8 · Geometry, materials, textures, cameras

Geometry. A BufferGeometry holds named attributes, each a typed array cut into fixed-size items: position (3 numbers per vertex), normal (3), uv (2), and an optional index (3 per triangle, counter-clockwise seen from the front). It is the vertex and index arrays of the meshes chapter, laid out for the graphics card:

const g = new THREE.BufferGeometry();
g.setAttribute('position', new THREE.BufferAttribute(new Float32Array(positions), 3));
g.setAttribute('normal',   new THREE.BufferAttribute(new Float32Array(normals), 3));
g.setIndex(indices);       // a plain array of integers works
// after editing an attribute's array in place:
g.attributes.position.needsUpdate = true;

The array is uploaded to the graphics card once; editing it in place changes nothing on screen until needsUpdate is set. computeVertexNormals() computes the averaged normals the meshes chapter derives by hand, and the homework asks you to compute them yourself (Section 11).

Material. MeshBasicMaterial draws a flat colour, MeshStandardMaterial lights with three.js’s physically based model, and ShaderMaterial runs shaders you write, which is how the homework’s lit sphere works; the shader chapter covers it. A material’s side chooses which faces are drawn (FrontSide, the default, or DoubleSide for a quad seen from both sides).

Texture and colour. A Texture wraps an image or a canvas; set texture.colorSpace = THREE.SRGBColorSpace for a photograph or painted image so its colours are converted to linear light before shading, and texture.needsUpdate = true after drawing into its canvas. three.js manages colour for you: new THREE.Color(0x808080) stores the linear value 0.2159, not 0.5, and the renderer converts back to sRGB on output (its outputColorSpace is sRGB by default). The colour chapter explains why shading must happen in linear light.

Camera. new THREE.PerspectiveCamera(fovYDeg, aspect, near, far) holds the parameters of the viewing chapter; position it like any Object3D and aim it with camera.lookAt(x, y, z), which turns its \(-z\) toward the point. When the canvas changes size, set camera.aspect, call updateProjectionMatrix(), and resize the renderer with renderer.setSize(w, h).

9 · The course library

The homework does not start from an empty page. It runs inside the course’s demo library, the code in lib/ behind every demo in this text. Four parts matter for the WebGL track.

10 · How a homework runs and reports

Each homework has one file to edit, lib/skeletons/hwNN.js, whose functions are stubs marked // TODO, and one page that runs it, homework/run.html?hw=hwNN. The page imports your file, runs the homework’s checks on your functions with the published inputs, prints a table under the scene, and draws the scene from your functions, so a wrong function shows twice: as a failed row and as a wrong picture.

1. Start the server in css551/ and open http://localhost:8000/homework/run.html?hw=hw01.
2. Read the checks table: each row is one check, with its points, yours (what your function returned) and expected. An untouched skeleton returns placeholders and scores 0.
3. Implement one function, save, reload (Section 2: your file is never cached), and watch its rows turn green.
4. A row that says threw means your function raised an error; the message is in the row and the line number is in the console.

The table reports the published inputs only. Grading runs the same checks on a second, hidden set of inputs, so a function that returns the expected numbers without computing them scores on the first and not on the second. The homework pages list every check and its tolerance.

11 · The course rule: implement and replace

The helpers each homework forbids, in both tracks, are listed in one table, in the Unity chapter’s Section 11, whose third column is the three.js list; this chapter does not repeat it, so there is one authority. For the WebGL track the allowed primitives are the library’s sub, dot, cross, normalize (and, where a homework says so, matMul and applyMat4), component access, arithmetic and Math. The head of each skeleton file names its own allowed and off-limits list, and each homework page is the authority for that homework.

12 · Exercises