nsi-intermediate 0.1.0

Renderer-agnostic intermediate representation for the Nodal Scene Interface – ɴsɪ.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
//! Owned mirrors of borrowed ɴsɪ arguments.
//!
//! The recorder outlives the calls that feed it, so it cannot hold a
//! borrowed `Arg`. [`OwnedArgument`] copies the payload out.
//!
//! This mirrors the ɴsɪ C API's own contract: every argument except a
//! `NSIType` pointer is copied during the call, so a caller may free its
//! data the moment the call returns. Copying here is therefore not an
//! extra cost the recorder introduces -- it is what a live renderer would
//! have done anyway.
//!
//! [`OwnedData::Reference`] is the exception, and holds a raw pointer
//! rather than a copy, because that is what ɴsɪ passes through.

use core::{
    ffi::{CStr, c_char, c_void},
    slice,
};
use nsi_ffi_wrap::{Arg, nsi_sys::NSIParamFlags};
use nsi_trait::{ParamValue, Type};

/// A raw host address recorded from an ɴsɪ `Reference` argument.
///
/// # Safety
///
/// `Send` and `Sync` are asserted on two grounds, both structural
/// rather than hopeful:
///
/// 1. **The recorder never dereferences it.** A `HostPointer` is stored on
///    the way in and handed back on the way out, nothing else. No data
///    race is possible through a pointer that is never read.
/// 2. **The pointee outlives everything.** The recorder's `Nsi` impl
///    declares `Arg<'call, 'static>`, so the only `Reference` it can be
///    handed is one whose data is `'static`. That is the same rule
///    `nsi-ffi-wrap` applies -- `Reference`, `Callback` and
///    `ReferenceSlice` are `Send`/`Sync` at `'static` and nowhere else.
///
/// The assertion lives on this newtype rather than on `Recorder` so it
/// covers exactly the field that needs it. A blanket
/// `unsafe impl Send for Recorder` would silently keep covering any
/// non-`Send` field added later.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(transparent)]
pub struct HostPointer(pub *const c_void);

// SAFETY: see the type's documentation.
unsafe impl Send for HostPointer {}
// SAFETY: see the type's documentation.
unsafe impl Sync for HostPointer {}

/// An ɴsɪ argument's payload, owned.
///
/// Variants are storage representations, not ɴsɪ types: colour, point,
/// vector, normal and 4x4 `f32` matrices all live in [`OwnedData::F32`]
/// and are told apart by [`OwnedArgument::type_tag`].
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub enum OwnedData {
    /// `f32` scalars, flattened. Also holds colour, point, vector,
    /// normal and 4x4 `f32` matrices; [`OwnedArgument::type_tag`] tells them
    /// apart.
    F32(Vec<f32>),
    /// `f64` scalars, flattened. Also holds 4x4 `f64` matrices.
    F64(Vec<f64>),
    /// 32-bit integers.
    I32(Vec<i32>),
    /// 64-bit integers.
    I64(Vec<i64>),
    /// Strings, copied out of their C representation.
    ///
    /// **Bytes, not `String`.** An ɴsɪ string is whatever the C API was
    /// handed. 3Delight writes a byte at or above `0x7f` raw and reads
    /// it back unchanged, and a file name on Linux is not required to be
    /// UTF-8 -- so an `imagefilename` naming `café.exr` in Latin-1 is a
    /// value this crate must carry, not one it may repair. Storing
    /// `String` here replaced the byte with U+FFFD at *recording* time,
    /// which no amount of care at replay could undo.
    ///
    /// Use `String::from_utf8_lossy` where text is wanted.
    ///
    /// # A path value may need expanding
    ///
    /// ɴsɪ streams carry `${VAR}` references so a scene can move between
    /// machines, and 3Delight expands them **when it uses the value**,
    /// not when it reads the stream. A backend that opens a path from
    /// here without expanding opens the wrong file -- and only on the
    /// machines where the variable mattered, which is when it is hardest
    /// to diagnose.
    ///
    /// The rules, measured rather than inferred, because each one
    /// changes what a backend must implement:
    ///
    /// - **`${NAME}` only.** A bare `$NAME` is left alone: a probe
    ///   naming `$VAR/x.exr` created a literal `$VAR` directory.
    /// - **Path-valued attributes only.** `imagefilename`,
    ///   `shaderfilename` and `Evaluate`'s `filename` expand, and nest
    ///   (`${A}/${B}`). `drivername` does **not** -- it fails with
    ///   `E6024 cannot find display driver '${...}'` -- nor does a node
    ///   handle (`E6087 unknown node handle`), nor an attribute *name*,
    ///   which is silently ignored.
    /// - **Any variable, not just `NSI_PATH_`.** `${HOME}` expands. That
    ///   prefix governs which variables 3Delight *writes* as references
    ///   under `streampathreplacement`; on read it means nothing.
    /// - **An unset variable stays literal**, rather than expanding to
    ///   empty or erroring: a probe created a literal `${MISSING}`
    ///   directory.
    ///
    /// One trap worth naming: `${...}` in an output layer's
    /// `variablename` **segfaults** 3Delight 2.9.207. Do not pass one
    /// through to a renderer expecting a diagnostic.
    ///
    /// See `specs/004` research Q1.
    String(Vec<Vec<u8>>),
    /// Raw host pointers. ɴsɪ calls this `Reference` (`Pointer` in the C
    /// API); it is not an object link and is never forwarded to a
    /// renderer as one. Stored so output-driver callbacks survive a
    /// replay. The recorder never dereferences these.
    Reference(Vec<HostPointer>),
}

