three_rs/lib.rs
1//! `three-rs` — a scene graph and a `wgpu`-based renderer, ported from
2//! three.js.
3//!
4//! # Relationship to three.js
5//!
6//! `three-rs` is a line-for-line port of three.js' core scene graph
7//! (`src/core`, `src/objects`, `src/math`, …) and its `WebGPURenderer`, grown
8//! one rung at a time: each ported example's shaders come out of the same
9//! node graph (see [`nodes`]) that three.js' own `WebGPURenderer` builds them
10//! from, rather than being hand-written, and a rung counts as correct only
11//! when it reproduces the pixels three.js' own end-to-end suite already
12//! captured for that page (`three.js/test/e2e`). Every type here is a port of
13//! a specific three.js source file; the module doc comments below and on
14//! individual items name it, so three.js' own docs and source are the place
15//! to go for semantics this crate's doc comments do not repeat.
16//!
17//! # Ownership
18//!
19//! The scene graph is single-threaded by design, not a 0.x limitation:
20//! nothing in it is `Send` or `Sync`. three.js' graph is single-threaded too,
21//! and `WebGPURenderer` never touches an `Object3D` off the main thread;
22//! parallelism belongs beside the scene rather than inside it — asset
23//! decoding, layout, rasterising and filesystem scans run on other threads
24//! and hand finished data to the scene thread, `wgpu` itself is thread-safe,
25//! and a compositor drives the scene from one thread and sends it messages.
26//! See [decision 1 of the API design note][api-md].
27//!
28//! A scene object is a [`ObjectRef`] — a newtype over `Rc<RefCell<Object3D>>`, so
29//! `borrow()` / `borrow_mut()` work as they would on the `RefCell` directly.
30//! Users hold `ObjectRef` clones across frames, as every three-rs consumer does.
31//! The one place this port's ownership differs from three.js: a child's
32//! `parent` link is a `Weak`, not a strong reference, so a subtree that is
33//! removed and not held anywhere else is freed rather than kept alive by its
34//! own children. See [decision 2 of the API design note][api-md].
35//!
36//! [`testing`] stays `pub` — the examples, the viewer, the e2e tests, the
37//! `sdf-text` crate's gates and consumers' own graders all use its
38//! `write_png` and `three_js_dir` — but it is `#[doc(hidden)]`, since it is
39//! not part of the renderer's API and carries no compatibility promise.
40//!
41//! # Errors
42//!
43//! Only what touches the filesystem or the GPU is fallible: the loaders,
44//! [`Renderer::new`](renderer::Renderer::new) and
45//! [`render()`](renderer::Renderer::render). Constructors, geometry builders
46//! and scene-graph methods are infallible, as they are in three.js. A single
47//! [`Error`], `#[non_exhaustive]`, covers this crate; every remaining panic in
48//! library code is a statement about the crate's own invariants (never about
49//! a caller's mistake) and its message starts `three-rs:`. See
50//! [decision 5 of the API design note][api-md].
51//!
52//! # Modules
53//!
54//! - [`addons`] — ports of `three.js/examples/jsm/`, the tier above core that
55//! three.js ships separately.
56//! - [`animation`] — ports of `three.js/src/animation`.
57//! - [`cameras`] — ports of `three.js/src/cameras`.
58//! - [`core`] — ports of `three.js/src/core`: `Object3D`, [`ObjectRef`],
59//! `BufferGeometry`, the raycaster.
60//! - [`environments`] — ports of `three.js/examples/jsm/environments/`, scenes
61//! built for [`renderer::pmrem::PmremGenerator::from_scene`] rather than for
62//! the screen.
63//! - [`extras`] — ports of `three.js/src/extras/`: curves, paths, shapes.
64//! - [`geometries`] — ports of `three.js/src/geometries`.
65//! - [`helpers`] — scene-graph objects that build their own geometry, ported
66//! from `three.js/src/helpers/`.
67//! - [`io`] — the one seam through which the loaders read bytes: `std::fs`
68//! natively, a host-preloaded map in a browser.
69//! - [`lights`] — ports of `three.js/src/lights`.
70//! - [`loaders`] — ports of `three.js/src/loaders`.
71//! - [`materials`] — ports of `three.js/src/materials/nodes`; under
72//! `WebGPURenderer` every material is a `NodeMaterial`.
73//! - [`math`] — ports of `three.js/src/math`.
74//! - [`nodes`] — the node system `WebGPURenderer` builds every material
75//! through, ported from `three.js/src/nodes/`. See
76//! [`docs/nodes.md`][nodes-md].
77//! - [`objects`] — ports of `three.js/src/objects`, plus `Scene` and the
78//! renderer's `QuadMesh`.
79//! - [`renderer`] — the renderer itself, ported from
80//! `three.js/src/renderers/common/Renderer.js` and the WebGPU backend.
81//! - [`testing`] (hidden) — the e2e harness' deterministic clock, RNG and
82//! pixel comparison, kept public for consumers' own graders.
83//! - [`textures`] — ports of `three.js/src/textures`.
84//! - [`utils`] — ports of `three.js/examples/jsm/utils`, plus the clock seam
85//! that in three.js is just the browser.
86//!
87//! Design notes for individual subsystems live under `docs/` rather than in
88//! doc comments — for example the [API design note][api-md], the
89//! [scene-graph note][scene-graph-md] and the [node-system note][nodes-md].
90//!
91//! [api-md]: https://github.com/oneilltomhq/three-rs/blob/main/docs/api.md
92//! [scene-graph-md]: https://github.com/oneilltomhq/three-rs/blob/main/docs/scene-graph.md
93//! [nodes-md]: https://github.com/oneilltomhq/three-rs/blob/main/docs/nodes.md
94//!
95//! # Example
96//!
97//! Headless: create a renderer with no window, add a lit box to a scene,
98//! render one frame and read the pixels back. `no_run` because CI's `test`
99//! job has no GPU adapter to create a renderer against; the shape below is
100//! exactly what every ported example's `main()` does.
101//!
102//! ```no_run
103//! use std::rc::Rc;
104//!
105//! use three_rs::{
106//! box_geometry, AmbientLight, Color, DirectionalLight, Mesh, MeshBasicNodeMaterial,
107//! PerspectiveCamera, Renderer, RendererParameters, Scene,
108//! };
109//!
110//! let mut renderer = Renderer::new(RendererParameters::default())?;
111//! renderer.set_size(800.0, 500.0);
112//!
113//! let mut scene = Scene::new();
114//! scene.add(&AmbientLight::new(Color::from_hex(0x404040), 1.0));
115//! scene.add(&DirectionalLight::new(Color::from_hex(0xffffff), 1.0));
116//!
117//! let geometry = Rc::new(box_geometry(1.0, 1.0, 1.0, 1, 1, 1));
118//! let material = MeshBasicNodeMaterial::new();
119//! let mesh = Mesh::new(geometry, material);
120//! scene.add(&mesh);
121//!
122//! let mut camera = PerspectiveCamera::new(60.0, 800.0 / 500.0, 0.1, 100.0);
123//! camera.node.borrow_mut().position.z = 3.0;
124//!
125//! renderer.render(&mut scene, &mut camera);
126//! let (width, height, pixels) = renderer.read_canvas_pixels()?;
127//! assert_eq!(pixels.len(), (width * height * 4) as usize);
128//! # Ok::<(), three_rs::Error>(())
129//! ```
130
131#![warn(missing_docs)]
132pub mod addons;
133pub mod animation;
134pub mod cameras;
135pub mod core;
136pub mod environments;
137pub(crate) mod error;
138pub mod extras;
139pub mod geometries;
140pub mod helpers;
141/// The one seam through which the loaders read bytes: `std::fs` natively, a
142/// host-preloaded map in a browser (issue #128).
143pub mod io;
144pub mod lights;
145pub mod loaders;
146pub mod materials;
147pub mod math;
148pub mod nodes;
149pub mod objects;
150pub mod renderer;
151/// Hidden from the rendered docs on purpose (#40). It stays `pub` because the
152/// examples, the viewer, the e2e tests, the `sdf-text` crate's gates and
153/// consumers' own graders use it; it is not part of the renderer's API and
154/// carries no compatibility promise.
155#[doc(hidden)]
156pub mod testing;
157pub mod textures;
158pub mod utils;
159
160pub use cameras::{
161 ArrayCamera, CubeCamera, OrthographicCamera, PerspectiveCamera, RenderCamera, StereoCamera,
162};
163pub use core::{BufferGeometry, Intersection, Object3D, ObjectRef, Raycaster, Timer};
164pub use environments::RoomEnvironment;
165pub use error::{Error, GltfError};
166pub use extras::{
167 CatmullRomCurve3, CubicBezierCurve, CubicBezierCurve3, Curve, CurvePath, CurveType,
168 CurveVector, EllipseCurve, FrenetFrames, LineCurve, LineCurve3, Path, QuadraticBezierCurve,
169 QuadraticBezierCurve3, Shape, ShapePath, SplineCurve,
170};
171pub use geometries::{
172 box_geometry, plane_geometry, quad_geometry, sphere_geometry, teapot_geometry,
173 torus_knot_geometry,
174};
175pub use helpers::{CameraHelper, GridHelper};
176pub use lights::{
177 AmbientLight, DirectionalLight, HemisphereLight, Light, LightKind, LightObject, LightProbe,
178 LightShadow, PointLight, ShadowCamera, SpotLight,
179};
180pub use loaders::{
181 BufferGeometryLoader, CubeTextureLoader, HdrCubeTextureLoader, HdrLoader, Ktx2Loader,
182 TextureLoader,
183};
184pub use materials::{
185 Line2NodeMaterial, LineBasicNodeMaterial, MaterialKind, MeshBasicNodeMaterial,
186 MeshLambertNodeMaterial, MeshNormalNodeMaterial, MeshPhongNodeMaterial,
187 MeshPhysicalNodeMaterial, MeshStandardNodeMaterial, MeshToonNodeMaterial, PointsNodeMaterial,
188 SpriteNodeMaterial, ToneMapping,
189};
190pub use math::{Color, ColorSpace, Euler, Matrix3, Matrix4, Quaternion, Vector2, Vector3};
191pub use objects::{
192 Background, ClippingGroup, Fog, FogExp2, Group, InstancedMesh, Line, LineSegments, Mesh,
193 Payload, Points, QuadMesh, Scene, SceneFog, Sprite,
194};
195pub use renderer::{
196 depth_pass, pass, BuildCounts, CameraRef, ComputeCounts, CubeRenderTarget,
197 DirectRenderPipeline, Info, MemoryCounts, PassNode, RenderCounts, RenderPipeline, RenderTarget,
198 Renderer, RendererParameters, SceneRef, SsaaPassNode, BACKENDS,
199};
200pub use textures::{
201 CubeTexture, Data3DTexture, DepthTexture, Mapping, MinFilter, Texture, TextureFilter,
202 TextureType,
203};