Expand description
Nodal Scene Interface – ɴsɪ
A flexible, modern API for offline 3D renderers
Nsɪ is built around the concept of nodes. Each node has a unique handle to identify it. It also has a type which describes its intended function in the scene.
Nodes are abstract containers for data. The interpretation depends on the node type. Nodes can also be connected to each other to express relationships.
Data is stored on nodes as attributes. Each attribute has a name which is unique on the node and a type which describes the kind of data it holds (strings, integer numbers, floating point numbers, etc).
Relationships and data flow between nodes are represented as connections. Connections have a source and a destination. Both can be either a node or a specific attribute of a node. There are no type restrictions for connections in the interface itself. It is acceptable to connect attributes of different types or even attributes to nodes. The validity of such connections depends on the types of the nodes involved.
What we refer to as the ɴsɪ has two major components:
-
Methods to create nodes, attributes and their connections. These are attached to a rendering
Context
. -
Nodes understood by the renderer.
Much of the complexity and expressiveness of the interface comes from the supported nodes.
The first part was kept deliberately simple to make it easy to support multiple ways of creating nodes.
Examples
// Create a context to send the scene to.
let ctx = nsi::Context::new(None).expect("Could not create NSI context.");
// Create a dodecahedron.
// 12 regular pentagon faces.
let face_index: [i32; 60] = [
0, 16, 2, 10, 8, 0, 8, 4, 14, 12, 16, 17, 1, 12, 0, 1, 9, 11, 3, 17, 1,
12, 14, 5, 9, 2, 13, 15, 6, 10, 13, 3, 17, 16, 2, 3, 11, 7, 15, 13, 4,
8, 10, 6, 18, 14, 5, 19, 18, 4, 5, 19, 7, 11, 9, 15, 7, 19, 18, 6,
];
// Golden ratio.
let phi: f32 = 0.5 * (1.0 + 5_f32.sqrt());
// Golden ratio conjugate.
let phi_c: f32 = phi - 1.0;
// 20 points @ 3 vertices.
let positions: [f32; 60] = [
1., 1., 1., 1., 1., -1., 1., -1., 1., 1., -1., -1., -1., 1., 1., -1.,
1., -1., -1., -1., 1., -1., -1., -1., 0., phi_c, phi, 0., phi_c, -phi,
0., -phi_c, phi, 0., -phi_c, -phi, phi_c, phi, 0., phi_c, -phi, 0.,
-phi_c, phi, 0., -phi_c, -phi, 0., phi, 0., phi_c, phi, 0., -phi_c,
-phi, 0., phi_c, -phi, 0., -phi_c,
];
// Create a new mesh node and call it 'dodecahedron'.
ctx.create("dodecahedron", nsi::MESH, None);
// Connect the 'dodecahedron' node to the scene's root.
ctx.connect("dodecahedron", None, nsi::ROOT, "objects", None);
// Define the geometry of the 'dodecahedron' node.
ctx.set_attribute(
"dodecahedron",
&[
nsi::points!("P", &positions),
nsi::integers!("P.indices", &face_index),
// 5 vertices per each face.
nsi::integers!("nvertices", &[5; 12]),
// Render this as a subdivison surface.
nsi::string!("subdivision.scheme", "catmull-clark"),
// Crease each of our 30 edges a bit.
nsi::integers!("subdivision.creasevertices", &face_index),
nsi::floats!("subdivision.creasesharpness", &[10.; 30]),
],
);
More Examples
These can be found in the examples
folder.
All the examples in this crate require a (free) 3Delight installation to run!
Interactive
Demonstrates using the FnStatus
callback closure during rendering and a
channel for communicating between main- and rendering thread(s).
Jupyter
Render directly into a Jupyter notebook.
Follow these instructions to get a Rust Jupyter kernel up and running first.
Output
This is a full output
example showing color conversion and writing data
out to 8bit/channel PNG and 32bit/channel (float) OpenEXR formats.
Volume
Demonstrates rendering an OpenVDB asset. Mostly
through the toolbelt
helpers.
Getting Pixels
The crate has support for streaming pixels from the renderer, via callbacks
(i.e. closures) during and/or after rendering via the output
module.
This module is enabled through the feature of the same name (see below).
It should be straightforward to create an async
implementation with this
or use channels to stream pixels back to a main thread (see the
interactive
example).
Cargo Features
-
output
– Add support for streaming pixels from the renderer to the calling context via closures. -
jupyter
– Add support for rendering to Jupyter notebooks (when using a Rust Jupyter kernel). -
toolbelt
– Add convenience methods that work with aContext
. -
delight
– Add some nodes & shaders specifi to 3Delight. -
nightly
– Enable some unstable features (suggested if you build with anightly
toolchain) -
ustr_handles
– useustr
for node handles. This will give a you a speed boost if your node names aren’t changing while an app using ɴsɪ is running but is not advised otherwise (ustr
are never freed).
Linking Style
The 3Delight dynamic library (lib3delight
) can either be linked to during
build or loaded at runtime.
By default the lib is loaded at runtime.
-
Load
lib3deligh
at runtime (default). This has several advantages:-
If you ship your application or library you can ship it without the library. It can still run and will print an informative error if the library cannot be loaded.
-
A user can install an updated version of the renderer and stuff will ‘just work’.
-
-
Dynamically link against
lib3delight
.-
lib3delight
becomes a dependency. If it cannot be found your lib/app will not load/start. -
The feature is called
link_lib3delight
. -
You should disable default features (they are not needed/used) in this case:
[dependencies] nsi = { version = "0.7", default-features = false, features = ["link_lib3delight"] }
-
-
Download
lib3delight
during build.-
lib3delight
is downloaded during build. Note that this may be an outdated version. This feature mainly exists for CI purposes. -
The feature is called
download_lib3delight
.
-
Modules
- Optional arguments passed to methods of an ɴsɪ context.
- An ɴsɪ context.
- Helpers for using ɴsɪ with 3Delight.
- Jupyter Notebook support.
- Standard ɴsɪ node types.
- output
output
Output driver callbacks. - Convenience methods for an ɴsɪ context.
Macros
- Create a
Callback
argument. - Create a
Color
argument. - Create a
Colors
array argument. - Create a
Double
precision argument. - Create a
DoubleMatrices
row-major, 4×4 transformation matrices argument. Each matrix is given as 16f64
values. - Create a
DoubleMatrix
row-major, 4×4 transformation matrix argument. The matrix is given as 16f64
values. - Create a
Doubles
precision array argument. - Create a
Float
argument. - Create a
Floats
array argument. - Create a
Integer
argument. - Create a
Integers
array argument. - Create a
Normal
argument. - Create a
Normals
array argument. - Create a
Point
argument. - Create a
Points
array argument. - Create a
Reference
argument. - Create a
Reference
array argument. - Create a
String
argument. - Create a
String
array argument. - Create a
Vector
argument. - Create a
Vectors
array argument.
Structs
- An (optional) argument passed to a method of
Context
. - See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - An ɴꜱɪ Context.
- See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - Wrapper to pass an
FnFinish
closure to anOutputDriver
node. - See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - Description of an
OutputLayer
node inside a flat, raw pixel. - See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - Wrapper to pass an
FnOpen
closure to anOutputDriver
node. - See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - See
ArgData
for details. - Wrapper to pass an
FnWrite
closure to anOutputDriver
node.
Enums
- The render action to perform when calling
render_control()
. - A variant describing data passed to the renderer.
- An error type the callbacks return to communicate with the renderer.
- The depth (number and type of channels) a pixel in a
Layer
is composed of. - The status of a interactive render session.
Constants
- Wildcard node that references all existing nodes at once (
.all
). - Container for generic attributes (e.g. visibility). Documentation.
- Linear, b-spline and Catmull-Rom curves. Documentation.
- A cylindrical camera. Documentation.
- Geometry type to define environment lighting. Documentation.
- Assign attributes to part of a mesh, curves or particles. Documentation.
- A fisheye camera. Documentation.
- Global settings node (
.global
). Documentation. - Specifies instances of other nodes. Documentation.
- Polygonal mesh or subdivision surface. Documentation.
- An orthographic camera. Documentation.
- A target where to output rendered pixels. Documentation.
- Describes one render layer to be connected to an
outputdriver
node. Documentation. - Collection of particles. Documentation.
- A perspective camera. Documentation.
- An infinite plane. Documentation.
- Geometry to be loaded or generated in delayed fashion. Documentation.
- The scene’s root (
.root
). Documentation. - Describes how the view from a camera node will be rasterized into an
outputlayer
node. Documentation. - Expresses relationships of groups of nodes. Documentation.
- ᴏsʟ shader or layer in a shader group. Documentation.
- A spherical camera. Documentation.
- Transformation to place objects in the scene. Documentation.
- A volume loaded from an OpenVDB file. Documentation.
Statics
- This is the name of the crate’s built-in output driver that understands the “closure.*” attributes.
Traits
- A closure which is called to inform about the errors during scene defintion or a render.
- A closure which is called once per
OutputDriver
instance. - A closure which is called once per
OutputDriver
instance. - A closure which is called to inform about the status of an ongoing render.
- A closure which is called for each bucket of pixels the
OutputDriver
instance sends during rendering.