Skip to main content

nsi_parse/
lua.rs

1//! Reading a Lua scene, by running it.
2//!
3//! ɴsɪ's Lua front end is a programming language: a script may loop,
4//! branch and compute the scene it describes, and the specification's
5//! own examples do. So an interpreter is the only correct reader, and
6//! pattern-matching `nsi.Create(...)` out of the source would work only
7//! on scripts a generator wrote.
8//!
9//! **Reading a script executes it.** That is a different trust decision
10//! from parsing a data file, which is why this is behind a feature and
11//! said plainly rather than implied.
12
13use crate::Error;
14use core::num::NonZeroUsize;
15use mlua::{Lua, Table, Value, Variadic};
16use nsi_ffi_wrap::{
17    Arg, ArgData, StringSlice,
18    argument::{
19        Color3F32Slice, IntegerI32Slice, Matrix4F32Slice, Matrix4F64Slice,
20        Normal3F32Slice, Point3F32Slice, Point4F32Slice, RealF32Slice,
21        Vector3F32Slice,
22    },
23};
24use nsi_trait::{Action, Nsi, Type};
25use std::cell::RefCell;
26
27/// One parameter, read out of a Lua table.
28#[derive(Clone)]
29struct Param {
30    name: String,
31    type_tag: Type,
32    array_length: Option<NonZeroUsize>,
33    f32s: Vec<f32>,
34    f64s: Vec<f64>,
35    i32s: Vec<i32>,
36    i64s: Vec<i64>,
37    /// Bytes, not `String`: a Lua string is a byte string, and an ɴsɪ
38    /// string value is whatever the C API was handed. Converting here
39    /// lost a Latin-1 file name to U+FFFD exactly as the stream reader
40    /// used to.
41    strings: Vec<Vec<u8>>,
42}
43
44/// Run `source`, applying the ɴsɪ calls it makes to `sink`.
45///
46/// Takes bytes because a Lua chunk is bytes: a script naming a Latin-1
47/// file is one 3Delight runs, and one `nsi_intermediate::write_lua`
48/// emits.
49///
50/// # Errors
51///
52/// [`Error::Lua`] for a script that fails to load or run, and
53/// [`Error::Sink`] when the sink refuses a call. A handle or attribute
54/// name that is not UTF-8 is an [`Error::Lua`] conversion failure: ɴsɪ
55/// identifiers reach [`nsi_trait::Nsi`] as `&str`, so this front end
56/// refuses them exactly as the stream reader does.
57pub fn run_lua<N>(source: &[u8], sink: &N) -> Result<(), Error<N::Error>>
58where
59    N: Nsi,
60    for<'call> N: Nsi<Arg<'call> = nsi_ffi_wrap::Arg<'call, 'static>>,
61{
62    let lua = Lua::new();
63    // A sink error is not a Lua error, so it is carried out of the
64    // script rather than stringified into one.
65    let failure: RefCell<Option<N::Error>> = RefCell::new(None);
66
67    let outcome = lua.scope(|scope| {
68        let nsi = lua.create_table()?;
69
70        // Exactly the constants 3Delight's own `nsi` table has.
71        // `TypeDouble` and `TypeInt64` are `nil` there, so offering them
72        // here would let a script be written that the renderer refuses.
73        for (name, tag) in [
74            ("TypeFloat", Type::RealF32),
75            ("TypeInteger", Type::IntegerI32),
76            ("TypeString", Type::String),
77            ("TypeColor", Type::Color3F32),
78            ("TypePoint", Type::Point3F32),
79            ("TypeVector", Type::Vector3F32),
80            ("TypeNormal", Type::Normal3F32),
81            ("TypeMatrix", Type::Matrix4F32),
82            ("TypeDoubleMatrix", Type::Matrix4F64),
83            ("TypeHPoint", Type::Point4F32),
84        ] {
85            nsi.set(name, tag as i32)?;
86        }
87
88        macro_rules! record {
89            ($body:expr) => {
90                scope.create_function_mut($body)?
91            };
92        }
93
94        nsi.set(
95            "Create",
96            record!(|_, (handle, node_type): (String, String)| {
97                keep(&failure, sink.create(&handle, &node_type, None))
98            }),
99        )?;
100        nsi.set(
101            "Delete",
102            record!(|_, (handle, rest): (String, Variadic<Value>)| {
103                // ɴsɪ's `recursive` rides here; dropping it turned a
104                // recursive delete into a plain one.
105                let params = params_of(rest)?;
106                with_args(&params, |args| {
107                    keep(&failure, sink.delete(&handle, Some(args)))
108                })
109            }),
110        )?;
111        nsi.set(
112            "DeleteAttribute",
113            record!(|_, (handle, name): (String, String)| {
114                keep(&failure, sink.delete_attribute(&handle, &name))
115            }),
116        )?;
117        nsi.set(
118            "SetAttribute",
119            record!(|_, (handle, rest): (String, Variadic<Value>)| {
120                let params = params_of(rest)?;
121                with_args(&params, |args| {
122                    keep(&failure, sink.set_attribute(&handle, args))
123                })
124            }),
125        )?;
126        nsi.set(
127            "SetAttributeAtTime",
128            record!(
129                |_, (handle, time, rest): (String, f64, Variadic<Value>)| {
130                    let params = params_of(rest)?;
131                    with_args(&params, |args| {
132                        keep(
133                            &failure,
134                            sink.set_attribute_at_time(&handle, time, args),
135                        )
136                    })
137                }
138            ),
139        )?;
140        nsi.set(
141            "Connect",
142            record!(|_,
143                     (from, from_attribute, to, to_attribute, rest): (
144                String,
145                String,
146                String,
147                String,
148                Variadic<Value>,
149            )| {
150                let params = params_of(rest)?;
151                let port =
152                    Some(from_attribute.as_str()).filter(|p| !p.is_empty());
153                with_args(&params, |args| {
154                    keep(
155                        &failure,
156                        sink.connect(
157                            &from,
158                            port,
159                            &to,
160                            &to_attribute,
161                            Some(args),
162                        ),
163                    )
164                })
165            }),
166        )?;
167        nsi.set(
168            "Disconnect",
169            record!(|_,
170                     (from, from_attribute, to, to_attribute): (
171                String,
172                String,
173                String,
174                String,
175            )| {
176                let port =
177                    Some(from_attribute.as_str()).filter(|p| !p.is_empty());
178                keep(&failure, sink.disconnect(&from, port, &to, &to_attribute))
179            }),
180        )?;
181        nsi.set(
182            "Evaluate",
183            record!(|_, rest: Variadic<Value>| {
184                let params = params_of(rest)?;
185                with_args(&params, |args| keep(&failure, sink.evaluate(args)))
186            }),
187        )?;
188
189        nsi.set(
190            "RenderControl",
191            record!(|_, rest: Variadic<Value>| {
192                let params = params_of(rest)?;
193                let action = params
194                    .iter()
195                    .find(|p| p.name == "action" && p.type_tag == Type::String)
196                    .and_then(|p| p.strings.first())
197                    .and_then(|name| action_of(name))
198                    .ok_or_else(|| {
199                        mlua::Error::runtime(
200                            "nsi.RenderControl needs a known action",
201                        )
202                    })?;
203                // ɴsɪ's own `render_control` appends the action, so
204                // passing it through here would send it twice.
205                let rest: Vec<&Param> =
206                    params.iter().filter(|p| p.name != "action").collect();
207                let owned: Vec<Param> = rest.into_iter().cloned().collect();
208                with_args(&owned, |args| {
209                    keep(&failure, sink.render_control(action, Some(args)))
210                })
211            }),
212        )?;
213
214        lua.globals().set("nsi", nsi)?;
215        lua.load(source).exec()
216    });
217
218    if let Some(error) = failure.into_inner() {
219        return Err(Error::Sink(error));
220    }
221    outcome.map_err(|error| Error::Lua(error.to_string()))
222}
223
224/// Record a sink error and unwind the script.
225///
226/// The error is kept rather than stringified, and the `Err` returned
227/// here stops the interpreter: without it the script ran on and the
228/// sink kept receiving calls after the refusal, which contradicted what
229/// `Error::Sink` promises.
230fn keep<E>(
231    slot: &RefCell<Option<E>>,
232    result: Result<(), E>,
233) -> mlua::Result<()> {
234    match result {
235        Ok(()) => Ok(()),
236        Err(error) => {
237            let mut slot = slot.borrow_mut();
238            if slot.is_none() {
239                *slot = Some(error);
240            }
241            Err(mlua::Error::runtime("the ɴsɪ sink refused a call"))
242        }
243    }
244}
245
246/// ɴsɪ accepts parameters as variadic tables, or as one table of them.
247fn params_of(rest: Variadic<Value>) -> mlua::Result<Vec<Param>> {
248    let mut tables: Vec<Table> = Vec::new();
249    for value in rest {
250        let Value::Table(table) = value else {
251            return Err(mlua::Error::runtime(
252                "an ɴsɪ parameter must be a table",
253            ));
254        };
255        // A table of parameters, rather than a parameter, has no `name`.
256        if table.contains_key("name")? {
257            tables.push(table);
258        } else {
259            for entry in table.sequence_values::<Table>() {
260                tables.push(entry?);
261            }
262        }
263    }
264
265    tables.into_iter().map(param_of).collect()
266}
267
268/// One `{name=, data=, type=, arraylength=}` table.
269fn param_of(table: Table) -> mlua::Result<Param> {
270    let name: String = table.get("name")?;
271    let array_length: Option<usize> = table.get("arraylength")?;
272    let declared: Option<i32> = table.get("type")?;
273    let data: Value = table.get("data")?;
274
275    let mut param = Param {
276        name,
277        type_tag: Type::Invalid,
278        array_length: array_length.and_then(NonZeroUsize::new),
279        f32s: Vec::new(),
280        f64s: Vec::new(),
281        i32s: Vec::new(),
282        i64s: Vec::new(),
283        strings: Vec::new(),
284    };
285
286    // ɴsɪ: "the type parameter can be omitted if the parameter is an
287    // integer, real or string". Lua 5.4 keeps the two number kinds
288    // apart, so the inference is exact rather than a guess.
289    let type_tag = match declared {
290        Some(value) => tag_of(value)?,
291        None => match &data {
292            Value::Integer(_) => Type::IntegerI32,
293            Value::Number(_) => Type::RealF32,
294            Value::String(_) => Type::String,
295            _ => {
296                return Err(mlua::Error::runtime(
297                    "an ɴsɪ parameter with table data needs a type",
298                ));
299            }
300        },
301    };
302    param.type_tag = type_tag;
303
304    let values: Vec<Value> = match data {
305        Value::Table(table) => table
306            .sequence_values::<Value>()
307            .collect::<mlua::Result<_>>()?,
308        scalar => vec![scalar],
309    };
310
311    for value in values {
312        match type_tag {
313            Type::String => {
314                let text = value
315                    .as_string()
316                    .ok_or_else(|| mlua::Error::runtime("expected a string"))?
317                    .as_bytes()
318                    .to_vec();
319                // An interior NUL would panic in `CString::new` at the
320                // ɴsɪ boundary. The stream reader refuses it; so does
321                // this, which is the path that runs a script.
322                if text.contains(&0) {
323                    return Err(mlua::Error::runtime(
324                        "an ɴsɪ string cannot contain an interior NUL",
325                    ));
326                }
327                param.strings.push(text);
328            }
329            Type::IntegerI32 => {
330                param.i32s.push(i32::try_from(integer(&value)?).map_err(
331                    |_| mlua::Error::runtime("an ɴsɪ int does not fit 32 bits"),
332                )?)
333            }
334            Type::IntegerI64 => param.i64s.push(integer(&value)?),
335            Type::RealF64 | Type::Matrix4F64 => {
336                param.f64s.push(number(&value)?)
337            }
338            _ => param.f32s.push(number(&value)? as f32),
339        }
340    }
341
342    // ɴsɪ's tuple types need whole elements; `as_chunks` would drop a
343    // remainder, turning a two-value point into an empty one.
344    let width = match type_tag {
345        Type::Color3F32
346        | Type::Point3F32
347        | Type::Vector3F32
348        | Type::Normal3F32 => 3,
349        Type::Point4F32 => 4,
350        Type::Matrix4F32 | Type::Matrix4F64 => 16,
351        _ => 1,
352    };
353    // The count has to come from the buffer this type actually filled,
354    // or the `arraylength` check below compares against zero and lets
355    // anything through.
356    let count = match type_tag {
357        Type::RealF64 | Type::Matrix4F64 => param.f64s.len(),
358        Type::IntegerI32 => param.i32s.len(),
359        Type::IntegerI64 => param.i64s.len(),
360        Type::String => param.strings.len(),
361        _ => param.f32s.len(),
362    };
363    if width > 1 && !count.is_multiple_of(width) {
364        return Err(mlua::Error::runtime(
365            "an ɴsɪ tuple parameter needs a whole number of elements",
366        ));
367    }
368
369    // `arraylength` multiplies the element size; the renderer refuses a
370    // parameter whose data does not divide by it, and emitting one
371    // produces a stream nothing can read.
372    let stride = width * param.array_length.map_or(1, NonZeroUsize::get);
373    if stride > 1 && !count.is_multiple_of(stride) {
374        return Err(mlua::Error::runtime(
375            "an ɴsɪ parameter's data must divide by its arraylength",
376        ));
377    }
378
379    Ok(param)
380}
381
382/// Lua 5.4 keeps integers and floats apart, and both are numbers here.
383fn number(value: &Value) -> mlua::Result<f64> {
384    match value {
385        Value::Integer(integer) => Ok(*integer as f64),
386        Value::Number(number) => Ok(*number),
387        _ => Err(mlua::Error::runtime("expected a number")),
388    }
389}
390
391/// The same, kept exact for the integer types.
392fn integer(value: &Value) -> mlua::Result<i64> {
393    match value {
394        Value::Integer(integer) => Ok(*integer),
395        Value::Number(number) => Ok(*number as i64),
396        _ => Err(mlua::Error::runtime("expected a number")),
397    }
398}
399
400/// ɴsɪ's `RenderControl` action names.
401fn action_of(name: &[u8]) -> Option<Action> {
402    // Byte literals: a string value is bytes here, and an action that is
403    // not one of these six is `None` either way.
404    Some(match name {
405        b"start" => Action::Start,
406        b"stop" => Action::Stop,
407        b"suspend" => Action::Suspend,
408        b"resume" => Action::Resume,
409        b"wait" => Action::Wait,
410        b"synchronize" => Action::Synchronize,
411        _ => return None,
412    })
413}
414
415fn tag_of(value: i32) -> mlua::Result<Type> {
416    Ok(match value {
417        1 => Type::RealF32,
418        2 => Type::IntegerI32,
419        3 => Type::String,
420        4 => Type::Color3F32,
421        5 => Type::Point3F32,
422        6 => Type::Vector3F32,
423        7 => Type::Normal3F32,
424        8 => Type::Matrix4F32,
425        0x18 => Type::Matrix4F64,
426        10 => Type::Point4F32,
427        _ => return Err(mlua::Error::runtime("unknown ɴsɪ type")),
428    })
429}
430
431/// Build the arguments and hand them to `apply`, borrowing the params.
432fn with_args<T>(
433    params: &[Param],
434    apply: impl FnOnce(&[Arg<'_, 'static>]) -> T,
435) -> T {
436    let triples: Vec<Vec<[f32; 3]>> = params
437        .iter()
438        .map(|p| p.f32s.as_chunks::<3>().0.to_vec())
439        .collect();
440    let quads: Vec<Vec<[f32; 4]>> = params
441        .iter()
442        .map(|p| p.f32s.as_chunks::<4>().0.to_vec())
443        .collect();
444    let matrices_f32: Vec<Vec<[f32; 16]>> = params
445        .iter()
446        .map(|p| p.f32s.as_chunks::<16>().0.to_vec())
447        .collect();
448    let matrices_f64: Vec<Vec<[f64; 16]>> = params
449        .iter()
450        .map(|p| p.f64s.as_chunks::<16>().0.to_vec())
451        .collect();
452    let borrowed: Vec<Vec<&[u8]>> = params
453        .iter()
454        .map(|p| p.strings.iter().map(Vec::as_slice).collect())
455        .collect();
456
457    let args: Vec<Arg<'_, 'static>> = params
458        .iter()
459        .enumerate()
460        .map(|(index, p)| {
461            let data = match p.type_tag {
462                Type::RealF32 => ArgData::from(RealF32Slice::new(&p.f32s)),
463                Type::IntegerI32 => {
464                    ArgData::from(IntegerI32Slice::new(&p.i32s))
465                }
466                Type::String => {
467                    ArgData::from(StringSlice::new(&borrowed[index]))
468                }
469                Type::Color3F32 => {
470                    ArgData::from(Color3F32Slice::new(&triples[index]))
471                }
472                Type::Point3F32 => {
473                    ArgData::from(Point3F32Slice::new(&triples[index]))
474                }
475                Type::Vector3F32 => {
476                    ArgData::from(Vector3F32Slice::new(&triples[index]))
477                }
478                Type::Normal3F32 => {
479                    ArgData::from(Normal3F32Slice::new(&triples[index]))
480                }
481                Type::Matrix4F32 => {
482                    ArgData::from(Matrix4F32Slice::new(&matrices_f32[index]))
483                }
484                Type::Matrix4F64 => {
485                    ArgData::from(Matrix4F64Slice::new(&matrices_f64[index]))
486                }
487                Type::Point4F32 => {
488                    ArgData::from(Point4F32Slice::new(&quads[index]))
489                }
490                // `tag_of` yields none of these and inference produces
491                // none: ɴsɪ's Lua binding has no name for a double, a
492                // 64-bit integer or a pointer.
493                // `tag_of` accepts none of these, and inference
494                // produces none.
495                Type::RealF64
496                | Type::IntegerI64
497                | Type::Reference
498                | Type::Invalid => {
499                    unreachable!("no Lua spelling yields {:?}", p.type_tag)
500                }
501            };
502
503            let arg = Arg::new(&p.name, data);
504            match p.array_length {
505                Some(length) => arg.array_len(length),
506                None => arg,
507            }
508        })
509        .collect();
510
511    apply(&args)
512}