nsi-ffi-wrap 0.9.0

//! Optional arguments passed to methods of an ɴsɪ context.
use enum_dispatch::enum_dispatch;
use nsi_sys::*;
use std::{
    ffi::{CString, c_void},
    marker::PhantomData,
    pin::Pin,
};
use ustr::{Ustr, ustr};

// Needed for docs.
#[allow(unused_imports)]
use crate::*;

#[inline(always)]
pub(crate) fn get_c_param_vec(
    args: Option<&ArgSlice>,
) -> (i32, *const NSIParam, Vec<NSIParam>) {
    let args = match args {
        Some(args) => args
            .iter()
            .map(|arg| NSIParam {
                name: arg.name.as_char_ptr(),
                data: arg.data.as_c_ptr(),
                type_: arg.data.type_() as _,
                arraylength: arg.array_length as _,
                count: (arg.data.len() / arg.array_length) as _,
                flags: arg.flags as _,
            })
            .collect::<Vec<_>>(),
        None => Vec::new(),
    };

    (args.len() as _, args.as_ptr(), args)
}

/// A slice of (optional) arguments passed to a method of
/// [`Context`].
pub type ArgSlice<'a, 'b> = [Arg<'a, 'b>];

/// A vector of (optional) arguments passed to a method of
/// [`Context`].
pub type ArgVec<'a, 'b> = Vec<Arg<'a, 'b>>;

/// An (optional) argument passed to a method of
/// [`Context`].
#[derive(Debug, Clone)]
pub struct Arg<'a, 'b> {
    pub(crate) name: Ustr,
    pub(crate) data: ArgData<'a, 'b>,
    // Length of each element if an array type.
    pub(crate) array_length: usize,
    // Number of elements.
    pub(crate) flags: i32,
}

impl<'a, 'b> Arg<'a, 'b> {
    #[inline]
    pub fn new(name: &str, data: ArgData<'a, 'b>) -> Self {
        Arg {
            name: ustr(name),
            data,
            array_length: 1,
            flags: 0,
        }
    }

    /// Sets the length of the argument for each element.
    #[inline]
    pub fn array_len(mut self, length: usize) -> Self {
        self.array_length = length;
        self.flags |= NSIParamFlags::IsArray.bits();
        self
    }

    /// Marks this argument as having per-face granularity.
    #[inline]
    pub fn per_face(mut self) -> Self {
        self.flags |= NSIParamFlags::PerFace.bits();
        self
    }

    /// Marks this argument as having per-vertex granularity.
    #[inline]
    pub fn per_vertex(mut self) -> Self {
        self.flags |= NSIParamFlags::PerVertex.bits();
        self
    }

    /// Marks this argument as to be interpolated linearly.
    #[inline]
    pub fn linear_interpolation(mut self) -> Self {
        self.flags |= NSIParamFlags::InterpolateLinear.bits();
        self
    }
}

#[enum_dispatch(ArgData)]
pub(crate) trait ArgDataMethods {
    //const TYPE: DataType;
    fn type_(&self) -> DataType;
    fn len(&self) -> usize;
    fn as_c_ptr(&self) -> *const c_void;
}

