verify-pixels

Prove pixels unchanged

A rendering change that must not alter the image is not proven by eyeballing a screenshot at one pose. Build a deterministic capture, compare byte-exact counts across a pose × phase matrix, and prove the capture harness itself is trustworthy before trusting what it reports about the change.

Make the frame deterministic

• Drive every animated shader or vertex effect from one app-owned time value, never Date.now() or performance.now() read inside the render path, so a captured phase is exactly reproducible.
• Freeze the clock with app.timeScale = 0 before capturing; nothing should advance between frames you did not explicitly step.
• Step frames explicitly: set app.autoRender = false once, then set app.renderNextFrame = true before each frame you want rendered. The engine renders exactly that frame and clears the flag — do not rely on the free-running render loop plus a timed screenshot.
• Read the rendered pixels with await device.readPixelsAsync(x, y, w, h, pixels) against the exact backbuffer, not a re-encoded screenshot (e.g. canvas.toDataURL) that can introduce compression or colour-management differences the eye won't catch. In the installed engine this method lives on WebglGraphicsDevice, not the base GraphicsDevice type, so narrow to it (or branch on device.isWebGL2) before calling; a WebGPU project needs its own equivalent readback. If the project already has a screenshot path, hold it to the same rule: fixed size, fixed pose, no lossy step before the byte comparison.

Build a pose × phase matrix

Single-pose, single-frame proof cannot see everything a rendering refactor can break. Choose at least two representative camera poses — angles that would expose a dropped instance, a wrong batch bound, or a seam differently — and at least two animation phases, including one mid-animation, not only frame zero. Capture every pose × phase pair for the build before the change and the build after it, with the same canvas size, camera, and lighting each time.