nsi_ffi_wrap/output/

mod.rs

#![cfg_attr(feature = "nightly", doc(cfg(feature = "output")))]
// The double-Box (`Box<Box<dyn Fn…>>`) pattern below is required for
// crossing the C-FFI boundary: a `Box<dyn Fn…>` is a fat pointer, and the
// outer Box makes it thin so it fits through `void*`. Clippy doesn't
// recognise the FFI shape and flags it as `redundant_allocation`. Same for
// the `new` constructor that returns a `*mut`-shaped state for ndspy to
// keep -- it's not idiomatic Rust but it IS the C-API contract.
#![allow(clippy::redundant_allocation)]
#![allow(clippy::new_ret_no_self)]
//! Output driver callbacks.
//!
//! This module provides type-safe, generic callback support for streaming pixel
//! data during and after renders. Callbacks are generic over pixel type (`f32`,
//! `u16`, `u8`, etc.) with zero runtime cost via monomorphization.
//!
//! ## Callback Types
//!
//! * [`FnOpen`] -- Called once when the output driver is opened by the renderer.
//!
//! * [`FnWrite`] -- Called for each bucket of pixel data. Generic over pixel
//!   type `T: PixelType`. Receives only the bucket data, not the full image.
//!
//! * [`FnFinish`] -- Called once when the output driver is closed. Does NOT
//!   receive pixel data (matching the C ndspy API). Use [`AccumulatingCallbacks`]
//!   if you need the full accumulated image.
//!
//! ## Pixel Types
//!
//! The callbacks are generic over pixel type via the [`PixelType`] trait.
//! Use the corresponding typed driver constant:
//!
//! * [`FERRIS_F32`] -- 32-bit float pixels.
//! * [`FERRIS_U32`]/[`FERRIS_I32`] -- 32-bit integer pixels.
//! * [`FERRIS_U16`]/[`FERRIS_I16`] -- 16-bit integer pixels.
//! * [`FERRIS_U8`]/[`FERRIS_I8`] -- 8-bit integer pixels.
//!
//! ## Example: Streaming buckets
//!
//! ```ignore
//! use nsi_ffi_wrap as nsi;
//! use std::sync::{Arc, Mutex};
//!
//! let pixels = Arc::new(Mutex::new(Vec::<f32>::new()));
//! let pixels_write = Arc::clone(&pixels);
//!
//! // Write callback receives each bucket as it's rendered.
//! let write = nsi::output::WriteCallback::<f32>::new(
//!     move |_name, width, _height, x0, x1, y0, y1, fmt, bucket: &[f32]| {
//!         let mut buf = pixels_write.lock().unwrap();
//!         // Accumulate bucket into full image buffer...
//!         nsi::output::Error::None
//!     },
//! );
//!
//! ctx.set_attribute(
//!     "driver",
//!     &[
//!         nsi::string!("drivername", nsi::output::FERRIS_F32),
//!         nsi::string!("imagefilename", "render"),
//!         nsi::callback!("callback.write", write),
//!     ],
//! );
//! ```
//!
//! ## Example: Using AccumulatingCallbacks
//!
//! For the common case where you need the full accumulated image at the end,
//! use [`AccumulatingCallbacks`]:
//!
//! ```ignore
//! use nsi_ffi_wrap as nsi;
//!
//! let (write, finish) = nsi::output::AccumulatingCallbacks::<f32>::new(
//!     |name, width, height, fmt, pixels: Vec<f32>| {
//!         // Called once with the complete accumulated image.
//!         write_exr(&name, width, height, &pixels);
//!         nsi::output::Error::None
//!     },
//! );
//!
//! ctx.set_attribute(
//!     "driver",
//!     &[
//!         nsi::string!("drivername", nsi::output::FERRIS_F32),
//!         nsi::string!("imagefilename", "render"),
//!         nsi::callback!("callback.write", write),
//!         nsi::callback!("callback.finish", finish),
//!     ],
//! );
//! ```
//!
//! ## Color Profiles
//!
//! The pixel color data that the renderer generates is linear and
//! scene-referred. I.e. relative to whatever units you used to describe
//! illuminants in your scene.
//!
//! Using the
//! [`"colorprofile"` attribute](https://nsi.readthedocs.io/en/latest/nodes.html?highlight=outputlayer#the-outputlayer-node)
//! of an [`OutputLayer`](crate::OUTPUT_LAYER) you can ask the
//! renderer to apply an [Open Color IO](https://opencolorio.org/) (OCIO)
//! [profile/LUT](https://github.com/colour-science/OpenColorIO-Configs/tree/feature/aces-1.2-config/aces_1.2/luts)
//! before quantizing (see below).
//!
//! Once OCIO has a [Rust wrapper](https://crates.io/crates/opencolorio) you can easily choose to
//! do these color conversions yourself. In the meantime there is the
//! [`colorspace`](https://crates.io/crates/colorspace) crate which has some useful profiles built
//! in, e.g. [ACEScg](https://en.wikipedia.org/wiki/Academy_Color_Encoding_System#ACEScg).
//!
//! ```
//! # use nsi_ffi_wrap as nsi;
//! # let ctx = nsi::Context::new(None).unwrap();
//! ctx.create("beauty", nsi::OUTPUT_LAYER, None);
//! ctx.set_attribute(
//!     "beauty",
//!     &[
//!         // The Ci variable comes from Open Shading Language.
//!         nsi::string!("variablename", "Ci"),
//!         // We want the pixel data 'display-referred' in sRGB and quantized down to 0.0..255.0.
//!         nsi::string!("colorprofile", "/home/luts/linear_to_sRGB.spi1d"),
//!         nsi::string!("scalarformat", "uint8"),
//!     ],
//! );
//! ```
//!
//! ## Quantization
//!
//! Using the [`"scalarformat"`
//! attribute](https://nsi.readthedocs.io/en/latest/nodes.html?highlight=outputlayer#the-outputlayer-node)
//! of an [`OutputLayer`](crate::OUTPUT_LAYER) you can ask the
//! renderer to quantize data down to a suitable range. For example, setting
//! this to `"uint16"` will get you valid `u16` values from `0.0..65535.0`, but
//! stored in the `f32`s of the `pixel_data` buffer. The value of `1.0` will map
//! to `65535.0` and everything above will be clipped. You can convert
//! such a value straight via `f32 as u16`.
//!
//! Unless you asked the renderer to also apply some color profile (see above)
//! the data is linear. To look good on a screen it needs to be made
//! display-referred.
//!
//! See the `output` example on how to do this with a simple, display-referred
//! `sRGB` curve.
use crate::argument::CallbackPtr;
use parking_lot::Mutex;
use std::{
    ffi::CStr,
    mem::{size_of, take},
    os::raw::{c_char, c_int, c_void},
    sync::Arc,
};