/// A variant describing data passed to the renderer.
///
/// # Lifetimes
/// Lifetime `'a` is for any tuple or array type as these are
/// passed as references and only need to live as long as the
/// function call where they get passed.
///
/// Lifetime `'b` is for the arbitrary reference type. This is
/// pegged to the lifetime of the [`Context`](crate::context::Context).
/// Use this to pass arbitrary Rust data through the FFI boundary.
#[enum_dispatch]
#[derive(Debug, Clone)]
pub enum ArgData<'a, 'b> {
    /// Single [`f32`] value.
    F32,
    /// An [`f32`] slice.
    F32Slice(F32Slice<'a>),
    /// Single [`f64`] value.
    F64,
    /// An [`f64`] slice.
    F64Slice(F64Slice<'a>),
    /// Single [`i32`] value.
    I32,
    /// An [`i32`] slice.
    I32Slice(I32Slice<'a>),
    /// Single [`i64`] value.
    I64,
    /// An [`i64`] slice.
    I64Slice(I64Slice<'a>),
    /// A [`String`].
    String(String),
    /// A [`String`] slice.
    StringSlice(StringSlice),
    /// Color in linear space, given as a red, green, blue triplet
    /// of [`f32`] values; usually in the range `0..1`.
    Color(Color<'a>),
    /// A flat [`f32`] slice of colors (`len % 3 == 0`).
    ColorSlice(ColorSlice<'a>),
    /// Point, given as three [`f32`] values.
    Point(Point<'a>),
    /// A flat [`f32`] slice of points (`len % 3 == 0`).
    PointSlice(PointSlice<'a>),
    /// Vector, given as three [`f32`] values.
    Vector(Vector<'a>),
    /// A flat [`f32`] slice of vectors (`len % 3 == 0`).
    VectorSlice(VectorSlice<'a>),
    /// Normal vector, given as three [`f32`] values.
    Normal(Normal<'a>),
    /// A flat [`f32`] slice of normals (`len % 3 == 0`).
    NormalSlice(NormalSlice<'a>),
    /// Row-major, 4×4 transformation matrix, given as 16 [`f32`] values.
    MatrixF32(MatrixF32<'a>),
    /// A flat [`f32`] slice of matrices (`len % 16 == 0`).
    MatrixF32Slice(MatrixF32Slice<'a>),
    /// Row-major, 4×4 transformation matrix, given as 16 [`f64`] values.
    MatrixF64(MatrixF64<'a>),
    /// A flat [`f64`] slice of matrices (`len % 16 == 0`).
    MatrixF64Slice(MatrixF64Slice<'a>),
    /// A slice of 4-component f32 points (xyzw).
    /// Wire-side: a flat `NSITypeFloat` slice of `4 * N` floats — the
    /// renderer groups them by attribute semantics. Use the
    /// [`point4_f32_slice!`][crate::point4_f32_slice] macro to keep
    /// `&[[f32; 4]]` ergonomics in Rust while the FFI sees the flat
    /// layout.
    Point4F32Slice(Point4F32Slice<'a>),
    /// Reference *with* lifetime guarantees.
    ///
    /// This gets converted to a raw pointer when passed
    /// through the FFI boundary.
    ///
    /// ```
    /// # use nsi_ffi_wrap as nsi;
    /// let ctx = nsi::Context::new(None).unwrap();
    ///
    /// // Lots of scene setup omitted ...
    ///
    /// // Setup a custom output driver and send
    /// // a payload to it through the FFI boundary.
    /// ctx.create("driver", nsi::OUTPUT_DRIVER, None);
    /// ctx.connect("driver", None, "beauty", "outputdrivers", None);
    ///
    /// struct Payload {
    ///     some_data: u32,
    /// }
    ///
    /// // Must use heap allocation for stable address
    /// let payload = Box::new(Payload { some_data: 42 });
    /// ctx.set_attribute(
    ///     "driver",
    ///     &[
    ///         nsi::string!("drivername", "custom_driver"),
    ///         // Payload gets sent as raw pointer through
    ///         // the FFI boundary. The Box ensures stable address.
    ///         nsi::reference!("payload", &payload),
    ///     ],
    /// );
    ///
    /// // We need to explicitly call drop here as
    /// // ctx's lifetime is pegged to that of payload.
    /// drop(ctx);
    /// ```
    Reference(Reference<'b>),
    /// A [`Reference`] slice.
    ReferenceSlice(ReferenceSlice<'b>),
    /// A callback.
    Callback(Callback<'b>),
}

macro_rules! nsi_data_def {
    ($type: ty, $name: ident, $nsi_type: expr) => {
        /// See [`ArgData`] for details.
        #[derive(Debug, Clone, PartialEq)]
        pub struct $name {
            data: $type,
        }

        impl $name {
            pub fn new(data: $type) -> Self {
                Self { data }
            }
        }

        impl ArgDataMethods for $name {
            fn type_(&self) -> DataType {
                $nsi_type
            }

            fn len(&self) -> usize {
                1
            }

            fn as_c_ptr(&self) -> *const c_void {
                &self.data as *const $type as _
            }
        }
    };
}

macro_rules! nsi_data_array_def {
    ($type: ty, $name: ident, $nsi_type: expr) => {
        /// See [`ArgData`] for details.
        #[derive(Debug, Clone, PartialEq)]
        pub struct $name<'a> {
            data: &'a [$type],
        }

        impl<'a> $name<'a> {
            pub fn new(data: &'a [$type]) -> Self {
                //debug_assert_eq!(0, data.len() % $nsi_type.elemensize());
                Self { data }
            }
        }

        impl<'a> ArgDataMethods for $name<'a> {
            fn type_(&self) -> DataType {
                $nsi_type
            }

            fn len(&self) -> usize {
                self.data.len() // / $nsi_type.elemensize()
            }

            fn as_c_ptr(&self) -> *const c_void {
                self.data.as_ptr() as _
            }
        }
    };
}

macro_rules! nsi_tuple_data_array_def {
    ($type: ty, $name: ident, $nsi_type: expr, $len: expr ) => {
        /// See [`ArgData`] for details.
        #[derive(Debug, Clone, PartialEq)]
        pub struct $name<'a> {
            data: &'a [[$type; $len]],
        }

        impl<'a> $name<'a> {
            pub fn new(data: &'a [[$type; $len]]) -> Self {
                //debug_assert_eq!(0, data.len() % $nsi_type.elemensize());
                Self { data }
            }
        }

        impl<'a> ArgDataMethods for $name<'a> {
            fn type_(&self) -> DataType {
                $nsi_type
            }

            fn len(&self) -> usize {
                self.data.len() // / $nsi_type.elemensize()
            }

            fn as_c_ptr(&self) -> *const c_void {
                self.data.as_ptr() as _
            }
        }
    };
}

macro_rules! nsi_tuple_data_def {
    ($type: tt, $len: expr, $name: ident, $nsi_type: expr) => {
        /// See [`ArgData`] for details.
        #[derive(Debug, Clone, PartialEq)]
        pub struct $name<'a> {
            data: &'a [$type; $len],
        }

        impl<'a> $name<'a> {
            pub fn new(data: &'a [$type; $len]) -> Self {
                Self { data }
            }
        }

        impl<'a> ArgDataMethods for $name<'a> {
            fn type_(&self) -> DataType {
                $nsi_type
            }

            fn len(&self) -> usize {
                1
            }

            fn as_c_ptr(&self) -> *const c_void {
                self.data.as_ptr() as _
            }
        }
    };
}

nsi_data_def!(f32, F32, DataType::F32);
nsi_data_def!(f64, F64, DataType::F64);
nsi_data_def!(i32, I32, DataType::I32);
nsi_data_def!(i64, I64, DataType::I64);

/// See [`ArgData`] for details.
/// A reference to data that will be passed through FFI.
///
/// # Safety
/// The referenced data must outlive the NSI context that uses this reference.
/// The data must remain at a stable memory address.
///
/// This type now properly enforces pinning by requiring heap-allocated data
/// through Box, Arc, or similar types that guarantee stable addresses.
#[derive(Debug, Clone)]
pub struct Reference<'a> {
    data: *const c_void,
    _marker: PhantomData<&'a ()>,
}

// SAFETY: Reference only contains a pointer and doesn't dereference it.
// The actual safety depends on the lifetime parameter being correct.
unsafe impl Send for Reference<'static> {}
unsafe impl Sync for Reference<'static> {}

/// Trait for types that can be safely converted to a Reference.
/// This is implemented only for types that guarantee stable memory addresses.
pub trait StableDeref<'a> {
    /// Get a stable pointer to the data
    fn stable_deref(&self) -> *const c_void;
}

impl<'a, T: ?Sized> StableDeref<'a> for &'a Box<T> {
    fn stable_deref(&self) -> *const c_void {
        self.as_ref() as *const T as *const c_void
    }
}

impl<'a, T: ?Sized> StableDeref<'a> for &'a Arc<T> {
    fn stable_deref(&self) -> *const c_void {
        self.as_ref() as *const T as *const c_void
    }
}

impl<'a, T: ?Sized> StableDeref<'a> for &'a Pin<Box<T>> {
    fn stable_deref(&self) -> *const c_void {
        self.as_ref().get_ref() as *const T as *const c_void
    }
}

use std::sync::Arc;

impl<'a> Reference<'a> {
    /// Create a reference from any type that implements StableDeref.
    /// This includes &Box<T>, &Arc<T>, and &Pin<Box<T>>.
    pub fn new<S: StableDeref<'a>>(data: S) -> Self {
        let ptr = data.stable_deref();
        debug_assert!(!ptr.is_null(), "Reference created with null pointer");

        Self {
            data: ptr,
            _marker: PhantomData,
        }
    }

    /// Create a reference from a Box.
    ///
    /// Box guarantees a stable heap address, making it safe for FFI.
    #[allow(clippy::borrowed_box)]
    pub fn from_box<T: ?Sized>(data: &'a Box<T>) -> Self {
        let ptr = data.as_ref() as *const T as *const c_void;
        debug_assert!(!ptr.is_null(), "Reference created with null pointer");

        Self {
            data: ptr,
            _marker: PhantomData,
        }
    }

    /// Create a reference from an Arc.
    ///
    /// Arc guarantees a stable heap address, making it safe for FFI.
    pub fn from_arc<T: ?Sized>(data: &'a Arc<T>) -> Self {
        let ptr = data.as_ref() as *const T as *const c_void;
        debug_assert!(!ptr.is_null(), "Reference created with null pointer");

        Self {
            data: ptr,
            _marker: PhantomData,
        }
    }

    /// Create a reference from a pinned Box.
    ///
    /// This is the safest option as it guarantees the data cannot be moved.
    pub fn from_pin_box<T: ?Sized>(data: &'a Pin<Box<T>>) -> Self {
        let ptr = data.as_ref().get_ref() as *const T as *const c_void;
        debug_assert!(!ptr.is_null(), "Reference created with null pointer");

        Self {
            data: ptr,
            _marker: PhantomData,
        }
    }

    /// Create a reference from data with a stable address.
    ///
    /// # Safety
    /// The caller must guarantee that `data` has a stable address for its entire
    /// lifetime. This is automatically true for:
    /// - Heap allocated types (Box, Arc, Vec's data, String's data)
    /// - Static data
    /// - Pinned data
    ///
    /// This is NOT safe for:
    /// - Stack allocated data that might move
    /// - Data inside collections that might reallocate
    pub unsafe fn from_stable<T: ?Sized>(data: &'a T) -> Self {
        let ptr = data as *const T as *const c_void;
        debug_assert!(!ptr.is_null(), "Reference created with null pointer");

        Self {
            data: ptr,
            _marker: PhantomData,
        }
    }

    /// Create a reference from a raw pointer.
    ///
    /// # Safety
    /// The caller must ensure that:
    /// 1. The pointer is valid and non-null
    /// 2. The pointed-to data outlives 'a
    /// 3. The data won't be moved or freed while this reference exists
    pub unsafe fn from_ptr(ptr: *const c_void) -> Self {
        debug_assert!(!ptr.is_null(), "Reference created with null pointer");
        Self {
            data: ptr,
            _marker: PhantomData,
        }
    }
}

impl<'a> ArgDataMethods for Reference<'a> {
    fn type_(&self) -> DataType {
        DataType::Reference
    }

    fn len(&self) -> usize {
        1
    }

    fn as_c_ptr(&self) -> *const c_void {
        self.data
    }
}

pub trait CallbackPtr {
    #[doc(hidden)]
    #[allow(clippy::wrong_self_convention)]
    fn to_ptr(self) -> *const c_void;
}

unsafe impl Send for Callback<'static> {}
unsafe impl Sync for Callback<'static> {}

/// See [`ArgData`] for details.
#[derive(Debug, Clone)]
pub struct Callback<'a> {
    data: *const c_void,
    _marker: PhantomData<&'a mut ()>,
}

impl<'a> Callback<'a> {
    pub fn new<T: CallbackPtr>(data: T) -> Self {
        Self {
            data: data.to_ptr(),
            _marker: PhantomData,
        }
    }
}

impl<'a> ArgDataMethods for Callback<'a> {
    fn type_(&self) -> DataType {
        DataType::Reference
    }

    fn len(&self) -> usize {
        1
    }

    fn as_c_ptr(&self) -> *const c_void {
        self.data
    }
}

/// See [`ArgData`] for details.
#[derive(Debug, Clone)]
pub struct String {
    #[allow(dead_code)]
    data: CString,
    // The FFI API needs a pointer to a C string.
    pointer: *const c_void,
}

unsafe impl Send for String {}
unsafe impl Sync for String {}

impl String {
    pub fn new<T: Into<Vec<u8>>>(data: T) -> Self {
        let data = CString::new(data).unwrap();
        let pointer = data.as_ptr() as _;

        String { data, pointer }
    }
}

impl ArgDataMethods for String {
    fn type_(&self) -> DataType {
        DataType::String
    }

    fn len(&self) -> usize {
        1
    }

    fn as_c_ptr(&self) -> *const c_void {
        &self.pointer as *const *const c_void as _
    }
}

nsi_data_array_def!(f32, F32Slice, DataType::F32);
nsi_data_array_def!(f64, F64Slice, DataType::F64);
nsi_data_array_def!(i32, I32Slice, DataType::I32);
nsi_data_array_def!(i64, I64Slice, DataType::I64);
nsi_tuple_data_array_def!(f32, ColorSlice, DataType::Color, 3);
nsi_tuple_data_array_def!(f32, PointSlice, DataType::Point, 3);
nsi_tuple_data_array_def!(f32, VectorSlice, DataType::Vector, 3);
nsi_tuple_data_array_def!(f32, NormalSlice, DataType::Normal, 3);
nsi_tuple_data_array_def!(f32, MatrixF32Slice, DataType::MatrixF32, 16);
nsi_tuple_data_array_def!(f64, MatrixF64Slice, DataType::MatrixF64, 16);

/// Slice of weighted (rational) homogeneous 4-component f32 control points
/// — backing for [`point4_f32_slice!`][crate::point4_f32_slice] (NURBS
/// rational positions `Pw`, RGBA-style colour-with-alpha attributes, etc.).
///
/// On the wire this is a flat `NSITypeFloat` slice — the renderer infers
/// the 4-component grouping from the attribute name (`Pw`). The wrapper
/// exists so callers can keep the natural `&[[f32; 4]]` shape in Rust
/// while the FFI sees `4 * N` flat floats.
#[derive(Debug, Clone, PartialEq)]
pub struct Point4F32Slice<'a> {
    data: &'a [[f32; 4]],
}

impl<'a> Point4F32Slice<'a> {
    pub fn new(data: &'a [[f32; 4]]) -> Self {
        Self { data }
    }
}

impl<'a> ArgDataMethods for Point4F32Slice<'a> {
    fn type_(&self) -> DataType {
        DataType::F32
    }

    /// Total flat `f32` count = `4 * number-of-points`. With the
    /// default `arraylength = 1` the renderer receives that many
    /// scalar floats and groups them by attribute semantics.
    fn len(&self) -> usize {
        self.data.len() * 4
    }

    fn as_c_ptr(&self) -> *const c_void {
        self.data.as_ptr() as _
    }
}

/// See [`ArgData`] for details.
#[derive(Debug, Clone)]
pub struct ReferenceSlice<'a> {
    data: Vec<*const c_void>,
    _marker: PhantomData<&'a ()>,
}

unsafe impl Send for ReferenceSlice<'static> {}
unsafe impl Sync for ReferenceSlice<'static> {}

impl<'a> ReferenceSlice<'a> {
    pub fn new<T>(data: &'a [&'a T]) -> Self {
        debug_assert_eq!(0, data.len() % DataType::Reference.elemensize());

        Self {
            data: data.iter().map(|r| r as *const _ as _).collect(),
            _marker: PhantomData,
        }
    }
}

impl<'a> ArgDataMethods for ReferenceSlice<'a> {
    fn type_(&self) -> DataType {
        DataType::Reference
    }

    fn len(&self) -> usize {
        self.data.len() / DataType::Reference.elemensize()
    }

    fn as_c_ptr(&self) -> *const c_void {
        self.data.as_ptr() as _
    }
}

/// See [`ArgData`] for details.
#[derive(Debug, Clone)]
pub struct StringSlice {
    #[allow(dead_code)]
    data: Vec<CString>,
    pointer: Vec<*const c_void>,
}

unsafe impl Send for StringSlice {}
unsafe impl Sync for StringSlice {}

impl StringSlice {
    pub fn new<T: Into<Vec<u8>> + Copy>(data: &[T]) -> Self {
        let data = data
            .iter()
            .map(|s| CString::new(*s).unwrap())
            .collect::<Vec<_>>();
        let pointer = data.iter().map(|s| s.as_ptr() as _).collect();

        StringSlice { data, pointer }
    }
}

impl ArgDataMethods for StringSlice {
    fn type_(&self) -> DataType {
        DataType::String
    }

    fn len(&self) -> usize {
        self.pointer.len()
    }

    fn as_c_ptr(&self) -> *const c_void {
        self.pointer.as_ptr() as _
    }
}

nsi_tuple_data_def!(f32, 3, Color, DataType::Color);
nsi_tuple_data_def!(f32, 3, Point, DataType::Point);
nsi_tuple_data_def!(f32, 3, Vector, DataType::Vector);
nsi_tuple_data_def!(f32, 3, Normal, DataType::Normal);
nsi_tuple_data_def!(f32, 16, MatrixF32, DataType::MatrixF32);
nsi_tuple_data_def!(f64, 16, MatrixF64, DataType::MatrixF64);

/// Identifies an [`Arg`]’s data type.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
#[repr(i32)]
pub(crate) enum DataType {
    /// A single [`f32`] value.
    F32 = NSIType::F32 as _,
    /// A single [`f64`] value.
    F64 = NSIType::F64 as _,
    /// Single [`i32`] value.
    I32 = NSIType::I32 as _,
    /// Single [`i64`] value.
    I64 = NSIType::I64 as _,
    /// A [`String`].
    String = NSIType::String as _,
    /// Color, given as three [`f32`] values,
    /// usually in the range `0..1`. Red would e.g. be `[1.0, 0.0,
    /// 0.0]. Assumed to be in a linear color space.`
    Color = NSIType::Color as _,
    /// Point, given as three [`f32`] values.
    Point = NSIType::Point as _,
    /// Vector, given as three [`f32`] values.
    Vector = NSIType::Vector as _,
    /// Normal vector, given as three [`f32`] values.
    Normal = NSIType::Normal as _,
    /// Transformation matrix, given as 16 [`f32`] values.
    MatrixF32 = NSIType::MatrixF32 as _,
    /// Transformation matrix, given as 16 [`f64`] values.
    MatrixF64 = NSIType::MatrixF64 as _,
    /// Raw (`*const T`) pointer.
    Reference = NSIType::Pointer as _,
}

impl DataType {
    /// Returns the number of components of the resp. type.
    #[inline]
    pub(crate) fn elemensize(&self) -> usize {
        match self {
            DataType::F32 => 1,
            DataType::F64 => 1,
            DataType::I32 => 1,
            DataType::I64 => 1,
            DataType::String => 1,
            DataType::Color => 3,
            DataType::Point => 3,
            DataType::Vector => 3,
            DataType::Normal => 3,
            DataType::MatrixF32 => 16,
            DataType::MatrixF64 => 16,
            DataType::Reference => 1,
        }
    }
}

/// Create a [`F32`] argument.
///
/// Name accepts a string literal (escape hatch) or a typed
/// [`Attribute<f32>`](crate::Attribute) / [`Parameter<f32>`](crate::Parameter)
/// constant (compile-time type-checked).
#[macro_export]
macro_rules! f32 {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::F32::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<f32> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::F32::new($value)),
        )
    }};
}

/// Create a [`F32Slice`] array argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<[f32]>`](crate::Attribute) constant.
#[macro_export]
macro_rules! f32_slice {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::F32Slice::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<[f32]> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::F32Slice::new($value)),
        )
    }};
}

