Command Palette

Search for a command to run...

Hectal

Phase 14 · part: Rear light

Under the Hood: Raw WebGL 2 and WebGPU

A triangle in raw WebGL 2 and raw WebGPU, every line explained: state, buffers, bind groups, real errors, what three.js does each frame. The rear light glows.

three.js hides a lot, and that is its job. This phase takes the cover off. You draw the same orange triangle twice, once with WebGL 2's own calls and once with WebGPU's, and read the real messages each API gives when something is wrong.

Then the ideas that matter in practice: WebGL is a switchboard of global state, and a forgotten switch leaks into the next draw; WebGPU fixes everything in advance in pipelines and bind groups, and checks your work. You count the WebGL calls three.js makes for one frame, and see what breaks when your code and three.js share a context.

The build draws the rear light's glow with your own GPU code on a canvas over the showroom: WebGPU where the browser has it, WebGL 2 everywhere else. The rear light is this phase's part.

Phase 14 · the brief from Lumen

Kofi, frontend engineer who owns the showroom's code

“A bug report shows a black square on some laptops, and the stack trace ends deep inside three.js, in code Kofi has never read.”

On Monday a support ticket arrives with a screenshot: a black square where the bike should be, and a console full of INVALID_OPERATION. The trace ends in WebGLRenderer, in calls Kofi has never written himself.

Ama has a wish at the same time: the rear light should glow and pulse like a real one, without slowing the page. And Tomás asks whether the showroom should move to WebGPU now, or wait.

All three questions have one answer: learn what three.js does underneath. By the end of this phase Kofi reads those calls, draws with both APIs himself, and gives the rear light its glow.

At this station

You will learn

  • Draw a triangle with raw WebGL 2 and raw WebGPU, and read their errors
  • Explain WebGL's global state and VAOs, and WebGPU's pipelines and bind groups
  • Lay out a uniform buffer by WGSL's alignment rules
  • Know what three.js sends each frame, and when to drop to the raw API

You write code in

In your lumen-3d project (npm run dev) and in the editor on this page; WebGPU examples need a browser with WebGPU (Chrome, Edge, Safari 26, Firefox 141+ on Windows)

Files you touch

  • src/world/glow-webgl2.js
  • src/world/glow-webgpu.js
  • src/systems/rear-glow.js
  • src/objects/bike.js
  • src/ui/panel.js
  • src/main.js
  • index.html
Start with 14.1

Work order · 6 steps

  1. 14.1A Triangle in Raw WebGL 2Raw WebGL 2 draws in five steps: get a context, compile two shaders and link them into a program, put vertices in a buffer, describe that buffer to the shader, then draw. Every step can fail, and nothing throws: you must ask. 20 min 2 live scenes
  2. 14.2WebGL Is a State MachineWebGL calls don't take "what to draw with" as arguments. They change global settings (the bound buffer, the current program, attribute pointers), and every later call uses whatever is set. Forget one setting and the next draw silently uses the last one. VAOs bundle the per-object settings. 20 min 2 live scenes
  3. 14.3A Triangle in Raw WebGPUWebGPU draws the same triangle with other ideas: ask for an adapter and a device (both asynchronous), write both shaders in one WGSL module, fix every setting in advance in a pipeline, record commands into an encoder, and submit them at once. Errors are checked and reported in detail. 19 min 2 live scenes
  4. 14.4Buffers, Bind Groups and PipelinesIn WebGPU, the values a shader reads (uniforms) live in buffers you fill yourself, at offsets WGSL's alignment rules decide. A bind group connects buffers to the shader's bindings. A wrong layout makes the shader read wrong bytes silently; a wrong size is stopped by validation. 21 min 2 live scenes
  5. 14.5When to Drop to the Raw APIthree.js turns a scene into WebGL calls: 156 on the first frame of a small scene (compiling, uploading), 10 on later ones, skipping everything that didn't change. Raw GPU code is worth it for small special jobs, custom renderers and compute; when it shares three.js's context, call renderer.resetState(). 20 min 2 live scenes
  6. 14.6Build: The Rear LightbuildThe showroom gets its rear light: a small red lamp on the seat tube, and a pulsing glow drawn by your own GPU code on a transparent canvas over the scene (WebGPU where available, WebGL 2 elsewhere). It follows the lamp, fades from the front, and stops pulsing with the pause button or reduced motion. 82 min 2 live scenes

Quality control · 4 tests

Build it yourself, press Check, and the page tests the scene you made: what is in it, where it sits, what it costs the GPU.

QC-01Fix the fragment shaderThe triangle should be Lumen orange, but nothing is drawn: the console shows the compiler's info log.AdvancedQC-02Bind the second triangleTwo triangles share one program: an orange one on the left, a blue one on the right. Only one blue triangle appears, on the left.AdvancedQC-03Lay out a WGSL uniform structlayout(members) should return each member's byte offset and the struct's size by WGSL's rules for uniform structs: each member starts at the next multiple of its alignment, and the size rounds up to the largest alignment.AdvancedQC-04A glow that respects motionThe overlay (already written) draws the rear light's glow every frame. Write its two rules from Topic 14.6.Advanced