Skip to main content

Crate nsi_intermediate

Crate nsi_intermediate 

Source
Expand description

A renderer-agnostic intermediate representation for the Nodal Scene Interface – ɴsɪ.

ɴsɪ is the front end and a renderer is the back end; this is what sits between them. It does the jobs an IR does – capture the incoming calls, classify and canonicalise them, lower ɴsɪ’s graph semantics into flat facts a renderer can consume, and serialise the result for inspection.

Nothing here is specific to any one renderer, and none of it needs a renderer present to build or test.

It does need libclang to build: the dependency chain reaches nsi-sys, whose build script runs bindgen over ɴsɪ’s header unconditionally. That is a build-host requirement, not a runtime one – no renderer has to be installed – but a machine without libclang fails there rather than here.

Backends consume a lowered scene and flush it into their own representation: nsi-mitsuba into Mitsuba Properties, nsi-moonray into scene_rdl2 SceneObjects.

§Naming

The crate is spelled out in full so the name says what it is. Consumers who prefer the shorter idiom may alias it:

ⓘ
use nsi_intermediate as nsi_ir;

§Writing a backend

Record with Recorder, which implements nsi_trait::Nsi, then ask the Scene for facts rather than walking it yourself:

use nsi_intermediate::{Recorder, ResolveError};
use nsi_trait::Nsi;

let recorder = Recorder::new();

// Any generic ɴsɪ consumer drives this; a renderer would too.
recorder.create("mesh", "mesh", None)?;
recorder.create("attr", "attributes", None)?;
recorder.create("metal", "shader", None)?;
recorder.connect("mesh", None, ".root", "objects", None)?;
recorder.connect("attr", None, "mesh", "geometryattributes", None)?;
recorder.connect("metal", None, "attr", "surfaceshader", None)?;

let scene = recorder.into_scene(); // or `scene()` to borrow it.

for output in scene.render_outputs() {
    // One entry per screen, with its layers and drivers in order.
    let _ = (&output.camera, &output.layers);
}

let meshes: Vec<String> = scene
    .nodes()
    .filter(|(_, node)| node.node_type() == "mesh")
    .map(|(handle, _)| handle.to_string())
    .collect();

for handle in &meshes {
    // Material, gathered along the whole path to `.root`.
    if let Some(binding) = scene.geometry_binding(handle)? {
        assert_eq!(binding.surface_shader.as_deref(), Some("metal"));
        // `binding.attributes` is every `attributes` node on the
        // path, in ɴsɪ's precedence order: take the first that
        // defines the attribute you want.
        assert_eq!(binding.attributes, vec!["attr".to_string()]);
    }

    // Transform, at whatever times the backend samples. Use the
    // *interpolating* accessor: `world_transform_samples` answers
    // only where every node on the chain has a sample at exactly
    // that time, and refuses a chain whose nodes are sampled at
    // different times -- a scene 3Delight renders.
    let times = scene.motion_times(handle)?;
    let matrices: Vec<(f64, [f64; 16])> = if times.is_empty() {
        vec![(0.0, scene.world_transform(handle)?)]
    } else {
        times
            .iter()
            .map(|&t| {
                Ok((t, scene.world_transform_interpolated_at(handle, t)?))
            })
            .collect::<Result<_, nsi_intermediate::ResolveError>>()?
    };
    assert_eq!(matrices.len(), 1);
}

A geometry with more than one objects parent is ɴsɪ’s lightweight instancing and has no single transform or binding. Use Scene::placements (or Scene::placements_at when it moves), which returns one entry per path with the transform and the binding resolved along it, and agrees with the single-answer accessors when there is only one path. Its binding.attributes is a list of nodes; Scene::attribute_value_along applies ɴsɪ’s precedence to one attribute along that same path.

Borrowing the scene while recording is possible but narrow: Recorder::scene holds the lock every nsi_trait::Nsi method takes, so two of those calls in one expression deadlock. When recording is finished, Recorder::into_scene hands the scene over without copying it.

§Output formats

ɴsɪ has three front ends, and this crate can write two of them back out. Both are optional, so a backend that only wants the resolver pays for neither.

FeatureWhat it adds
(none)write_stream – the .nsi stream, ɴsɪ’s own text format.
luawrite_lua – the same scene as a Lua script.
gzipCompression::Gzip for write_stream_with.
zstdCompression::Zstd.

The stream writer is unconditional because it is also this crate’s verification backbone: the fidelity gate compares it against what 3Delight writes for the same calls.

Compression is a property of the file, not of the format – 3Delight reads a compressed stream wherever it reads a plain one – so it is a parameter of write_stream_with rather than a separate emitter.