/// Create a [`F64`] precision argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<f64>`](crate::Attribute) constant.
#[macro_export]
macro_rules! f64 {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::F64::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<f64> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::F64::new($value)),
        )
    }};
}

/// Create a [`F64Slice`] precision array argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<[f64]>`](crate::Attribute) constant.
#[macro_export]
macro_rules! f64_slice {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::F64Slice::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<[f64]> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::F64Slice::new($value)),
        )
    }};
}

/// Create a [`I32`] argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<i32>`](crate::Attribute) constant.
#[macro_export]
macro_rules! i32 {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::I32::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<i32> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::I32::new($value)),
        )
    }};
}

/// Create a [`I32Slice`] array argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<[i32]>`](crate::Attribute) constant.
#[macro_export]
macro_rules! i32_slice {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::I32Slice::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<[i32]> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::I32Slice::new($value)),
        )
    }};
}

/// Create a [`I64`] argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<i64>`](crate::Attribute) constant.
#[macro_export]
macro_rules! i64 {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::I64::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<i64> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::I64::new($value)),
        )
    }};
}

/// Create a [`I64Slice`] array argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<[i64]>`](crate::Attribute) constant.
#[macro_export]
macro_rules! i64_slice {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::I64Slice::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<[i64]> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::I64Slice::new($value)),
        )
    }};
}

