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;