Skip to main content

nsi_intermediate/owned/
mod.rs

1//! Owned mirrors of borrowed ɴsɪ arguments.
2//!
3//! The recorder outlives the calls that feed it, so it cannot hold a
4//! borrowed `Arg`. [`OwnedArgument`] copies the payload out.
5//!
6//! This mirrors the ɴsɪ C API's own contract: every argument except a
7//! `NSIType` pointer is copied during the call, so a caller may free its
8//! data the moment the call returns. Copying here is therefore not an
9//! extra cost the recorder introduces -- it is what a live renderer would
10//! have done anyway.
11//!
12//! [`OwnedData::Reference`] is the exception, and holds a raw pointer
13//! rather than a copy, because that is what ɴsɪ passes through.
14
15use core::{
16    ffi::{CStr, c_char, c_void},
17    slice,
18};
19use nsi_ffi_wrap::{Arg, nsi_sys::NSIParamFlags};
20use nsi_trait::{ParamValue, Type};
21
22/// A raw host address recorded from an ɴsɪ `Reference` argument.
23///
24/// # Safety
25///
26/// `Send` and `Sync` are asserted on two grounds, both structural
27/// rather than hopeful:
28///
29/// 1. **The recorder never dereferences it.** A `HostPointer` is stored on
30///    the way in and handed back on the way out, nothing else. No data
31///    race is possible through a pointer that is never read.
32/// 2. **The pointee outlives everything.** The recorder's `Nsi` impl
33///    declares `Arg<'call, 'static>`, so the only `Reference` it can be
34///    handed is one whose data is `'static`. That is the same rule
35///    `nsi-ffi-wrap` applies -- `Reference`, `Callback` and
36///    `ReferenceSlice` are `Send`/`Sync` at `'static` and nowhere else.
37///
38/// The assertion lives on this newtype rather than on `Recorder` so it
39/// covers exactly the field that needs it. A blanket
40/// `unsafe impl Send for Recorder` would silently keep covering any
41/// non-`Send` field added later.
42#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
43#[repr(transparent)]
44pub struct HostPointer(pub *const c_void);
45
46// SAFETY: see the type's documentation.
47unsafe impl Send for HostPointer {}
48// SAFETY: see the type's documentation.
49unsafe impl Sync for HostPointer {}
50
51/// An ɴsɪ argument's payload, owned.
52///
53/// Variants are storage representations, not ɴsɪ types: colour, point,
54/// vector, normal and 4x4 `f32` matrices all live in [`OwnedData::F32`]
55/// and are told apart by [`OwnedArgument::type_tag`].
56#[derive(Debug, Clone, PartialEq)]
57#[non_exhaustive]
58pub enum OwnedData {
59    /// `f32` scalars, flattened. Also holds colour, point, vector,
60    /// normal and 4x4 `f32` matrices; [`OwnedArgument::type_tag`] tells them
61    /// apart.
62    F32(Vec<f32>),
63    /// `f64` scalars, flattened. Also holds 4x4 `f64` matrices.
64    F64(Vec<f64>),
65    /// 32-bit integers.
66    I32(Vec<i32>),
67    /// 64-bit integers.
68    I64(Vec<i64>),
69    /// Strings, copied out of their C representation.
70    ///
71    /// **Bytes, not `String`.** An ɴsɪ string is whatever the C API was
72    /// handed. 3Delight writes a byte at or above `0x7f` raw and reads
73    /// it back unchanged, and a file name on Linux is not required to be
74    /// UTF-8 -- so an `imagefilename` naming `café.exr` in Latin-1 is a
75    /// value this crate must carry, not one it may repair. Storing
76    /// `String` here replaced the byte with U+FFFD at *recording* time,
77    /// which no amount of care at replay could undo.
78    ///
79    /// Use `String::from_utf8_lossy` where text is wanted.
80    ///
81    /// # A path value may need expanding
82    ///
83    /// ɴsɪ streams carry `${VAR}` references so a scene can move between
84    /// machines, and 3Delight expands them **when it uses the value**,
85    /// not when it reads the stream. A backend that opens a path from
86    /// here without expanding opens the wrong file -- and only on the
87    /// machines where the variable mattered, which is when it is hardest
88    /// to diagnose.
89    ///
90    /// The rules, measured rather than inferred, because each one
91    /// changes what a backend must implement:
92    ///
93    /// - **`${NAME}` only.** A bare `$NAME` is left alone: a probe
94    ///   naming `$VAR/x.exr` created a literal `$VAR` directory.
95    /// - **Path-valued attributes only.** `imagefilename`,
96    ///   `shaderfilename` and `Evaluate`'s `filename` expand, and nest
97    ///   (`${A}/${B}`). `drivername` does **not** -- it fails with
98    ///   `E6024 cannot find display driver '${...}'` -- nor does a node
99    ///   handle (`E6087 unknown node handle`), nor an attribute *name*,
100    ///   which is silently ignored.
101    /// - **Any variable, not just `NSI_PATH_`.** `${HOME}` expands. That
102    ///   prefix governs which variables 3Delight *writes* as references
103    ///   under `streampathreplacement`; on read it means nothing.
104    /// - **An unset variable stays literal**, rather than expanding to
105    ///   empty or erroring: a probe created a literal `${MISSING}`
106    ///   directory.
107    ///
108    /// One trap worth naming: `${...}` in an output layer's
109    /// `variablename` **segfaults** 3Delight 2.9.207. Do not pass one
110    /// through to a renderer expecting a diagnostic.
111    ///
112    /// See `specs/004` research Q1.
113    String(Vec<Vec<u8>>),
114    /// Raw host pointers. ɴsɪ calls this `Reference` (`Pointer` in the C
115    /// API); it is not an object link and is never forwarded to a
116    /// renderer as one. Stored so output-driver callbacks survive a
117    /// replay. The recorder never dereferences these.
118    Reference(Vec<HostPointer>),
119}
120
121/// A recorded ɴsɪ argument.
122#[derive(Debug, Clone, PartialEq)]
123#[non_exhaustive]
124pub struct OwnedArgument {
125    /// The attribute name this argument sets.
126    pub name: String,
127    /// The ɴsɪ type, which is what tells one [`OwnedData`] layout from
128    /// another sharing the same storage.
129    pub type_tag: Type,
130    /// ɴsɪ's `array_len`. The C `count` field is `len/array_length`.
131    pub array_length: usize,
132    /// ɴsɪ's argument flags: `per_vertex`, `per_face` and the like.
133    /// Replayed as the letter prefix 3Delight writes -- `"v point"`,
134    /// `"f float"`, `"vl float"`; see `contracts/stream.md`.
135    pub flags: i32,
136    /// The payload, copied unless it is a pointer.
137    pub data: OwnedData,
138}
139
140impl OwnedArgument {
141    /// One recorded argument, built by hand.
142    ///
143    /// [`Scene::set_attribute`](crate::Scene::set_attribute) and its
144    /// timed twin take these, and the struct is `#[non_exhaustive]` so
145    /// that a later field is not a breaking change -- which also means
146    /// a struct literal will not compile outside this crate. Without
147    /// this, half of `Scene`'s public surface could only ever be
148    /// handed an empty vector.
149    pub fn new(
150        name: impl Into<String>,
151        type_tag: Type,
152        array_length: usize,
153        flags: i32,
154        data: OwnedData,
155    ) -> Self {
156        Self {
157            name: name.into(),
158            type_tag,
159            array_length,
160            flags,
161            data,
162        }
163    }
164
165    /// The payload as `f32` scalars, or `None` for another layout.
166    ///
167    /// Colour, point, vector, normal and an `f32` matrix all share this
168    /// storage flattened; [`OwnedArgument::type_tag`] tells them apart.
169    pub fn as_f32s(&self) -> Option<&[f32]> {
170        match &self.data {
171            OwnedData::F32(values) => Some(values),
172            _ => None,
173        }
174    }
175
176    /// The payload as `f64` scalars, or `None` for another layout.
177    pub fn as_f64s(&self) -> Option<&[f64]> {
178        match &self.data {
179            OwnedData::F64(values) => Some(values),
180            _ => None,
181        }
182    }
183
184    /// The payload as 32-bit integers, or `None` for another layout.
185    pub fn as_i32s(&self) -> Option<&[i32]> {
186        match &self.data {
187            OwnedData::I32(values) => Some(values),
188            _ => None,
189        }
190    }
191
192    /// The payload as 64-bit integers, or `None` for another layout.
193    pub fn as_i64s(&self) -> Option<&[i64]> {
194        match &self.data {
195            OwnedData::I64(values) => Some(values),
196            _ => None,
197        }
198    }
199
200    /// The payload as strings, or `None` for another layout.
201    ///
202    /// Bytes, not `str`: see [`OwnedData::String`]. A path may need
203    /// `${VAR}` expanding before use.
204    pub fn as_strings(&self) -> Option<&[Vec<u8>]> {
205        match &self.data {
206            OwnedData::String(values) => Some(values),
207            _ => None,
208        }
209    }
210
211    /// A single `f32`, for the common scalar case.
212    ///
213    /// `None` unless the payload is exactly one `f32`, so a caller
214    /// cannot silently read the first component of a colour as a float.
215    pub fn as_f32(&self) -> Option<f32> {
216        match self.as_f32s() {
217            Some([value]) => Some(*value),
218            _ => None,
219        }
220    }
221
222    /// A single `i32`, on the same terms as [`OwnedArgument::as_f32`].
223    pub fn as_i32(&self) -> Option<i32> {
224        match self.as_i32s() {
225            Some([value]) => Some(*value),
226            _ => None,
227        }
228    }
229
230    /// How many *elements* this argument carries.
231    ///
232    /// Scalars count themselves; a `point` counts triples; an
233    /// `array_len(n)` argument counts runs of `n`. This is ɴsɪ's `count`
234    /// field, and it is what says whether a primitive variable is one
235    /// value per face, per vertex or per face-vertex.
236    pub fn element_count(&self) -> usize {
237        let per = match self.type_tag {
238            Type::Color3F32
239            | Type::Point3F32
240            | Type::Vector3F32
241            | Type::Normal3F32 => 3,
242            Type::Point4F32 => 4,
243            Type::Matrix4F32 | Type::Matrix4F64 => 16,
244            _ => 1,
245        };
246        let scalars = match &self.data {
247            OwnedData::F32(values) => values.len(),
248            OwnedData::F64(values) => values.len(),
249            OwnedData::I32(values) => values.len(),
250            OwnedData::I64(values) => values.len(),
251            OwnedData::String(values) => values.len(),
252            OwnedData::Reference(values) => values.len(),
253        };
254        scalars / per / self.array_length.max(1)
255    }
256
257    /// A 4x4 `doublematrix`, row-major.
258    ///
259    /// `None` unless the declared type is [`nsi_trait::Type::Matrix4F64`]
260    /// with sixteen values: sixteen `double`s are not a `doublematrix`,
261    /// and 3Delight refuses that too.
262    pub fn as_matrix(&self) -> Option<[f64; 16]> {
263        match self.as_matrices()? {
264            [] => None,
265            values if values.len() == 16 => {
266                // SAFETY: the match arm above tested the length, so the
267                // slice is exactly the sixteen the array wants.
268                Some(values[..16].try_into().expect("length checked"))
269            }
270            _ => None,
271        }
272    }
273
274    /// The payload of a `doublematrix` argument, however many.
275    ///
276    /// **The array suffix is part of the declaration.** ɴsɪ marks an
277    /// array with `NSIParamIsArray` rather than by length, and
278    /// 3Delight reads `doublematrix[2]` as a different type from
279    /// `doublematrix`: rendered, an instancer whose
280    /// `transformationmatrices` is declared `"doublematrix[2]" 1` --
281    /// or `"doublematrix[1]" 2`, the same values again -- is `E6007`
282    /// and **nothing draws**, where the plain `"doublematrix" 2` draws
283    /// two copies. Reading the tag alone drew them anyway.
284    pub fn as_matrices(&self) -> Option<&[f64]> {
285        if self.type_tag != Type::Matrix4F64 || self.is_array() {
286            return None;
287        }
288        match &self.data {
289            OwnedData::F64(values) => Some(values),
290            _ => None,
291        }
292    }
293
294    /// Whether ɴsɪ's `NSIParamIsArray` is set, which makes the
295    /// argument's type `T[n]` rather than `T`.
296    pub fn is_array(&self) -> bool {
297        self.flags & NSIParamFlags::IsArray.bits() != 0
298    }
299
300    /// Copy a borrowed parameter into owned storage.
301    ///
302    /// `pub(crate)` on purpose. It carried two failure paths that
303    /// nothing in this crate can reach -- a panic if `as_c_param`
304    /// returned `None`, and an empty `f32` array for `Type::Invalid` --
305    /// because [`Recorder`](crate::Recorder)'s `Arg` GAT pins the
306    /// parameter to `nsi_ffi_wrap::Arg`, whose `as_c_param` always
307    /// returns `Some` and which never produces `Invalid`. Only a
308    /// *foreign* `ParamValue` could reach either, and only through this
309    /// being public.
310    ///
311    /// Narrowing it makes both unreachable by construction rather than
312    /// by argument, which is cheaper than a `Result` every internal
313    /// caller would have to unwrap for a case that cannot arise.
314    /// Callers wanting an [`OwnedArgument`] use [`OwnedArgument::new`].
315    ///
316    /// It takes `Arg` rather than any `ParamValue` for the same reason:
317    /// while it stayed generic, "unreachable" rested on nobody in this
318    /// crate ever passing something else, which is a habit rather than
319    /// a guarantee. Named, the compiler holds it.
320    pub(crate) fn from_param(param: &Arg<'_, '_>) -> Self {
321        let type_tag = param.type_tag();
322
323        // The C call hands the renderer `count = len/array_length`
324        // elements, so a run that does not divide is *dropped there*.
325        // Copying `len` outright kept data 3Delight never saw -- and
326        // made this crate's own stream fail the count `nsi-parse`
327        // checks. Round the element count down the same way the C
328        // boundary does.
329        let array_length = param.array_length().max(1);
330        let elements = param.len() / array_length * array_length;
331        let scalars = elements * components_per_element(type_tag);
332
333        // SAFETY: unreachable while this is `pub(crate)` -- the only
334        // implementor that reaches here is `nsi_ffi_wrap::Arg`, whose
335        // `as_c_param` returns `Some` unconditionally.
336        let c = param
337            .as_c_param()
338            .expect("nsi-ffi-wrap Arg always yields a C view");
339
340        // SAFETY: `c.data` points at `scalars` values of the type named
341        // by `type_tag`, valid while `param` lives, which is this call.
342        let data = unsafe {
343            match type_tag {
344                Type::RealF32
345                | Type::Color3F32
346                | Type::Point3F32
347                | Type::Vector3F32
348                | Type::Normal3F32
349                | Type::Matrix4F32
350                | Type::Point4F32 => OwnedData::F32(
351                    slice::from_raw_parts(c.data as *const f32, scalars)
352                        .to_vec(),
353                ),
354                Type::RealF64 | Type::Matrix4F64 => OwnedData::F64(
355                    slice::from_raw_parts(c.data as *const f64, scalars)
356                        .to_vec(),
357                ),
358                Type::IntegerI32 => OwnedData::I32(
359                    slice::from_raw_parts(c.data as *const i32, scalars)
360                        .to_vec(),
361                ),
362                Type::IntegerI64 => OwnedData::I64(
363                    slice::from_raw_parts(c.data as *const i64, scalars)
364                        .to_vec(),
365                ),
366                Type::String => {
367                    let ptrs = slice::from_raw_parts(
368                        c.data as *const *const c_char,
369                        scalars,
370                    );
371                    OwnedData::String(
372                        ptrs.iter()
373                            .map(|p| CStr::from_ptr(*p).to_bytes().to_vec())
374                            .collect(),
375                    )
376                }
377                Type::Reference => OwnedData::Reference(
378                    slice::from_raw_parts(
379                        c.data as *const *const c_void,
380                        scalars,
381                    )
382                    .iter()
383                    .map(|p| HostPointer(*p))
384                    .collect(),
385                ),
386                // Also unreachable: `Invalid` is ɴsɪ's C sentinel for
387                // "no type" and nothing in this workspace produces it.
388                // It used to yield an empty `f32` array, which would
389                // have recorded a *different* argument rather than
390                // refusing -- the silent wrong answer this crate exists
391                // to avoid. If it ever fires, the pinned type has
392                // changed and this must be revisited, not patched over.
393                Type::Invalid => {
394                    unreachable!("nsi-ffi-wrap never yields Type::Invalid")
395                }
396            }
397        };
398
399        Self {
400            name: param.name().to_string(),
401            type_tag,
402            array_length: param.array_length(),
403            flags: param.flags(),
404            data,
405        }
406    }
407}
408
409/// Scalars per element for each ɴsɪ type.
410#[inline]
411const fn components_per_element(type_tag: Type) -> usize {
412    match type_tag {
413        Type::Color3F32
414        | Type::Point3F32
415        | Type::Vector3F32
416        | Type::Normal3F32 => 3,
417        Type::Point4F32 => 4,
418        Type::Matrix4F32 | Type::Matrix4F64 => 16,
419        _ => 1,
420    }
421}
422
423#[cfg(test)]
424mod tests;