/// Create a [`Color`] argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<Color3F32>`](crate::Attribute) constant.
#[macro_export]
macro_rules! color {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::Color::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<$crate::Color3F32> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::Color::new($value)),
        )
    }};
}

/// Create a [`ColorSlice`] array argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<[Color3F32]>`](crate::Attribute) constant.
#[macro_export]
macro_rules! color_slice {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::ColorSlice::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<[$crate::Color3F32]> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::ColorSlice::new($value)),
        )
    }};
}

/// Create a [`Point`] argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<Point3F32>`](crate::Attribute) constant.
#[macro_export]
macro_rules! point {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::Point::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<$crate::Point3F32> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::Point::new($value)),
        )
    }};
}

/// Create a [`PointSlice`] array argument.
///
/// First argument may be either:
/// * a string literal (escape hatch — no static check), or
/// * a typed name constant of type [`Attribute<[Point3F32]>`](crate::Attribute) /
///   [`Parameter<[Point3F32]>`](crate::Parameter) (compile-time type-checked).
#[macro_export]
macro_rules! point_slice {
    // String-literal name -- legacy / escape hatch (no type check).
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::PointSlice::new($value)))
    };
    // Typed Attribute<[Point3F32]> path -- compile-time type-checked.
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<[$crate::Point3F32]> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::PointSlice::new($value)),
        )
    }};
}