pub mod pixel_format;
pub use pixel_format::*;

pub mod pixel_type;
pub use pixel_type::*;

/// Driver name for f32 pixel type.
pub static FERRIS_F32: &str = "ferris_f32";
/// Driver name for u32 pixel type.
pub static FERRIS_U32: &str = "ferris_u32";
/// Driver name for i32 pixel type.
pub static FERRIS_I32: &str = "ferris_i32";
/// Driver name for u16 pixel type.
pub static FERRIS_U16: &str = "ferris_u16";
/// Driver name for i16 pixel type.
pub static FERRIS_I16: &str = "ferris_i16";
/// Driver name for u8 pixel type.
pub static FERRIS_U8: &str = "ferris_u8";
/// Driver name for i8 pixel type.
pub static FERRIS_I8: &str = "ferris_i8";

/// Legacy driver name - defaults to f32.
/// Deprecated: Use [`FERRIS_F32`], [`FERRIS_U16`], etc. for type-specific drivers.
#[deprecated(
    since = "0.9.0",
    note = "Use FERRIS_F32, FERRIS_U16, etc. for type-specific drivers"
)]
pub static FERRIS: &str = "ferris_f32";

/// An error type the callbacks return to communicate with the
/// renderer.
#[repr(u32)]
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, num_enum::IntoPrimitive)]
pub enum Error {
    /// Everything is dandy.
    None = ndspy_sys::PtDspyError::None as _,
    /// We ran out of memory.
    NoMemory = ndspy_sys::PtDspyError::NoMemory as _,
    /// We do no support this request.
    Unsupported = ndspy_sys::PtDspyError::Unsupported as _,
    BadParameters = ndspy_sys::PtDspyError::BadParams as _,
    NoResource = ndspy_sys::PtDspyError::NoResource as _,
    /// Something else went wrong.
    Undefined = ndspy_sys::PtDspyError::Undefined as _,
    /// Stop the render.
    Stop = ndspy_sys::PtDspyError::Stop as _,
}

impl From<Error> for ndspy_sys::PtDspyError {
    fn from(item: Error) -> ndspy_sys::PtDspyError {
        match item {
            Error::None => ndspy_sys::PtDspyError::None,
            Error::NoMemory => ndspy_sys::PtDspyError::NoMemory,
            Error::Unsupported => ndspy_sys::PtDspyError::Unsupported,
            Error::BadParameters => ndspy_sys::PtDspyError::BadParams,
            Error::NoResource => ndspy_sys::PtDspyError::NoResource,
            Error::Undefined => ndspy_sys::PtDspyError::Undefined,
            Error::Stop => ndspy_sys::PtDspyError::Stop,
        }
    }
}

/// A closure which is called once per
/// [`OutputDriver`](crate::OUTPUT_DRIVER) instance.
///
/// It is passed to ɴsɪ via the `"callback.open"` attribute on that node.
///
/// The closure is called once, before the renderer starts sending pixels to the
/// output driver.
///
/// # Arguments
/// The `pixel_format` parameter is an array of strings that details the
/// composition of the `f32` data that the renderer will send to the [`FnWrite`]
/// and/or [`FnFinish`] closures.
///
/// # Example
/// ```
/// # #[cfg(feature = "output")]
/// # {
/// # use nsi_ffi_wrap as nsi;
/// # use nsi::output::PixelFormat;
/// # let ctx = nsi::Context::new(None).unwrap();
/// # ctx.create("display_driver", nsi::OUTPUT_DRIVER, None);
/// let open = nsi::output::OpenCallback::new(
///     |name: &str,
///      width: usize,
///      height: usize,
///      pixel_format: &nsi::output::PixelFormat| {
///         println!(
///             "Resolution: {}×{}\nPixel Format:\n{:?}",
///             width, height, pixel_format
///         );
///         nsi::output::Error::None
///     },
/// );
/// # }
/// ```
pub trait FnOpen<'a>: FnMut(
    // Filename.
    &str,
    // Width.
    usize,
    // Height.
    usize,
    // Pixel format.
    &PixelFormat,
) -> Error
+ 'a {}

#[doc(hidden)]
impl<'a, T: FnMut(&str, usize, usize, &PixelFormat) -> Error + 'a> FnOpen<'a>
    for T
{
}

// FIXME once trait aliases are in stable.
/*
trait FnOpen<'a> = FnMut(
        // Filename.
        &str,
        // Width.
        usize,
        // Height.
        usize,
        // Pixel format.
        &PixelFormat,
    ) -> Error
    + 'a
*/

/// A closure which is called for each bucket of pixels the
/// [`OutputDriver`](crate::OUTPUT_DRIVER) instance sends
/// during rendering.
///
/// The closure receives ONLY the bucket data, not an accumulated image.
/// Bucket dimensions are: `(x_max_plus_one - x_min) x (y_max_plus_one - y_min)`.
/// Data layout is row-major with channels interleaved per pixel.
///
/// It is passed to ɴsɪ via the `"callback.write"` attribute on that node.
///
/// # Type Parameter
///
/// `T` is the pixel scalar type (e.g., `f32`, `u16`, `u8`). It must implement
/// [`PixelType`]. The driver name must match the type (e.g., `FERRIS_F32` for `f32`).
///
/// # Example
/// ```ignore
/// let write = nsi::output::WriteCallback::<f32>::new(
///     |name: &str,
///      width: usize,
///      height: usize,
///      x_min: usize,
///      x_max_plus_one: usize,
///      y_min: usize,
///      y_max_plus_one: usize,
///      pixel_format: &nsi::output::PixelFormat,
///      bucket_data: &[f32]| {
///         // bucket_data contains ONLY this bucket, not the full image
///         // Upload bucket to GPU texture, etc.
///         nsi::output::Error::None
///     },
/// );
///
/// ctx.set_attribute(
///     "driver",
///     &[
///         nsi::string!("drivername", nsi::output::FERRIS_F32),
///         nsi::callback!("callback.write", write),
///     ],
/// );
/// ```
pub trait FnWrite<'a, T: PixelType>: Fn(
        // Filename.
        &str,
        // Full image width.
        usize,
        // Full image height.
        usize,
        // Bucket x_min.
        usize,
        // Bucket x_max_plus_one.
        usize,
        // Bucket y_min.
        usize,
        // Bucket y_max_plus_one.
        usize,
        // Pixel format.
        &PixelFormat,
        // Bucket pixel data (NOT the full image!).
        &[T],
    ) -> Error
    + Sync
    + 'a {}

