three-rs
A port of three.js core and its
WebGPURenderer to Rust on wgpu, graded by
Three's own end-to-end pixel comparison: each ported example renders headless
and is diffed against the reference screenshot Three ships for that example,
using Three's unmodified test/e2e/image.js comparator.
Two things distinguish it from other three.js-shaped Rust crates (including
the similarly named threers): the shaders are not hand-written but generated
from Three's node graph (TSL) by a port of Three's NodeBuilder, the way
WebGPURenderer does it, so Three's own WGSL dumps are the reference; and
correctness is judged by Three's own examples and reference screenshots, not
by scenes written for the port.
Status: early, working, incomplete. Ten of Three's webgpu_* examples
pass the grader; the vast majority of Three's 600-odd examples have not been
attempted. The API follows Three's object model but is not stable. Vulkan on
Linux is the only backend that has been run.
What is ported
- Math and core. Vector/Matrix/Quaternion/Euler/Color and the geometric
helpers (Box, Sphere, Plane, Ray, Frustum, Triangle, ...),
Object3Dscene graph,BufferGeometrywith named attributes, groups, draw ranges and morph attributes, layers, cameras. Verified against Three's QUnit tests. - Geometries. Box, Plane, Cylinder, Cone, Torus, the polyhedra, Circle, Ring, Lathe, Capsule, plus the Teapot and RoundedBox addons, bit-exact against samples generated from Three.
- Node system (TSL). A
NodeBuilderthat generates both WGSL stages and the bind group layout from a node graph, following Three'snodes/andrenderers/webgpu/nodes/. Generated WGSL is kept structurally identical to Three's dumps; deliberate divergences are listed indocs/nodes.md. - Materials.
MeshBasic,MeshPhong,MeshStandard(physical lighting model with DFG LUT),Sprite,LineBasic, and the shadow-pass material. Bump maps, env maps, blending modes, tone mapping. - Lights and shadows. Ambient, Hemisphere, Point, Spot, Directional; planar and cube shadow maps with Three's Vogel-disk filter.
- Renderer. Render lists, instancing, morph targets, render targets,
MSAA, the linear-to-sRGB output pass,
PassNodepost-processing, mipmaps, cube textures, line topology. - Loaders. glTF/GLB (all accessor types, skins, animations, KHR specular and ior), textures (PNG, JPEG), cube textures.
- Animation. Interpolants, keyframe tracks, clips,
PropertyMixer,AnimationActionandAnimationMixer. - Workspace crates.
sdf-text: signed-distance-field text rendering with aBatchedTextobject (ttf-parser outlines, analytic rasteriser).d3/hierarchy: a port of d3-hierarchy 3.1.2 (cluster, tree, partition, pack, treemap, stratify).
Examples graded green
| Three example | different pixels (of 100000) | steady frame (ms) |
|---|---|---|
| webgpu_depth_texture | 0 | 11.0 |
| webgpu_instance_mesh | 60 (Three itself scores 60 against the same JPEG) | 9.3 |
| webgpu_materials_basic | 0 | 16.1 |
| webgpu_rtt | 1 | 2.3 |
| webgpu_lights_phong | 31 | 4.3 |
| webgpu_morphtargets | 0 | 2.8 |
| webgpu_shadowmap | 7 | 7.7 |
| webgpu_lights_physical | 4 | 4.2 |
| webgpu_postprocessing_masking | 18 | 1.0 |
| webgpu_tsl_galaxy | 40 | 5.3 |
Measured on Intel Iris Xe, Mesa 25.3.6, Fedora 43, against three.js r186. Other GPUs and drivers will land somewhere else on the pass threshold; the threshold is Three's own (0.1% of pixels).
The steady frame is the whole cost of a frame once the first has built and
uploaded everything — the example's animate() through to the GPU finishing
it, at 800x500, mean of 30 frames after a 10-frame warm-up in a release build
(viewer <example> --headless --frames 40, below). The same machine caveat
applies. The e2e grader renders three more frames after the graded one and
fails a rung whose steady frame is over a ceiling set well above these
(STEADY_FRAME_CEILING in tests/e2e/main.rs), so a per-frame cost the single
graded frame cannot see fails the ladder.
Building
Requires a Rust toolchain (1.87 or newer) and a Vulkan driver. wgpu comes
from crates.io, pinned to 30.0.1 in Cargo.toml; nothing else is unusual.
The rest of cargo test --workspace needs a GPU (the renderer tests) and,
for the e2e grader, the three.js checkout described next. The e2e tests
serialise themselves on the one GPU; no --test-threads flag is needed.
The viewer
Opens the named example in a window (winit, tested on Wayland) with orbit,
zoom and pan. All ten graded examples are there; --list prints them with
their keys (1-9, 0), which switch examples in the window and stand in
for the name on the command line. The window prints one line a second with
the frame rate and the steady-state render time (mean and max over the last
60 frames, after a 10-frame warm-up):
webgpu_lights_phong — 1000x625 — 59.9 fps — render mean 1.61 ms max 1.79 ms (last 60 frames, after 10 warm-up)
--headless --frames N renders N frames with no window and reports the same
numbers for the whole frame, CPU and GPU, which is how the table above was
measured; add --screenshot out.png to keep the last frame.
Running the examples and the e2e grader
The examples load their textures and models from Three's own examples/
directory, and the grader reads Three's reference screenshots and runs its
comparator under node. So they need a three.js checkout:
( && )
# this is the default location
Each e2e test writes actual.png, the reference, and a diff strip under
target/e2e/<example>/. The grader is unmodified; rung0/grader-flags.patch
is only needed to run Three's own Chrome-based e2e suite on Linux with a
real Vulkan adapter, which is how the reference numbers were calibrated
(rung0/RUNG0.md).
Two more checkouts are optional:
| env var | default | needed by |
|---|---|---|
D3_HIERARCHY_DIR |
~/src/vendor/d3-hierarchy |
the d3-hierarchy crate's tests (its test/data fixtures) |
D3_GALLERY_DIR |
~/src/vendor/d3-gallery |
the d33_treemap_labels example (its flare.json) |
Tests that need a checkout that is missing fail on the open with the path they looked for.
Layout
src/ the three-rs crate, mirroring three.js's src/ tree
math core cameras geometries lights loaders materials objects textures animation
nodes/ TSL nodes and the WGSL NodeBuilder
renderer/ the wgpu backend: pipelines, bindings, passes, shadows, present
bin/viewer.rs
examples/ one file per ported Three example, also compiled into tests/e2e
tests/ Three's QUnit tests ported per module, plus the e2e harness
sdf-text/ workspace crate: SDF text and BatchedText
d3/hierarchy/ workspace crate: d3-hierarchy port
docs/ design notes per subsystem and per-example progress logs
rung0/ how the grader was calibrated
docs/nodes.md and docs/scene-graph.md are the two to read first: how the
node system maps onto Three's, and how the Rc<RefCell<Object3D>> scene graph
replaces Three's prototype tree.
How it was built
Example by example. Each "rung" takes one Three example, dumps the WGSL Three
generates for it, ports whatever the example needs until the generated WGSL
matches and the grader passes, then merges. The port was directed and largely
written by Claude agents with the pixel diff as the ground truth; the
per-rung progress notes in docs/ record what each rung found, including the
places where Three's own output was reproduced bug-for-bug and the places
where it deliberately was not.
License
MIT. See LICENSE, which also carries the three.js (MIT) and d3-hierarchy
(ISC) notices this port derives from.