/// Create a slice-of-4-component-f32-points argument.
///
/// Wraps a `&[[f32; 4]]` (e.g. weighted homogeneous control points
/// `Pw` for NURBS, RGBA colour-with-alpha attributes, or any other
/// 4-float-per-element vertex datum) and sends it as a **flat**
/// `NSITypeFloat` slice — the renderer groups the floats into
/// 4-tuples by attribute name, analogous to how `uknot`/`vknot` are
/// flat float slices.
///
/// Name accepts:
/// * a string literal (escape hatch — no static check), or
/// * a typed name constant of type
///   [`Attribute<[Point4F32]>`](crate::Attribute) / [`Parameter<[Point4F32]>`](crate::Parameter)
///   (compile-time type-checked, e.g. [`WEIGHTED_POSITION`](crate::WEIGHTED_POSITION)).
#[macro_export]
macro_rules! point4_f32_slice {
    // String-literal name — legacy / escape hatch (no type check).
    ($name: literal, $value: expr) => {
        nsi::Arg::new(
            $name,
            nsi::ArgData::from(nsi::Point4F32Slice::new($value)),
        )
    };
    // Typed Attribute<[Point4F32]> path — compile-time type-checked.
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<[$crate::Point4F32]> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::Point4F32Slice::new($value)),
        )
    }};
}