#[doc(hidden)]
impl<'a, T: PixelType, F> FnWrite<'a, T> for F where
    F: Fn(
            &str,
            usize,
            usize,
            usize,
            usize,
            usize,
            usize,
            &PixelFormat,
            &[T],
        ) -> Error
        + Sync
        + 'a
{
}

/// A closure which is called once per
/// [`OutputDriver`](crate::OUTPUT_DRIVER) instance when rendering completes.
///
/// It is passed to ɴsɪ via the `"callback.finish"` attribute on that node.
///
/// **Note:** This closure does NOT receive pixel data. This matches the C ndspy
/// API behavior where the display driver is responsible for accumulating pixels
/// if needed. Use [`AccumulatingCallbacks`] if you need the complete image.
///
/// # Example
/// ```ignore
/// let finish = nsi::output::FinishCallback::new(
///     |name: String,
///      width: usize,
///      height: usize,
///      pixel_format: nsi::output::PixelFormat| {
///         println!("Rendering complete: {}x{}", width, height);
///         nsi::output::Error::None
///     },
/// );
///
/// ctx.set_attribute(
///     "driver",
///     &[
///         nsi::string!("drivername", nsi::output::FERRIS_F32),
///         nsi::callback!("callback.finish", finish),
///     ],
/// );
/// ```
pub trait FnFinish<'a>: FnMut(
    // Filename.
    String,
    // Width.
    usize,
    // Height.
    usize,
    // Pixel format.
    PixelFormat,
) -> Error
+ 'a {}

#[doc(hidden)]
impl<'a, F> FnFinish<'a> for F where
    F: FnMut(String, usize, usize, PixelFormat) -> Error + 'a
{
}

enum Query {}

trait FnQuery<'a>: FnMut(Query) -> Error + 'a {}
impl<'a, T: FnMut(Query) -> Error + 'a> FnQuery<'a> for T {}

// FIXME once trait aliases are in stable.
/*
pub trait FnQuery<'a> = dyn FnMut(Query) -> Error + 'a;
*/

/// Wrapper to pass an [`FnOpen`] closure to an
/// [`OutputDriver`](crate::OUTPUT_DRIVER) node.
pub struct OpenCallback<'a>(Box<Box<dyn FnOpen<'a>>>);

// A `Box<dyn Trait>` is a fat pointer (data + vtable), which cannot cross
// the C boundary; one more `Box` makes it thin. That is the whole reason
// for the double `Box` -- and, correspondingly, for `Box<Box<T>>` being
// the type `extract_callback` reads back.
//
// This used to be a *triple* `Box`, which was compensating for
// `Callback::as_c_ptr` handing ɴsɪ the pointer where ɴsɪ expects the
// address of the pointer. The renderer's extra dereference consumed the
// extra layer. With the marshalling fixed, two layers are correct; see
// `argument::pointer_marshalling_tests` and `ffi_round_trip_tests`.
impl<'a> OpenCallback<'a> {
    pub fn new<F>(fn_open: F) -> Self
    where
        F: FnOpen<'a>,
    {
        OpenCallback(Box::new(Box::new(fn_open)))
    }
}

impl CallbackPtr for OpenCallback<'_> {
    #[doc(hidden)]
    fn to_ptr(self) -> *const core::ffi::c_void {
        Box::into_raw(self.0) as *const _ as _
    }

    #[doc(hidden)]
    unsafe fn drop_ptr(ptr: *const core::ffi::c_void) {
        // The lifetime is erased here; drop glue lives in the vtable, so
        // reclaiming through any lifetime runs the right destructor.
        // SAFETY: `ptr` came from `to_ptr` above and is reclaimed once.
        drop(unsafe { Box::from_raw(ptr as *mut Box<dyn FnOpen<'static>>) });
    }
}
/// Wrapper to pass an [`FnWrite`] closure to an
/// [`OutputDriver`](crate::OUTPUT_DRIVER) node.
///
/// # Type Parameter
///
/// `T` is the pixel scalar type. Use the matching driver name:
/// - `WriteCallback::<f32>` with `FERRIS_F32`
/// - `WriteCallback::<u16>` with `FERRIS_U16`
/// - etc.
pub struct WriteCallback<'a, T: PixelType>(Box<Box<dyn FnWrite<'a, T>>>);

impl<'a, T: PixelType> WriteCallback<'a, T> {
    pub fn new<F>(fn_write: F) -> Self
    where
        F: FnWrite<'a, T>,
    {
        WriteCallback(Box::new(Box::new(fn_write)))
    }
}

impl<T: PixelType> CallbackPtr for WriteCallback<'_, T> {
    #[doc(hidden)]
    fn to_ptr(self) -> *const core::ffi::c_void {
        Box::into_raw(self.0) as *const _ as _
    }

    #[doc(hidden)]
    unsafe fn drop_ptr(ptr: *const core::ffi::c_void) {
        // SAFETY: `ptr` came from `to_ptr` above and is reclaimed once.
        drop(unsafe {
            Box::from_raw(ptr as *mut Box<dyn FnWrite<'static, T>>)
        });
    }
}

/// Wrapper to pass an [`FnFinish`] closure to an
/// [`OutputDriver`](crate::OUTPUT_DRIVER) node.
///
/// **Note:** `FnFinish` does not receive pixel data. If you need the complete
/// accumulated image, use [`AccumulatingCallbacks`] instead.
pub struct FinishCallback<'a>(Box<Box<dyn FnFinish<'a>>>);