/// A recorded ɴsɪ argument.
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub struct OwnedArgument {
    /// The attribute name this argument sets.
    pub name: String,
    /// The ɴsɪ type, which is what tells one [`OwnedData`] layout from
    /// another sharing the same storage.
    pub type_tag: Type,
    /// ɴsɪ's `array_len`. The C `count` field is `len/array_length`.
    pub array_length: usize,
    /// ɴsɪ's argument flags: `per_vertex`, `per_face` and the like.
    /// Replayed as the letter prefix 3Delight writes -- `"v point"`,
    /// `"f float"`, `"vl float"`; see `contracts/stream.md`.
    pub flags: i32,
    /// The payload, copied unless it is a pointer.
    pub data: OwnedData,
}

impl OwnedArgument {
    /// One recorded argument, built by hand.
    ///
    /// [`Scene::set_attribute`](crate::Scene::set_attribute) and its
    /// timed twin take these, and the struct is `#[non_exhaustive]` so
    /// that a later field is not a breaking change -- which also means
    /// a struct literal will not compile outside this crate. Without
    /// this, half of `Scene`'s public surface could only ever be
    /// handed an empty vector.
    pub fn new(
        name: impl Into<String>,
        type_tag: Type,
        array_length: usize,
        flags: i32,
        data: OwnedData,
    ) -> Self {
        Self {
            name: name.into(),
            type_tag,
            array_length,
            flags,
            data,
        }
    }

    /// The payload as `f32` scalars, or `None` for another layout.
    ///
    /// Colour, point, vector, normal and an `f32` matrix all share this
    /// storage flattened; [`OwnedArgument::type_tag`] tells them apart.
    pub fn as_f32s(&self) -> Option<&[f32]> {
        match &self.data {
            OwnedData::F32(values) => Some(values),
            _ => None,
        }
    }

    /// The payload as `f64` scalars, or `None` for another layout.
    pub fn as_f64s(&self) -> Option<&[f64]> {
        match &self.data {
            OwnedData::F64(values) => Some(values),
            _ => None,
        }
    }

    /// The payload as 32-bit integers, or `None` for another layout.
    pub fn as_i32s(&self) -> Option<&[i32]> {
        match &self.data {
            OwnedData::I32(values) => Some(values),
            _ => None,
        }
    }

    /// The payload as 64-bit integers, or `None` for another layout.
    pub fn as_i64s(&self) -> Option<&[i64]> {
        match &self.data {
            OwnedData::I64(values) => Some(values),
            _ => None,
        }
    }