/// Create a [`Vector`] argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<Vector3F32>`](crate::Attribute) constant.
#[macro_export]
macro_rules! vector {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::Vector::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<$crate::Vector3F32> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::Vector::new($value)),
        )
    }};
}

/// Create a [`VectorSlice`] array argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<[Vector3F32]>`](crate::Attribute) constant.
#[macro_export]
macro_rules! vector_slice {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::VectorSlice::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<[$crate::Vector3F32]> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::VectorSlice::new($value)),
        )
    }};
}

/// Create a [`Normal`] argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<Normal3F32>`](crate::Attribute) constant.
#[macro_export]
macro_rules! normal {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::Normal::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<$crate::Normal3F32> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::Normal::new($value)),
        )
    }};
}

/// Create a [`NormalSlice`] array argument.
///
/// Name accepts a string literal or a typed
/// [`Attribute<[Normal3F32]>`](crate::Attribute) constant.
#[macro_export]
macro_rules! normal_slice {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::NormalSlice::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<[$crate::Normal3F32]> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::NormalSlice::new($value)),
        )
    }};
}

/// Create a [`MatrixF32`] row-major, 4×4 transformation matrix argument.
/// The matrix is given as 16 [`f32`] values.
///
/// Name accepts a string literal or a typed
/// [`Attribute<Matrix4F32>`](crate::Attribute) constant.
#[macro_export]
macro_rules! matrix_f32 {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::MatrixF32::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<$crate::Matrix4F32> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::MatrixF32::new($value)),
        )
    }};
}