impl<'a> FinishCallback<'a> {
    pub fn new<F>(fn_finish: F) -> Self
    where
        F: FnFinish<'a>,
    {
        FinishCallback(Box::new(Box::new(fn_finish)))
    }
}

impl CallbackPtr for FinishCallback<'_> {
    #[doc(hidden)]
    fn to_ptr(self) -> *const core::ffi::c_void {
        Box::into_raw(self.0) as *const _ as _
    }

    #[doc(hidden)]
    unsafe fn drop_ptr(ptr: *const core::ffi::c_void) {
        // SAFETY: `ptr` came from `to_ptr` above and is reclaimed once.
        drop(unsafe { Box::from_raw(ptr as *mut Box<dyn FnFinish<'static>>) });
    }
}

/// Internal data structure passed through FFI as the image handle.
/// Generic over pixel type T for zero-cost type handling.
struct DisplayData<'a, T: PixelType> {
    name: String,
    width: usize,
    height: usize,
    pixel_format: PixelFormat,
    // NO pixel_data buffer - we pass buckets directly to callbacks
    // Non-owning: these point into the renderer's memory (see
    // `extract_callback`). Dropping them would free memory we do not own.
    fn_write: Option<*mut Box<dyn FnWrite<'a, T>>>,
    fn_finish: Option<*mut Box<dyn FnFinish<'a>>>,
    // FIXME: unused atm.
    #[allow(dead_code)]
    fn_query: Option<*mut Box<dyn FnQuery<'a>>>,
    // PhantomData to ensure T is used
    _phantom: std::marker::PhantomData<T>,
}

/// Reads a callback pointer back out of the parameters ndspy hands the
/// driver.
///
/// `UserParameter::value` is a `void**`: it addresses the renderer's own
/// copy of the pointer we passed to ɴsɪ. So we read the pointer *out of*
/// that cell and return it without taking ownership -- the cell belongs to
/// the renderer, and `Box::from_raw`-ing it frees memory we never
/// allocated (`free(): invalid pointer`).
fn extract_callback<T: ?Sized>(
    name: &str,
    type_: u8,
    len: usize,
    parameters: &[ndspy_sys::UserParameter],
) -> Option<*mut Box<T>> {
    for p in parameters.iter() {
        // SAFETY: Parameter names come from NSI API and should be valid C strings
        if p.name.is_null() {
            continue;
        }
        let p_name = match unsafe { CStr::from_ptr(p.name) }.to_str() {
            Ok(name) => name,
            Err(_) => continue,
        };

        if name == p_name
            && type_ == p.valueType as _
            && len == p.valueCount as _
        {
            if !p.value.is_null() {
                // SAFETY: `value` addresses the renderer's copy of the
                // pointer produced by the callback's `to_ptr`, and the
                // parameter type has been verified above. We copy that
                // pointer out; ownership stays with whoever allocated it.
                return Some(unsafe { *(p.value as *const *mut Box<T>) });
            } else {
                // Parameter exists but value is missing - exit quietly.
                break;
            }
        }
    }
    None
}

// Generic trampoline function for the FnOpen callback.
// Each instantiation (image_open::<f32>, image_open::<u16>, etc.) handles a specific pixel type.
pub(crate) extern "C" fn image_open<T: PixelType>(
    image_handle_ptr: *mut ndspy_sys::PtDspyImageHandle,
    _driver_name: *const c_char,
    output_filename: *const c_char,
    width: c_int,
    height: c_int,
    parameters_count: c_int,
    parameters: *const ndspy_sys::UserParameter,
    format_count: c_int,
    format: *mut ndspy_sys::PtDspyDevFormat,
    flag_stuff: *mut ndspy_sys::PtFlagStuff,
) -> ndspy_sys::PtDspyError {
    // Catch any panics to prevent unwinding into C code.
    match std::panic::catch_unwind(|| {
        if (image_handle_ptr.is_null())
            || (output_filename.is_null())
            || format.is_null()
            || (format_count <= 0)
            || ((parameters_count > 0) && parameters.is_null())
        {
            return Error::BadParameters.into();
        }

        // SAFETY: We only read from the parameters slice, never modify it.
        let parameters = unsafe {
            std::slice::from_raw_parts(parameters, parameters_count as _)
        };

        let mut display_data = Box::new(DisplayData::<T> {
            name: {
                // SAFETY: output_filename is checked for null above and comes from NSI C API
                let c_str = unsafe { CStr::from_ptr(output_filename) };
                c_str.to_string_lossy().into_owned()
            },
            width: width as _,
            height: height as _,
            pixel_format: PixelFormat::default(),
            // NO pixel_data allocation - we pass buckets directly
            fn_write: extract_callback::<dyn FnWrite<T>>(
                "callback.write",
                b'p',
                1,
                parameters,
            ),
            fn_finish: extract_callback::<dyn FnFinish>(
                "callback.finish",
                b'p',
                1,
                parameters,
            ),
            fn_query: None,
            _phantom: std::marker::PhantomData,
        });

        // SAFETY: format is a valid pointer to format_count elements from NSI C API.
        let format = unsafe {
            std::slice::from_raw_parts_mut(format, format_count as _)
        };

        // Set format to the requested pixel type T
        format.iter_mut().for_each(|f| f.type_ = T::NDSPY_TYPE);

        display_data.pixel_format = PixelFormat::new(format);

        let error = if let Some(fn_open) =
            extract_callback::<dyn FnOpen>("callback.open", b'p', 1, parameters)
        {
            // SAFETY: `fn_open` is the pointer the caller handed to ɴsɪ via
            // `callback!`; it stays alive for as long as the node holds the
            // attribute. We borrow it, we do not own it.
            let fn_open = unsafe { &mut *fn_open };
            fn_open(
                &display_data.name,
                width as _,
                height as _,
                &display_data.pixel_format,
            )
        } else {
            Error::None
        };

        // SAFETY: image_handle_ptr and flag_stuff are valid pointers from NSI C API
        unsafe {
            *image_handle_ptr = Box::into_raw(display_data) as _;
            // Preserve renderer-provided flags, but clear the empty-bucket request.
            (*flag_stuff).flags &=
                !(ndspy_sys::PkDspyFlagsWantsEmptyBuckets as i32);
        }

        error.into()
    }) {
        Ok(result) => result,
        Err(_) => {
            // If we panicked, return an error to the renderer
            Error::Undefined.into()
        }
    }
}

// FIXME: this will be used for a FnProgress callback later.
#[unsafe(no_mangle)]
pub(crate) extern "C" fn image_query(
    _image_handle_ptr: ndspy_sys::PtDspyImageHandle,
    query_type: ndspy_sys::PtDspyQueryType,
    data_len: c_int,
    data: *mut c_void,
) -> ndspy_sys::PtDspyError {
    // Catch any panics to prevent unwinding into C code.
    match std::panic::catch_unwind(|| {
        match query_type {
        ndspy_sys::PtDspyQueryType::RenderProgress => {
            if (data_len as usize)
                < core::mem::size_of::<ndspy_sys::PtDspyRenderProgressFuncPtr>()
                || data.is_null()
            {
                Error::BadParameters
            } else {
                // SAFETY: data is a valid pointer to PtDspyRenderProgressFuncPtr
                // as specified by the query type and validated by data_len check.
                unsafe {
                    let func_ptr = data as *mut ndspy_sys::PtDspyRenderProgressFuncPtr;
                    *func_ptr = Some(image_progress);
                }
                Error::None
            }
        }
        ndspy_sys::PtDspyQueryType::Progressive => {
            if (data_len as usize) < size_of::<ndspy_sys::PtDspyProgressiveInfo>()
                || data.is_null()
            {
                Error::BadParameters
            } else {
                // SAFETY: data points to PtDspyProgressiveInfo with validated length.
                unsafe {
                    let info = data as *mut ndspy_sys::PtDspyProgressiveInfo;
                    (*info).acceptProgressive = 1;
                }
                Error::None
            }
        }
        ndspy_sys::PtDspyQueryType::Thread => {
            if (data_len as usize) < size_of::<ndspy_sys::PtDspyThreadInfo>()
                || data.is_null()
            {
                Error::BadParameters
            } else {
                // SAFETY: data points to PtDspyThreadInfo with validated length.
                unsafe {
                    let info = data as *mut ndspy_sys::PtDspyThreadInfo;
                    // Allow multithreaded buckets.
                    (*info).multithread = 1;
                }
                Error::None
            }
        }
        ndspy_sys::PtDspyQueryType::Cooked => {
            if (data_len as usize) < size_of::<ndspy_sys::PtDspyCookedInfo>()
                || data.is_null()
            {
                Error::BadParameters
            } else {
                // SAFETY: data points to PtDspyCookedInfo with validated length.
                unsafe {
                    let info = data as *mut ndspy_sys::PtDspyCookedInfo;
                    // Accept filtered pixel data (cooked=1 = PkDspyCQDefault).
                    (*info).cooked = 1;
                }
                Error::None
            }
        }
        // StopQuery asks "should rendering stop?" - return None to continue.
        ndspy_sys::PtDspyQueryType::Stop => Error::None,
        ndspy_sys::PtDspyQueryType::Overwrite => {
            if (data_len as usize) < size_of::<ndspy_sys::PtDspyOverwriteInfo>()
                || data.is_null()
            {
                Error::BadParameters
            } else {
                // SAFETY: data points to PtDspyOverwriteInfo with validated length.
                unsafe {
                    let info = data as *mut ndspy_sys::PtDspyOverwriteInfo;
                    // Allow the renderer to overwrite existing files.
                    (*info).overwrite = 1;
                }
                Error::None
            }
        }
        _ => Error::Unsupported,
    }
    .into()
    }) {
        Ok(result) => result,
        Err(_) => {
            // If we panicked, return an error to the renderer
            Error::Undefined.into()
        }
    }
}

// Generic trampoline function for the FnWrite callback.
// Passes bucket data directly to callback - NO accumulation, NO memcpy to full buffer.
pub(crate) extern "C" fn image_write<T: PixelType>(
    image_handle_ptr: ndspy_sys::PtDspyImageHandle,
    x_min: c_int,
    x_max_plus_one: c_int,
    y_min: c_int,
    y_max_plus_one: c_int,
    _entry_size: c_int,
    pixel_data: *const u8,
) -> ndspy_sys::PtDspyError {
    // Catch any panics to prevent unwinding into C code
    match std::panic::catch_unwind(|| {
        // SAFETY: image_handle_ptr should be valid as it was created by image_open
        if image_handle_ptr.is_null() {
            return Error::BadParameters.into();
        }
        // Shared, not exclusive. We answer `multithread = 1`, so the
        // renderer may be inside this call on another thread; `&mut` here
        // would be two exclusive references to one `DisplayData`. Every
        // field read below is just that -- a read.
        let display_data =
            unsafe { &*(image_handle_ptr as *const DisplayData<T>) };

        let channels = display_data.pixel_format.channels();
        let bucket_width = (x_max_plus_one - x_min) as usize;
        let bucket_height = (y_max_plus_one - y_min) as usize;
        let bucket_pixel_count = bucket_width * bucket_height * channels;

        // SAFETY: pixel_data comes from the renderer and should be valid
        if pixel_data.is_null() {
            return Error::None.into();
        }

        // Zero-cost slice creation - just pointer reinterpretation, no copy!
        let bucket_data = unsafe {
            std::slice::from_raw_parts(
                pixel_data as *const T,
                bucket_pixel_count,
            )
        };

        // Pass bucket directly to callback - NO memcpy, NO accumulation!
        if let Some(fn_write) = display_data.fn_write {
            // Shared, not exclusive: we answer `multithread = 1` to
            // `PkThreadQuery`, so the renderer may be inside this call on
            // another thread right now. `FnWrite` is `Fn + Sync` for
            // exactly that reason -- taking `&mut` here would be two
            // exclusive references to one closure.
            // SAFETY: borrowed, renderer-owned; see `extract_callback`.
            let fn_write = unsafe { &*fn_write };
            fn_write(
                &display_data.name,
                display_data.width,
                display_data.height,
                x_min as _,
                x_max_plus_one as _,
                y_min as _,
                y_max_plus_one as _,
                &display_data.pixel_format,
                bucket_data, // Just the bucket!
            )
        } else {
            Error::None
        }
        .into()
    }) {
        Ok(result) => result,
        Err(_) => {
            // If we panicked, return an error to the renderer
            Error::Undefined.into()
        }
    }
}

// Generic trampoline function for the FnFinish callback.
// FnFinish does NOT receive pixel data - user accumulates if needed.
pub(crate) extern "C" fn image_close<T: PixelType>(
    image_handle_ptr: ndspy_sys::PtDspyImageHandle,
) -> ndspy_sys::PtDspyError {
    // Catch any panics to prevent unwinding into C code
    match std::panic::catch_unwind(|| {
        // SAFETY: image_handle_ptr should be valid as it was created by image_open
        if image_handle_ptr.is_null() {
            return Error::BadParameters.into();
        }
        let mut display_data =
            unsafe { Box::from_raw(image_handle_ptr as *mut DisplayData<T>) };

        // FnFinish receives no pixel data - user accumulates if needed
        let error = if let Some(fn_finish) = display_data.fn_finish {
            // SAFETY: borrowed, renderer-owned; see `extract_callback`.
            let fn_finish = unsafe { &mut *fn_finish };
            fn_finish(
                std::mem::take(&mut display_data.name),
                display_data.width,
                display_data.height,
                std::mem::take(&mut display_data.pixel_format),
            )
        } else {
            Error::None
        };

        // The callback fields are non-owning pointers into renderer memory,
        // so there is nothing to release here. The double-free this block
        // used to guard against was `extract_callback` claiming ownership
        // of the renderer's pointer cell; see its documentation.

        error.into()
    }) {
        Ok(result) => result,
        Err(_) => {
            // If we panicked, return an error to the renderer
            Error::Undefined.into()
        }
    }
}

#[unsafe(no_mangle)]
extern "C" fn image_progress(
    _image_handle_ptr: ndspy_sys::PtDspyImageHandle,
    _progress: f32,
) -> ndspy_sys::PtDspyError {
    // Progress logging disabled to reduce spam
    Error::None.into()
}

/// Helper for users who want the complete accumulated image at finish time.
///
/// The core API passes buckets directly to callbacks without accumulation.
/// This helper provides the common use case of receiving the complete image
/// when rendering finishes.
///
/// # Example
///
/// ```ignore
/// use std::sync::{Arc, Mutex};
///
/// // Create accumulating callbacks that deliver the full image at finish
/// let (write, finish) = nsi::output::AccumulatingCallbacks::<f32>::new(
///     |name, width, height, format, pixels| {
///         // Called once at end with complete accumulated image
///         save_image(&name, width, height, &pixels);
///         nsi::output::Error::None
///     },
/// );
///
/// ctx.set_attribute(
///     "driver",
///     &[
///         nsi::string!("drivername", nsi::output::FERRIS_F32),
///         nsi::callback!("callback.write", write),
///         nsi::callback!("callback.finish", finish),
///     ],
/// );
/// ```
pub struct AccumulatingCallbacks<T: PixelType> {
    _phantom: std::marker::PhantomData<T>,
}

impl<T: PixelType> AccumulatingCallbacks<T> {
    /// Create a pair of callbacks that accumulate pixels and deliver the
    /// complete image to the finish callback.
    ///
    /// Returns `(WriteCallback, FinishCallback)` where:
    /// - The write callback accumulates buckets into an internal buffer
    /// - The finish callback delivers the complete buffer to your closure
    pub fn new<'a, F>(
        mut on_finish: F,
    ) -> (WriteCallback<'a, T>, FinishCallback<'a>)
    where
        F: FnMut(String, usize, usize, PixelFormat, Vec<T>) -> Error + 'a,
    {
        // Shared state between write and finish callbacks.
        struct AccumState<T: PixelType> {
            buffer: Vec<T>,
            width: usize,
            height: usize,
            channels: usize,
            initialized: bool,
        }

        let state = Arc::new(Mutex::new(AccumState::<T> {
            buffer: Vec::new(),
            width: 0,
            height: 0,
            channels: 0,
            initialized: false,
        }));

        let write_state = state.clone();
        let finish_state = state;

        let write = WriteCallback::new(
            move |_name: &str,
                  width: usize,
                  height: usize,
                  x_min: usize,
                  x_max_plus_one: usize,
                  y_min: usize,
                  y_max_plus_one: usize,
                  format: &PixelFormat,
                  bucket_data: &[T]| {
                let mut state = write_state.lock();

                // Initialize on first bucket
                if !state.initialized {
                    state.width = width;
                    state.height = height;
                    state.channels = format.channels();
                    state.buffer =
                        vec![T::default(); width * height * state.channels];
                    state.initialized = true;
                }

                // Copy bucket into the full buffer
                let bucket_width = x_max_plus_one - x_min;
                let channels = state.channels;

                for y in y_min..y_max_plus_one {
                    let src_start = (y - y_min) * bucket_width * channels;
                    let dst_start = (y * state.width + x_min) * channels;
                    let row_len = bucket_width * channels;

                    state.buffer[dst_start..dst_start + row_len]
                        .copy_from_slice(
                            &bucket_data[src_start..src_start + row_len],
                        );
                }

                Error::None
            },
        );

        let finish = FinishCallback::new(
            move |name: String,
                  width: usize,
                  height: usize,
                  format: PixelFormat| {
                let mut state = finish_state.lock();
                let buffer = take(&mut state.buffer);
                // Release the lock before calling the user's callback.
                drop(state);

                on_finish(name, width, height, format, buffer)
            },
        );

        (write, finish)
    }
}

