three-rs 0.2.0

A port of three.js core and its WebGPURenderer to Rust on wgpu, graded against three.js's own end-to-end pixel comparison.
Documentation

three-rs

CI

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, ...), Object3D scene graph, BufferGeometry with 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, ShapeUtils with Earcut, and Shape, Extrude and Tube geometries, with their QUnit ports and a 1e-6 oracle against Three's own output.
  • Node system (TSL). A NodeBuilder that generates both WGSL stages and the bind group layout from a node graph, following Three's nodes/ and renderers/webgpu/nodes/. Generated WGSL is kept structurally identical to Three's dumps; deliberate divergences are listed in docs/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, PassNode post-processing, mipmaps, cube textures, line topology, viewport / scissor / clearDepth and autoClear.
  • Addons. src/addons/ holds the three/addons/… tier that the graded examples import: lines (LineSegmentsGeometry, LineGeometry, LineSegments2, Line2 — fat lines, with Line2NodeMaterial in core beside them, as three.js ships it), geometry_utils, text_geometry (TextGeometry), curve_modifier_gpu (Flow), and controls::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/controls is 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_compression and KHR_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, AnimationAction and AnimationMixer.
  • Workspace crate. sdf-text: signed-distance-field text rendering with a BatchedText object (ttf-parser outlines, analytic rasteriser), and the SDF text examples with their gates. Its d33_treemap_labels example lays its treemap out with d3-hierarchy, a port of d3-hierarchy 3.1.2 that began in this repository.

Examples graded green

webgpu_depth_texture webgpu_instance_mesh webgpu_materials_basic webgpu_rtt
webgpu_lights_phong · notes webgpu_morphtargets · notes webgpu_shadowmap · notes webgpu_lights_physical · notes
webgpu_postprocessing_masking · notes webgpu_tsl_galaxy · notes webgpu_skinning · notes webgpu_mesh_batch · notes
webgpu_postprocessing_radial_blur · notes webgpu_materials · notes webgpu_postprocessing_ssaa · notes webgpu_pmrem_cubemap · notes
webgpu_postprocessing_bloom_selective · notes webgpu_compute_points · notes webgpu_lines_fat · notes webgpu_lines_fat_raycasting · notes
webgpu_pmrem_test · notes webgpu_postprocessing_difference · notes webgpu_postprocessing_direct · notes webgpu_furnace_test · notes
webgpu_postprocessing_anamorphic · notes webgpu_pmrem_scene · notes webgpu_postprocessing_bloom · notes webgpu_materials_envmaps · notes
webgpu_materials_cubemap_mipmaps · notes webgpu_postprocessing_bloom_emissive · notes webgpu_instance_uniform · notes webgpu_tsl_interoperability · notes
webgpu_pmrem_equirectangular · notes webgpu_postprocessing_ca · notes webgpu_loader_gltf · notes webgpu_mrt · notes
webgpu_custom_fog_background · notes webgpu_loader_gltf_sheen · notes webgpu_deferred · notes webgpu_loader_gltf_anisotropy · notes
webgpu_materials_texture_manualmipmap · notes webgpu_tsl_vfx_flames · notes webgpu_procedural_texture · notes webgpu_postprocessing_sobel · notes
webgpu_postprocessing_transition · notes webgpu_tsl_raging_sea · notes webgpu_tsl_angular_slicing · notes webgpu_textures_2d-array_compressed · notes
webgpu_compute_texture · notes webgpu_volume_perlin · notes webgpu_shadowmap_vsm · notes webgpu_shadowmap_pointlight · notes
webgpu_struct_drawindirect · notes webgpu_particles · notes webgpu_clearcoat · notes webgpu_modifier_curve · notes
webgpu_camera_array · notes webgpu_sprites · notes webgpu_instance_sprites · notes webgpu_materials_toon · notes
webgpu_occlusion · notes webgpu_fog_height · notes webgpu_shadowmap_opacity · notes webgpu_multiple_rendertargets · notes
webgpu_multiple_rendertargets_readback · notes webgpu_texturegrad · notes webgpu_texturegather · notes webgpu_postprocessing_fxaa · notes
webgpu_lights_selective · notes webgpu_loader_gltf_compressed · notes webgpu_equirectangular · notes webgpu_skinning_points · notes
webgpu_instance_points · notes webgpu_textures_partialupdate · notes webgpu_layers · notes webgpu_loader_gltf_diffuse_roughness · notes
webgpu_cubemap_mix · notes webgpu_mirror · notes webgpu_tsl_halftone · notes webgpu_tsl_earth · notes

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.

cargo build --release
cargo test -p sdf-text --lib                # sdf-text unit tests; no GPU
cargo test -p three-rs --lib                # three-rs unit tests; no GPU

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

cargo run --release --bin viewer -- --list
cargo run --release --bin viewer -- webgpu_lights_physical
cargo run --release --bin viewer -- 8                        # the same, by key
cargo run --release --bin viewer -- shadowmap --headless --frames 40

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.

cargo run --release -p three-rs-controls --bin heli -- \
    --headless addons/controls/shots/heli-sphere-high.png \
    --radius 300 --pose 0,0,800,0,20 [--overview] [--size 1600x1000] [--no-legend]

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:

git clone https://github.com/mrdoob/three.js ~/src/vendor/three.js
git -C ~/src/vendor/three.js checkout 5f610f5   # the r187 tag, once upstream tags it
(cd ~/src/vendor/three.js && npm ci)
export THREE_JS_DIR=~/src/vendor/three.js     # this is the default location
cargo test --test e2e -- --nocapture

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.