/// Create a [`MatrixF32Slice`] row-major, 4×4 transformation matrices argument.
/// Each matrix is given as 16 [`f32`] values.
///
/// Name accepts a string literal or a typed
/// [`Attribute<[Matrix4F32]>`](crate::Attribute) constant.
#[macro_export]
macro_rules! matrix_f32_slice {
    ($name: literal, $value: expr) => {
        nsi::Arg::new(
            $name,
            nsi::ArgData::from(nsi::MatrixF32Slice::new($value)),
        )
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<[$crate::Matrix4F32]> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::MatrixF32Slice::new($value)),
        )
    }};
}

/// Create a [`MatrixF64`] row-major, 4×4 transformation matrix argument.
/// The matrix is given as 16 [`f64`] values.
///
/// # Examples
///
/// ```
/// # use nsi_ffi_wrap as nsi;
/// # let ctx = nsi::Context::new(None).unwrap();
/// // Setup a transform node.
/// ctx.create("xform", nsi::TRANSFORM, None);
/// ctx.connect("xform", None, nsi::ROOT, "objects", None);
///
/// // Translate 5 units along z-axis.
/// ctx.set_attribute(
///     "xform",
///     &[nsi::matrix_f64!(
///         "transformationmatrix",
///         &[
///             1., 0., 0., 0., 0., 1., 0., 0., 0., 0., 1., 0., 0., 0., 5., 1.,
///         ]
///     )],
/// );
/// ```
#[macro_export]
macro_rules! matrix_f64 {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::MatrixF64::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<$crate::Matrix4F64> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::MatrixF64::new($value)),
        )
    }};
}