    /// The payload as strings, or `None` for another layout.
    ///
    /// Bytes, not `str`: see [`OwnedData::String`]. A path may need
    /// `${VAR}` expanding before use.
    pub fn as_strings(&self) -> Option<&[Vec<u8>]> {
        match &self.data {
            OwnedData::String(values) => Some(values),
            _ => None,
        }
    }

    /// A single `f32`, for the common scalar case.
    ///
    /// `None` unless the payload is exactly one `f32`, so a caller
    /// cannot silently read the first component of a colour as a float.
    pub fn as_f32(&self) -> Option<f32> {
        match self.as_f32s() {
            Some([value]) => Some(*value),
            _ => None,
        }
    }

    /// A single `i32`, on the same terms as [`OwnedArgument::as_f32`].
    pub fn as_i32(&self) -> Option<i32> {
        match self.as_i32s() {
            Some([value]) => Some(*value),
            _ => None,
        }
    }

    /// How many *elements* this argument carries.
    ///
    /// Scalars count themselves; a `point` counts triples; an
    /// `array_len(n)` argument counts runs of `n`. This is ɴsɪ's `count`
    /// field, and it is what says whether a primitive variable is one
    /// value per face, per vertex or per face-vertex.
    pub fn element_count(&self) -> usize {
        let per = match self.type_tag {
            Type::Color | Type::Point | Type::Vector | Type::Normal => 3,
            Type::MatrixF32 | Type::MatrixF64 => 16,
            _ => 1,
        };
        let scalars = match &self.data {
            OwnedData::F32(values) => values.len(),
            OwnedData::F64(values) => values.len(),
            OwnedData::I32(values) => values.len(),
            OwnedData::I64(values) => values.len(),
            OwnedData::String(values) => values.len(),
            OwnedData::Reference(values) => values.len(),
        };
        scalars / per / self.array_length.max(1)
    }

    /// A 4x4 `doublematrix`, row-major.
    ///
    /// `None` unless the declared type is [`nsi_trait::Type::MatrixF64`]
    /// with sixteen values: sixteen `double`s are not a `doublematrix`,
    /// and 3Delight refuses that too.
    pub fn as_matrix(&self) -> Option<[f64; 16]> {
        match self.as_matrices()? {
            [] => None,
            values if values.len() == 16 => {
                // SAFETY: the match arm above tested the length, so the
                // slice is exactly the sixteen the array wants.
                Some(values[..16].try_into().expect("length checked"))
            }
            _ => None,
        }
    }

    /// The payload of a `doublematrix` argument, however many.
    ///
    /// **The array suffix is part of the declaration.** ɴsɪ marks an
    /// array with `NSIParamIsArray` rather than by length, and
    /// 3Delight reads `doublematrix[2]` as a different type from
    /// `doublematrix`: rendered, an instancer whose
    /// `transformationmatrices` is declared `"doublematrix[2]" 1` --
    /// or `"doublematrix[1]" 2`, the same values again -- is `E6007`
    /// and **nothing draws**, where the plain `"doublematrix" 2` draws
    /// two copies. Reading the tag alone drew them anyway.
    pub fn as_matrices(&self) -> Option<&[f64]> {
        if self.type_tag != Type::MatrixF64 || self.is_array() {
            return None;
        }
        match &self.data {
            OwnedData::F64(values) => Some(values),
            _ => None,
        }
    }

    /// Whether ɴsɪ's `NSIParamIsArray` is set, which makes the
    /// argument's type `T[n]` rather than `T`.
    pub fn is_array(&self) -> bool {
        self.flags & NSIParamFlags::IsArray.bits() != 0
    }