/// End-to-end shape of a callback's journey through the FFI boundary.
///
/// The driver trampolines are pure Rust -- they never call out through the
/// C API -- so Miri can execute the whole lifecycle, which is what makes
/// these a proof rather than a smoke test. Run them with:
///
/// ```text
/// cargo +nightly miri test -p nsi-ffi-wrap --features output --lib -- \
///     pointer_marshalling ffi_round_trip
/// ```
#[cfg(test)]
mod ffi_round_trip_tests {
    use super::*;
    use crate::{Arg, ArgData, Callback, argument::to_c_param_vec};
    use nsi_sys::NSIParam;
    use std::{
        cell::Cell,
        ffi::CString,
        rc::Rc,
        sync::{
            Arc,
            atomic::{AtomicUsize, Ordering},
        },
    };

    /// One ɴsɪ parameter as it reaches a display driver.
    ///
    /// Models the two hops between `set_attribute` and `DspyImageOpen`:
    ///
    /// 1. ɴsɪ copies one `void*` **out of** `NSIParam::data` and keeps its
    ///    own copy -- `data` addresses the value, it is not the value.
    /// 2. ndspy hands the driver the address of *that copy*, so
    ///    `UserParameter::value` is a `void**` into renderer memory.
    ///
    /// Verified against lib3delight 2.9.208 with a probe driver.
    struct RendererParam {
        name: CString,
        /// The renderer's own copy of the pointer. Boxed so its address is
        /// stable and distinct from ours, exactly like renderer memory.
        cell: Box<*const c_void>,
    }

