Expand description
three-rs — a scene graph and a wgpu-based renderer, ported from
three.js.
§Relationship to three.js
three-rs is a line-for-line port of three.js’ core scene graph
(src/core, src/objects, src/math, …) and its WebGPURenderer, grown
one rung at a time: each ported example’s shaders come out of the same
node graph (see nodes) that three.js’ own WebGPURenderer builds them
from, rather than being hand-written, and a rung counts as correct only
when it reproduces the pixels three.js’ own end-to-end suite already
captured for that page (three.js/test/e2e). Every type here is a port of
a specific three.js source file; the module doc comments below and on
individual items name it, so three.js’ own docs and source are the place
to go for semantics this crate’s doc comments do not repeat.
§Ownership
The scene graph is single-threaded by design, not a 0.x limitation:
nothing in it is Send or Sync. three.js’ graph is single-threaded too,
and WebGPURenderer never touches an Object3D off the main thread;
parallelism belongs beside the scene rather than inside it — asset
decoding, layout, rasterising and filesystem scans run on other threads
and hand finished data to the scene thread, wgpu itself is thread-safe,
and a compositor drives the scene from one thread and sends it messages.
See decision 1 of the API design note.
A scene object is a ObjectRef — a newtype over Rc<RefCell<Object3D>>, so
borrow() / borrow_mut() work as they would on the RefCell directly.
Users hold ObjectRef clones across frames, as every three-rs consumer does.
The one place this port’s ownership differs from three.js: a child’s
parent link is a Weak, not a strong reference, so a subtree that is
removed and not held anywhere else is freed rather than kept alive by its
own children. See decision 2 of the API design note.
[testing] stays pub — the examples, the viewer, the e2e tests, the
sdf-text crate’s gates and consumers’ own graders all use its
write_png and three_js_dir — but it is #[doc(hidden)], since it is
not part of the renderer’s API and carries no compatibility promise.
§Errors
Only what touches the filesystem or the GPU is fallible: the loaders,
Renderer::new and
render(). Constructors, geometry builders
and scene-graph methods are infallible, as they are in three.js. A single
Error, #[non_exhaustive], covers this crate; every remaining panic in
library code is a statement about the crate’s own invariants (never about
a caller’s mistake) and its message starts three-rs:. See
decision 5 of the API design note.
§Modules
addons— ports ofthree.js/examples/jsm/, the tier above core that three.js ships separately.animation— ports ofthree.js/src/animation.cameras— ports ofthree.js/src/cameras.core— ports ofthree.js/src/core:Object3D,ObjectRef,BufferGeometry, the raycaster.environments— ports ofthree.js/examples/jsm/environments/, scenes built forrenderer::pmrem::PmremGenerator::from_scenerather than for the screen.extras— ports ofthree.js/src/extras/: curves, paths, shapes.geometries— ports ofthree.js/src/geometries.helpers— scene-graph objects that build their own geometry, ported fromthree.js/src/helpers/.io— the one seam through which the loaders read bytes:std::fsnatively, a host-preloaded map in a browser.lights— ports ofthree.js/src/lights.loaders— ports ofthree.js/src/loaders.materials— ports ofthree.js/src/materials/nodes; underWebGPURendererevery material is aNodeMaterial.math— ports ofthree.js/src/math.nodes— the node systemWebGPURendererbuilds every material through, ported fromthree.js/src/nodes/. Seedocs/nodes.md.objects— ports ofthree.js/src/objects, plusSceneand the renderer’sQuadMesh.renderer— the renderer itself, ported fromthree.js/src/renderers/common/Renderer.jsand the WebGPU backend.- [
testing] (hidden) — the e2e harness’ deterministic clock, RNG and pixel comparison, kept public for consumers’ own graders. textures— ports ofthree.js/src/textures.utils— ports ofthree.js/examples/jsm/utils, plus the clock seam that in three.js is just the browser.
Design notes for individual subsystems live under docs/ rather than in
doc comments — for example the API design note, the
scene-graph note and the node-system note.
§Example
Headless: create a renderer with no window, add a lit box to a scene,
render one frame and read the pixels back. no_run because CI’s test
job has no GPU adapter to create a renderer against; the shape below is
exactly what every ported example’s main() does.
use std::rc::Rc;
use three_rs::{
box_geometry, AmbientLight, Color, DirectionalLight, Mesh, MeshBasicNodeMaterial,
PerspectiveCamera, Renderer, RendererParameters, Scene,
};
let mut renderer = Renderer::new(RendererParameters::default())?;
renderer.set_size(800.0, 500.0);
let mut scene = Scene::new();
scene.add(&AmbientLight::new(Color::from_hex(0x404040), 1.0));
scene.add(&DirectionalLight::new(Color::from_hex(0xffffff), 1.0));
let geometry = Rc::new(box_geometry(1.0, 1.0, 1.0, 1, 1, 1));
let material = MeshBasicNodeMaterial::new();
let mesh = Mesh::new(geometry, material);
scene.add(&mesh);
let mut camera = PerspectiveCamera::new(60.0, 800.0 / 500.0, 0.1, 100.0);
camera.node.borrow_mut().position.z = 3.0;
renderer.render(&mut scene, &mut camera);
let (width, height, pixels) = renderer.read_canvas_pixels()?;
assert_eq!(pixels.len(), (width * height * 4) as usize);Re-exports§
pub use cameras::ArrayCamera;pub use cameras::CubeCamera;pub use cameras::OrthographicCamera;pub use cameras::PerspectiveCamera;pub use cameras::RenderCamera;pub use cameras::StereoCamera;pub use core::BufferGeometry;pub use core::Intersection;pub use core::Object3D;pub use core::ObjectRef;pub use core::Raycaster;pub use core::Timer;pub use environments::RoomEnvironment;pub use extras::CatmullRomCurve3;pub use extras::CubicBezierCurve;pub use extras::CubicBezierCurve3;pub use extras::Curve;pub use extras::CurvePath;pub use extras::CurveType;pub use extras::CurveVector;pub use extras::EllipseCurve;pub use extras::FrenetFrames;pub use extras::LineCurve;pub use extras::LineCurve3;pub use extras::Path;pub use extras::QuadraticBezierCurve;pub use extras::QuadraticBezierCurve3;pub use extras::Shape;pub use extras::ShapePath;pub use extras::SplineCurve;pub use geometries::box_geometry;pub use geometries::plane_geometry;pub use geometries::quad_geometry;pub use geometries::sphere_geometry;pub use geometries::teapot_geometry;pub use geometries::torus_knot_geometry;pub use helpers::CameraHelper;pub use helpers::GridHelper;pub use lights::AmbientLight;pub use lights::DirectionalLight;pub use lights::HemisphereLight;pub use lights::Light;pub use lights::LightKind;pub use lights::LightObject;pub use lights::LightProbe;pub use lights::LightShadow;pub use lights::PointLight;pub use lights::ShadowCamera;pub use lights::SpotLight;pub use loaders::BufferGeometryLoader;pub use loaders::CubeTextureLoader;pub use loaders::HdrCubeTextureLoader;pub use loaders::HdrLoader;pub use loaders::Ktx2Loader;pub use loaders::TextureLoader;pub use materials::Line2NodeMaterial;pub use materials::LineBasicNodeMaterial;pub use materials::MaterialKind;pub use materials::MeshBasicNodeMaterial;pub use materials::MeshLambertNodeMaterial;pub use materials::MeshNormalNodeMaterial;pub use materials::MeshPhongNodeMaterial;pub use materials::MeshPhysicalNodeMaterial;pub use materials::MeshStandardNodeMaterial;pub use materials::MeshToonNodeMaterial;pub use materials::PointsNodeMaterial;pub use materials::SpriteNodeMaterial;pub use materials::ToneMapping;pub use math::Color;pub use math::ColorSpace;pub use math::Euler;pub use math::Matrix3;pub use math::Matrix4;pub use math::Quaternion;pub use math::Vector2;pub use math::Vector3;pub use objects::Background;pub use objects::ClippingGroup;pub use objects::Fog;pub use objects::FogExp2;pub use objects::Group;pub use objects::InstancedMesh;pub use objects::Line;pub use objects::LineSegments;pub use objects::Mesh;pub use objects::Payload;pub use objects::Points;pub use objects::QuadMesh;pub use objects::Scene;pub use objects::SceneFog;pub use objects::Sprite;pub use renderer::depth_pass;pub use renderer::pass;pub use renderer::BuildCounts;pub use renderer::CameraRef;pub use renderer::ComputeCounts;pub use renderer::CubeRenderTarget;pub use renderer::DirectRenderPipeline;pub use renderer::Info;pub use renderer::MemoryCounts;pub use renderer::PassNode;pub use renderer::RenderCounts;pub use renderer::RenderPipeline;pub use renderer::RenderTarget;pub use renderer::Renderer;pub use renderer::RendererParameters;pub use renderer::SceneRef;pub use renderer::SsaaPassNode;pub use renderer::BACKENDS;pub use textures::CubeTexture;pub use textures::Data3DTexture;pub use textures::DepthTexture;pub use textures::Mapping;pub use textures::MinFilter;pub use textures::Texture;pub use textures::TextureFilter;pub use textures::TextureType;
Modules§
- addons
- Port of
three.js/examples/jsm/— the addons, the tier above the core library that three.js ships from a separate directory and that applications import asthree/addons/…. - animation
- Ports of
three.js/src/animation. - cameras
- Ports of
three.js/src/cameras. - core
- Ports of
three.js/src/core. - environments
- Port of
three.js/examples/jsm/environments/— scenes built to be fed toPmremGenerator::from_scene, not to be rendered to the screen. - extras
- Ports of
three.js/src/extras/: theCurvebase class and its 2D / 3D subclasses,CurvePath/Path/Shape/ShapePath,EarcutandShapeUtils, andDataUtils. - geometries
- Ports of
three.js/src/geometries. - helpers
- Ports of
three.js/src/helpers/: scene-graph objects that build their own geometry to visualise something else (axes, a box, a plane, a light, a skeleton). - io
- The one seam through which the loaders read bytes:
std::fsnatively, a host-preloaded map in a browser (issue #128). The one seam through which the loaders read bytes. - lights
- Ports of
three.js/src/lights:Light, the six light types this port uses, theLightShadowfamily andPointShadowNode. - loaders
- Ports of
three.js/src/loaders. - materials
- Ports of
three.js/src/materials/nodes— underWebGPURendererevery material is aNodeMaterial, so this is the only material path. - math
- Ports of
three.js/src/math. - nodes
- Port of
three.js/src/nodes/— the node system the WebGPU renderer builds every material through. Seedocs/nodes.md. - objects
- Ports of
three.js/src/objects(plusSceneand the renderer’sQuadMesh). - renderer
- Port of
three.js/src/renderers/common/Renderer.js+ the WebGPU backend: walk the scene, build each material through the node system, resolve the bindings it declared, draw into a render target or into the “canvas” texture, read back. - textures
- Ports of
three.js/src/textures. - utils
- Ports of
three.js/examples/jsm/utils, plus the one seam that has no three.js counterpart because in three.js it is the browser:time, which isperformance.now()andDate.now().