    /// Copy a borrowed parameter into owned storage.
    ///
    /// `pub(crate)` on purpose. It carried two failure paths that
    /// nothing in this crate can reach -- a panic if `as_c_param`
    /// returned `None`, and an empty `f32` array for `Type::Invalid` --
    /// because [`Recorder`](crate::Recorder)'s `Arg` GAT pins the
    /// parameter to `nsi_ffi_wrap::Arg`, whose `as_c_param` always
    /// returns `Some` and which never produces `Invalid`. Only a
    /// *foreign* `ParamValue` could reach either, and only through this
    /// being public.
    ///
    /// Narrowing it makes both unreachable by construction rather than
    /// by argument, which is cheaper than a `Result` every internal
    /// caller would have to unwrap for a case that cannot arise.
    /// Callers wanting an [`OwnedArgument`] use [`OwnedArgument::new`].
    ///
    /// It takes `Arg` rather than any `ParamValue` for the same reason:
    /// while it stayed generic, "unreachable" rested on nobody in this
    /// crate ever passing something else, which is a habit rather than
    /// a guarantee. Named, the compiler holds it.
    pub(crate) fn from_param(param: &Arg<'_, '_>) -> Self {
        let type_tag = param.type_tag();

        // The C call hands the renderer `count = len/array_length`
        // elements, so a run that does not divide is *dropped there*.
        // Copying `len` outright kept data 3Delight never saw -- and
        // made this crate's own stream fail the count `nsi-parse`
        // checks. Round the element count down the same way the C
        // boundary does.
        let array_length = param.array_length().max(1);
        let elements = param.len() / array_length * array_length;
        let scalars = elements * components_per_element(type_tag);

        // Unreachable while this is `pub(crate)`: the only implementor
        // reaching here is `nsi_ffi_wrap::Arg`, whose `as_c_param`
        // returns `Some` unconditionally.
        // SAFETY: unreachable while this is `pub(crate)` -- the only
        // implementor that reaches here is `nsi_ffi_wrap::Arg`, whose
        // `as_c_param` returns `Some` unconditionally.
        let c = param
            .as_c_param()
            .expect("nsi-ffi-wrap Arg always yields a C view");

        // SAFETY: `c.data` points at `scalars` values of the type named
        // by `type_tag`, valid while `param` lives, which is this call.
        let data = unsafe {
            match type_tag {
                Type::F32
                | Type::Color
                | Type::Point
                | Type::Vector
                | Type::Normal
                | Type::MatrixF32 => OwnedData::F32(
                    slice::from_raw_parts(c.data as *const f32, scalars)
                        .to_vec(),
                ),
                Type::F64 | Type::MatrixF64 => OwnedData::F64(
                    slice::from_raw_parts(c.data as *const f64, scalars)
                        .to_vec(),
                ),
                Type::I32 => OwnedData::I32(
                    slice::from_raw_parts(c.data as *const i32, scalars)
                        .to_vec(),
                ),
                Type::I64 => OwnedData::I64(
                    slice::from_raw_parts(c.data as *const i64, scalars)
                        .to_vec(),
                ),
                Type::String => {
                    let ptrs = slice::from_raw_parts(
                        c.data as *const *const c_char,
                        scalars,
                    );
                    OwnedData::String(
                        ptrs.iter()
                            .map(|p| CStr::from_ptr(*p).to_bytes().to_vec())
                            .collect(),
                    )
                }
                Type::Reference => OwnedData::Reference(
                    slice::from_raw_parts(
                        c.data as *const *const c_void,
                        scalars,
                    )
                    .iter()
                    .map(|p| HostPointer(*p))
                    .collect(),
                ),
                // Also unreachable: `Invalid` is ɴsɪ's C sentinel for
                // "no type" and nothing in this workspace produces it.
                // It used to yield an empty `f32` array, which would
                // have recorded a *different* argument rather than
                // refusing -- the silent wrong answer this crate exists
                // to avoid. If it ever fires, the pinned type has
                // changed and this must be revisited, not patched over.
                Type::Invalid => {
                    unreachable!("nsi-ffi-wrap never yields Type::Invalid")
                }
            }
        };

        Self {
            name: param.name().to_string(),
            type_tag,
            array_length: param.array_length(),
            flags: param.flags(),
            data,
        }
    }
}

/// Scalars per element for each ɴsɪ type.
#[inline]
const fn components_per_element(type_tag: Type) -> usize {
    match type_tag {
        Type::Color | Type::Point | Type::Vector | Type::Normal => 3,
        Type::MatrixF32 | Type::MatrixF64 => 16,
        _ => 1,
    }
}

#[cfg(test)]
mod tests;