nsi_intermediate/lib.rs
1//! A renderer-agnostic intermediate representation for the
2//! [Nodal Scene Interface](https://nsi.readthedocs.io/) -- ɴsɪ.
3//!
4//! ɴsɪ is the front end and a renderer is the back end; this is what
5//! sits between them. It does the jobs an IR does -- capture the
6//! incoming calls, classify and canonicalise them, lower ɴsɪ's graph
7//! semantics into flat facts a renderer can consume, and serialise the
8//! result for inspection.
9//!
10//! Nothing here is specific to any one renderer, and none of it needs a
11//! renderer present to build or test.
12//!
13//! It does need **libclang** to build: the dependency chain reaches
14//! `nsi-sys`, whose build script runs `bindgen` over ɴsɪ's header
15//! unconditionally. That is a build-host requirement, not a runtime
16//! one -- no renderer has to be installed -- but a machine without
17//! libclang fails there rather than here.
18//!
19//! Backends consume a lowered scene and flush it into their own
20//! representation: [`nsi-mitsuba`] into Mitsuba `Properties`,
21//! [`nsi-moonray`] into `scene_rdl2` `SceneObject`s.
22//!
23//! # Naming
24//!
25//! The crate is spelled out in full so the name says what it is.
26//! Consumers who prefer the shorter idiom may alias it:
27//!
28//! ```ignore
29//! use nsi_intermediate as nsi_ir;
30//! ```
31//!
32//! [`nsi-mitsuba`]: https://github.com/virtualritz/nsi-mitsuba
33//! [`nsi-moonray`]: https://github.com/virtualritz/nsi-moonray
34//!
35//! # Writing a backend
36//!
37//! Record with [`Recorder`], which implements [`nsi_trait::Nsi`], then
38//! ask the [`Scene`] for facts rather than walking it yourself:
39//!
40//! ```
41//! use nsi_intermediate::{Recorder, ResolveError};
42//! use nsi_trait::Nsi;
43//!
44//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
45//! let recorder = Recorder::new();
46//!
47//! // Any generic ɴsɪ consumer drives this; a renderer would too.
48//! recorder.create("mesh", "mesh", None)?;
49//! recorder.create("attr", "attributes", None)?;
50//! recorder.create("metal", "shader", None)?;
51//! recorder.connect("mesh", None, ".root", "objects", None)?;
52//! recorder.connect("attr", None, "mesh", "geometryattributes", None)?;
53//! recorder.connect("metal", None, "attr", "surfaceshader", None)?;
54//!
55//! let scene = recorder.into_scene(); // or `scene()` to borrow it.
56//!
57//! for output in scene.render_outputs() {
58//! // One entry per screen, with its layers and drivers in order.
59//! let _ = (&output.camera, &output.layers);
60//! }
61//!
62//! let meshes: Vec<String> = scene
63//! .nodes()
64//! .filter(|(_, node)| node.node_type() == "mesh")
65//! .map(|(handle, _)| handle.to_string())
66//! .collect();
67//!
68//! for handle in &meshes {
69//! // Material, gathered along the whole path to `.root`.
70//! if let Some(binding) = scene.geometry_binding(handle)? {
71//! assert_eq!(binding.surface_shader.as_deref(), Some("metal"));
72//! // `binding.attributes` is every `attributes` node on the
73//! // path, in ɴsɪ's precedence order: take the first that
74//! // defines the attribute you want.
75//! assert_eq!(binding.attributes, vec!["attr".to_string()]);
76//! }
77//!
78//! // Transform, at whatever times the backend samples. Use the
79//! // *interpolating* accessor: `world_transform_samples` answers
80//! // only where every node on the chain has a sample at exactly
81//! // that time, and refuses a chain whose nodes are sampled at
82//! // different times -- a scene 3Delight renders.
83//! let times = scene.motion_times(handle)?;
84//! let matrices: Vec<(f64, [f64; 16])> = if times.is_empty() {
85//! vec![(0.0, scene.world_transform(handle)?)]
86//! } else {
87//! times
88//! .iter()
89//! .map(|&t| {
90//! Ok((t, scene.world_transform_interpolated_at(handle, t)?))
91//! })
92//! .collect::<Result<_, nsi_intermediate::ResolveError>>()?
93//! };
94//! assert_eq!(matrices.len(), 1);
95//! }
96//! # Ok(())
97//! # }
98//! ```
99//!
100//! A geometry with more than one `objects` parent is ɴsɪ's lightweight
101//! instancing and has no single transform or binding. Use
102//! [`Scene::placements`] (or [`Scene::placements_at`] when it moves),
103//! which returns one entry per path with the transform *and* the
104//! binding resolved along it, and agrees with the single-answer
105//! accessors when there is only one path. Its `binding.attributes` is a
106//! list of nodes; [`Scene::attribute_value_along`] applies ɴsɪ's
107//! precedence to one attribute along that same path.
108//!
109//! Borrowing the scene while recording is possible but narrow:
110//! [`Recorder::scene`] holds the lock every [`nsi_trait::Nsi`] method
111//! takes, so two of those calls in one expression deadlock. When
112//! recording is finished, [`Recorder::into_scene`] hands the scene over
113//! without copying it.
114//!
115//! # Output formats
116//!
117//! ɴsɪ has three front ends, and this crate can write two of them back
118//! out. Both are optional, so a backend that only wants the resolver
119//! pays for neither.
120//!
121//! | Feature | What it adds |
122//! | --- | --- |
123//! | *(none)* | [`write_stream`] -- the `.nsi` stream, ɴsɪ's own text format. |
124//! | `lua` | `write_lua` -- the same scene as a Lua script. |
125//! | `gzip` | `Compression::Gzip` for [`write_stream_with`]. |
126//! | `zstd` | `Compression::Zstd`. |
127//!
128//! The stream writer is unconditional because it is also this crate's
129//! verification backbone: the fidelity gate compares it against what
130//! 3Delight writes for the same calls.
131//!
132//! Compression is a property of the *file*, not of the format --
133//! 3Delight reads a compressed stream wherever it reads a plain one --
134//! so it is a parameter of [`write_stream_with`] rather than a separate
135//! emitter.
136//!
137//! Lua is not merely another spelling of the stream. ɴsɪ's Lua binding
138//! exposes fewer types than its C API: there is no `nsi.TypeDouble`, no
139//! `nsi.TypeInt64` and no pointer type. An attribute Lua cannot express
140//! is refused with a `LuaError::Inexpressible` rather than degraded,
141//! because emitting it untyped silently turns a double into a float and
142//! a large integer into a different number.
143//!
144//! # What it refuses to answer
145//!
146//! ɴsɪ permits scenes with no single correct answer, and this crate
147//! returns a typed error for each rather than a plausible wrong one: a
148//! cycle, a node that never reaches `.root`, and -- from the
149//! *exact-hit* accessors only -- a motion-sampled transform asked for
150//! at a time it has no sample at.
151//!
152//! A node with two `objects` parents is refused by the single-answer
153//! accessors for the same reason, because there is no single answer;
154//! [`Scene::placements`] enumerates them instead.
155//!
156//! Interpolation is available and is the renderer's own model, not a
157//! guess: [`Scene::world_transform_interpolated_at`] interpolates
158//! element-wise, which is what 3Delight does -- its rotation blur fits
159//! component-wise far better than slerp -- and holds the end sample
160//! outside the sampled range, as 3Delight holds it. An earlier version
161//! of this section said nothing here interpolates and that the
162//! decomposition was the backend's; both stopped being true several
163//! releases of this crate ago.
164//!
165//! # What it does not resolve
166//!
167//! Shader networks are classified and carried with their ports intact,
168//! because their consumer is OSL rather than a graph walk. `evaluate`
169//! is a no-op: procedurals and Lua imply an execution model this
170//! surface does not define, and a stream carrying `Evaluate` records as
171//! a scene without whatever it would have produced, silently.
172//!
173//! Asking an instancing *prototype* for a world transform is
174//! [`ResolveError::Instanced`], because ɴsɪ gives an `instances` node
175//! one matrix per instance rather than one for the prototype -- ask
176//! [`Scene::instance_transforms`], or
177//! [`Scene::instance_transforms_at`] when the instancer is animated.
178//! Lightweight instancing (a node under two parents) *is* expanded, by
179//! [`Scene::placements`]; an earlier version of this section said it
180//! was refused and not expanded, which was true only before that method
181//! existed.
182//!
183//! # The ɴsɪ copy contract
184//!
185//! Every ɴsɪ argument except a `NSIType` pointer (`Type::Reference`) is
186//! copied during the call, so a caller may free its data as soon as the
187//! call returns. The recorder copies for the same reason a renderer
188//! does; it introduces no cost that a live context would not have paid.
189//! `Reference` is the exception: it is passed through and retained,
190//! which is why its pointee must outlive the recorder -- see
191//! [`Recorder`] for why that is a `'static` bound rather than a
192//! lifetime parameter.
193
194#![deny(missing_docs)]
195
196/// ɴsɪ's root node handle.
197pub const ROOT: &str = ".root";
198
199/// ɴsɪ's global-options node handle.
200///
201/// Reserved like [`ROOT`]: it need not be created.
202pub const GLOBAL: &str = ".global";
203
204/// Whether `handle` is one of ɴsɪ's reserved handles.
205///
206/// ɴsɪ: `.root` and `.global` "don't need to be created using
207/// NSICreate". They carry attributes and connections like any node, but
208/// a stream never declares them.
209pub fn is_reserved(handle: &str) -> bool {
210 handle == ROOT || handle == GLOBAL
211}
212
213/// ɴsɪ's wildcard handle and attribute name.
214///
215/// `NSIDisconnect` accepts it for either node handle and for either
216/// attribute name, matching everything in that position.
217pub const ALL: &str = ".all";
218
219mod edge;
220mod error;
221mod handle;
222#[cfg(feature = "lua")]
223mod lua;
224mod owned;
225mod recorder;
226mod resolve;
227mod scene;
228mod stream;
229
230/// The crate's hash map, hashed by `ahash`.
231///
232/// `std`'s `SipHash` is chosen to resist collision attacks on
233/// adversarial input. A recorded scene is not adversarial input, and
234/// the keys here are handles hashed on every edge walk, so the trade
235/// is the wrong way round.
236pub(crate) type HashMap<K, V> = ahash::AHashMap<K, V>;
237
238/// The crate's hash set, hashed by `ahash`. See [`HashMap`].
239pub(crate) type HashSet<T> = ahash::AHashSet<T>;
240
241pub use edge::{Edge, EdgeKind, classify};
242pub use error::RecordError;
243#[cfg(feature = "lua")]
244pub use lua::{LuaError, LuaWriter, write_lua};
245pub use owned::{HostPointer, OwnedArgument, OwnedData};
246pub use recorder::{Recorder, RenderState};
247pub use resolve::{
248 AttributeValue, Binding, Face, Faces, IDENTITY, Instance, InstanceRef,
249 Instances, Interpolation, OutputLayer, Placement, PrimitiveVariable,
250 RAY_TYPES, RenderOutput, ResolveError, Sampled, WorldTransforms,
251};
252pub use scene::{Affected, Changes, Node, Scene};
253pub use stream::{Compression, StreamWriter, write_stream, write_stream_with};