Render validation

Golden-image tests (tests/golden/test_golden_gltf.mojo) render Khronos glTF-Sample-Assets models headless and compare them with committed references per platform. This file records how the references were produced and reviewed, and the tolerances.

Setup #

Models: tools/fetch_sample_assets.py, pinned to glTF-Sample-Assets commit 8f492390ddc7a2ae221a1369ef560589cf8c70fb (recorded in assets/samples/COMMIT).
Frame: 512 x 512, 4x MSAA, AgX, bloom, GTAO, cascaded sun shadows (sun from upper left front, 3 lux), procedural sky IBL, camera auto-framed on the model's bounds from the front right above.
Reference location: tests/golden/<platform>/<Model>.png. Regenerate with pixi run update-golden; compare with pixi run test-golden (also part of tools/run_tests.sh).

Tolerances #

Metric	Threshold	Why
SSIM (luma, 8x8 windows)	>= 0.985	Catches structural changes (missing geometry, shifted shadows, broken textures) while ignoring sub-texel rasterisation noise.
Pixels differing by more than 8/255 in any channel	<= 0.5% of the frame	Bounds local colour drift (lighting or material regressions) that SSIM on luma can miss.

Both must hold. The thresholds were chosen from the observed run-to-run difference on lavapipe (zero: frames are bit-identical between runs) with headroom for driver updates; a change that fails them is either a regression or an intentional change that must update the reference and this review.

Review of the Linux (lavapipe) references #

Each image was inspected against the Khronos reference render of the model (the screenshot/screenshot.png or .jpg in the model's folder of glTF-Sample-Assets) for geometry, orientation, material response and alpha handling. The lighting setup differs from Khronos's, so only structure, texture mapping and material plausibility are compared.

Model	Review
DamagedHelmet	Visor, metal trim and the emissive HUD glyphs (cyan) match the Khronos render; normal map detail on the shell reads correctly; roughness variation on the metal is plausible. Passed.
Sponza	Framed from inside the atrium at eye height looking down the hall (the auto-framing camera would sit outside the closed building). Columns, arches, fabric banners and floor tiles are present with their textures; alpha-masked foliage renders with cutouts. Passed.
MetalRoughSpheres	The 11 x 11 grid shows the metallic axis (top rows reflect the sky, bottom rows are dielectric white) and the roughness axis (sharp to diffuse highlights left to right); the gold-textured spheres and the axis labels are legible. Passed.
NormalTangentMirrorTest	Both the blue and yellow panels show the bump as a raised dome lit from the same side in every tile, including the U/V mirrored tiles, so tangent handedness (w) and mirrored UVs are honoured. Passed.
AlphaBlendModeTest	Opaque, blend and the three cutoff columns differ as the chart labels say: the blend panel is translucent over the marble, cutoff 0.25 keeps more of the gradient than 0.75. Passed.
TextureTransformTest	Top row: the U, V and UV transformed checkmarks are upright and complete; bottom row: each arrow ends on the green check marker, which is the pass condition the model encodes (KHR_texture_transform offset, rotation, scale, texCoord override). Passed.
Fox	Low-poly fox with its texture, standing at the bind pose; skinning data loaded (joint matrices at rest). Passed.
CesiumMan	Framed after posing the skinned mesh on the CPU for bounds; T-pose with the striped texture, upright (Y up after the skin's bind matrices). Passed.
MorphPrimitivesTest	Red and green checkered quads with the default morph weights from the mesh; no distortion artefacts at the shared edge. Passed. Re-reviewed 2026-11-09: the first reference showed a notch in the green primitive, which was deformed by the red primitive's morph deltas because the renderer bound only the first morphed mesh's delta buffer per frame. With one object group per morph buffer, both primitives use their own deltas and meet cleanly along the shared edge; the reference was regenerated from that render and inspected (no gap, no overlap, checker continuous across the seam).
BoomBox	Dark body, PLAY label, speaker grille and antenna present; metal/roughness map gives the expected sheen on the rim. Passed.
WaterBottle	Yellow translucent-looking bottle (opaque material with a glossy normal map), red cap and logo, black holder. Passed.
Lantern	Wooden post, iron fittings and the emissive lamp (warm glow with bloom). Passed.
Avocado	Half avocado with skin, flesh gradient and pit, correct mapping of the diffuse and normal maps. Passed.
BoxTextured	The Cesium logo on every face with the correct orientation per face. Passed.
Suzanne	Dark glossy monkey with golden eyes, matching the sample's material. Passed.
FlightHelmet	Leather helmet, goggles (glass over green lenses), mask, hoses and the wooden stand with its plaque; multiple materials and double-sided straps. Passed.

macOS (Metal) #

No references yet: no macOS machine or runner was available (see REPORT.md, Blockers). The test selects the platform directory by PLATFORM; Metal references must be generated on a Mac with pixi run update-golden and reviewed the same way.