Expand description
A fast reader for ɴsɪ scenes.
nsi-intermediate writes ɴsɪ out; this reads it back. Together they
close the loop: a scene can be captured, inspected, replayed and
round-tripped without a renderer.
§It calls you
Parsing drives nsi_trait::Nsi rather than producing a scene type
of its own, so the same parser feeds a live 3Delight context, an
nsi-intermediate Recorder, or a backend’s own implementation. A
reader that insisted on its own representation would make every
consumer translate.
A sink brings its own behaviour, not its own argument type: every
entry point here binds Nsi<Arg<'call> = nsi_ffi_wrap::Arg<'call, 'static>>, because the parser has to build the arguments it hands
over and can only build the one shape. Implement nsi_trait::Nsi
with that associated type and the parser will drive it.
let bytes = std::fs::read("scene.nsi")?;
let recorder = nsi_intermediate::Recorder::new();
parse_stream(&bytes, &recorder)?;§The grammar is observed, not specified
ɴsɪ publishes no grammar for its stream, only examples. This parser is written against what 3Delight accepts, and the decisive observation is that an entire scene on one line parses: the newlines and indents a renderer writes are formatting, not syntax. So a parameter list runs until the next bare token naming a statement – parameter names are always quoted, which makes that unambiguous – and a line-oriented reader would be wrong on valid input.
§Paths are carried verbatim
A string value may hold a ${VAR} reference – ɴsɪ’s
streampathreplacement writes them so a scene can move between
machines – and this parser does not expand them. Rendered,
that is what 3Delight does too: renderdl -cat echoes
${NSI_PATH_TEST}/out.exr back unexpanded, while a render whose
imagefilename holds it writes to the expanded path. Expansion
happens at use, in whatever opens the file.
Expanding here would bake one machine’s paths into a stream whose
purpose is to move between them. The obligation is the consumer’s:
open a path without expanding and you open the wrong file, on
exactly the machines where the variable was meant to matter. Note
that any variable expands, not only NSI_PATH_-prefixed ones;
the prefix governs only which ones 3Delight writes as
references.
§Features
| Feature | What it adds |
|---|---|
| (none) | The .nsi stream reader. |
lua | Reading a Lua scene, which runs the script. Builds Lua 5.4 from vendored C source. |
gzip | Reading a gzip-compressed stream. |
zstd | Reading a zstd-compressed stream. |
parallel | parse_stream_parallel: reading and applying a stream on every core. |
Reading a Lua scene means executing it. ɴsɪ’s Lua front end is a programming language – a script may compute the scene it describes – so an interpreter is the only correct reader, and that is a different trust decision from parsing a data file.
Enums§
- Error
- Why a scene could not be read.
Functions§
- parse_
compressed - Read an ɴsɪ stream that may be compressed, applying it to
sink. - parse_
stream - Read an ɴsɪ stream, applying it to
sink. - parse_
stream_ parallel - Read an ɴsɪ stream on every core, applying it to
sink. - run_lua
- Run
source, applying the ɴsɪ calls it makes tosink.