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. The webgpu_* examples in the gallery
below 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. The curve family (
Curve,CurvePath, lines, Béziers, ellipses/arcs, splines,CatmullRomCurve3),Path/Shape/ShapePath,ShapeUtilswith Earcut, andShape,ExtrudeandTubegeometries, with their QUnit ports and a 1e-6 oracle against Three's own output. - 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, viewport / scissor /clearDepthandautoClear. - Addons.
src/addons/holds thethree/addons/…tier that the graded examples import:lines(LineSegmentsGeometry,LineGeometry,LineSegments2,Line2— fat lines, withLine2NodeMaterialin core beside them, as three.js ships it),geometry_utils,text_geometry(TextGeometry),curve_modifier_gpu(Flow), andcontrols::OrbitControls, a port of the JS class graded against the JS class itself. An addon that needs nothing from core would be a workspace crate instead —addons/controlsis one — and that stays the preferred shape; these live in the root crate because the e2e harness pulls examples in with#[path = "../../examples/…"], and an example in another crate would need its own test binary. - Loaders. glTF/GLB (all accessor types, skins, animations, KHR specular
and ior,
EXT_meshopt_compressionandKHR_mesh_quantization), textures (PNG, JPEG), cube textures. and ior,EXT_texture_webp), textures (PNG, JPEG, GIF, WebP; not AVIF), cube textures. and ior), textures (PNG, JPEG), cube textures, typeface.json fonts (FontLoader). - Animation. Interpolants, keyframe tracks, clips,
PropertyMixer,AnimationActionandAnimationMixer. - Workspace crate.
sdf-text: signed-distance-field text rendering with aBatchedTextobject (ttf-parser outlines, analytic rasteriser), and the SDF text examples with their gates. Itsd33_treemap_labelsexample lays its treemap out with d3-hierarchy, a port of d3-hierarchy 3.1.2 that began in this repository.
Examples graded green
Our own rendered frames, one per graded example. Each thumbnail opens the example running in your browser on WebGPU (all of them); the caption links the ported source. See docs/gallery.md.
Every one of these also runs in a browser, on the browser's own WebGPU, from
the same init(): the graded frame first, then the page's own animation loop,
with drag to orbit, wheel to dolly and right-drag to pan. See
web/README.md
for how to build and serve the shell, and issue #128
for where that is going. The table's browser column is CI's web-gate job:
the same example in headless Chrome on software WebGPU, graded against the
same screenshots at the same threshold (see
Grading in the browser).
| Three example | different pixels (of 100000) | steady frame (ms) | draw calls | triangles | browser |
|---|---|---|---|---|---|
| webgpu_depth_texture | 0 | 11.0 | 43 | 671746 | yes |
| webgpu_instance_mesh | 60 (Three itself scores 60 against the same JPEG) | 9.3 | 2 | 967001 | yes |
| webgpu_materials_basic | 0 | 16.1 | 118 | 113345 | yes |
| webgpu_rtt | 1 | 2.3 | 3 | 14 | yes |
| webgpu_lights_phong | 31 | 4.3 | 5 | 62001 | yes |
| webgpu_morphtargets | 0 | 2.8 | 2 | 12289 | yes |
| webgpu_shadowmap | 7 | 7.7 | 19 | 39399 | yes |
| webgpu_lights_physical | 4 | 4.2 | 11 | 4267 | yes |
| webgpu_postprocessing_masking | 18 | 1.0 | 3 | 1037 | yes |
| webgpu_tsl_galaxy | 40 | 5.3 | 2 | 40001 | yes |
| webgpu_skinning | 6 | 3.0 | 3 | 30091 | yes |
| webgpu_mesh_batch | 0 | 2.5 | 454 | 44341 | yes |
| webgpu_postprocessing_radial_blur | 7 | 3.9 | 2 | 401 | yes |
| webgpu_materials | 44 | 7.3 | 19 | 350065 | yes |
| webgpu_postprocessing_ssaa | 0 | 11.9 | 17 | 2119689 | yes |
| webgpu_pmrem_cubemap | 31 | 8.2 | 32 | 243905 | yes |
| webgpu_postprocessing_bloom_selective | 1 | 16.5 | 63 | 256013 | yes |
| webgpu_compute_points | 4 (see below) | 10.7 | 2 | 1 + 300000 points | yes |
| webgpu_lines_fat | 0 | 3.8 | 6 | 11191 | yes |
| webgpu_lines_fat_raycasting | 57 | 1.7 | 2 | 901 | yes |
| webgpu_pmrem_test | 0 | 6.1 | 35 | 67457 | yes |
| webgpu_postprocessing_difference | 13 | 1.5 | 2 | 13 | yes |
| webgpu_postprocessing_direct | 21 | 4.9 | 93 | 4192 | yes |
| webgpu_furnace_test | 0 | 7.1 | 122 | 116161 | yes |
| webgpu_postprocessing_anamorphic | 2 | 8.1 | 16 | 398798 | yes |
| webgpu_pmrem_scene | 0 | 3.8 | 9 | 58433 | yes |
| webgpu_postprocessing_bloom | 0 | 8.6 | 19 | 52085 | yes |
| webgpu_materials_envmaps | 0 | 2.1 | 3 | 7105 | yes |
| webgpu_materials_cubemap_mipmaps | 1 | 2.6 | 3 | 65025 | yes |
| webgpu_postprocessing_bloom_emissive | 0 | 5.1 | 15 | 17449 | yes |
| webgpu_instance_uniform | 13 | 6.0 | 14 | 247105 | yes |
| webgpu_tsl_interoperability | 0 | 2.2 | 2 | 4 | yes |
| webgpu_pmrem_equirectangular | 0 | 5.9 | 32 | 243905 | yes |
| webgpu_postprocessing_ca | 0 | 3.4 | 23 | 5658 (+ 42 lines) | yes |
| webgpu_loader_gltf | 22 | 1.9 | 3 | 17437 | yes |
| webgpu_mrt | 10 | 2.8 | 3 | 17437 | yes |
| webgpu_custom_fog_background | 7 | 2.0 | 2 | 15453 | yes |
| webgpu_loader_gltf_sheen | 28 | 3.1 | 6 | 41921 | yes |
| webgpu_deferred | 0 | 2.8 | 25 | 26378 | yes |
| webgpu_loader_gltf_anisotropy | 94 | 3.2 | 5 | 12188 | yes |
| webgpu_materials_texture_manualmipmap | 81 | 2.5 | 11 | 19 | yes |
| webgpu_tsl_vfx_flames | 31 | 5.4 | 5 | 9 | yes |
| webgpu_procedural_texture | 0 | 3.2 | 5 | 6 | yes |
| webgpu_postprocessing_sobel | 0 | 2.8 | 3 | 91218 | yes |
| webgpu_postprocessing_transition | 0 | 1.4 | 2 | 40001 | yes |
| webgpu_tsl_raging_sea | 12 | 10.5 | 2 | 131073 | yes |
| webgpu_tsl_angular_slicing | 4 | 3.3 | 9 | 45397 | yes |
| webgpu_textures_2d-array_compressed | 0 | 6.1 | 1 | 2 | yes |
| webgpu_compute_texture | 0 | 1.2 | 2 | 3 | yes |
| webgpu_volume_perlin | 23 | 5.2 | 2 | 13 | yes |
| webgpu_shadowmap_vsm | 0 | 4.5 | 22 | 10419 | yes |
| webgpu_shadowmap_pointlight | 63 (Three itself scores 63 against the same JPEG) | 5.0 | 20 | 7421 | yes |
| webgpu_struct_drawindirect | 0 (see below) | 1.3 | 2 | 100001 (drawn indirect) | yes |
| webgpu_particles | 0 (see below) | 5.8 | 4 | 6001 (+ 82 lines; the fire's 2000 drawn indirect) | yes |
| webgpu_clearcoat | 4 | 2.7 | 6 | 17857 | yes |
| webgpu_modifier_curve | 3 (Three itself scores 3 against the same JPEG) | 1.3 | 7 | 34753 (+ 50 lines) | yes |
| webgpu_camera_array | 20 | 4.0 | 73 | 4808 | yes |
| webgpu_sprites | 0 | 13.8 | 201 | 401 | yes |
| webgpu_instance_sprites | 32 | 1.0 | 2 | 20001 | yes |
| webgpu_materials_toon | 0 | 58.9 | 438 | 421985 | yes |
| webgpu_occlusion | 0 | 1.9 | 3 | 963 | yes |
| webgpu_fog_height | 0 | 2.8 | 3 | 3185 | yes |
| webgpu_shadowmap_opacity | 9 | 6.0 | 6 | 408644 | yes |
| webgpu_multiple_rendertargets | 22 | 2.2 | 2 | 8193 | yes |
| webgpu_multiple_rendertargets_readback | 22 | 2.4 | 3 | 8194 | yes |
| webgpu_texturegrad | 0 | 2.2 | 4 | 6 | yes |
| webgpu_texturegather | 16 | 1.8 | 4 | 6 | yes |
| webgpu_postprocessing_fxaa | 56 (Three itself scores 56 against the same JPEG) | 4.0 | 3 | 402 | yes |
| webgpu_lights_selective | 9 (Three itself scores 9 against the same JPEG) | 4.6 | 5 | 62001 | yes |
| webgpu_loader_gltf_compressed | 4 | 6.1 | 3 | 332259 | yes |
| webgpu_equirectangular | 0 | 3.6 | 2 | 1985 | yes |
| webgpu_skinning_points | 44 | 7.5 | 2 | 32681 (16340 point quads) | yes |
| webgpu_instance_points | 16 | 21.5 | 6 | 3011 (256 point quads, drawn twice) | yes |
| webgpu_textures_partialupdate | 0 | 9.3 | 2 | 3 | yes |
| webgpu_layers | 76 (Three itself scores 76 against the same JPEG) | 3.5 | 5 | 16985 | yes |
| webgpu_loader_gltf_diffuse_roughness | 0 | 8.6 | 26 | 75713 | yes |
| webgpu_cubemap_mix | 1 | 6.4 | 3 | 17437 | yes |
| webgpu_mirror | 22 | 6.4 | 40 | 6269 | yes |
| webgpu_tsl_halftone | 93 (Three itself scores 93 against the same JPEG) | 3.1 | 4 | 44363 | yes |
| webgpu_tsl_earth | 0 | 2.6 | 3 | 16129 | yes |
webgpu_compute_points is graded like the rest and its 4 pixels mean less
than the rest: its frame is black apart from a 2x2 block at the centre, so
Three's comparator would pass it at 0.0% even if the compute passes never ran.
That rung is gated on the WGSL its kernels compile to and on reading the
storage buffers back — docs/rung12-progress.md says why and what the tests
assert.
webgpu_struct_drawindirect and webgpu_particles are the same kind of
green. three's page draws before it dispatches the kernels that fill the
indirect buffer, so the graded frame of the first is the clear colour; at the
grader's pinned time every sprite of the second has zero opacity, so its frame
is the grid. Both are gated on their shaders against three's own dump
(tests/nodes_compute_indirect_wgsl.rs) and on what the GPU draws a frame or
a moment later (tests/renderer_compute_indirect.rs); the notes say what each
asserts. The triangle counts are the CPU-side counts renderer.info() records
for an indirect draw, as three's does, not what the GPU was told to draw.
Measured on Intel Iris Xe, Mesa 25.3.6, Fedora 43, against three.js 5f610f5 (past r186, for the cube PMREM of 2f80402; the pin becomes the r187 tag once upstream tags it). 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.
The last two columns are renderer.info() for the whole graded frame — draw
calls and the triangles they drew, instancing multiplied in (webgpu_rtt's 14
is a cube and two full-screen quads; webgpu_instance_mesh's million is one
instanced draw). Unlike the time, these are exact: the same grader asserts
that frames two and three of every rung compile, build and upload nothing,
as an equality, which is what catches a regression that re-uploads a live
geometry every frame while staying well under a time ceiling. Info has the
rest of the counts (pipelines, geometries, attribute buffers, textures, and
the resident totals).
Building
(For how to contribute, what is in scope, and the gates a change has to pass,
see CONTRIBUTING.md.)
Requires a Rust toolchain (1.90 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 the
SDF text gates) 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 for them, but sdf-text's three GPU gates still want
-- --test-threads=1.
The viewer
Opens the named example in a window (winit, tested on Wayland). All 58 graded
examples are there, and each one animates, orbits, dollies and pans through
its own animate(), resize() and OrbitControls — the viewer drives the
example, it does not restate it. --list prints the examples with their keys,
and a key stands in for the name on the command line; in the window, [ and
] step to the previous and next example, because 56 of them do not fit in
the 36 single keys a keyboard has. 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. It also writes
target/e2e/<example>/strip.png: three more frames tiled left to right at
1:1, each with its draw calls and its build counts in the gutter under it, so
the count ladder sits beside the time one. The e2e harness writes the same
strip per rung (steady-strip.png) and one for the geometry-mutation case.
Addons
three.js keeps its controls, loaders and helpers out of core, in
examples/jsm/ — exported as three/addons/*, importing from three like any
user, and without core's stability promise. addons/ is the same tier here:
workspace crates that depend on three-rs and are not ports of anything in
three.js' src/.
three_rs::addons::controls::OrbitControls is the exception to that rule, and
it is in the root crate rather than a workspace one: 38 of the 58 graded pages
create an OrbitControls, and an example pulled in by #[path] cannot reach a
crate that depends on three-rs. It is a port of
examples/jsm/controls/OrbitControls.js — the same state, the same defaults,
the same update() — but input-agnostic: it takes pointer_down,
pointer_move, pointer_up, wheel and key as plain values, so the same
controls serve a winit window, a DOM canvas and a test. It is graded the way
everything else here is, against the original: tools/orbit_controls_reference.mjs
runs the JS class under node over twelve scripted scenarios and prints the
camera it ends with, and tests/addons_orbit_controls.rs replays the same
scenarios and asserts every number to 1e-9.
addons/controls/ is a different addon: three-rs-controls, a MapControls in the spirit of
three.js' addon of that name, over a Ground — a sphere whose north pole is the
world origin, so R = 1e7 is a plane and a small R a planet, with no separate
case. The orbit target is a point on the ground, the camera never rolls —
up is the ground normal — and every field is damped with smooth_damp, a port
of camera-controls' smoothDamp.
cargo run --release -p three-rs-controls --bin heli is the demo, with its key
map on screen: left-drag grabs the ground,
right-drag (or ctrl-drag) orbits, the wheel zooms to the pointer,
the arrows pan, [ ] curl the ground and P flattens it, Home
resets, Tab is the overview (click a pane to drop onto it), Esc quits.
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).
One more checkout is optional:
| env var | default | needed by |
|---|---|---|
D3_GALLERY_DIR |
~/src/vendor/d3-gallery |
sdf-text's 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, with its examples and gates
addons/ workspace crates in the role of three.js' examples/jsm: not ports
controls/ three-rs-controls — the map camera, its ground, and the heli demo
docs/ design notes per subsystem and per-example progress logs
rung0/ how the grader was calibrated
tools/ dump-webgpu.mjs, the rung dump hook (see docs/dumping.md)
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. docs/dumping.md says how a rung captures
the WGSL and GPU descriptors it ports against.
How it was built
Example by example. Each "rung" takes one Three example, dumps the WGSL Three
generates for it (tools/dump-webgpu.mjs; see docs/dumping.md), 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) notice this port
derives from.