    impl RendererParam {
        fn new(name: &str, param: &NSIParam) -> Self {
            // SAFETY: `data` addresses one `NSITypePointer` value.
            let value = unsafe { *(param.data as *const *const c_void) };
            Self {
                name: CString::new(name).unwrap(),
                cell: Box::new(value),
            }
        }

        fn as_user_parameter(&self) -> ndspy_sys::UserParameter {
            ndspy_sys::UserParameter {
                name: self.name.as_ptr(),
                valueType: b'p' as _,
                valueCount: 1,
                value: &*self.cell as *const *const c_void as *const c_void,
                nbytes: core::mem::size_of::<*const c_void>() as _,
            }
        }
    }

    /// Marshals `args` and returns them as the driver would see them.
    fn through_the_renderer(args: &[Arg]) -> Vec<RendererParam> {
        let (_, _, params) = to_c_param_vec(Some(args));
        args.iter()
            .zip(params.iter())
            .map(|(arg, param)| RendererParam::new(arg.name.as_str(), param))
            .collect()
    }

    #[test]
    fn open_callback_survives_the_round_trip() {
        let ran = Rc::new(Cell::new(false));
        let flag = Rc::clone(&ran);

        let args = [Arg::new(
            "callback.open",
            ArgData::from(Callback::new(OpenCallback::new(
                move |_: &str, _: usize, _: usize, _: &PixelFormat| {
                    flag.set(true);
                    Error::None
                },
            ))),
        )];
        let seen = through_the_renderer(&args);
        let user_params: Vec<_> =
            seen.iter().map(RendererParam::as_user_parameter).collect();

        let recovered = extract_callback::<dyn FnOpen>(
            "callback.open",
            b'p',
            1,
            &user_params,
        )
        .expect("the callback must be recoverable from the parameters");

        {
            // Borrow, exactly as the driver trampolines do. Owning this
            // would free the renderer's cell.
            // SAFETY: `recovered` is the pointer we handed to ɴsɪ above.
            let callback = unsafe { &mut *recovered };
            assert_eq!(
                Error::None,
                callback("beauty", 4, 4, &PixelFormat::default())
            );
        }
        assert!(
            ran.get(),
            "the closure handed to ɴsɪ must be the one invoked"
        );

        // The round trip must be lossless: what comes back is the very
        // pointer that went in, so its original owner can still reclaim it.
        // Miri's leak check is the assertion here.
        // SAFETY: nothing else owns this allocation.
        drop(unsafe { Box::from_raw(recovered) });
    }