/// Create a [`MatrixF64Slice`] row-major, 4×4 transformation matrices argument.
/// Each matrix is given as 16 [`f64`] values.
///
/// Name accepts a string literal or a typed
/// [`Attribute<[Matrix4F64]>`](crate::Attribute) constant.
#[macro_export]
macro_rules! matrix_f64_slice {
    ($name: literal, $value: expr) => {
        nsi::Arg::new(
            $name,
            nsi::ArgData::from(nsi::MatrixF64Slice::new($value)),
        )
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<[$crate::Matrix4F64]> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::MatrixF64Slice::new($value)),
        )
    }};
}

/// Create a [`String`] argument.
///
/// # Examples
///
/// ```
/// # use nsi_ffi_wrap as nsi;
/// // Create rendering context.
/// let ctx =
///     nsi::Context::new(Some(&[nsi::string!("streamfilename", "stdout")]))
///         .expect("Could not create NSI context.");
/// ```
#[macro_export]
macro_rules! string {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::String::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<&'static str> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::String::new($value)),
        )
    }};
}

/// Create a [`String`] array argument.
///
/// # Examples
///
/// ```
/// # use nsi_ffi_wrap as nsi;
/// # let ctx = nsi::Context::new(None).unwrap();
/// // One of these is not an actor:
/// ctx.set_attribute(
///     "dummy",
///     &[nsi::string_slice!(
///         "actors",
///         &["Klaus Kinski", "Giorgio Moroder", "Rainer Brandt"]
///     )],
/// );
/// ```
#[macro_export]
macro_rules! string_slice {
    ($name: literal, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::StringSlice::new($value)))
    };
    ($name: path, $value: expr) => {{
        const __ATTR_CHECK: $crate::Attribute<[&'static str]> = $name;
        nsi::Arg::new(
            __ATTR_CHECK.name(),
            nsi::ArgData::from(nsi::StringSlice::new($value)),
        )
    }};
}

/// Create a [`Reference`] argument.
///
/// This macro accepts:
/// - `&Box<T>` - ReferenceSlice to boxed data
/// - `&Arc<T>` - ReferenceSlice to Arc'd data  
/// - `&Pin<Box<T>>` - ReferenceSlice to pinned boxes
///
/// For other types with stable addresses, use `reference_stable!` instead.
#[macro_export]
macro_rules! reference {
    ($name: tt, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::Reference::new($value)))
    };
}

/// Create a [`Reference`] argument from data with a stable address.
///
/// # Safety
/// You must ensure the data has a stable address (heap allocated, static, etc.)
/// and won't be moved for the lifetime of the reference.
#[macro_export]
macro_rules! reference_stable {
    ($name: tt, $value: expr) => {
        nsi::Arg::new(
            $name,
            nsi::ArgData::from(unsafe { nsi::Reference::from_stable($value) }),
        )
    };
}

/// Create a [`Reference`] array argument.
#[macro_export]
macro_rules! reference_slice {
    ($name: tt, $value: expr) => {
        nsi::Arg::new(
            $name,
            nsi::ArgData::from(nsi::ReferenceSlice::new($value)),
        )
    };
}

/// Create a [`Callback`] argument.
#[macro_export]
macro_rules! callback {
    ($name: tt, $value: expr) => {
        nsi::Arg::new($name, nsi::ArgData::from(nsi::Callback::new($value)))
    };
}