Lua is not merely another spelling of the stream. ɴsɪ’s Lua binding exposes fewer types than its C API: there is no nsi.TypeDouble, no nsi.TypeInt64 and no pointer type. An attribute Lua cannot express is refused with a LuaError::Inexpressible rather than degraded, because emitting it untyped silently turns a double into a float and a large integer into a different number.

§What it refuses to answer

ɴsɪ permits scenes with no single correct answer, and this crate returns a typed error for each rather than a plausible wrong one: a cycle, a node that never reaches .root, and – from the exact-hit accessors only – a motion-sampled transform asked for at a time it has no sample at.

A node with two objects parents is refused by the single-answer accessors for the same reason, because there is no single answer; Scene::placements enumerates them instead.

Interpolation is available and is the renderer’s own model, not a guess: Scene::world_transform_interpolated_at interpolates element-wise, which is what 3Delight does – its rotation blur fits component-wise far better than slerp – and holds the end sample outside the sampled range, as 3Delight holds it. An earlier version of this section said nothing here interpolates and that the decomposition was the backend’s; both stopped being true several releases of this crate ago.

§What it does not resolve

Shader networks are classified and carried with their ports intact, because their consumer is OSL rather than a graph walk. evaluate is a no-op: procedurals and Lua imply an execution model this surface does not define, and a stream carrying Evaluate records as a scene without whatever it would have produced, silently.

Asking an instancing prototype for a world transform is ResolveError::Instanced, because ɴsɪ gives an instances node one matrix per instance rather than one for the prototype – ask Scene::instance_transforms, or Scene::instance_transforms_at when the instancer is animated. Lightweight instancing (a node under two parents) is expanded, by Scene::placements; an earlier version of this section said it was refused and not expanded, which was true only before that method existed.

§The ɴsɪ copy contract

Every ɴsɪ argument except a NSIType pointer (Type::Reference) is copied during the call, so a caller may free its data as soon as the call returns. The recorder copies for the same reason a renderer does; it introduces no cost that a live context would not have paid. Reference is the exception: it is passed through and retained, which is why its pointee must outlive the recorder – see Recorder for why that is a 'static bound rather than a lifetime parameter.

Structs§

Affected
What a Changes batch may have moved.
AttributeValue
The winning definition of one attribute, gathered along a path.
Binding
What an ɴsɪ attributes node resolves to for one piece of geometry.
Changes
What changed since the last Scene::take_changes.
Edge
A recorded, classified connection.
Face
One face: an outer perimeter, and one perimeter per hole.
Faces
The faces of a mesh, in order.
HostPointer
A raw host address recorded from an ɴsɪ Reference argument.
Instance
One instance an instances node places.
InstanceRef
One instance, borrowing the matrix the scene already holds.
Instances
The instances of one instances node, borrowed.
LuaWriter
An Nsi sink that writes each call straight to a Lua script.
Node
One ɴsɪ node.
OutputLayer
One AOV, resolved: what to output, how to encode it, and where it goes.
OwnedArgument
A recorded ɴsɪ argument.
Placement
One placement of a geometry in the scene.
PrimitiveVariable
One primitive variable, resolved against its primitive.
Recorder
Records an ɴsɪ scene without rendering it.
RenderOutput
One renderable output: a camera paired with a screen, and the AOVs written from it. Eq and Hash are absent for the reason OwnedArgument’s are (research D7): a layer carries filter_width, and a float has no total equality to derive one from.
Scene
The recorded scene graph.
StreamWriter
An Nsi sink that writes each call straight to a .nsi stream.
WorldTransforms
Every node under .root, with the world transform composed on the way down.

Enums§

Compression
How a written ɴsɪ stream is compressed.
EdgeKind
What an ɴsɪ connection means, once classified.
Interpolation
How a primitive variable’s values map onto a primitive.
LuaError
Why a scene could not be written as a Lua script.
OwnedData
An ɴsɪ argument’s payload, owned.
RecordError
Why an ɴsɪ call could not be recorded.
RenderState
Where the render is in its lifecycle.
ResolveError
Why a scene could not be resolved into flat facts.
Sampled
What ɴsɪ’s typing rule makes of one attribute’s samples.

Constants§

ALL
ɴsɪ’s wildcard handle and attribute name.
GLOBAL
ɴsɪ’s global-options node handle.
IDENTITY
A 4x4 identity, row-major.
RAY_TYPES
ɴsɪ’s ray types: the suffixes a visibility.<ray> attribute takes.
ROOT
ɴsɪ’s root node handle.

Functions§

classify
Classify a connection by its destination attribute.
is_reserved
Whether handle is one of ɴsɪ’s reserved handles.
write_lua
Write scene as a Lua script.
write_stream
Write scene as an ɴsɪ stream.
write_stream_with
Write scene as an ɴsɪ stream, compressed.