    /// We answer `PkThreadQuery` with `multithread = 1`, so prove we
    /// honour it: drive `image_write` from two threads at once on one
    /// handle.
    ///
    /// `PkThreadQuery` is a 3Delight extension (`ndspy.h:167`) -- standard
    /// ndspy has no thread negotiation and the renderer serialises calls
    /// into the driver. Opting in is what makes `FnWrite: Fn + Sync`
    /// necessary: `image_write` takes a *shared* reference to one closure
    /// that two threads may be inside simultaneously. Taking `&mut` there
    /// -- which this crate did until this test existed -- is two exclusive
    /// references to the same `FnMut`.
    ///
    /// Run under Miri, whose data-race detector is the actual assertion:
    ///
    /// ```text
    /// cargo +nightly miri test -p nsi-ffi-wrap --features output --lib \
    ///     -- concurrent_buckets
    /// ```
    #[test]
    fn concurrent_buckets_are_honoured_not_just_advertised() {
        let mut info = ndspy_sys::PtDspyThreadInfo { multithread: 0 };
        let error = image_query(
            core::ptr::null_mut(),
            ndspy_sys::PtDspyQueryType::Thread,
            core::mem::size_of::<ndspy_sys::PtDspyThreadInfo>() as _,
            &mut info as *mut _ as *mut c_void,
        );
        assert_eq!(ndspy_sys::PtDspyError::None as u32, error as u32);
        assert_eq!(
            1, info.multithread,
            "we advertise concurrent buckets; the rest of this test is \
             what earns the right to"
        );

        let seen = Arc::new(AtomicUsize::new(0));
        let counted = Arc::clone(&seen);

        let args = [Arg::new(
            "callback.write",
            ArgData::from(Callback::new(WriteCallback::<f32>::new(
                move |_: &str,
                      _: usize,
                      _: usize,
                      _: usize,
                      _: usize,
                      _: usize,
                      _: usize,
                      _: &PixelFormat,
                      pixels: &[f32]| {
                    assert!(pixels.iter().all(|p| *p == 0.5));
                    counted.fetch_add(1, Ordering::SeqCst);
                    Error::None
                },
            ))),
        )];
        let params = through_the_renderer(&args);
        let user_params: Vec<_> = params
            .iter()
            .map(RendererParam::as_user_parameter)
            .collect();

        let layer_name = CString::new("beauty.000").unwrap();
        let mut format = [ndspy_sys::PtDspyDevFormat {
            name: layer_name.as_ptr(),
            type_: 0,
        }];
        let mut flags = ndspy_sys::PtFlagStuff { flags: 0 };
        let filename = CString::new("render").unwrap();
        let driver = CString::new("ferris_f32").unwrap();
        let mut handle: ndspy_sys::PtDspyImageHandle = core::ptr::null_mut();

        assert_eq!(
            ndspy_sys::PtDspyError::None as u32,
            image_open::<f32>(
                &mut handle,
                driver.as_ptr(),
                filename.as_ptr(),
                4,
                4,
                user_params.len() as _,
                user_params.as_ptr(),
                format.len() as _,
                format.as_mut_ptr(),
                &mut flags,
            ) as u32
        );

        let channels = PixelFormat::new(&format).channels();
        let bucket = vec![0.5f32; 2 * 2 * channels];

        // The renderer hands different regions to different threads; the
        // handle and the closure behind it are shared. Carried in a
        // newtype rather than as a `usize`, which would launder away the
        // pointer's provenance and blind Miri to exactly what we are
        // asking it to check.
        struct Shared(ndspy_sys::PtDspyImageHandle);
        // SAFETY: this is the renderer's contract under `multithread = 1`
        // -- the handle is used from several threads at once.
        unsafe impl Sync for Shared {}
        let shared = Shared(handle);

        std::thread::scope(|scope| {
            for y in 0..2 {
                let bucket = &bucket;
                let shared = &shared;
                scope.spawn(move || {
                    let error = image_write::<f32>(
                        shared.0,
                        0,
                        2,
                        y * 2,
                        y * 2 + 2,
                        core::mem::size_of::<f32>() as _,
                        bucket.as_ptr() as *const u8,
                    );
                    assert_eq!(
                        ndspy_sys::PtDspyError::None as u32,
                        error as u32
                    );
                });
            }
        });

        assert_eq!(
            2,
            seen.load(Ordering::SeqCst),
            "both concurrent buckets must reach the callback"
        );

        assert_eq!(
            ndspy_sys::PtDspyError::None as u32,
            image_close::<f32>(handle) as u32
        );
        // SAFETY: reclaim the one callback we handed over.
        unsafe { WriteCallback::<f32>::drop_ptr(*params[0].cell) };
    }

