Skip to main content

Crate three_rs

Crate three_rs 

Source
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 of three.js/examples/jsm/, the tier above core that three.js ships separately.
  • animation — ports of three.js/src/animation.
  • cameras — ports of three.js/src/cameras.
  • core — ports of three.js/src/core: Object3D, ObjectRef, BufferGeometry, the raycaster.
  • environments — ports of three.js/examples/jsm/environments/, scenes built for renderer::pmrem::PmremGenerator::from_scene rather than for the screen.
  • extras — ports of three.js/src/extras/: curves, paths, shapes.
  • geometries — ports of three.js/src/geometries.
  • helpers — scene-graph objects that build their own geometry, ported from three.js/src/helpers/.
  • io — the one seam through which the loaders read bytes: std::fs natively, a host-preloaded map in a browser.
  • lights — ports of three.js/src/lights.
  • loaders — ports of three.js/src/loaders.
  • materials — ports of three.js/src/materials/nodes; under WebGPURenderer every material is a NodeMaterial.
  • math — ports of three.js/src/math.
  • nodes — the node system WebGPURenderer builds every material through, ported from three.js/src/nodes/. See docs/nodes.md.
  • objects — ports of three.js/src/objects, plus Scene and the renderer’s QuadMesh.
  • renderer — the renderer itself, ported from three.js/src/renderers/common/Renderer.js and the WebGPU backend.
  • [testing] (hidden) — the e2e harness’ deterministic clock, RNG and pixel comparison, kept public for consumers’ own graders.
  • textures — ports of three.js/src/textures.
  • utils — ports of three.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 as three/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 to PmremGenerator::from_scene, not to be rendered to the screen.
extras
Ports of three.js/src/extras/: the Curve base class and its 2D / 3D subclasses, CurvePath / Path / Shape / ShapePath, Earcut and ShapeUtils, and DataUtils.
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::fs natively, 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, the LightShadow family and PointShadowNode.
loaders
Ports of three.js/src/loaders.
materials
Ports of three.js/src/materials/nodes — under WebGPURenderer every material is a NodeMaterial, 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. See docs/nodes.md.
objects
Ports of three.js/src/objects (plus Scene and the renderer’s QuadMesh).
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 is performance.now() and Date.now().

Enums§

Error
Everything the public API of three-rs can fail with.
GltfError
What went wrong inside a glTF asset, as far as the loader reads it.