    /// The whole driver lifecycle, through the real trampolines: open, a
    /// bucket of pixels, then close. Nothing here calls out through the C
    /// API, so Miri executes every step and checks the memory it touches.
    #[test]
    fn the_driver_lifecycle_is_sound_end_to_end() {
        let opened = Rc::new(Cell::new(false));
        // Not `Rc<Cell<_>>`: `FnWrite` is `Fn + Sync`, because the
        // renderer may call the write path concurrently.
        let buckets = Arc::new(AtomicUsize::new(0));
        let finished = Rc::new(Cell::new(false));

        let open_flag = Rc::clone(&opened);
        let write_count = Arc::clone(&buckets);
        let finish_flag = Rc::clone(&finished);

        let args = [
            Arg::new(
                "callback.open",
                ArgData::from(Callback::new(OpenCallback::new(
                    move |_: &str, w: usize, h: usize, _: &PixelFormat| {
                        assert_eq!((4, 4), (w, h));
                        open_flag.set(true);
                        Error::None
                    },
                ))),
            ),
            Arg::new(
                "callback.write",
                ArgData::from(Callback::new(WriteCallback::<f32>::new(
                    move |_: &str,
                          _: usize,
                          _: usize,
                          x_min: usize,
                          x_max: usize,
                          y_min: usize,
                          y_max: usize,
                          format: &PixelFormat,
                          pixels: &[f32]| {
                        // The bucket must be exactly the region announced,
                        // one f32 per channel per pixel.
                        assert_eq!(
                            (x_max - x_min)
                                * (y_max - y_min)
                                * format.channels(),
                            pixels.len()
                        );
                        assert!(pixels.iter().all(|p| *p == 0.5));
                        write_count.fetch_add(1, Ordering::SeqCst);
                        Error::None
                    },
                ))),
            ),
            Arg::new(
                "callback.finish",
                ArgData::from(Callback::new(FinishCallback::new(
                    move |_: String, _: usize, _: usize, _: PixelFormat| {
                        finish_flag.set(true);
                        Error::None
                    },
                ))),
            ),
        ];
        let seen = through_the_renderer(&args);
        let user_params: Vec<_> =
            seen.iter().map(RendererParam::as_user_parameter).collect();

        // One single-channel layer, named the way ndspy names them.
        let layer_name = CString::new("beauty.000").unwrap();
        let mut format = [ndspy_sys::PtDspyDevFormat {
            name: layer_name.as_ptr(),
            type_: 0,
        }];
        let mut flags = ndspy_sys::PtFlagStuff { flags: 0 };
        let filename = CString::new("render").unwrap();
        let driver = CString::new("ferris_f32").unwrap();
        let mut handle: ndspy_sys::PtDspyImageHandle = core::ptr::null_mut();

        let error = image_open::<f32>(
            &mut handle,
            driver.as_ptr(),
            filename.as_ptr(),
            4,
            4,
            user_params.len() as _,
            user_params.as_ptr(),
            format.len() as _,
            format.as_mut_ptr(),
            &mut flags,
        );
        assert_eq!(
            ndspy_sys::PtDspyError::None as u32,
            error as u32,
            "image_open must accept the parameters"
        );
        assert!(opened.get(), "the open callback must have run");
        assert!(!handle.is_null(), "image_open must hand back a handle");

        // One 2x2 bucket, sized from the format the driver settled on.
        // Getting this wrong is a buffer overread, which is precisely the
        // kind of thing running this under Miri is meant to catch.
        let channels = PixelFormat::new(&format).channels();
        let bucket = vec![0.5f32; 2 * 2 * channels];
        let error = image_write::<f32>(
            handle,
            0,
            2,
            0,
            2,
            core::mem::size_of::<f32>() as _,
            bucket.as_ptr() as *const u8,
        );
        assert_eq!(ndspy_sys::PtDspyError::None as u32, error as u32);
        assert_eq!(
            1,
            buckets.load(Ordering::SeqCst),
            "the write callback must have run once"
        );

        let error = image_close::<f32>(handle);
        assert_eq!(ndspy_sys::PtDspyError::None as u32, error as u32);
        assert!(finished.get(), "the finish callback must have run");

        // Reclaim what we handed over -- the context does this in real use.
        // Miri's leak check verifies we get all of it back, and that
        // `image_close` did not free the renderer's memory on the way.
        for param in &seen {
            // SAFETY: each cell holds the pointer we produced above, and
            // each is reclaimed exactly once.
            unsafe {
                let ptr = *param.cell;
                if param.name.as_c_str() == c"callback.open" {
                    OpenCallback::drop_ptr(ptr);
                } else if param.name.as_c_str() == c"callback.write" {
                    WriteCallback::<f32>::drop_ptr(ptr);
                } else {
                    FinishCallback::drop_ptr(ptr);
                }
            }
        }
    }
}