embree3 0.4.1

//! Callback closures and user-data are mutated only through a `&mut
//! GeometryBuilder`, which is the *sole* `Arc<GeometryShared>` owner (`!Clone`,
//! `!Sync`, `strong_count == 1`). A geometry cannot be a builder while attached
//! to a scene or cloned (`try_edit` needs sole ownership). Therefore every
//! shared observer (for example other clones, `Scene::attach_geometry`'s
//! retained clone, and Embree's traversal threads) sees the state only *after*
//! it is frozen. Two distinct facts make this sound:
//!
//! 1. `Arc::get_mut == Some` proves **exclusivity**: while a write happens, no
//!    `&GeometryShared` reader exists at all
//! 2. the writes become **visible** to a later reader on another thread through
//!    the ordinary happens-before of the ownership move / thread handoff that
//!    separates them; entering Embree's parallel `commit`/traversal, or an
//!    `Arc` clone sent to another application thread.
//!
//! The refcount alone does *not* publish non-atomic `UnsafeCell` bytes; the
//! handoff does. The trampolines and `callback_data` perform plain reads with
//! no lock because, by (1)+(2), no write is ever concurrent with, or
//! unpublished before them.

use std::{
    any::Any, cell::UnsafeCell, collections::HashMap, marker::PhantomData, ptr, sync::Mutex,
};

use crate::{
    buffer::required_layout_bytes, callback::ErasedFn, sys::*, Bounds, Buffer, BufferData,
    BufferLayout, BufferSize, BufferSource, BufferUsage, BufferView, BufferViewMut, BuildQuality,
    Device, Error, Format, GeometryKind, Hit, HitN, IntersectContext, QuaternionDecomposition, Ray,
    RayN, Scene, SoAHit, SubdivisionMode, UserData,
};

use std::{
    borrow::Cow,
    ops::{Bound, Deref, DerefMut, Index, IndexMut, RangeBounds},
    os::raw::c_void,
    sync::Arc,
};

/// How a buffer is bound to a geometry slot (internal record; the public query
/// form is [`BufferSource`]). `Managed` owns a retained [`Buffer`] (no `'buf`
/// constraint); `Shared` borrows the caller's host bytes (ties `'buf`); `Local`
/// is embree-owned.
#[derive(Debug)]
pub(crate) enum AttachedBuffer<'buf> {
    Managed {
        buffer: Buffer,
        byte_offset: usize,
        layout: BufferLayout,
    },
    Shared {
        data: &'buf [u8],
        layout: BufferLayout,
    },
    Local {
        size: BufferSize,
        layout: BufferLayout,
    },
}

/// Identifies one of a geometry's callback slots.
///
/// Pass it to [`GeometryBuilder::callback_data`] /
/// [`Geometry::callback_data`] to read the owned data bound to a specific
/// callback. Internally it is also the **single source of truth** for slot
/// ordering: the (private) `CallSite` and `CallbackOwners` tables are arrays
/// indexed by `kind as usize`, so there is no parallel name↔index mapping to
/// drift.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(usize)]
pub enum CbKind {
    /// The intersect filter function
    /// ([`GeometryBuilder::set_intersect_filter_function`]).
    IntersectFilter,
    /// The occluded filter function
    /// ([`GeometryBuilder::set_occluded_filter_function`]).
    OccludedFilter,
    /// The user-geometry intersect function
    /// ([`GeometryBuilder::set_intersect_function`]).
    UserIntersect,
    /// The user-geometry occluded function
    /// ([`GeometryBuilder::set_occluded_function`]).
    UserOccluded,
    /// The user-geometry bounds function
    /// ([`GeometryBuilder::set_bounds_function`]).
    UserBounds,
    /// The displacement function
    /// ([`GeometryBuilder::set_displacement_function`]).
    Displacement,
}

impl CbKind {
    /// Number of callback kinds used for the length of the per-geometry
    /// callback slot arrays.
    pub const COUNT: usize = 6;
}

/// One callback slot, read by the trampoline on every invocation: a raw pointer
/// to the boxed closure plus *that callback's own* data pointer (null = no data
/// bound). Closure and data are bound together at the setter with a
/// statically-known `D`, so the trampoline which monomorphized over that same
/// `D`, casts `user_data` **unchecked**; there is no resolution table and no
/// `TypeId` on the hot path. The pointers are raw because the writer (the
/// unique `&mut GeometryBuilder`) and the reader (the embree trampoline) never
/// overlap (see the module invariant).
#[derive(Debug, Clone, Copy)]
#[repr(C)]
pub(crate) struct Slot {
    pub closure: *const (), // -> the boxed `F`; recovered as `&F` (monomorphized)
    pub user_data: *const (), // -> the callback's own `*const D`, or null
}

impl Slot {
    const EMPTY: Slot = Slot {
        closure: ptr::null(),
        user_data: ptr::null(),
    };
}

/// Hot, immutable-after-publish callback table that embree's `geometryUserPtr`
/// points directly at, so a trampoline resolves its closure + data with a
/// single indexed read and no pointer-chasing. `#[repr(C, align(64))]` puts it
/// on its own cache line(s), away from the cold `owners`/`attachments` that
/// share the enclosing `Arc` allocation, so concurrent reads from many
/// traversal threads never false-share with a builder's cold writes.
#[derive(Debug, Clone, Copy)]
#[repr(C, align(64))]
pub(crate) struct CallSite {
    pub slots: [Slot; CbKind::COUNT],
}

impl CallSite {
    const EMPTY: CallSite = CallSite {
        slots: [Slot::EMPTY; CbKind::COUNT],
    };
}

/// Cold side of the callback table: keeps each slot's boxed closure alive (the
/// `Slot.closure` raw pointer borrows from it) and, for *owned* data, the
/// `Box<dyn Any>` whose `Slot.user_data` points into. Borrowed data has no
/// entry here as the application owns it, kept valid by the geometry's `'buf`
/// lifetime. Indexed by `CbKind as usize`. Touched only by the builder setters
/// and [`callback_data`](GeometryBuilder::callback_data); never by a
/// trampoline.
#[derive(Debug, Default)]
pub(crate) struct CallbackOwners {
    pub closures: [Option<ErasedFn>; CbKind::COUNT],
    pub owned_data: [Option<Box<dyn Any + Send + Sync>>; CbKind::COUNT],
}

/// Heap-owned callback state that embree's `geometryUserPtr` points into: the
/// hot [`CallSite`] (read by trampolines) and the cold [`CallbackOwners`] (the
/// closures/data they reference). Both are `UnsafeCell` because they are
/// mutated through a `&GeometryShared` (the builder writes via the shared
/// `Arc`) yet read lock-free; soundness rests on the module invariant(see
/// [`GeometryShared`]).
#[derive(Debug)]
pub(crate) struct GeometryData {
    pub call_site: UnsafeCell<CallSite>,
    pub owners: UnsafeCell<CallbackOwners>,
}

impl Default for GeometryData {
    fn default() -> Self {
        Self {
            call_site: UnsafeCell::new(CallSite::EMPTY),
            owners: UnsafeCell::new(CallbackOwners::default()),
        }
    }
}

/// All per-geometry state, heap-owned for the object's whole lifetime.
///
/// Its address is embree's `userPtr` (set in `new`), so it must never move.
#[derive(Debug)]
pub(crate) struct GeometryShared<'buf> {
    pub(crate) device: Device,
    pub(crate) handle: RTCGeometry,
    pub(crate) kind: GeometryKind,
    pub(crate) attachments: Mutex<HashMap<(BufferUsage, u32), AttachedBuffer<'buf>>>,
    pub(crate) data: GeometryData,
}

impl<'buf> Drop for GeometryShared<'buf> {
    fn drop(&mut self) {
        // Released exactly once, when the last wrapper (and the scene's clone)
        // is gone.
        unsafe {
            rtcReleaseGeometry(self.handle);
        }
    }
}

// SAFETY: `GeometryData`'s `UnsafeCell`s are mutated only through a `&mut
// GeometryBuilder`, the unique `Arc<GeometryShared>` owner (strong_count == 1,
// !Clone, !Sync). No shared observer (other clones, the scene's retained clone,
// Embree's traversal threads) coexists with that mutation; and the ownership
// move / thread handoff that must separate the last write from any later shared
// read is what makes the writes visible (see the module invariant). So a shared
// `&Geometry` only ever observes frozen state. The boxed `F`/`D` are
// `Send + Sync` (enforced at registration).
//
// `Send` is intentionally NOT implemented here. That `!Send` is load-bearing:
// it keeps `Arc<GeometryShared>` `!Sync`, which is the only thing keeping
// `GeometryBuilder` `!Sync` (a builder must not be shared across
// threads while it mutates its `UnsafeCell`s via `&mut`). `Geometry` opts into
// `Send`/`Sync` at the wrapper instead; see the `arc_with_non_send_sync` note
// at the `Arc::new` site in `Geometry::new`.
unsafe impl Sync for GeometryShared<'_> {}

impl<'buf> GeometryShared<'buf> {
    /// Snapshot of the buffer bound at `(usage, slot)`, owning/copying out of
    /// the lock guard (a `Managed` retain clone, the `Shared` host borrow,
    /// or `Local` metadata) so the result does not borrow the `attachments`
    /// lock.
    fn buffer_source(&self, usage: BufferUsage, slot: u32) -> Option<BufferSource<'buf>> {
        let attachments = self.attachments.lock().unwrap();
        attachments.get(&(usage, slot)).map(|a| match a {
            AttachedBuffer::Managed {
                buffer,
                byte_offset,
                layout,
            } => BufferSource::Managed {
                buffer: buffer.clone(),
                byte_offset: *byte_offset,
                layout: *layout,
            },
            AttachedBuffer::Shared { data, layout } => BufferSource::Shared {
                data,
                layout: *layout,
            },
            AttachedBuffer::Local { size, layout } => BufferSource::Local {
                size: *size,
                layout: *layout,
            },
        })
    }

    /// Resolves a geometry-**local** buffer slot to `(ptr, element_count)` for
    /// mapping it as `[T]`, with the runtime layout checks (`T` tiles the
    /// allocation, `T`-aligned pointer, non-ZST). `Err(INVALID_ARGUMENT)`
    /// if the slot is unbound or not a local buffer, or the checks fail.
    /// Only `Local` buffers are mappable this way: `Managed`
    /// is mapped through its `Buffer`, `Shared` is the caller's own slice.
    pub(crate) fn map_local<T: BufferData>(
        &self,
        usage: BufferUsage,
        slot: u32,
    ) -> Result<(*mut T, usize), Error> {
        let byte_size = {
            let attachments = self.attachments.lock().unwrap();
            match attachments.get(&(usage, slot)) {
                Some(AttachedBuffer::Local { size, .. }) => size.get(),
                _ => return Err(Error::INVALID_ARGUMENT),
            }
        };
        let ptr = unsafe { rtcGetGeometryBufferData(self.handle, usage, slot) } as *mut T;
        let t_size = std::mem::size_of::<T>();
        if ptr.is_null()
            || t_size == 0
            || byte_size % t_size != 0
            || (ptr as usize) & (std::mem::align_of::<T>() - 1) != 0
        {
            return Err(Error::INVALID_ARGUMENT);
        }
        Ok((ptr, byte_size / t_size))
    }

    /// SAFETY: caller has exclusive access (unique `&mut GeometryBuilder`).
    unsafe fn data_mut(&self) -> (&mut CallSite, &mut CallbackOwners) {
        (
            &mut *self.data.call_site.get(),
            &mut *self.data.owners.get(),
        )
    }
}

/// The **mutable build/edit phase** of an Embree geometry.
///
/// A geometry starts here (created via [`Device::create_geometry`]), the typed
/// constructors (`TriangleMesh::new`, `QuadMesh::new`, ...), or
/// [`Geometry::new`]. You configure it in this phase and then call
/// [`commit`](GeometryBuilder::commit) to obtain a shareable, read-only
/// [`Geometry`] that can be attached to scenes.
///
/// Depending on the geometry type, different buffers must be bound (typically
/// a vertex and an index buffer) using
/// [`set_managed_buffer`](GeometryBuilder::set_managed_buffer) or
/// [`set_new_buffer`](GeometryBuilder::set_new_buffer). The primitive and
/// vertex counts are usually inferred from the bound buffer sizes.
///
/// All geometry types support multi-segment motion blur with 2..=129
/// equidistant time steps inside a user-specified time range: set the count
/// with [`set_time_step_count`](GeometryBuilder::set_time_step_count), bind one
/// vertex buffer per time step, and optionally a time range (geometries may
/// also appear / disappear during the shutter if the range is a sub-range of
/// `[0, 1]`).
///
/// Per-geometry intersection / occlusion **filter** callbacks
/// ([`set_intersect_filter_function`](GeometryBuilder::set_intersect_filter_function)
/// and the occlusion counterpart) are invoked for each hit found during
/// `Scene::intersect` / `Scene::occluded` and let you discard intersections
/// (e.g. to model alpha-cutout silhouettes such as tree leaves).
///
/// # Thread safety
///
/// `GeometryBuilder` is `Send` but **not** `Sync` and **not** `Clone`: it is
/// the *unique* owner of its geometry, so `&mut self` is genuine exclusive
/// access. That is exactly embree's contract that a single geometry must be
/// modified by at most one thread at a time. You may move a builder to another
/// thread to build it there, but you cannot share it. Regain a builder from a
/// committed geometry with [`Geometry::try_edit`].
///
/// A `GeometryBuilder` cannot be cloned (that would create an aliased mutable
/// handle):
///
/// ```compile_fail
/// use embree3::{Device, GeometryKind};
/// let device = Device::new().unwrap();
/// let builder = device.create_geometry(GeometryKind::TRIANGLE).unwrap();
/// let _alias = builder.clone(); // error: GeometryBuilder is not Clone
/// ```
///
/// nor shared across threads (`!Sync`):
///
/// ```compile_fail
/// use embree3::{Device, GeometryKind};
/// fn needs_sync<T: Sync>(_: &T) {}
/// let device = Device::new().unwrap();
/// let builder = device.create_geometry(GeometryKind::TRIANGLE).unwrap();
/// needs_sync(&builder); // error: GeometryBuilder is not Sync
/// ```
#[derive(Debug)]
pub struct GeometryBuilder<'buf> {
    pub(crate) shared: Arc<GeometryShared<'buf>>,
}

// SAFETY: a `GeometryBuilder` is the *unique* owner of its
// `Arc<GeometryShared>` (it is never `Clone`d, and `try_edit` only produces one
// when strong_count == 1). Its state is `Send` (closures are `Fn + Send +
// Sync`, user data `Send + Sync`). Moving it transfers exclusive access, which
// maps exactly to embree's "one thread modifies one geometry". It is
// intentionally NOT `Sync` and NOT `Clone`.
unsafe impl<'buf> Send for GeometryBuilder<'buf> {}

impl<'buf> GeometryBuilder<'buf> {
    /// Binds caller-owned host memory as a geometry buffer, zero-copy
    /// (`rtcSetSharedGeometryBuffer`). `data` must outlive the geometry; the
    /// `'buf` borrow enforces it.
    ///
    /// Embree reads `data[0 .. (count-1)*stride + tail]`, where `tail` is the
    /// element size, **rounded up to 16 bytes for a vertex buffer** (embree
    /// SSE-reads the last element). The host pointer and `stride` must be
    /// 4-byte aligned. Pre-slice `data` for a non-zero start, there is no
    /// separate byte offset.
    pub fn set_shared_buffer(
        &mut self,
        usage: BufferUsage,
        slot: u32,
        format: Format,
        data: &'buf [u8],
        stride: usize,
        count: usize,
    ) -> Result<(), Error> {
        if usage == BufferUsage::VERTEX_ATTRIBUTE {
            self.check_vertex_attribute()?;
        }
        let vertex = matches!(usage, BufferUsage::VERTEX | BufferUsage::VERTEX_ATTRIBUTE);
        let req =
            required_layout_bytes(format, stride, count, vertex).ok_or(Error::INVALID_ARGUMENT)?;
        if data.len() < req || (data.as_ptr() as usize) & 3 != 0 {
            return Err(Error::INVALID_ARGUMENT);
        }
        unsafe {
            rtcSetSharedGeometryBuffer(
                self.shared.handle,
                usage,
                slot,
                format,
                data.as_ptr() as *const c_void,
                0, // caller pre-slices; embree gets no separate byteOffset
                stride,
                count,
            );
        }
        let layout = BufferLayout {
            format,
            stride,
            count,
        };
        self.shared
            .attachments
            .lock()
            .unwrap()
            .insert((usage, slot), AttachedBuffer::Shared { data, layout });
        Ok(())
    }

    /// Typed convenience for [`set_shared_buffer`](Self::set_shared_buffer):
    /// bind a host slice `&'buf [T]` directly, deriving `stride =
    /// size_of::<T>()` and `count = data.len()` instead of byte-erasing at
    /// the call site.
    ///
    /// `format` stays explicit: it cannot be derived from `T` in general (e.g.
    /// `[f32; 4]` could be `FLOAT3` *or* `FLOAT4`). `data` must outlive the
    /// geometry (the `'buf` borrow enforces it). For a `VERTEX` buffer each
    /// element must be readable up to a 16-byte boundary, so a tightly packed
    /// `[f32; 3]` slice is rejected; use a 16-byte element type (e.g. `[f32;
    /// 4]`) or the byte-level
    /// [`set_shared_buffer`](Self::set_shared_buffer) with
    /// trailing padding. Reach for
    /// [`set_shared_buffer`](Self::set_shared_buffer) directly when you
    /// need a custom `stride` (interleaved / over-aligned data)
    /// or a `count` smaller than the slice.
    pub fn set_shared_slice<T: BufferData>(
        &mut self,
        usage: BufferUsage,
        slot: u32,
        format: Format,
        data: &'buf [T],
    ) -> Result<(), Error> {
        // SAFETY: `T: BufferData` is plain data with no padding-sensitivity, so
        // viewing `&[T]` as its underlying bytes is sound; the byte slice borrows
        // `data` for `'buf`, preserving the host-memory lifetime constraint.
        let bytes: &'buf [u8] = unsafe {
            std::slice::from_raw_parts(data.as_ptr() as *const u8, std::mem::size_of_val(data))
        };
        self.set_shared_buffer(
            usage,
            slot,
            format,
            bytes,
            std::mem::size_of::<T>(),
            data.len(),
        )
    }

    /// Binds a byte sub-range of a refcounted [`Buffer`]
    /// (`rtcSetGeometryBuffer`). The geometry **retains** the buffer, so
    /// this does not constrain the geometry's lifetime. `byte_range`'s
    /// start is the byte offset (must be 4-byte aligned); the range must
    /// lie within the buffer and be long enough for the layout.
    #[allow(clippy::too_many_arguments)]
    pub fn set_managed_buffer<S: RangeBounds<usize>>(
        &mut self,
        usage: BufferUsage,
        slot: u32,
        format: Format,
        buffer: &Buffer,
        byte_range: S,
        stride: usize,
        count: usize,
    ) -> Result<(), Error> {
        if usage == BufferUsage::VERTEX_ATTRIBUTE {
            self.check_vertex_attribute()?;
        }
        let byte_offset = match byte_range.start_bound() {
            Bound::Included(&n) => n,
            Bound::Excluded(&n) => n + 1,
            Bound::Unbounded => 0,
        };
        let end = match byte_range.end_bound() {
            Bound::Included(&n) => n + 1,
            Bound::Excluded(&n) => n,
            Bound::Unbounded => buffer.size.get(),
        };
        let vertex = matches!(usage, BufferUsage::VERTEX | BufferUsage::VERTEX_ATTRIBUTE);
        let req =
            required_layout_bytes(format, stride, count, vertex).ok_or(Error::INVALID_ARGUMENT)?;
        if byte_offset % 4 != 0
            || byte_offset > end
            || end > buffer.size.get()
            || end - byte_offset < req
        {
            return Err(Error::INVALID_ARGUMENT);
        }
        unsafe {
            rtcSetGeometryBuffer(
                self.shared.handle,
                usage,
                slot,
                format,
                buffer.handle,
                byte_offset,
                stride,
                count,
            );
        }
        let layout = BufferLayout {
            format,
            stride,
            count,
        };
        self.shared.attachments.lock().unwrap().insert(
            (usage, slot),
            AttachedBuffer::Managed {
                buffer: buffer.clone(), // rtcRetainBuffer
                byte_offset,
                layout,
            },
        );
        Ok(())
    }

    /// Typed convenience for [`set_managed_buffer`](Self::set_managed_buffer):
    /// bind a sub-range of a refcounted [`Buffer`] indexed in **elements of
    /// `T`** (`stride = size_of::<T>()`) rather than bytes. An unbounded end
    /// covers every whole `T` that fits in the buffer.
    ///
    /// Like [`set_managed_buffer`](Self::set_managed_buffer), the geometry
    /// **retains** the buffer, so this does not constrain the geometry's
    /// lifetime. `format` stays explicit (see
    /// [`set_shared_slice`](Self::set_shared_slice) for why). Reach for the
    /// byte-level [`set_managed_buffer`](Self::set_managed_buffer) when you
    /// need a `stride` different from `size_of::<T>()`.
    pub fn set_managed_slice<T: BufferData, S: RangeBounds<usize>>(
        &mut self,
        usage: BufferUsage,
        slot: u32,
        format: Format,
        buffer: &Buffer,
        elem_range: S,
    ) -> Result<(), Error> {
        let stride = std::mem::size_of::<T>();
        if stride == 0 {
            return Err(Error::INVALID_ARGUMENT);
        }
        let start = match elem_range.start_bound() {
            Bound::Included(&n) => n,
            Bound::Excluded(&n) => n + 1,
            Bound::Unbounded => 0,
        };
        let end = match elem_range.end_bound() {
            Bound::Included(&n) => n + 1,
            Bound::Excluded(&n) => n,
            Bound::Unbounded => buffer.size.get() / stride,
        };
        let count = end.checked_sub(start).ok_or(Error::INVALID_ARGUMENT)?;
        let byte_offset = start.checked_mul(stride).ok_or(Error::INVALID_ARGUMENT)?;
        let byte_end = end.checked_mul(stride).ok_or(Error::INVALID_ARGUMENT)?;
        self.set_managed_buffer(
            usage,
            slot,
            format,
            buffer,
            byte_offset..byte_end,
            stride,
            count,
        )
    }

    /// Creates a new [`Buffer`](`crate::Buffer`) and binds it as a specific
    /// attribute for this geometry.
    ///
    /// Analogous to [`rtcSetNewGeometryBuffer`](https://spec.oneapi.io/oneart/0.5-rev-1/embree-spec.html#rtcsetnewgeometrybuffer).
    ///
    /// The allocated buffer will be automatically over-allocated slightly when
    /// used as a [`BufferUsage::VERTEX`] buffer, where a requirement is
    /// that each buffer element should be readable using 16-byte SSE load
    /// instructions. This means that the buffer will be padded to a multiple of
    /// 16 bytes.
    ///
    /// The allocated buffer is managed internally and automatically released
    /// when the geometry is destroyed by Embree.
    ///
    /// # Arguments
    ///
    /// * `usage` - The usage of the buffer.
    ///
    /// * `slot` - The slot to bind the buffer to.
    ///
    /// * `format` - The format of the buffer items. See [`Format`] for more
    ///   information.
    ///
    /// * `count` - The number of items in the buffer.
    ///
    /// * `stride` - The stride of the buffer items. MUST be a multiple of 4.
    pub fn set_new_buffer<T: BufferData>(
        &mut self,
        usage: BufferUsage,
        slot: u32,
        format: Format,
        stride: usize,
        count: usize,
    ) -> Result<BufferViewMut<'_, T>, Error> {
        if usage == BufferUsage::VERTEX_ATTRIBUTE {
            self.check_vertex_attribute()?;
        }
        let vertex = matches!(usage, BufferUsage::VERTEX | BufferUsage::VERTEX_ATTRIBUTE);
        // Validates count >= 1, known format, stride >= elem & 4-aligned, no overflow.
        required_layout_bytes(format, stride, count, vertex).ok_or(Error::INVALID_ARGUMENT)?;
        let size = stride.checked_mul(count).ok_or(Error::INVALID_ARGUMENT)?;
        let t_size = std::mem::size_of::<T>();
        if t_size == 0 || size % t_size != 0 {
            return Err(Error::INVALID_ARGUMENT);
        }
        let raw_ptr = unsafe {
            rtcSetNewGeometryBuffer(self.shared.handle, usage, slot, format, stride, count)
        };
        if raw_ptr.is_null() {
            return Err(self.shared.device.get_error());
        }
        if (raw_ptr as usize) & (std::mem::align_of::<T>() - 1) != 0 {
            return Err(Error::INVALID_ARGUMENT);
        }
        let layout = BufferLayout {
            format,
            stride,
            count,
        };
        self.shared.attachments.lock().unwrap().insert(
            (usage, slot),
            AttachedBuffer::Local {
                size: BufferSize::new(size).ok_or(Error::INVALID_ARGUMENT)?,
                layout,
            },
        );
        // SAFETY: embree-allocated storage of `size` bytes; `T: BufferData` tiles it
        // (`size % t_size == 0`), the pointer is `T`-aligned, and `&mut self` (the
        // unique builder) gives exclusive access for the returned view's borrow.
        Ok(unsafe { BufferViewMut::from_raw_parts(raw_ptr as *mut T, size / t_size) })
    }

    /// Marks a buffer slice bound to this geometry as modified.
    ///
    /// If a data buffer is changed by the application, this function must be
    /// called for the buffer to be updated in the geometry. Each buffer slice
    /// assigned to a buffer slot is initially marked as modified, thus this
    /// method needs to be called only when doing buffer modifications after the
    /// first [`Scene::commit`] call.
    pub fn update_buffer(&mut self, usage: BufferUsage, slot: u32) {
        unsafe {
            rtcUpdateGeometryBuffer(self.shared.handle, usage, slot);
        }
    }

    /// Disables the geometry, so it is not rendered. Each geometry is enabled
    /// by default at construction time.
    ///
    /// This modifies the geometry, so it lives on the builder (the build/edit
    /// phase). To toggle a geometry that is already attached to a scene during
    /// a render loop, use
    /// [`Scene::disable_geometry`](crate::Scene::disable_geometry)
    /// instead (it excludes concurrent traversal via `&mut Scene`). After the
    /// change, the containing scene must be committed for it to take effect.
    pub fn disable(&mut self) {
        unsafe {
            rtcDisableGeometry(self.shared.handle);
        }
    }

    /// Enables the geometry, so it is rendered. Each geometry is enabled by
    /// default at construction time.
    ///
    /// See [`GeometryBuilder::disable`] for the build-phase vs. dynamic
    /// ([`Scene::enable_geometry`](crate::Scene::enable_geometry)) distinction.
    /// After the change, the containing scene must be committed for it to take
    /// effect.
    pub fn enable(&mut self) {
        unsafe {
            rtcEnableGeometry(self.shared.handle);
        }
    }

    /// Sets the number of vertex attributes of the geometry.
    ///
    /// This function sets the number of slots for vertex attributes buffers
    /// (BufferUsage::VERTEX_ATTRIBUTE) that can be used for the specified
    /// geometry.
    ///
    /// Only supported by triangle meshes, quad meshes, curves, points, and
    /// subdivision geometries.
    ///
    /// # Arguments
    ///
    /// * `count` - The number of vertex attribute slots.
    pub fn set_vertex_attribute_count(&mut self, count: u32) {
        match self.shared.kind {
            // Vertex attributes are not supported by these kinds; no-op.
            GeometryKind::GRID | GeometryKind::USER | GeometryKind::INSTANCE => {}
            _ => {
                // Update the vertex attribute count.
                unsafe {
                    rtcSetGeometryVertexAttributeCount(self.shared.handle, count);
                }
            }
        }
    }

    /// Sets the build quality for the geometry.
    ///
    /// The per-geometry build quality is only a hint and may be ignored. Embree
    /// currently uses the per-geometry build quality when the scene build
    /// quality is set to [`BuildQuality::LOW`]. In this mode a two-level
    /// acceleration structure is build, and geometries build a separate
    /// acceleration structure using the geometry build quality.
    ///
    /// The build quality can be one of the following:
    ///
    /// - [`BuildQuality::LOW`]: Creates lower quality data structures, e.g. for
    ///   dynamic scenes.
    ///
    /// - [`BuildQuality::MEDIUM`]: Default build quality for most usages. Gives
    ///   a good balance between quality and performance.
    ///
    /// - [`BuildQuality::HIGH`]: Creates higher quality data structures for
    ///   final frame rendering. Enables a spatial split builder for certain
    ///   primitive types.
    ///
    /// - [`BuildQuality::REFIT`]: Uses a BVH refitting approach when changing
    ///   only the vertex buffer.
    pub fn set_build_quality(&mut self, quality: BuildQuality) {
        unsafe {
            rtcSetGeometryBuildQuality(self.shared.handle, quality);
        }
    }

    /// Sets the tessellation rate for a subdivision mesh or flat curves.
    ///
    /// For curves, the tessellation rate specifies the number of ray-facing
    /// quads per curve segment. For subdivision surfaces, the tessellation
    /// rate specifies the number of quads along each edge.
    pub fn set_tessellation_rate(&mut self, rate: f32) {
        match self.shared.kind {
            GeometryKind::SUBDIVISION
            | GeometryKind::FLAT_LINEAR_CURVE
            | GeometryKind::FLAT_BEZIER_CURVE
            | GeometryKind::ROUND_LINEAR_CURVE
            | GeometryKind::ROUND_BEZIER_CURVE => unsafe {
                rtcSetGeometryTessellationRate(self.shared.handle, rate);
            },
            _ => panic!(
                "GeometryBuilder::set_tessellation_rate is only supported for subdivision meshes \
                 and flat curves"
            ),
        }
    }

    /// Sets the maximal curve-radius scaling factor for the **min-width**
    /// feature (rounds curves / points up to reduce aliasing).
    ///
    /// The feature is off unless embree was built with the `EMBREE_MIN_WIDTH`
    /// option, so on a default build this returns
    /// [`Error::INVALID_OPERATION`](crate::Error::INVALID_OPERATION). When the
    /// feature is enabled, `scale` must be `>= 1.0` (otherwise
    /// [`Error::INVALID_ARGUMENT`](crate::Error::INVALID_ARGUMENT)); pair it
    /// with `IntersectContext`'s `minWidthDistanceFactor` at query time.
    pub fn set_max_radius_scale(&mut self, scale: f32) -> Result<(), Error> {
        // Clear any stale per-thread error so we attribute only this call's error.
        let _ = self.shared.device.get_error();
        unsafe { rtcSetGeometryMaxRadiusScale(self.shared.handle, scale) };
        match self.shared.device.get_error() {
            Error::NONE => Ok(()),
            error => Err(error),
        }
    }

    /// Sets the mask for the geometry.
    ///
    /// This geometry mask is used together with the ray mask stored inside the
    /// mask field of the ray. The primitives of the geometry are hit by the ray
    /// only if the bitwise and operation of the geometry mask with the ray mask
    /// is not 0.
    /// This feature can be used to disable selected geometries for specifically
    /// tagged rays, e.g. to disable shadow casting for certain geometries.
    ///
    /// Ray masks are disabled in Embree by default at compile time, and can be
    /// enabled through the `EMBREE_RAY_MASK` parameter in CMake. One can query
    /// whether ray masks are enabled by querying the
    /// [`DeviceProperty::RAY_MASK_SUPPORTED`](`crate::DeviceProperty::RAY_MASK_SUPPORTED`)
    /// device property using [`Device::get_property`].
    pub fn set_mask(&mut self, mask: u32) {
        unsafe {
            rtcSetGeometryMask(self.shared.handle, mask);
        }
    }

    /// Sets the number of time steps for multi-segment motion blur for the
    /// geometry.
    ///
    /// For triangle meshes, quad meshes, curves, points, and subdivision
    /// geometries, the number of time steps directly corresponds to the
    /// number of vertex buffer slots available [`BufferUsage::VERTEX`].
    ///
    /// For instance geometries, a transformation must be specified for each
    /// time step (see [`GeometryBuilder::set_transform`]).
    ///
    /// For user geometries, the registered bounding callback function must
    /// provide a bounding box per primitive and time step, and the
    /// intersection and occlusion callback functions should properly
    /// intersect the motion-blurred geometry at the ray time.
    pub fn set_time_step_count(&mut self, count: u32) {
        unsafe {
            rtcSetGeometryTimeStepCount(self.shared.handle, count);
        }
    }

    /// Sets the time range for a motion blur geometry.
    ///
    /// The time range is defined relative to the camera shutter interval
    /// \[0,1\] but it can be arbitrary. Thus the `start` time can be
    /// smaller, equal, or larger 0, indicating a geometry whose animation
    /// definition start before, at, or after the camera shutter opens.
    /// Similar the `end` time can be smaller, equal, or larger than 1,
    /// indicating a geometry whose animation definition ends after, at, or
    /// before the camera shutter closes. The `start` time has to be smaller
    /// or equal to the `end` time.
    ///
    /// The default time range when this function is not called is the entire
    /// camera shutter \[0,1\]. For best performance at most one time segment
    /// of the piece wise linear definition of the motion should fall
    /// outside the shutter window to the left and to the right. Thus do not
    /// set the `start` time or `end` time too far outside the
    /// \[0,1\] interval for best performance.
    ///
    /// This time range feature will also allow geometries to appear and
    /// disappear during the camera shutter time if the specified time range
    /// is a sub range of \[0,1\].
    ///
    /// Please also have a look at the [`GeometryBuilder::set_time_step_count`]
    /// to see how to define the time steps for the specified time range.
    pub fn set_time_range(&mut self, start: f32, end: f32) {
        unsafe {
            rtcSetGeometryTimeRange(self.shared.handle, start, end);
        }
    }

    /// Registers an intersection filter callback function for the geometry.
    ///
    /// Only a single callback function can be registered per geometry, and
    /// further invocations overwrite the previously set callback function.
    /// Unregister the callback function by calling
    /// [`GeometryBuilder::unset_intersect_filter_function`].
    ///
    /// The registered filter function is invoked for every hit encountered
    /// during the intersect-type ray queries and can accept or reject that
    /// hit. The feature can be used to define a silhouette for a primitive
    /// and reject hits that are outside the silhouette. E.g. a tree leaf
    /// could be modeled with an alpha texture that decides whether hit
    /// points lie inside or outside the leaf.
    ///
    /// If [`BuildQuality::HIGH`] is set, the filter functions may be called
    /// multiple times for the same primitive hit. Further, rays hitting
    /// exactly the edge might also report two hits for the same surface. For
    /// certain use cases, the application may have to work around this
    /// limitation by collecting already reported hits (geomID/primID pairs)
    /// and ignoring duplicates.
    ///
    /// The filter function callback of type [`RTCFilterFunctionN`] gets passed
    /// a number of arguments through the [`RTCFilterFunctionNArguments`]
    /// structure. The valid parameter of that structure points to an
    /// integer valid mask (0 means invalid and -1 means valid). The
    /// `geometryUserPtr` member is handled by the wrapper: the data optionally
    /// bound to *this* callback (via its `_owned` / `_borrowed` variant) is
    /// delivered as the closure's `Option<&D>` argument. The
    /// context member points to the intersection context passed to
    /// the ray query function. The ray parameter points to N rays in SOA layout
    /// (see `RayN`, `HitN`).
    /// The hit parameter points to N hits in SOA layout to test. The N
    /// parameter is the number of rays and hits in ray and hit. The hit
    /// distance is provided as the tfar value of the ray. If the hit
    /// geometry is instanced, the `instID` member of the ray is valid, and
    /// the ray and the potential hit are in object space.
    ///
    /// The filter callback function has the task to check for each valid ray
    /// whether it wants to accept or reject the corresponding hit. To
    /// reject a hit, the filter callback function just has to *write 0* to
    /// the integer valid mask of the corresponding ray. To accept the hit,
    /// it just has to *leave the valid mask set to -1*. The filter function
    /// is further allowed to change the hit and decrease the tfar value of the
    /// ray but it should not modify other ray data nor any inactive
    /// components of the ray or hit.
    ///
    /// When performing ray queries using [`Scene::intersect`], it is
    /// *guaranteed* that the packet size is 1 when the callback is invoked.
    /// When performing ray queries using the
    /// [`Scene::intersect4`]/[`Scene::intersect8`]/[`Scene::intersect16`]
    /// functions, it is not generally guaranteed that the ray packet size
    /// (and order of rays inside the packet) passed to the callback matches
    /// the initial ray packet. However, under some circumstances these
    /// properties are guaranteed, and whether this is the case can be
    /// queried using [`Device::get_property`]. When performing ray queries
    /// using the stream API such as [`Scene::intersect_stream_aos`],
    /// [`Scene::intersect_stream_soa`], the order of rays and ray packet size
    /// of the callback function might change to either 1, 4, 8, or 16.
    ///
    /// For many usage scenarios, repacking and re-ordering of rays does not
    /// cause difficulties in implementing the callback function. However,
    /// algorithms that need to extend the ray with additional data must use
    /// the rayID component of the ray to identify the original ray to
    /// access the per-ray data.
    ///
    /// # Thread safety
    ///
    /// Embree may invoke this callback from multiple threads concurrently, for
    /// example during a parallel [`Scene::commit`](crate::Scene::commit),
    /// or when ray queries are issued from several threads on a shared
    /// scene. The closure must therefore be safe to call from several
    /// threads at once and to share across them: it must not depend
    /// on exclusive `&mut` access to its captures, and everything it captures
    /// must be `Send + Sync`. The `Fn + Send + Sync` bounds on the closure
    /// enforce this.
    ///
    /// # Performance
    ///
    /// The [`RayN`]/[`HitN`]/[`ValidityN`] accessors bounds-check every field
    /// access unconditionally (they `assert!`, even in release). When the
    /// closure iterates the packet over a lane index it has already proven in
    /// range (e.g. `for i in 0..rays.len()`), that check is redundant; the
    /// `unsafe` [`RayN::gather_unchecked`] / [`HitN::gather_unchecked`] /
    /// [`HitN::scatter_unchecked`] / [`ValidityN::get_unchecked`] /
    /// [`ValidityN::set_unchecked`] accessors skip it (the user-geometry
    /// callbacks get the same elision automatically via
    /// [`IntersectFunctionNArgs::for_each_active_lane`]).
    pub fn set_intersect_filter_function<F, D>(&mut self, filter: F)
    where
        D: UserData,
        F: for<'a> Fn(RayN<'a>, HitN<'a>, ValidityN<'a>, &mut IntersectContext, Option<&D>)
            + Send
            + Sync
            + 'static,
    {
        // Register the trampoline first, then store the owner (so the old one, if any,
        // is dropped only after the new closure is installed).
        unsafe {
            rtcSetGeometryIntersectFilterFunction(
                self.shared.handle,
                trampoline::intersect_filter_function::<F, D>(),
            );
            self.install_callback(
                CbKind::IntersectFilter,
                ErasedFn::new(filter),
                std::ptr::null(),
                None,
            );
        }
    }

    /// Registers an intersection filter that receives **owned** per-callback
    /// data as its `Option<&D>` argument.
    ///
    /// Identical to
    /// [`set_intersect_filter_function`](Self::set_intersect_filter_function)
    /// (see it for the full filter contract and thread-safety bounds) except
    /// that this callback gets its *own* `data`, distinct from every other
    /// callback's. The geometry takes ownership of `data` and drops it exactly
    /// once, when this slot is replaced, or when the last geometry clone is
    /// dropped. Read it back outside the callback with
    /// [`callback_data`](Self::callback_data) /
    /// [`callback_data_mut`](Self::callback_data_mut).
    ///
    /// Use this when the geometry should own the data. To instead lend data you
    /// keep on the application side (zero-copy, no refcount), use
    /// [`set_intersect_filter_function_borrowed`](Self::set_intersect_filter_function_borrowed).
    pub fn set_intersect_filter_function_owned<F, D>(&mut self, filter: F, data: D)
    where
        D: UserData,
        F: for<'a> Fn(RayN<'a>, HitN<'a>, ValidityN<'a>, &mut IntersectContext, Option<&D>)
            + Send
            + Sync
            + 'static,
    {
        // SOUNDNESS: the owned-data pointer is taken before coercing `Box<D>` to
        // `Box<dyn Any>`; coercion does not move the `D`, so `ptr` remains
        // valid for the box's lifetime.
        let boxed = Box::new(data);
        let ptr = &*boxed as *const D as *const ();
        unsafe {
            rtcSetGeometryIntersectFilterFunction(
                self.shared.handle,
                trampoline::intersect_filter_function::<F, D>(),
            );
            self.install_callback(
                CbKind::IntersectFilter,
                ErasedFn::new(filter),
                ptr,
                Some(boxed),
            );
        }
    }

    /// Registers an intersection filter that receives **borrowed** per-callback
    /// data as its `Option<&D>` argument.
    ///
    /// Identical to
    /// [`set_intersect_filter_function`](Self::set_intersect_filter_function)
    /// (see it for the full filter contract and thread-safety bounds) except
    /// that this callback reads `data` that the *application* owns. Nothing is
    /// allocated or reference-counted: `data` is borrowed for the geometry's
    /// lifetime `'buf` (the same lifetime that bounds shared vertex buffers)
    /// so the borrow checker forbids `data` from being dropped while the
    /// geometry (and hence any traversal that could invoke the callback) is
    /// still alive.
    ///
    /// Use this to share long-lived application data without an `Arc`. To make
    /// the geometry own the data instead, use
    /// [`set_intersect_filter_function_owned`](Self::set_intersect_filter_function_owned).
    ///
    /// The borrow is enforced at compile time, data dropped before the
    /// geometry is a type error:
    ///
    /// ```compile_fail
    /// # use embree3::{Device, GeometryKind, IntersectContext};
    /// let device = Device::new().unwrap();
    /// let mut tri = device.create_geometry(GeometryKind::TRIANGLE).unwrap();
    /// let data = vec![1u32, 2, 3];
    /// tri.set_intersect_filter_function_borrowed::<_, Vec<u32>, IntersectContext>(
    ///     |_r, _h, _v, _c, _ud| {},
    ///     &data,
    /// );
    /// drop(data); // ERROR: `data` is borrowed by `tri` for its `'buf`
    /// let _ = tri.commit(); // `tri` (holding the borrow) is still used here
    /// ```
    pub fn set_intersect_filter_function_borrowed<F, D>(&mut self, filter: F, data: &'buf D)
    where
        D: UserData,
        F: for<'a> Fn(RayN<'a>, HitN<'a>, ValidityN<'a>, &mut IntersectContext, Option<&D>)
            + Send
            + Sync
            + 'static,
    {
        // SOUNDNESS: The borrowed form's `&'buf D` ties the data to the geometry's
        // `'buf` (the same `'buf` shared buffers already use), so the borrow checker
        // forbids the geometry (hence traversal) from outliving the data.
        // `GeometryShared<'buf>` already *uses* `'buf` (via `AttachedBuffer::Shared`);
        // keep it so (a `PhantomData<&'buf ()>` if needed) so the erased `*const ()` is
        // not silently `'static`.
        let ptr = data as *const D as *const ();
        unsafe {
            rtcSetGeometryIntersectFilterFunction(
                self.shared.handle,
                trampoline::intersect_filter_function::<F, D>(),
            );
            self.install_callback(CbKind::IntersectFilter, ErasedFn::new(filter), ptr, None);
        }
    }

    /// Unsets the intersection filter function for the geometry.
    pub fn unset_intersect_filter_function(&mut self) {
        unsafe {
            rtcSetGeometryIntersectFilterFunction(self.shared.handle, None);
            self.clear_callback(CbKind::IntersectFilter);
        }
    }

    /// Sets the occlusion filter for the geometry.
    ///
    /// Only a single callback function can be registered per geometry, and
    /// further invocations overwrite the previously set callback function.
    /// Unregister the callback function by calling
    /// [`GeometryBuilder::unset_occluded_filter_function`].
    ///
    /// The registered intersection filter function is invoked for every hit
    /// encountered during the occluded-type ray queries and can accept or
    /// reject that hit.
    ///
    /// The feature can be used to define a silhouette for a primitive and
    /// reject hits that are outside the silhouette. E.g. a tree leaf could
    /// be modeled with an alpha texture that decides whether hit points lie
    /// inside or outside the leaf. Please see the description of the
    /// [`GeometryBuilder::set_intersect_filter_function`] for a description of
    /// the filter callback function.
    ///
    /// # Thread safety
    ///
    /// Embree may invoke this callback from multiple threads concurrently, for
    /// example during a parallel [`Scene::commit`](crate::Scene::commit),
    /// or when ray queries are issued from several threads on a shared
    /// scene. The closure must therefore be safe to call from several
    /// threads at once and to share across them: it must not depend
    /// on exclusive `&mut` access to its captures, and everything it captures
    /// must be `Send + Sync`. The `Fn + Send + Sync` bounds on the closure
    /// enforce this.
    pub fn set_occluded_filter_function<F, D>(&mut self, filter: F)
    where
        D: UserData,
        F: for<'a> Fn(RayN<'a>, HitN<'a>, ValidityN<'a>, &mut IntersectContext, Option<&D>)
            + Send
            + Sync
            + 'static,
    {
        // Register the trampoline first, then store the owner (so the old one, if any)
        // is dropped only after the new closure is installed).
        unsafe {
            rtcSetGeometryOccludedFilterFunction(
                self.shared.handle,
                trampoline::occluded_filter_function::<F, D>(),
            );
            self.install_callback(
                CbKind::OccludedFilter,
                ErasedFn::new(filter),
                std::ptr::null(),
                None,
            );
        }
    }

    /// The owned-data variant of
    /// [`set_occluded_filter_function`](Self::set_occluded_filter_function).
    /// See
    /// [`set_intersect_filter_function_owned`](Self::set_intersect_filter_function_owned)
    /// for the per-callback owned-vs-borrowed data model.
    pub fn set_occluded_filter_function_owned<F, D>(&mut self, filter: F, data: D)
    where
        D: UserData,
        F: for<'a> Fn(RayN<'a>, HitN<'a>, ValidityN<'a>, &mut IntersectContext, Option<&D>)
            + Send
            + Sync
            + 'static,
    {
        // SOUNDNESS: the owned-data pointer is taken before coercing `Box<D>` to
        // `Box<dyn Any>`; coercion does not move the `D`, so `ptr` remains
        // valid for the box's lifetime.
        let boxed = Box::new(data);
        let ptr = &*boxed as *const D as *const ();
        unsafe {
            rtcSetGeometryOccludedFilterFunction(
                self.shared.handle,
                trampoline::occluded_filter_function::<F, D>(),
            );
            self.install_callback(
                CbKind::OccludedFilter,
                ErasedFn::new(filter),
                ptr,
                Some(boxed),
            );
        }
    }

    /// The borrowed-data variant of
    /// [`set_occluded_filter_function`](Self::set_occluded_filter_function).
    /// See
    /// [`set_intersect_filter_function_borrowed`](Self::set_intersect_filter_function_borrowed)
    /// for the per-callback owned-vs-borrowed data model.
    pub fn set_occluded_filter_function_borrowed<F, D>(&mut self, filter: F, data: &'buf D)
    where
        D: UserData,
        F: for<'a> Fn(RayN<'a>, HitN<'a>, ValidityN<'a>, &mut IntersectContext, Option<&D>)
            + Send
            + Sync
            + 'static,
    {
        // SOUNDNESS: The borrowed form's `&'buf D` ties the data to the geometry's
        // `'buf` (the same `'buf` shared buffers already use), so the borrow checker
        // forbids the geometry (hence traversal) from outliving the data.
        // `GeometryShared<'buf>` already *uses* `'buf` (via `AttachedBuffer::Shared`);
        // keep it so (a `PhantomData<&'buf ()>` if needed) so the erased `*const ()` is
        // not silently `'static`.
        let ptr = data as *const D as *const ();
        unsafe {
            rtcSetGeometryOccludedFilterFunction(
                self.shared.handle,
                trampoline::occluded_filter_function::<F, D>(),
            );
            self.install_callback(CbKind::OccludedFilter, ErasedFn::new(filter), ptr, None);
        }
    }

    /// Unsets the occlusion filter function for the geometry.
    pub fn unset_occluded_filter_function(&mut self) {
        unsafe {
            rtcSetGeometryOccludedFilterFunction(self.shared.handle, None);
            self.clear_callback(CbKind::OccludedFilter);
        }
    }

    /// Sets a callback to query the bounding box of user-defined primitives.
    ///
    /// Only a single callback function can be registered per geometry, and
    /// further invocations overwrite the previously set callback function.
    ///
    /// Unregister the callback function by calling
    /// [`GeometryBuilder::unset_bounds_function`].
    ///
    /// The registered bounding box callback function is invoked to calculate
    /// axis- aligned bounding boxes of the primitives of the user-defined
    /// geometry during spatial acceleration structure construction.
    ///
    /// The arguments of the callback closure are:
    ///
    /// - a shared reference to the user data of the geometry
    ///
    /// - the ID of the primitive to calculate the bounds for
    ///
    /// - the time step at which to calculate the bounds
    ///
    /// - a mutable reference to the bounding box where the result should be
    ///   written to
    ///
    /// In a typical usage scenario one binds the user geometry's primitive data
    /// to this callback with
    /// [`set_bounds_function_owned`](Self::set_bounds_function_owned) /
    /// [`set_bounds_function_borrowed`](Self::set_bounds_function_borrowed) (or
    /// captures it in the closure). The callback then receives it as its
    /// `Option<&D>` argument, indexes by `prim_id`, and writes the proper
    /// bounding box for the requested primitive and time to the destination.
    ///
    /// # Thread safety
    ///
    /// Embree may invoke this callback from multiple threads concurrently, for
    /// example during a parallel [`Scene::commit`](crate::Scene::commit),
    /// or when ray queries are issued from several threads on a shared
    /// scene. The closure must therefore be safe to call from several
    /// threads at once and to share across them: it must not depend
    /// on exclusive `&mut` access to its captures, and everything it captures
    /// must be `Send + Sync`. The `Fn + Send + Sync` bounds on the closure
    /// enforce this.
    pub fn set_bounds_function<F, D>(&mut self, bounds: F)
    where
        D: UserData,
        F: Fn(&mut Bounds, u32, u32, Option<&D>) + Send + Sync + 'static,
    {
        if self.shared.kind == GeometryKind::USER {
            unsafe {
                rtcSetGeometryBoundsFunction(
                    self.shared.handle,
                    trampoline::bounds_function::<F, D>(),
                    ptr::null_mut(),
                );
                self.install_callback(
                    CbKind::UserBounds,
                    ErasedFn::new(bounds),
                    std::ptr::null(),
                    None,
                );
            }
        }
    }

    /// The owned-data variant of
    /// [`set_bounds_function`](Self::set_bounds_function). See
    /// [`set_intersect_filter_function_owned`](Self::set_intersect_filter_function_owned)
    /// for the per-callback owned-vs-borrowed data model. (User geometry only.)
    pub fn set_bounds_function_owned<F, D>(&mut self, bounds: F, data: D)
    where
        D: UserData,
        F: Fn(&mut Bounds, u32, u32, Option<&D>) + Send + Sync + 'static,
    {
        if self.shared.kind == GeometryKind::USER {
            let boxed = Box::new(data);
            let ptr = &*boxed as *const D as *const ();
            unsafe {
                rtcSetGeometryBoundsFunction(
                    self.shared.handle,
                    trampoline::bounds_function::<F, D>(),
                    ptr::null_mut(),
                );
            }
            self.install_callback(CbKind::UserBounds, ErasedFn::new(bounds), ptr, Some(boxed));
        }
    }

    /// The borrowed-data variant of
    /// [`set_bounds_function`](Self::set_bounds_function). See
    /// [`set_intersect_filter_function_borrowed`](Self::set_intersect_filter_function_borrowed)
    /// for the per-callback owned-vs-borrowed data model. (User geometry only.)
    pub fn set_bounds_function_borrowed<F, D>(&mut self, bounds: F, data: &'buf D)
    where
        D: UserData,
        F: Fn(&mut Bounds, u32, u32, Option<&D>) + Send + Sync + 'static,
    {
        if self.shared.kind == GeometryKind::USER {
            let ptr = data as *const D as *const ();
            unsafe {
                rtcSetGeometryBoundsFunction(
                    self.shared.handle,
                    trampoline::bounds_function::<F, D>(),
                    ptr::null_mut(),
                );
            }
            self.install_callback(CbKind::UserBounds, ErasedFn::new(bounds), ptr, None);
        }
    }

    /// Unsets the callback to calculate the bounding box of user-defined
    /// geometry.
    pub fn unset_bounds_function(&mut self) {
        if self.shared.kind == GeometryKind::USER {
            unsafe {
                rtcSetGeometryBoundsFunction(self.shared.handle, None, ptr::null_mut());
                self.clear_callback(CbKind::UserBounds);
            }
        }
    }

    /// Sets the callback function to intersect a user geometry.
    ///
    /// The registered callback function is invoked by intersect-type ray
    /// queries to calculate the intersection of a ray packet of variable
    /// size with one user-defined primitive.
    ///
    /// Only a single callback function can be registered per geometry and
    /// further invocations overwrite the previously set callback function.
    /// Unregister the callback function by calling
    /// [`GeometryBuilder::unset_intersect_function`].
    ///
    /// # The callback
    ///
    /// The closure receives a single
    /// [`&mut IntersectFunctionNArgs<D>`](IntersectFunctionNArgs) carrying
    /// the ray packet, validity mask, intersection context,
    /// geometry/primitive IDs, and per-callback user data. Its task is to
    /// intersect each **active** lane (`args.valid_n()[i] != 0`) of the
    /// packet against the user primitive `args.prim_id()`, and commit the
    /// closest hit found within each lane's `tnear..tfar` range. Lanes the
    /// primitive misses are left untouched.
    ///
    /// The packet's `hit` data is **write-only** scratch. The ray data is
    /// valid; in particular each lane's `tfar` is the current closest-hit
    /// distance.
    ///
    /// Per lane `i` (the filter primitive is single-ray, so loop the packet):
    ///
    /// 1. Gather the lane's ray with
    ///    [`args.ray(i)`](IntersectFunctionNArgs::ray).
    /// 2. Run your ray/primitive test; for a hit, build a fully-initialized
    ///    [`Hit`] (`Ng_*`, `u`, `v`, `geomID`, `primID`, and `instID`
    ///    deep-copied from the context's instance stack) and set `ray.tfar` to
    ///    the candidate distance.
    /// 3. If filtering is desired, run the filter chain with
    ///    [`args.filter_intersection(&mut ray, &mut
    ///    hit)`](IntersectFunctionNArgs::filter_intersection). It invokes the
    ///    geometry filter
    ///    ([`set_intersect_filter_function`](Self::set_intersect_filter_function))
    ///    **and** the context filter, returning `false` if the hit was
    ///    rejected. For *built-in* geometry embree runs the filter
    ///    automatically; for *user* geometry the intersector must call it,
    ///    because embree never sees the user-computed hit. To filter a whole
    ///    packet in one call instead, see
    ///    [`filter_intersection_n`](IntersectFunctionNArgs::filter_intersection_n).
    /// 4. Commit a surviving hit with [`args.commit_hit(i, &ray,
    ///    &hit)`](IntersectFunctionNArgs::commit_hit).
    ///
    /// A primitive may be hit more than once per ray (e.g. a sphere's front and
    /// back faces): repeat steps 1–4 for each candidate. A rejected candidate
    /// leaves the packet untouched, so the next one can still be accepted.
    ///
    /// Per-callback user data is bound via this setter's `_owned` / `_borrowed`
    /// variants and read back through
    /// [`args.user_data()`](IntersectFunctionNArgs::user_data).
    ///
    /// # Examples
    ///
    /// A user geometry that reports a hit and runs it through the filter chain:
    ///
    /// ```no_run
    /// # use embree3::{Device, GeometryKind, Hit, IntersectFunctionNArgs, INVALID_ID};
    /// let device = Device::new().unwrap();
    /// let mut geom = device.create_geometry(GeometryKind::USER).unwrap();
    /// geom.set_primitive_count(1);
    /// geom.set_intersect_function::<_, ()>(|args: &mut IntersectFunctionNArgs<'_, ()>| {
    ///     for i in 0..args.len() {
    ///         if args.valid_n()[i] == 0 {
    ///             continue; // skip inactive lanes
    ///         }
    ///         let mut ray = args.ray(i);
    ///         let t = 1.0_f32; // distance from your ray/primitive test
    ///         if t > ray.tnear && t < ray.tfar {
    ///             let mut hit = Hit {
    ///                 Ng_x: 0.0,
    ///                 Ng_y: 0.0,
    ///                 Ng_z: 1.0,
    ///                 u: 0.0,
    ///                 v: 0.0,
    ///                 primID: args.prim_id(),
    ///                 geomID: args.geom_id(),
    ///                 instID: [INVALID_ID],
    ///             };
    ///             ray.tfar = t;
    ///             if args.filter_intersection(&mut ray, &mut hit) {
    ///                 args.commit_hit(i, &ray, &hit);
    ///             }
    ///         }
    ///     }
    /// });
    /// ```
    ///
    /// - Within the user geometry intersect function, it is safe to trace new
    ///   rays and create new scenes and geometries.
    ///
    /// - When performing ray queries using [`Scene::intersect`], it is
    ///   guaranteed that the packet size is 1 when the callback is invoked.
    ///
    /// - When performing ray queries using the
    ///   [`Scene::intersect4`]/[`Scene::intersect8`]/[`Scene::intersect16`]
    ///   functions, it is **not** generally guaranteed that the ray packet size
    ///   (and order of rays inside the packet) passed to the callback matches
    ///   the initial ray packet. However, under some circumstances these
    ///   properties are guaranteed, and whether this is the case can be queried
    ///   using [`Device::get_property`].
    ///
    /// - When performing ray queries using the stream API such as
    ///   [`Scene::intersect_stream_soa`], [`Scene::intersect_stream_aos`], the
    ///   order of rays and ray packet size of the callback function might
    ///   change to either 1, 4, 8, or 16.
    ///
    /// - For many usage scenarios, repacking and re-ordering of rays does not
    ///   cause difficulties in implementing the callback function. However,
    ///   algorithms that need to extend the ray with additional data must use
    ///   the rayID component of the ray to identify the original ray to access
    ///   the per-ray data.
    ///
    /// # Thread safety
    ///
    /// Embree may invoke this callback from multiple threads concurrently, for
    /// example during a parallel [`Scene::commit`](crate::Scene::commit),
    /// or when ray queries are issued from several threads on a shared
    /// scene. The closure must therefore be safe to call from several
    /// threads at once and to share across them: it must not depend
    /// on exclusive `&mut` access to its captures, and everything it captures
    /// must be `Send + Sync`. The `Fn + Send + Sync` bounds on the closure
    /// enforce this.
    pub fn set_intersect_function<F, D>(&mut self, intersect: F)
    where
        D: UserData,
        F: for<'a> Fn(&mut IntersectFunctionNArgs<'a, D>) + Send + Sync + 'static,
    {
        if self.shared.kind == GeometryKind::USER {
            unsafe {
                rtcSetGeometryIntersectFunction(
                    self.shared.handle,
                    trampoline::intersect_function::<F, D>(),
                );
                self.install_callback(
                    CbKind::UserIntersect,
                    ErasedFn::new(intersect),
                    std::ptr::null(),
                    None,
                );
            }
        }
    }

    /// The owned-data variant of
    /// [`set_intersect_function`](Self::set_intersect_function). See
    /// [`set_intersect_filter_function_owned`](Self::set_intersect_filter_function_owned)
    /// for the per-callback owned-vs-borrowed data model. (User geometry only.)
    pub fn set_intersect_function_owned<F, D>(&mut self, intersect: F, data: D)
    where
        D: UserData,
        F: for<'a> Fn(&mut IntersectFunctionNArgs<'a, D>) + Send + Sync + 'static,
    {
        if self.shared.kind == GeometryKind::USER {
            let boxed = Box::new(data);
            let ptr = &*boxed as *const D as *const ();
            unsafe {
                rtcSetGeometryIntersectFunction(
                    self.shared.handle,
                    trampoline::intersect_function::<F, D>(),
                );
            }
            self.install_callback(
                CbKind::UserIntersect,
                ErasedFn::new(intersect),
                ptr,
                Some(boxed),
            );
        }
    }

    /// The borrowed-data variant of
    /// [`set_intersect_function`](Self::set_intersect_function). See
    /// [`set_intersect_filter_function_borrowed`](Self::set_intersect_filter_function_borrowed)
    /// for the per-callback owned-vs-borrowed data model. (User geometry only.)
    pub fn set_intersect_function_borrowed<F, D>(&mut self, intersect: F, data: &'buf D)
    where
        D: UserData,
        F: for<'a> Fn(&mut IntersectFunctionNArgs<'a, D>) + Send + Sync + 'static,
    {
        if self.shared.kind == GeometryKind::USER {
            unsafe {
                let ptr = data as *const D as *const ();
                rtcSetGeometryIntersectFunction(
                    self.shared.handle,
                    trampoline::intersect_function::<F, D>(),
                );
                self.install_callback(CbKind::UserIntersect, ErasedFn::new(intersect), ptr, None);
            }
        }
    }

    /// Unsets the callback to intersect user-defined geometry.
    pub fn unset_intersect_function(&mut self) {
        if self.shared.kind == GeometryKind::USER {
            unsafe {
                rtcSetGeometryIntersectFunction(self.shared.handle, None);
            }
            self.clear_callback(CbKind::UserIntersect);
        }
    }

    /// Sets the callback function to occlude a user geometry.
    ///
    /// Similar to [`GeometryBuilder::set_intersect_function`], but for
    /// occlusion queries.
    ///
    /// # The callback
    ///
    /// The closure receives a single
    /// [`&mut OccludedFunctionNArgs<D>`](OccludedFunctionNArgs) carrying the
    /// ray packet, validity mask, intersection context, geometry/primitive IDs,
    /// and per-callback user data. For each **active** lane
    /// (`args.valid_n()[i] != 0`) it tests whether the user primitive
    /// `args.prim_id()` occludes the ray, and marks the lanes that are
    /// occluded.
    ///
    /// Per lane `i` (single-ray filter primitive, so loop the packet):
    ///
    /// 1. Gather the lane's ray with
    ///    [`args.ray(i)`](OccludedFunctionNArgs::ray).
    /// 2. Run your ray/primitive test; for an occluding hit within
    ///    `tnear..tfar`, build a fully-initialized [`Hit`] and set `ray.tfar`
    ///    to its distance.
    /// 3. Optionally run the occlusion filter chain with
    ///    [`args.filter_occlusion(&mut ray, &mut
    ///    hit)`](OccludedFunctionNArgs::filter_occlusion) which returns `false`
    ///    if the occluder was rejected.
    /// 4. For a surviving occluder, mark the lane with
    ///    [`args.set_occluded(i)`](OccludedFunctionNArgs::set_occluded) (embree
    ///    signals occlusion by setting the ray's `tfar` to `-inf`).
    ///
    /// Whole-packet filtering is available via
    /// [`filter_occlusion_n`](OccludedFunctionNArgs::filter_occlusion_n). See
    /// [`set_intersect_function`](Self::set_intersect_function) for the
    /// analogous intersect callback and a worked example.
    ///
    /// # Thread safety
    ///
    /// Embree may invoke this callback from multiple threads concurrently, for
    /// example during a parallel [`Scene::commit`](crate::Scene::commit),
    /// or when ray queries are issued from several threads on a shared
    /// scene. The closure must therefore be safe to call from several
    /// threads at once and to share across them: it must not depend
    /// on exclusive `&mut` access to its captures, and everything it captures
    /// must be `Send + Sync`. The `Fn + Send + Sync` bounds on the closure
    /// enforce this.
    pub fn set_occluded_function<F, D>(&mut self, occluded: F)
    where
        D: UserData,
        F: for<'a> Fn(&mut OccludedFunctionNArgs<'a, D>) + Send + Sync + 'static,
    {
        if self.shared.kind == GeometryKind::USER {
            unsafe {
                rtcSetGeometryOccludedFunction(
                    self.shared.handle,
                    trampoline::occluded_function::<F, D>(),
                )
            };
            self.install_callback(
                CbKind::UserOccluded,
                ErasedFn::new(occluded),
                std::ptr::null(),
                None,
            );
        }
    }

    /// The owned-data variant of
    /// [`set_occluded_function`](Self::set_occluded_function). See
    /// [`set_intersect_filter_function_owned`](Self::set_intersect_filter_function_owned)
    /// for the per-callback owned-vs-borrowed data model. (User geometry only.)
    pub fn set_occluded_function_owned<F, D>(&mut self, occluded: F, data: D)
    where
        D: UserData,
        F: for<'a> Fn(&mut OccludedFunctionNArgs<'a, D>) + Send + Sync + 'static,
    {
        if self.shared.kind == GeometryKind::USER {
            let boxed = Box::new(data);
            let ptr = &*boxed as *const D as *const ();
            unsafe {
                rtcSetGeometryOccludedFunction(
                    self.shared.handle,
                    trampoline::occluded_function::<F, D>(),
                )
            };
            self.install_callback(
                CbKind::UserOccluded,
                ErasedFn::new(occluded),
                ptr,
                Some(boxed),
            );
        }
    }

    /// The borrowed-data variant of
    /// [`set_occluded_function`](Self::set_occluded_function). See
    /// [`set_intersect_filter_function_borrowed`](Self::set_intersect_filter_function_borrowed)
    /// for the per-callback owned-vs-borrowed data model. (User geometry only.)
    ///
    /// # Arguments
    ///
    /// - `occluded`: The callback function to register, which is invoked by
    ///   occlusion queries to test whether the rays of a packet of variable
    ///   size are occluded by a user-defined primitive.
    /// - `data`: A shared reference to the user data of the geometry, which is
    ///   passed to the callback when invoked. The caller must ensure that the
    ///   geometry does not outlive the data.
    pub fn set_occluded_function_borrowed<F, D>(&mut self, occluded: F, data: &'buf D)
    where
        D: UserData,
        F: for<'a> Fn(&mut OccludedFunctionNArgs<'a, D>) + Send + Sync + 'static,
    {
        if self.shared.kind == GeometryKind::USER {
            let ptr = data as *const D as *const ();
            unsafe {
                rtcSetGeometryOccludedFunction(
                    self.shared.handle,
                    trampoline::occluded_function::<F, D>(),
                )
            };
            self.install_callback(CbKind::UserOccluded, ErasedFn::new(occluded), ptr, None);
        }
    }

    /// Unsets the callback to occlude user-defined geometry.
    pub fn unset_occluded_function(&mut self) {
        if self.shared.kind == GeometryKind::USER {
            unsafe {
                rtcSetGeometryOccludedFunction(self.shared.handle, None);
                self.clear_callback(CbKind::UserOccluded);
            }
        }
    }

    /// Sets the number of primitives of a user-defined geometry.
    pub fn set_primitive_count(&mut self, count: u32) {
        match self.shared.kind {
            GeometryKind::USER => unsafe {
                rtcSetGeometryUserPrimitiveCount(self.shared.handle, count);
            },
            _ => panic!("Only user geometries can have a primitive count!"),
        }
    }

    /// Set the subdivision mode for the topology of the specified subdivision
    /// geometry.
    ///
    /// The subdivision modes can be used to force linear interpolation for
    /// certain parts of the subdivision mesh:
    ///
    /// * [`RTCSubdivisionMode::NO_BOUNDARY`]: Boundary patches are ignored.
    ///   This way each rendered patch has a full set of control vertices.
    ///
    /// * [`RTCSubdivisionMode::SMOOTH_BOUNDARY`]: The sequence of boundary
    ///   control points are used to generate a smooth B-spline boundary curve
    ///   (default mode).
    ///
    /// * [`RTCSubdivisionMode::PIN_CORNERS`]: Corner vertices are pinned to
    ///   their location during subdivision.
    ///
    /// * [`RTCSubdivisionMode::PIN_BOUNDARY`]: All vertices at the border are
    ///   pinned to their location during subdivision. This way the boundary is
    ///   interpolated linearly. This mode is typically used for texturing to
    ///   also map texels at the border of the texture to the mesh.
    ///
    /// * [`RTCSubdivisionMode::PIN_ALL`]: All vertices at the border are pinned
    ///   to their location during subdivision. This way all patches are
    ///   linearly interpolated.
    pub fn set_subdivision_mode(&mut self, topology_id: u32, mode: SubdivisionMode) {
        match self.shared.kind {
            GeometryKind::SUBDIVISION => unsafe {
                rtcSetGeometrySubdivisionMode(self.shared.handle, topology_id, mode)
            },
            _ => panic!("Only subdivision geometries can have a subdivision mode!"),
        }
    }

    /// Sets the number of topologies of a subdivision geometry.
    ///
    /// The number of topologies of a subdivision geometry must be greater
    /// or equal to 1.
    ///
    /// To use multiple topologies, first the number of topologies must be
    /// specified, then the individual topologies can be configured using
    /// [`GeometryBuilder::set_subdivision_mode`] and by setting an index buffer
    /// ([`BufferUsage::INDEX`]) using the topology ID as the buffer slot.
    pub fn set_topology_count(&mut self, count: u32) {
        match self.shared.kind {
            GeometryKind::SUBDIVISION => unsafe {
                rtcSetGeometryTopologyCount(self.shared.handle, count);
            },
            _ => panic!("Only subdivision geometries can have multiple topologies!"),
        }
    }

    /// The geometry kind. Mirrors [`Geometry::kind`] for the build phase.
    pub fn kind(&self) -> GeometryKind { self.shared.kind }

    /// The raw Embree geometry handle. Mirrors [`Geometry::handle`].
    ///
    /// # Safety
    ///
    /// The handle is not reference-counted by this call and must not outlive
    /// the geometry.
    pub unsafe fn handle(&self) -> RTCGeometry { self.shared.handle }

    /// The buffer bound to the given slot/usage. Mirrors
    /// [`Geometry::get_buffer`].
    pub fn get_buffer(&self, usage: BufferUsage, slot: u32) -> Option<BufferSource<'_>> {
        self.shared.buffer_source(usage, slot)
    }

    /// Maps a geometry-local buffer slot for **exclusive writing** (re-fill a
    /// buffer created with
    /// [`set_new_buffer`](GeometryBuilder::set_new_buffer)). Sound because
    /// the builder is the unique owner: `&mut self` is genuine exclusive
    /// access. `Err(INVALID_ARGUMENT)` if the slot is unbound / not a local
    /// buffer, or the `T` layout checks fail.
    pub fn map_buffer_mut<T: BufferData>(
        &mut self,
        usage: BufferUsage,
        slot: u32,
    ) -> Result<BufferViewMut<'_, T>, Error> {
        let (ptr, len) = self.shared.map_local::<T>(usage, slot)?;
        // SAFETY: `map_local` validated layout/alignment; `&mut self` (unique builder)
        // gives exclusive access for the view's borrow.
        Ok(unsafe { BufferViewMut::from_raw_parts(ptr, len) })
    }

    /// Maps a geometry-local buffer slot for reading.
    pub fn map_buffer<T: BufferData>(
        &self,
        usage: BufferUsage,
        slot: u32,
    ) -> Result<BufferView<'_, T>, Error> {
        let (ptr, len) = self.shared.map_local::<T>(usage, slot)?;
        // SAFETY: validated; shared borrow of `self` for the view.
        Ok(unsafe { BufferView::from_raw_parts(ptr, len) })
    }

    /// Sets the number of primitives of a user-defined geometry.
    pub fn set_user_primitive_count(&mut self, count: u32) {
        if self.shared.kind == GeometryKind::USER {
            // Update the primitive count.
            unsafe {
                rtcSetGeometryUserPrimitiveCount(self.shared.handle, count);
            }
        }
    }

    /// Binds a vertex attribute to a topology of the geometry.
    ///
    /// This function binds a vertex attribute buffer slot to a topology for the
    /// specified subdivision geometry. Standard vertex buffers are always bound
    /// to the default topology (topology 0) and cannot be bound
    /// differently. A vertex attribute buffer always uses the topology it
    /// is bound to when used in the `rtcInterpolate` and `rtcInterpolateN`
    /// calls.
    ///
    /// A topology with ID `i` consists of a subdivision mode set through
    /// `GeometryBuilder::set_subdivision_mode` and the index buffer bound to
    /// the index buffer slot `i`. This index buffer can assign indices for
    /// each face of the subdivision geometry that are different to the
    /// indices of the default topology. These new indices can for example
    /// be used to introduce additional borders into the subdivision mesh to
    /// map multiple textures onto one subdivision geometry.
    pub fn set_vertex_attribute_topology(&mut self, vertex_attribute_id: u32, topology_id: u32) {
        unsafe {
            rtcSetGeometryVertexAttributeTopology(
                self.shared.handle,
                vertex_attribute_id,
                topology_id,
            );
        }
    }

    /// Sets the displacement function for a subdivision geometry.
    ///
    /// Only one displacement function can be set per geometry, further calls to
    /// this will overwrite the previous displacement function. Use
    /// [`GeometryBuilder::unset_displacement_function`] to remove the
    /// displacement function.
    ///
    /// The registered function is invoked to displace points on the subdivision
    /// geometry during spatial acceleration structure construction,
    /// during the [`Scene::commit`] call.
    ///
    /// # Arguments
    ///
    /// * `displacement`: The displacement function. The displacement function
    ///   is called for each vertex of the subdivision geometry.
    ///
    ///   The function is called with the following parameters:
    ///
    ///   * `geometry`: The raw geometry handle [`crate::sys::RTCGeometry`].
    ///   * `vertices`: The information about the vertices to displace. See
    ///     [`Vertices`].
    ///   * `prim_id`: The ID of the primitive that contains the vertices to
    ///     displace.
    ///   * `time_step`: The time step for which the displacement function is
    ///     evaluated. Important for time dependent displacement and motion
    ///     blur.
    ///   * `user_data`: the data bound to this callback via its `_owned` /
    ///     `_borrowed` variant, or `None`.
    ///
    /// # Safety
    ///
    /// The callback function provided to this function contains a raw pointer
    /// to Embree geometry.
    ///
    /// # Thread safety
    ///
    /// Embree may invoke this callback from multiple threads concurrently
    /// during a parallel [`Scene::commit`](crate::Scene::commit). The
    /// closure must therefore be safe to call from several threads at once
    /// and to share across them: it must not depend on exclusive `&mut`
    /// access to its captures, and everything it captures must be `Send +
    /// Sync`. The `Fn + Send + Sync` bounds on the closure enforce this.
    pub unsafe fn set_displacement_function<F, D>(&mut self, displacement: F)
    where
        D: UserData,
        F: for<'a> Fn(RTCGeometry, Vertices<'a>, u32, u32, Option<&D>) + Send + Sync + 'static,
    {
        if self.shared.kind == GeometryKind::SUBDIVISION {
            unsafe {
                rtcSetGeometryDisplacementFunction(
                    self.shared.handle,
                    trampoline::displacement_function::<F, D>(),
                )
            }
            self.install_callback(
                CbKind::Displacement,
                ErasedFn::new(displacement),
                std::ptr::null(),
                None,
            );
        }
    }

    /// The owned-data variant of
    /// [`set_displacement_function`](Self::set_displacement_function). See
    /// [`set_intersect_filter_function_owned`](Self::set_intersect_filter_function_owned)
    /// for the per-callback owned-vs-borrowed data model. (Subdivision only.)
    ///
    /// # Safety
    ///
    /// Same contract as
    /// [`set_displacement_function`](Self::set_displacement_function).
    pub unsafe fn set_displacement_function_owned<F, D>(&mut self, displacement: F, data: D)
    where
        D: UserData,
        F: for<'a> Fn(RTCGeometry, Vertices<'a>, u32, u32, Option<&D>) + Send + Sync + 'static,
    {
        if self.shared.kind == GeometryKind::SUBDIVISION {
            let boxed = Box::new(data);
            let ptr = &*boxed as *const D as *const ();
            unsafe {
                rtcSetGeometryDisplacementFunction(
                    self.shared.handle,
                    trampoline::displacement_function::<F, D>(),
                )
            }
            self.install_callback(
                CbKind::Displacement,
                ErasedFn::new(displacement),
                ptr,
                Some(boxed),
            );
        }
    }

    /// The borrowed-data variant of
    /// [`set_displacement_function`](Self::set_displacement_function). See
    /// [`set_intersect_filter_function_borrowed`](Self::set_intersect_filter_function_borrowed)
    /// for the per-callback owned-vs-borrowed data model. (Subdivision only.)
    ///
    /// # Safety
    ///
    /// Same contract as
    /// [`set_displacement_function`](Self::set_displacement_function).
    pub unsafe fn set_displacement_function_borrowed<F, D>(
        &mut self,
        displacement: F,
        data: &'buf D,
    ) where
        D: UserData,
        F: for<'a> Fn(RTCGeometry, Vertices<'a>, u32, u32, Option<&D>) + Send + Sync + 'static,
    {
        if self.shared.kind == GeometryKind::SUBDIVISION {
            let ptr = data as *const D as *const ();
            unsafe {
                rtcSetGeometryDisplacementFunction(
                    self.shared.handle,
                    trampoline::displacement_function::<F, D>(),
                )
            }
            self.install_callback(CbKind::Displacement, ErasedFn::new(displacement), ptr, None);
        }
    }

    /// Removes the displacement function for a subdivision geometry.
    pub fn unset_displacement_function(&mut self) {
        match self.shared.kind {
            GeometryKind::SUBDIVISION => unsafe {
                rtcSetGeometryDisplacementFunction(self.shared.handle, None);
                self.clear_callback(CbKind::Displacement);
            },
            _ => panic!("Only subdivision geometries can have displacement functions!"),
        }
    }

    /// Sets the instanced scene of an instance geometry.
    pub fn set_instanced_scene(&mut self, scene: &Scene) {
        match self.shared.kind {
            GeometryKind::INSTANCE => unsafe {
                rtcSetGeometryInstancedScene(self.shared.handle, scene.handle)
            },
            _ => panic!("Only instance geometries can have instanced scenes!"),
        }
    }

    /// Sets the transformation for a particular time step of an instance
    /// geometry.
    ///
    /// The transformation is specified as a 4x4 column-major matrix.
    pub fn set_transform(&mut self, time_step: u32, transform: &[f32; 16]) {
        match self.shared.kind {
            GeometryKind::INSTANCE => unsafe {
                rtcSetGeometryTransform(
                    self.shared.handle,
                    time_step,
                    Format::FLOAT4X4_COLUMN_MAJOR,
                    transform.as_ptr() as *const _,
                );
            },
            _ => panic!("Only instance geometries can have instanced scenes!"),
        }
    }

    /// Sets the transformation for a particular time step of an instance
    /// geometry as a decomposition of the transformation matrix using
    /// quaternions to represent the rotation.
    pub fn set_transform_quaternion(
        &mut self,
        time_step: u32,
        transform: &QuaternionDecomposition,
    ) {
        match self.shared.kind {
            GeometryKind::INSTANCE => unsafe {
                rtcSetGeometryTransformQuaternion(
                    self.shared.handle,
                    time_step,
                    transform as &QuaternionDecomposition as *const _,
                );
            },
            _ => panic!("Only instance geometries can have instanced scenes!"),
        }
    }

    /// Checks if the vertex attribute is allowed for the geometry.
    ///
    /// This function do not check if the slot of the vertex attribute.
    fn check_vertex_attribute(&self) -> Result<(), Error> {
        match self.shared.kind {
            GeometryKind::GRID | GeometryKind::USER | GeometryKind::INSTANCE => {
                Err(Error::INVALID_OPERATION)
            }
            _ => Ok(()),
        }
    }

    /// Commits pending changes (`rtcCommitGeometry`) and transitions to the
    /// committed, shareable [`Geometry`] phase.
    ///
    /// Consumes the builder: the geometry can no longer be mutated unless you
    /// later regain a builder via [`Geometry::try_edit`]. The returned
    /// [`Geometry`] can be attached to scenes
    /// ([`Scene::attach_geometry`](crate::Scene::attach_geometry))
    /// and shared across threads for concurrent ray queries.
    pub fn commit(self) -> Geometry<'buf> {
        unsafe {
            rtcCommitGeometry(self.shared.handle);
        }
        Geometry {
            shared: self.shared,
        }
    }

    /// The *owned* data bound to `kind` (set via `set_*_owned`), if its type is
    /// `D`. Borrowed data is not returned here, the application already
    /// owns it. Type check is a free `Any` downcast (no stored `TypeId`).
    pub fn callback_data<D: UserData>(&self, kind: CbKind) -> Option<&D> {
        // SAFETY: a live clone => not sole owner => no concurrent mutation (invariant).
        unsafe {
            (*self.shared.data.owners.get()).owned_data[kind as usize]
                .as_ref()?
                .downcast_ref::<D>()
        }
    }
    /// `&mut` to owned data, during the build phase (unique builder =>
    /// exclusive).
    pub fn callback_data_mut<D: UserData>(&mut self, kind: CbKind) -> Option<&mut D> {
        unsafe {
            (*self.shared.data.owners.get()).owned_data[kind as usize]
                .as_mut()?
                .downcast_mut::<D>()
        }
    }

    fn install_callback(
        &mut self,
        kind: CbKind,
        erased: ErasedFn,
        user_data: *const (),
        owned_data: Option<Box<dyn Any + Send + Sync>>,
    ) {
        unsafe {
            let (site, owners) = self.shared.data_mut();
            let i = kind as usize;
            site.slots[i].closure = erased.as_ptr() as *const ();
            site.slots[i].user_data = user_data;
            owners.closures[i] = Some(erased);
            owners.owned_data[i] = owned_data;
        }
    }

    fn clear_callback(&mut self, kind: CbKind) {
        unsafe {
            let (site, owners) = self.shared.data_mut();
            let i = kind as usize;
            site.slots[i] = Slot::EMPTY;
            owners.closures[i] = None;
            owners.owned_data[i] = None;
        }
    }
}

/// The **committed, shareable phase** of an Embree geometry.
///
/// Obtained from [`GeometryBuilder::commit`] (see [`GeometryBuilder`] for the
/// build phase). A committed geometry is read-only and `Send + Sync + Clone`,
/// so it can be attached to one or more scenes
/// ([`Scene::attach_geometry`](crate::Scene::attach_geometry) /
/// [`Scene::attach_geometry_by_id`](crate::Scene::attach_geometry_by_id)) and
/// shared across threads for concurrent ray queries which matches embree's rule
/// that ray queries are thread-safe as long as nothing is modifying the
/// geometry.
///
/// Only read-only operations live here ([`interpolate`](Geometry::interpolate),
/// [`get_buffer`](Geometry::get_buffer),
/// [`callback_data`](Geometry::callback_data), the half-edge topology queries,
/// …). Every mutator lives on [`GeometryBuilder`].
///
/// To modify a geometry again, regain a [`GeometryBuilder`] with
/// [`try_edit`](Geometry::try_edit), which succeeds only when you are the
/// **sole owner**, so a geometry attached to any scene cannot be edited until
/// it is detached everywhere. For the common render-loop toggles
/// (enable/disable, mark a buffer dirty) *without* detaching, use
/// [`Scene::enable_geometry`](crate::Scene::enable_geometry) /
/// [`Scene::disable_geometry`](crate::Scene::disable_geometry) /
/// [`Scene::update_geometry_buffer`](crate::Scene::update_geometry_buffer).
///
/// It does not own the host buffers bound to it, but it does own the underlying
/// embree geometry object (released when the last clone drops).
#[derive(Debug, Clone)]
pub struct Geometry<'buf> {
    pub(crate) shared: Arc<GeometryShared<'buf>>,
}

unsafe impl<'buf> Send for Geometry<'buf> {}

// SAFETY: `GeometryData`'s `UnsafeCell`s are mutated only through a `&mut
// GeometryBuilder`, the unique `Arc<GeometryShared>` owner (strong_count == 1,
// !Clone, !Sync). No shared observer (other clones, the scene's retained clone,
// Embree's traversal threads) coexists with that mutation; and the ownership
// move / thread handoff that must separate the last write from any later shared
// read is what makes the writes visible (see the module invariant). So a shared
// `&Geometry` only ever observes frozen state. The boxed `F`/`D` are
// `Send + Sync` (enforced at registration).
unsafe impl<'buf> Sync for Geometry<'buf> {}

impl<'buf> Geometry<'buf> {
    /// Creates a new geometry in its mutable build phase (a
    /// [`GeometryBuilder`]). Configure it (buffers, callbacks, …), then
    /// [`GeometryBuilder::commit`] to a shareable [`Geometry`].
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use embree3::{Device, Geometry, GeometryKind};
    ///
    /// let device = Device::new().unwrap();
    /// let builder = Geometry::new(&device, GeometryKind::TRIANGLE);
    /// let geometry = builder.commit();
    /// ```
    ///
    /// or use the [`Device::create_geometry`] method:
    ///
    /// ```no_run
    /// use embree3::{Device, GeometryKind};
    ///
    /// let device = Device::new().unwrap();
    /// let builder = device.create_geometry(GeometryKind::TRIANGLE).unwrap();
    /// ```
    #[allow(clippy::new_ret_no_self)]
    pub fn new<'dev>(device: &'dev Device, kind: GeometryKind) -> GeometryBuilder<'buf> {
        let handle = unsafe { rtcNewGeometry(device.handle, kind) };
        // `GeometryShared` is `Sync` but deliberately NOT `Send` (only `Sync` is
        // `unsafe impl`'d), so `Arc<GeometryShared>` is auto-`!Send`/`!Sync` and
        // clippy's `arc_with_non_send_sync` fires. This is intended, not a bug:
        // - The `Arc` is required (NOT `Rc`): `Geometry` is `Send + Sync` and its
        //   clones may be dropped on a different thread, so the strong-count must be
        //   atomic. Thread-safety is asserted at the `Geometry` wrapper (`unsafe impl
        //   Send + Sync`) plus `unsafe impl Sync for GeometryShared`.
        // - Do NOT silence this by making `GeometryShared: Send`. That `!Send` is
        //   load-bearing: it is the only thing keeping `Arc<GeometryShared>` `!Sync`,
        //   which is the only thing keeping `GeometryBuilder` `!Sync` (SB-11 -- a
        //   builder must not be shared across threads while it mutates its
        //   `UnsafeCell`s through `&mut`). Adding `Send` here makes the builder
        //   auto-`Send + Sync` and breaks that guarantee.
        #[allow(clippy::arc_with_non_send_sync)]
        let shared = Arc::new(GeometryShared {
            device: device.clone(),
            handle,
            kind,
            attachments: Mutex::new(HashMap::new()),
            data: GeometryData::default(),
        });
        unsafe {
            rtcSetGeometryUserData(handle, shared.data.call_site.get() as *mut _);
        }
        GeometryBuilder { shared }
    }

    /// Regains the unique mutable [`GeometryBuilder`] to edit this geometry.
    ///
    /// Succeeds only if this is the **sole owner** (not attached to any scene,
    /// no other clone). Returns `Err(self)` if it is shared.
    ///
    /// To fully edit an attached geometry: detach it from every scene first,
    /// then `try_edit`. For cheap dynamic toggles (visibility /
    /// buffer-dirty) on an attached geometry, prefer the
    /// `Scene::{enable,disable}_geometry` / `update_geometry_buffer`
    /// methods, which need no detach.
    ///
    /// # Soundness contract
    ///
    /// Exclusivity is tracked via the `Arc` strong count, i.e. **wrapper
    /// clones**. This is sound because all safe sharing goes through
    /// wrapper clones (including
    /// [`Scene::attach_geometry`](crate::Scene::attach_geometry), which retains
    /// one). Raw [`Geometry::handle`] escapes are outside this guarantee.
    pub fn try_edit(mut self) -> Result<GeometryBuilder<'buf>, Geometry<'buf>> {
        if Arc::get_mut(&mut self.shared).is_some() {
            Ok(GeometryBuilder {
                shared: self.shared,
            })
        } else {
            Err(self)
        }
    }

    /// Returns the raw Embree geometry handle.
    ///
    /// # Safety
    ///
    /// Use this function only if you know what you are doing. The returned
    /// handle is a raw pointer to an Embree reference-counted object. The
    /// reference count is not increased by this function, so the caller must
    /// ensure that the handle is not used after the geometry object is
    /// destroyed.
    pub unsafe fn handle(&self) -> RTCGeometry { self.shared.handle }

    /// Returns the buffer bound to the given slot and usage.
    pub fn get_buffer(&self, usage: BufferUsage, slot: u32) -> Option<BufferSource<'_>> {
        self.shared.buffer_source(usage, slot)
    }

    /// Maps a geometry-local buffer slot for **reading**. The returned view
    /// borrows `&self`, so it cannot coexist with
    /// [`try_edit`](Geometry::try_edit) (which consumes `self`), i.e. the
    /// buffer cannot be rebound while a view is held. Concurrent read views
    /// are fine. `Err(INVALID_ARGUMENT)` if the slot is unbound /
    /// not a local buffer, or the `T` layout checks fail. To *write* an
    /// attached geometry's buffer, go through
    /// [`Scene::with_geometry_buffer_mut`](crate::Scene::with_geometry_buffer_mut).
    pub fn map_buffer<T: BufferData>(
        &self,
        usage: BufferUsage,
        slot: u32,
    ) -> Result<BufferView<'_, T>, Error> {
        let (ptr, len) = self.shared.map_local::<T>(usage, slot)?;
        // SAFETY: validated; shared borrow of `self` for the view.
        Ok(unsafe { BufferView::from_raw_parts(ptr, len) })
    }

    /// Returns the type of geometry of this geometry.
    pub fn kind(&self) -> GeometryKind { self.shared.kind }

    /// The *owned* data bound to `kind` (set via `set_*_owned`), if its type is
    /// `D`. Borrowed data is not returned here, the application already
    /// owns it. Type check is a free `Any` downcast (no stored `TypeId`).
    pub fn callback_data<D: UserData>(&self, kind: CbKind) -> Option<&D> {
        // SAFETY: a live clone => not sole owner => no concurrent mutation (invariant).
        unsafe {
            (*self.shared.data.owners.get()).owned_data[kind as usize]
                .as_ref()?
                .downcast_ref::<D>()
        }
    }

    /// Smoothly interpolates per-vertex data over the geometry.
    ///
    /// This interpolation is supported for triangle meshes, quad meshes, curve
    /// geometries, and subdivision geometries. Apart from interpolating the
    /// vertex at- tribute itself, it is also possible to get the first and
    /// second order derivatives of that value. This interpolation ignores
    /// displacements of subdivision surfaces and always interpolates the
    /// underlying base surface.
    ///
    /// Interpolated values are written to `args.p`, `args.dp_du`, `args.dp_dv`,
    /// `args.ddp_du_du`, `args.ddp_dv_dv`, and `args.ddp_du_dv`. Set them to
    /// `None` if you do not need to interpolate them.
    ///
    /// All output arrays must be padded to 16 bytes.
    pub fn interpolate(&self, input: InterpolateInput, output: &mut InterpolateOutput) {
        let args = RTCInterpolateArguments {
            geometry: self.shared.handle,
            primID: input.prim_id,
            u: input.u,
            v: input.v,
            bufferType: input.usage,
            bufferSlot: input.slot,
            P: output
                .p_mut()
                .map(|p| p.as_mut_ptr())
                .unwrap_or(ptr::null_mut()),
            dPdu: output
                .dp_du_mut()
                .map(|p| p.as_mut_ptr())
                .unwrap_or(ptr::null_mut()),
            dPdv: output
                .dp_dv_mut()
                .map(|p| p.as_mut_ptr())
                .unwrap_or(ptr::null_mut()),
            ddPdudu: output
                .ddp_du_du_mut()
                .map(|p| p.as_mut_ptr())
                .unwrap_or(ptr::null_mut()),
            ddPdvdv: output
                .ddp_dv_dv_mut()
                .map(|p| p.as_mut_ptr())
                .unwrap_or(ptr::null_mut()),
            ddPdudv: output
                .ddp_du_dv_mut()
                .map(|p| p.as_mut_ptr())
                .unwrap_or(ptr::null_mut()),
            valueCount: output.value_count(),
        };
        unsafe {
            rtcInterpolate(&args as _);
        }
    }

    /// Performs N interpolations of vertex attribute data.
    ///
    /// Similar to [`Geometry::interpolate`], but performs N many interpolations
    /// at once. It additionally gets an array of u/v coordinates
    /// ([`InterpolateNInput::u`]/[`InterpolateNInput::v`]) and a valid mask
    /// ([`InterpolateNInput::valid`]) that specifies which of these
    /// coordinates are valid. The valid mask points to `n` integers, and a
    /// value of -1 denotes valid and 0 invalid.
    ///
    /// If [`InterpolateNInput::valid`] is `None`, all coordinates are
    /// assumed to be valid.
    ///
    /// The destination arrays are filled in structure of array (SOA) layout.
    /// The value [`InterpolateNInput::n`] must be divisible by 4.
    ///
    /// All changes to that geometry must be properly committed.
    pub fn interpolate_n(&self, input: InterpolateNInput, output: &mut InterpolateOutput) {
        assert_eq!(input.n % 4, 0, "N must be a multiple of 4!");
        let args = RTCInterpolateNArguments {
            geometry: self.shared.handle,
            N: input.n,
            valid: input
                .valid
                .as_ref()
                .map(|v| v.as_ptr() as *const _)
                .unwrap_or(ptr::null()),
            primIDs: input.prim_id.as_ptr(),
            u: input.u.as_ptr(),
            v: input.v.as_ptr(),
            bufferType: input.usage,
            bufferSlot: input.slot,
            P: output
                .p_mut()
                .map(|p| p.as_mut_ptr())
                .unwrap_or(ptr::null_mut()),
            dPdu: output
                .dp_du_mut()
                .map(|p| p.as_mut_ptr())
                .unwrap_or(ptr::null_mut()),
            dPdv: output
                .dp_dv_mut()
                .map(|p| p.as_mut_ptr())
                .unwrap_or(ptr::null_mut()),
            ddPdudu: output
                .ddp_du_du_mut()
                .map(|p| p.as_mut_ptr())
                .unwrap_or(ptr::null_mut()),
            ddPdvdv: output
                .ddp_dv_dv_mut()
                .map(|p| p.as_mut_ptr())
                .unwrap_or(ptr::null_mut()),
            ddPdudv: output
                .ddp_du_dv_mut()
                .map(|p| p.as_mut_ptr())
                .unwrap_or(ptr::null_mut()),
            valueCount: output.value_count(),
        };
        unsafe {
            rtcInterpolateN(&args as _);
        }
    }

    /// Returns the first half edge of a face.
    ///
    /// This function can only be used for subdivision meshes. As all topologies
    /// of a subdivision geometry share the same face buffer the function does
    /// not depend on the topology ID.
    pub fn get_first_half_edge(&self, face_id: u32) -> u32 {
        match self.shared.kind {
            GeometryKind::SUBDIVISION => unsafe {
                rtcGetGeometryFirstHalfEdge(self.shared.handle, face_id)
            },
            _ => panic!("Only subdivision geometries can have half edges!"),
        }
    }

    /// Returns the face of some half edge.
    ///
    /// This function can only be used for subdivision meshes. As all topologies
    /// of a subdivision geometry share the same face buffer the function does
    /// not depend on the topology ID.
    pub fn get_face(&self, half_edge_id: u32) -> u32 {
        match self.shared.kind {
            GeometryKind::SUBDIVISION => unsafe {
                rtcGetGeometryFace(self.shared.handle, half_edge_id)
            },
            _ => panic!("Only subdivision geometries can have half edges!"),
        }
    }

    /// Returns the next half edge of some half edge.
    ///
    /// This function can only be used for subdivision meshes. As all topologies
    /// of a subdivision geometry share the same face buffer the function does
    /// not depend on the topology ID.
    pub fn get_next_half_edge(&self, half_edge_id: u32) -> u32 {
        match self.shared.kind {
            GeometryKind::SUBDIVISION => unsafe {
                rtcGetGeometryNextHalfEdge(self.shared.handle, half_edge_id)
            },
            _ => panic!("Only subdivision geometries can have half edges!"),
        }
    }

    /// Returns the previous half edge of some half edge.
    pub fn get_previous_half_edge(&self, half_edge_id: u32) -> u32 {
        match self.shared.kind {
            GeometryKind::SUBDIVISION => unsafe {
                rtcGetGeometryPreviousHalfEdge(self.shared.handle, half_edge_id)
            },
            _ => panic!("Only subdivision geometries can have half edges!"),
        }
    }

    /// Returns the opposite half edge of some half edge.
    pub fn get_opposite_half_edge(&self, topology_id: u32, edge_id: u32) -> u32 {
        match self.shared.kind {
            GeometryKind::SUBDIVISION => unsafe {
                rtcGetGeometryOppositeHalfEdge(self.shared.handle, topology_id, edge_id)
            },
            _ => panic!("Only subdivision geometries can have half edges!"),
        }
    }

    /// Returns the interpolated instance transformation for the specified time
    /// step.
    ///
    /// The transformation is returned as a 4x4 column-major matrix.
    pub fn get_transform(&mut self, time: f32) -> [f32; 16] {
        match self.shared.kind {
            GeometryKind::INSTANCE => unsafe {
                let mut transform = [0.0; 16];
                rtcGetGeometryTransform(
                    self.shared.handle,
                    time,
                    Format::FLOAT4X4_COLUMN_MAJOR,
                    transform.as_mut_ptr() as *mut _,
                );
                transform
            },
            _ => panic!("Only instance geometries can have instanced scenes!"),
        }
    }
}

/// The arguments for the `Geometry::interpolate` function.
pub struct InterpolateInput {
    /// Primitive to interpolate within.
    pub prim_id: u32,
    /// First barycentric / parametric coordinate.
    pub u: f32,
    /// Second barycentric / parametric coordinate.
    pub v: f32,
    /// Which buffer to interpolate (e.g. `VERTEX` or `VERTEX_ATTRIBUTE`).
    pub usage: BufferUsage,
    /// Buffer slot to interpolate.
    pub slot: u32,
}

/// The arguments for the `Geometry::interpolate_n` function.
pub struct InterpolateNInput<'a> {
    /// Optional per-element validity mask (`-1` valid, `0` skip); `None` runs
    /// all elements.
    pub valid: Option<Cow<'a, [u32]>>,
    /// Primitive index per element.
    pub prim_id: Cow<'a, [u32]>,
    /// First coordinate per element.
    pub u: Cow<'a, [f32]>,
    /// Second coordinate per element.
    pub v: Cow<'a, [f32]>,
    /// Which buffer to interpolate.
    pub usage: BufferUsage,
    /// Buffer slot to interpolate.
    pub slot: u32,
    /// Number of elements.
    pub n: u32,
}

/// The output of the `Geometry::interpolate` and `Geometry::interpolate_n`
/// functions in structure of array (SOA) layout.
pub struct InterpolateOutput {
    /// The buffer containing the interpolated values.
    buffer: Vec<f32>,
    /// The number of values per attribute.
    count_per_attribute: u32,
    /// The offset of the `p` attribute in the buffer.
    p_offset: Option<u32>,
    /// The offset of the `dp_du` attribute in the buffer.
    dp_du_offset: Option<u32>,
    /// The offset of the `dp_dv` attribute in the buffer.
    dp_dv_offset: Option<u32>,
    /// The offset of the `ddp_du_du` attribute in the buffer.
    ddp_du_du_offset: Option<u32>,
    /// The offset of the `ddp_dv_dv` attribute in the buffer.
    ddp_dv_dv_offset: Option<u32>,
    /// The offset of the `ddp_du_dv` attribute in the buffer.
    ddp_du_dv_offset: Option<u32>,
}

impl InterpolateOutput {
    pub fn new(count: u32, zeroth_order: bool, first_order: bool, second_order: bool) -> Self {
        assert!(
            count > 0,
            "The number of interpolated values must be greater than 0!"
        );
        assert!(
            zeroth_order || first_order || second_order,
            "At least one of the origin value, first order derivative, or second order derivative \
             must be true!"
        );
        let mut offset = 0;
        let p_offset = zeroth_order.then(|| {
            let _offset = offset;
            offset += count;
            _offset
        });
        let dp_du_offset = first_order.then(|| {
            let _offset = offset;
            offset += count;
            _offset
        });
        let dp_dv_offset = first_order.then(|| {
            let _offset = offset;
            offset += count;
            _offset
        });
        let ddp_du_du_offset = second_order.then(|| {
            let _offset = offset;
            offset += count;
            _offset
        });
        let ddp_dv_dv_offset = second_order.then(|| {
            let _offset = offset;
            offset += count;
            _offset
        });
        let ddp_du_dv_offset = second_order.then(|| {
            let _offset = offset;
            offset += count;
            _offset
        });

        Self {
            buffer: vec![0.0; (offset + count) as usize],
            count_per_attribute: count,
            p_offset,
            dp_du_offset,
            dp_dv_offset,
            ddp_du_du_offset,
            ddp_dv_dv_offset,
            ddp_du_dv_offset,
        }
    }

    /// Returns the interpolated `p` attribute.
    pub fn p(&self) -> Option<&[f32]> {
        self.p_offset.map(|offset| {
            &self.buffer[offset as usize..(offset + self.count_per_attribute) as usize]
        })
    }

    /// Returns the mutable interpolated `p` attribute.
    pub fn p_mut(&mut self) -> Option<&mut [f32]> {
        self.p_offset.map(move |offset| {
            &mut self.buffer[offset as usize..(offset + self.count_per_attribute) as usize]
        })
    }

    /// Returns the interpolated `dp_du` attribute.
    pub fn dp_du(&self) -> Option<&[f32]> {
        self.dp_du_offset.map(|offset| {
            &self.buffer[offset as usize..(offset + self.count_per_attribute) as usize]
        })
    }

    /// Returns the mutable interpolated `dp_du` attribute.
    pub fn dp_du_mut(&mut self) -> Option<&mut [f32]> {
        self.dp_du_offset.map(|offset| {
            &mut self.buffer[offset as usize..(offset + self.count_per_attribute) as usize]
        })
    }

    /// Returns the interpolated `dp_dv` attribute.
    pub fn dp_dv(&self) -> Option<&[f32]> {
        self.dp_dv_offset.map(|offset| {
            &self.buffer[offset as usize..(offset + self.count_per_attribute) as usize]
        })
    }

    /// Returns the mutable interpolated `dp_dv` attribute.
    pub fn dp_dv_mut(&mut self) -> Option<&mut [f32]> {
        self.dp_dv_offset.map(|offset| {
            &mut self.buffer[offset as usize..(offset + self.count_per_attribute) as usize]
        })
    }

    /// Returns the interpolated `ddp_du_du` attribute.
    pub fn ddp_du_du(&self) -> Option<&[f32]> {
        self.ddp_du_du_offset.map(|offset| {
            &self.buffer[offset as usize..(offset + self.count_per_attribute) as usize]
        })
    }

    /// Returns the mutable interpolated `ddp_du_du` attribute.
    pub fn ddp_du_du_mut(&mut self) -> Option<&mut [f32]> {
        self.ddp_du_du_offset.map(|offset| {
            &mut self.buffer[offset as usize..(offset + self.count_per_attribute) as usize]
        })
    }

    /// Returns the interpolated `ddp_dv_dv` attribute.
    pub fn ddp_dv_dv(&self) -> Option<&[f32]> {
        self.ddp_dv_dv_offset.map(|offset| {
            &self.buffer[offset as usize..(offset + self.count_per_attribute) as usize]
        })
    }

    /// Returns the mutable interpolated `ddp_dv_dv` attribute.
    pub fn ddp_dv_dv_mut(&mut self) -> Option<&mut [f32]> {
        self.ddp_dv_dv_offset.map(move |offset| {
            &mut self.buffer[offset as usize..(offset + self.count_per_attribute) as usize]
        })
    }

    /// Returns the interpolated `ddp_du_dv` attribute.
    pub fn ddp_du_dv(&self) -> Option<&[f32]> {
        self.ddp_du_dv_offset.map(|offset| {
            &self.buffer[offset as usize..(offset + self.count_per_attribute) as usize]
        })
    }

    /// Returns the mutable interpolated `ddp_du_dv` attribute.
    pub fn ddp_du_dv_mut(&mut self) -> Option<&mut [f32]> {
        self.ddp_du_dv_offset.map(move |offset| {
            &mut self.buffer[offset as usize..(offset + self.count_per_attribute) as usize]
        })
    }

    /// Returns the number of values per attribute.
    pub fn value_count(&self) -> u32 { self.count_per_attribute }
}

macro_rules! impl_geometry_type {
    ($name:ident, $kind:path, $(#[$meta:meta])*) => {
        /// Typed [`GeometryBuilder`] for a fixed geometry kind. Build via its
        /// `Deref`/`DerefMut` to [`GeometryBuilder`], then `commit` to a
        /// shareable [`Geometry`].
        #[derive(Debug)]
        pub struct $name<'a>(GeometryBuilder<'a>);

        impl<'a> Deref for $name<'a> {
            type Target = GeometryBuilder<'a>;

            fn deref(&self) -> &Self::Target { &self.0 }
        }

        impl<'a> DerefMut for $name<'a> {
            fn deref_mut(&mut self) -> &mut Self::Target { &mut self.0 }
        }

        $(#[$meta])*
        impl<'a> $name<'a> {
            pub fn new(device: &Device) -> Result<Self, Error> {
                Ok(Self(Geometry::new(device, $kind)))
            }

            /// Commit pending changes and move to the shareable committed phase.
            pub fn commit(self) -> Geometry<'a> { self.0.commit() }
        }
    };
}

impl_geometry_type!(TriangleMeshBuilder, GeometryKind::TRIANGLE,
    /// A triangle mesh geometry builder.
    ///
    /// The index buffer must contain an array of three 32-bit indices per triangle
    /// ([`Format::UINT3`]), and the number of primitives is inferred from the size
    /// of the index buffer.
    ///
    /// The vertex buffer must contain an array of single precision x, y,
    /// and z floating point coordinates per vertex ([`Format::FLOAT3`]), and the
    /// number of vertices is inferred from the size of the vertex buffer.
    /// The vertex buffer can be at most 16 GB in size.
    ///
    /// The parameterization of a triangle uses the first vertex `p0` as the
    /// base point, the vector `p1 - p0` as the u-direction, and the vector
    /// `p2 - p0` as the v-direction. Thus vertex attributes t0, t1, and t2
    /// can be linearly interpolated over the triangle using the barycentric
    /// coordinates `(u,v)` of the hit point:
    ///
    /// t_uv = (1-u-v) * t0 + u * t1 + v * t2
    ///      = t0 + u * (t1 - t0) + v * (t2 - t0)
    ///
    /// A triangle whose vertices are laid out counter-clockwise has its geometry
    /// normal pointing upwards outside the front face.
    ///
    /// For multi-segment motion blur, the number of time steps must be first
    /// specified using the [`GeometryBuilder::set_time_step_count`] call. Then a vertex
    /// buffer for each time step can be set using different buffer slots, and all
    /// these buffers have to have the same stride and size.
);

impl_geometry_type!(QuadMeshBuilder, GeometryKind::QUAD,
    /// A quad mesh geometry builder.
    ///
    /// The index buffer must contain an array of four 32-bit indices per triangle
    /// ([`Format::UINT4`]), and the number of primitives is inferred from the size
    /// of the index buffer.
    ///
    /// The vertex buffer must contain an array of single precision x, y,
    /// and z floating point coordinates per vertex ([`Format::FLOAT3`]), and the
    /// number of vertices is inferred from the size of the vertex buffer.
    /// The vertex buffer can be at most 16 GB in size.
    ///
    /// A quad is internally handled as a pair of two triangles `v0`, `v1`, `v3`
    /// and `v2`, `v3`, `v1`, with the `u'/v'` coordinates of the second triangle
    /// corrected by `u = 1-u'` and `v = 1-v'` to produce a quad parametrization
    /// where `u` and `v` are in the range 0 to 1. Thus the parametrization of a quad
    /// uses the first vertex `p0` as base point, and the vector `p1 - p0` as
    /// u-direction, and `p3 - p0` as v-direction. Thus vertex attributes t0, t1, t2, t3
    /// can be bilinearly interpolated over the quadrilateral the following way:
    ///
    /// t_uv = (1-v)((1-u) * t0 + u * t1) + v * ((1-u) * t3 + u * t2)
    ///
    /// Mixed triangle/quad meshes are supported by encoding a triangle as a quad,
    /// which can be achieved by replicating the last triangle vertex (v0,v1,v2 ->
    /// v0,v1,v2,v2). This way the second triangle is a line (which can never get
    /// hit), and the parametrization of the first triangle is compatible with the
    /// standard triangle parametrization.
    /// A quad whose vertices are laid out counter-clockwise has its geometry
    /// normal pointing upwards outside the front face.
    ///
    ///    p3 ------- p2
    ///    ^          |
    ///  v |          |
    ///    |          |
    ///    p0 ------> p1
    ///        u
);

impl_geometry_type!(UserGeometryBuilder, GeometryKind::USER,
    /// A user geometry builder.
);

impl_geometry_type!(InstanceGeometryBuilder, GeometryKind::INSTANCE,
    /// An instance geometry builder.
);

/// Arguments handed to a user-geometry **intersect** callback registered via
/// [`GeometryBuilder::set_intersect_function`].
///
/// Besides the ray packet and per-callback user data, it carries the machinery
/// to run a candidate hit through the geometry's intersection filter and the
/// context filter via [`filter_intersection`](Self::filter_intersection), which
/// is the only way a user geometry can honour filter functions, since embree
/// cannot auto-invoke them for user-computed hits.
///
/// Per-ray usage (the filter primitive is always `N = 1`; loop the packet):
/// gather lane `i` with [`ray`](Self::ray), build a fully-initialized [`Hit`],
/// set `ray.tfar` to the candidate distance, call
/// [`filter_intersection`](Self::filter_intersection), and on `true` commit
/// with [`commit_hit`](Self::commit_hit). Skip lanes where `valid_n()[i] == 0`.
pub struct IntersectFunctionNArgs<'a, D: UserData> {
    // The original FFI args pointer. Required by `rtcFilterIntersection`, and the
    // source of the ray/hit packet (`(*raw).rayhit`) and `N`. Valid only for the
    // duration of the callback invocation; `*const` makes the struct `!Send`/`!Sync`
    // so it cannot escape to another thread.
    raw: *const RTCIntersectFunctionNArguments,
    valid_n: ValidityN<'a>,
    context: &'a mut IntersectContext,
    geom_id: u32,
    prim_id: u32,
    user_data: Option<&'a D>,
}

impl<'a, D: UserData> IntersectFunctionNArgs<'a, D> {
    /// Number of rays in the packet.
    pub fn len(&self) -> usize {
        // SAFETY: `raw` is the live args pointer for this callback invocation.
        unsafe { (*self.raw).N as usize }
    }

    /// Whether the packet is empty.
    pub fn is_empty(&self) -> bool { self.len() == 0 }

    /// Per-ray validity mask (`0` = inactive lane, skip it; `-1` = active).
    pub fn valid_n(&self) -> &ValidityN<'a> { &self.valid_n }

    /// Mutable validity mask.
    pub fn valid_n_mut(&mut self) -> &mut ValidityN<'a> { &mut self.valid_n }

    /// The base intersection context.
    pub fn context(&self) -> &IntersectContext { self.context }

    /// The base intersection context, mutably.
    pub fn context_mut(&mut self) -> &mut IntersectContext { self.context }

    /// Recover the per-ray extension `T` from the context.
    ///
    /// # Safety
    ///
    /// The ray query that produced this callback must have used an
    /// [`IntersectContextExt<T>`](crate::IntersectContextExt) with the same
    /// `T`. See [`IntersectContext::ext`](crate::IntersectContext::ext).
    pub unsafe fn context_ext<T>(&self) -> &T { self.context.ext::<T>() }

    /// Mutable [`context_ext`](Self::context_ext).
    ///
    /// # Safety
    ///
    /// Same as [`context_ext`](Self::context_ext).
    pub unsafe fn context_ext_mut<T>(&mut self) -> &mut T { self.context.ext_mut::<T>() }

    /// Geometry ID being intersected.
    pub fn geom_id(&self) -> u32 { self.geom_id }

    /// Primitive ID being intersected.
    pub fn prim_id(&self) -> u32 { self.prim_id }

    /// Per-callback user data (if bound via the `_owned` / `_borrowed` setter).
    pub fn user_data(&self) -> Option<&D> { self.user_data }

    // The ray packet (SoA) of the underlying `RTCRayHitN`. The ray block is at
    // offset 0 of the rayhit buffer.
    #[inline]
    fn rays(&self) -> RayN<'a> {
        RayN {
            ptr: unsafe { (*self.raw).rayhit as *mut RTCRayN },
            len: self.len(),
            marker: PhantomData,
        }
    }

    // The hit packet (SoA). `RTCRayHitN` lays the hit block after the 12-float
    // ray block, i.e. at `rayhit + 12 * N` u32s, the same offset `RayHitN::hit_n`
    // uses. NOTE: this is the rayhit's *own* hit block (for scatter); it is NOT
    // the filter's `hit` argument, which is always a separate `Hit` local.
    #[inline]
    fn hits(&self) -> HitN<'a> {
        let n = self.len();
        HitN {
            ptr: unsafe { ((*self.raw).rayhit as *const u32).add(12 * n) as *mut RTCHitN },
            len: n,
            marker: PhantomData,
        }
    }

    /// Gather lane `i` of the packet into a contiguous single-ray [`Ray`]
    /// (≈ embree's `rtcGetRayHitFromRayHitN`, ray part). `ray.tfar` is the
    /// current closest-hit distance for that lane.
    pub fn ray(&self, i: usize) -> Ray {
        assert!(i < self.len(), "ray index out of bounds");
        // SAFETY: just checked `i < len`.
        unsafe { self.ray_unchecked(i) }
    }

    /// Run a candidate single-ray `hit` (paired with its `ray`, whose `tfar` is
    /// the candidate distance) through the geometry's intersection filter
    /// **and** the context filter. Returns `true` if the hit survived (then
    /// commit it with [`commit_hit`](Self::commit_hit)); `false` if
    /// rejected.
    ///
    /// `hit` must be **fully initialized** (`Ng_*`, `u`, `v`, `geomID`,
    /// `primID`, `instID`) which are required by the filter.
    pub fn filter_intersection(&mut self, ray: &mut Ray, hit: &mut Hit) -> bool {
        let mut valid: i32 = -1;
        let fargs = RTCFilterFunctionNArguments {
            valid: &mut valid,
            // SAFETY: `raw` is the live args pointer for this callback invocation.
            // `geometryUserPtr` here is the crate's per-geometry `CallSite` pointer,
            // which the filter trampolines already expect.
            geometryUserPtr: unsafe { (*self.raw).geometryUserPtr },
            context: unsafe { (*self.raw).context },
            ray: ray as *mut Ray as *mut RTCRayN,
            hit: hit as *mut Hit as *mut RTCHitN,
            N: 1,
        };
        // SAFETY: `fargs` supplies separate contiguous N=1 `ray` and `hit` buffers
        // (the filter reads `ray` and `hit` as independent pointers, `hit` is NOT
        // `ray + 12*N`; we always pass the candidate `hit`, never one derived from
        // the rayhit). `raw` is the live args pointer.
        unsafe { rtcFilterIntersection(self.raw, &fargs) };
        valid != 0
    }

    /// Scatter an accepted single `hit` and `ray.tfar` back to lane `i` of the
    /// packet (≈ embree's `rtcCopyHitToHitN`). Single-level instancing only
    /// (`instID[0]`).
    pub fn commit_hit(&mut self, i: usize, ray: &Ray, hit: &Hit) {
        assert!(i < self.len(), "commit index out of bounds");
        // SAFETY: just checked `i < len`.
        unsafe { self.commit_hit_unchecked(i, ray, hit) }
    }

    /// Convenience: [`filter_intersection`](Self::filter_intersection) then, on
    /// survival, [`commit_hit`](Self::commit_hit).
    ///
    /// Runs the candidate (`ray`, `hit`) through the geometry's intersection
    /// filter and the context filter; if it survives, commits it to lane `i`.
    /// Returns `true` if the hit was committed, `false` if the filter rejected
    /// it. `ray.tfar` must already be set to the candidate distance and `hit`
    /// fully initialized (see
    /// [`filter_intersection`](Self::filter_intersection)).
    pub fn filter_and_commit_hit(&mut self, i: usize, ray: &mut Ray, hit: &mut Hit) -> bool {
        if self.filter_intersection(ray, hit) {
            self.commit_hit(i, ray, hit);
            true
        } else {
            false
        }
    }

    /// Set lane `i`'s packet-ray `tfar` (to a candidate distance before a
    /// packet filter, or to restore it after a rejection).
    pub fn set_tfar(&mut self, i: usize, tfar: f32) {
        assert!(i < self.len(), "tfar index out of bounds");
        // SAFETY: just checked `i < len`.
        unsafe { self.set_tfar_unchecked(i, tfar) }
    }

    // --- Unchecked gather/scatter primitives for the proven-in-range lane
    // handles. The public `ray`/`commit_hit`/`set_tfar` above keep their bounds
    // check; these omit it and are `#[inline(always)]`, so on the lane path the
    // `RayN`/`HitN` SoA accesses inline to direct loads/stores with no per-field
    // `cmp`/panic branch.

    /// # Safety: `i < self.len()`.
    #[inline(always)]
    unsafe fn ray_unchecked(&self, i: usize) -> Ray { self.rays().gather_unchecked(i) }

    /// # Safety: `i < self.len()`.
    #[inline(always)]
    unsafe fn commit_hit_unchecked(&mut self, i: usize, ray: &Ray, hit: &Hit) {
        self.rays().set_tfar_unchecked(i, ray.tfar);
        self.hits().scatter_unchecked(i, hit);
    }

    /// # Safety: `i < self.len()`.
    #[inline(always)]
    unsafe fn set_tfar_unchecked(&mut self, i: usize, tfar: f32) {
        self.rays().set_tfar_unchecked(i, tfar);
    }

    /// Iterate the **active** lanes (`valid_n()[i] != 0`), skipping inactive
    /// ones. Each [`IntersectLane`] handle carries its (already in-range,
    /// active) index, so per-lane operations need no index argument:
    ///
    /// ```ignore
    /// args.for_each_active_lane(|mut lane| {
    ///     let mut ray = lane.ray();
    ///     // ... compute a candidate `hit`, set `ray.tfar` ...
    ///     if lane.filter_intersection(&mut ray, &mut hit) {
    ///         lane.commit_hit(&ray, &hit);
    ///     }
    /// });
    /// ```
    ///
    /// This is the safe replacement for the `for i in 0..len { if valid... }`
    /// boilerplate. (A `for lane in ...` iterator yielding mutating handles
    /// would be a *lending* iterator, which `std::iter::Iterator` cannot
    /// express soundly; the closure form gives the same ergonomics with one
    /// lane borrowed at a time.)
    #[inline(always)]
    pub fn for_each_active_lane(&mut self, mut f: impl for<'b> FnMut(IntersectLane<'a, 'b, D>)) {
        let n = self.len();
        for i in 0..n {
            // SAFETY: `i < n`; read this lane of the validity mask directly,
            // skipping the checked `ValidityN` index on this hot loop.
            if unsafe { *self.valid_n.ptr.add(i) } != 0 {
                f(IntersectLane {
                    args: &mut *self,
                    i,
                });
            }
        }
    }

    /// Filter the whole packet in ONE `rtcFilterIntersection` call (`N =
    /// len()`), using the packet's own ray block as the filter ray input.
    ///
    /// - `hits[i]`: candidate [`Hit`] for lane `i`, fully initialized for every
    ///   lane marked active in `valid`. `hits.len()` must equal `len()`.
    /// - `valid[i]`: `-1` = test this lane, `0` = skip. On return `valid[i] ==
    ///   0` means the lane was skipped or rejected; `-1` means it survived.
    ///   `valid.len()` must equal `len()`.
    ///
    /// Set each active lane's `tfar` via [`set_tfar`](Self::set_tfar)
    /// **before** calling (the filter reads the packet ray). This does NOT
    /// commit and does NOT restore `tfar`: commit survivors (e.g.
    /// `commit_hit(i, &self.ray(i), &hits[i])`) and restore `tfar` on
    /// rejected lanes yourself.
    pub fn filter_intersection_n(&mut self, hits: &mut [Hit], valid: &mut [i32]) {
        let n = self.len();
        assert_eq!(hits.len(), n, "hits length must equal packet width");
        assert_eq!(valid.len(), n, "valid length must equal packet width");

        // Stage an N-wide SoA candidate-hit scratch (separate from the packet's hit
        // block, so a rejected lane never leaves a stale hit there). RTCHitN SoA is
        // 8 fields x N: [Ng_x, Ng_y, Ng_z, u, v, primID, geomID, instID], N <= 16.
        let mut scratch = [0u32; 8 * 16];
        {
            let mut hn = HitN {
                ptr: scratch.as_mut_ptr() as *mut RTCHitN,
                len: n,
                marker: PhantomData,
            };
            for i in 0..n {
                if valid[i] == 0 {
                    continue;
                }
                hn.set_normal(i, [hits[i].Ng_x, hits[i].Ng_y, hits[i].Ng_z]);
                hn.set_uv(i, [hits[i].u, hits[i].v]);
                hn.set_prim_id(i, hits[i].primID);
                hn.set_geom_id(i, hits[i].geomID);
                hn.set_inst_id(i, hits[i].instID[0]);
            }
        }

        let fargs = RTCFilterFunctionNArguments {
            valid: valid.as_mut_ptr(),
            // SAFETY: `raw` is the live args pointer for this callback invocation.
            geometryUserPtr: unsafe { (*self.raw).geometryUserPtr },
            context: unsafe { (*self.raw).context },
            // Packet's own ray block, already N-wide SoA, no copy.
            ray: unsafe { (*self.raw).rayhit as *mut RTCRayN },
            hit: scratch.as_mut_ptr() as *mut RTCHitN,
            N: n as u32,
        };
        // SAFETY: `ray` is the packet's N-wide SoA ray block; `hit` is our N-wide SoA
        // candidate scratch; `valid` has N entries; `raw` is live.
        unsafe { rtcFilterIntersection(self.raw, &fargs) };

        // The filter may modify the candidate hits; transpose the scratch back.
        let hn = HitN {
            ptr: scratch.as_mut_ptr() as *mut RTCHitN,
            len: n,
            marker: PhantomData,
        };
        for i in 0..n {
            if valid[i] == 0 {
                continue;
            }
            let ng = hn.normal(i);
            hits[i].Ng_x = ng[0];
            hits[i].Ng_y = ng[1];
            hits[i].Ng_z = ng[2];
            hits[i].u = hn.u(i);
            hits[i].v = hn.v(i);
            hits[i].primID = hn.prim_id(i);
            hits[i].geomID = hn.geom_id(i);
            hits[i].instID[0] = hn.inst_id(i);
        }
    }
}

/// A single active lane of an intersect callback's packet, yielded by
/// [`IntersectFunctionNArgs::for_each_active_lane`]. Its index is already known
/// in-range and active, so the per-lane operations take no index argument.
pub struct IntersectLane<'a, 'b, D: UserData> {
    args: &'b mut IntersectFunctionNArgs<'a, D>,
    i: usize,
}

impl<'a, 'b, D: UserData> IntersectLane<'a, 'b, D> {
    // The per-lane operations call the `*_unchecked` primitives directly: the
    // index is in range by construction (`for_each_active_lane` is the only
    // constructor), so the bounds check is genuinely redundant and is omitted
    // structurally (not just hinted to the optimizer).

    /// This lane's index in the packet.
    pub fn index(&self) -> usize { self.i }

    /// Gather this lane's ray.
    #[inline(always)]
    pub fn ray(&self) -> Ray {
        // SAFETY: `self.i` is in range by construction (see above).
        unsafe { self.args.ray_unchecked(self.i) }
    }

    /// Run a candidate through the filter chain (see
    /// [`IntersectFunctionNArgs::filter_intersection`]).
    #[inline(always)]
    pub fn filter_intersection(&mut self, ray: &mut Ray, hit: &mut Hit) -> bool {
        self.args.filter_intersection(ray, hit)
    }

    /// Commit a surviving hit to this lane (see
    /// [`IntersectFunctionNArgs::commit_hit`]).
    #[inline(always)]
    pub fn commit_hit(&mut self, ray: &Ray, hit: &Hit) {
        // SAFETY: `self.i` is in range by construction (see above).
        unsafe { self.args.commit_hit_unchecked(self.i, ray, hit) }
    }

    /// Set this lane's packet-ray `tfar`.
    #[inline(always)]
    pub fn set_tfar(&mut self, tfar: f32) {
        // SAFETY: `self.i` is in range by construction (see above).
        unsafe { self.args.set_tfar_unchecked(self.i, tfar) }
    }

    /// Geometry ID being intersected.
    pub fn geom_id(&self) -> u32 { self.args.geom_id() }

    /// Primitive ID being intersected.
    pub fn prim_id(&self) -> u32 { self.args.prim_id() }

    /// Per-callback user data.
    pub fn user_data(&self) -> Option<&D> { self.args.user_data() }
}

/// Arguments handed to a user-geometry **occluded** callback registered via
/// [`GeometryBuilder::set_occluded_function`]. The occlusion analogue of
/// [`IntersectFunctionNArgs`]: there is no hit buffer in the packet, so on
/// survival mark the lane occluded with [`set_occluded`](Self::set_occluded).
pub struct OccludedFunctionNArgs<'a, D: UserData> {
    raw: *const RTCOccludedFunctionNArguments,
    valid_n: ValidityN<'a>,
    context: &'a mut IntersectContext,
    geom_id: u32,
    prim_id: u32,
    user_data: Option<&'a D>,
}

impl<'a, D: UserData> OccludedFunctionNArgs<'a, D> {
    /// Number of rays in the packet.
    pub fn len(&self) -> usize {
        // SAFETY: `raw` is the live args pointer for this callback invocation.
        unsafe { (*self.raw).N as usize }
    }

    /// Whether the packet is empty.
    pub fn is_empty(&self) -> bool { self.len() == 0 }

    /// Per-ray validity mask (`0` = inactive lane, skip it; `-1` = active).
    pub fn valid_n(&self) -> &ValidityN<'a> { &self.valid_n }

    /// Mutable validity mask.
    pub fn valid_n_mut(&mut self) -> &mut ValidityN<'a> { &mut self.valid_n }

    /// The base intersection context.
    pub fn context(&self) -> &IntersectContext { self.context }

    /// The base intersection context, mutably.
    pub fn context_mut(&mut self) -> &mut IntersectContext { self.context }

    /// Recover the per-ray extension `T` from the context.
    ///
    /// # Safety
    ///
    /// The ray query that produced this callback must have used an
    /// [`IntersectContextExt<T>`](crate::IntersectContextExt) with the same
    /// `T`. See [`IntersectContext::ext`](crate::IntersectContext::ext).
    pub unsafe fn context_ext<T>(&self) -> &T { self.context.ext::<T>() }

    /// Mutable [`context_ext`](Self::context_ext).
    ///
    /// # Safety
    ///
    /// Same as [`context_ext`](Self::context_ext).
    pub unsafe fn context_ext_mut<T>(&mut self) -> &mut T { self.context.ext_mut::<T>() }

    /// Geometry ID being tested.
    pub fn geom_id(&self) -> u32 { self.geom_id }

    /// Primitive ID being tested.
    pub fn prim_id(&self) -> u32 { self.prim_id }

    /// Per-callback user data (if bound via the `_owned` / `_borrowed` setter).
    pub fn user_data(&self) -> Option<&D> { self.user_data }

    // The ray packet (SoA). For occlusion the args carry a plain `ray` pointer.
    #[inline]
    fn rays(&self) -> RayN<'a> {
        RayN {
            ptr: unsafe { (*self.raw).ray },
            len: self.len(),
            marker: PhantomData,
        }
    }

    /// Gather lane `i` of the packet into a contiguous single-ray [`Ray`].
    pub fn ray(&self, i: usize) -> Ray {
        assert!(i < self.len(), "ray index out of bounds");
        // SAFETY: just checked `i < len`.
        unsafe { self.ray_unchecked(i) }
    }

    /// Run a candidate occluder (`ray` + fully-initialized `hit`) through the
    /// geometry's occlusion filter **and** the context filter. Returns `true`
    /// if it survived (then mark the lane occluded via
    /// [`set_occluded`](Self::set_occluded)); `false` if rejected.
    pub fn filter_occlusion(&mut self, ray: &mut Ray, hit: &mut Hit) -> bool {
        let mut valid: i32 = -1;
        let fargs = RTCFilterFunctionNArguments {
            valid: &mut valid,
            // SAFETY: `raw` is the live args pointer for this callback invocation.
            geometryUserPtr: unsafe { (*self.raw).geometryUserPtr },
            context: unsafe { (*self.raw).context },
            ray: ray as *mut Ray as *mut RTCRayN,
            hit: hit as *mut Hit as *mut RTCHitN,
            N: 1,
        };
        // SAFETY: separate contiguous N=1 ray/hit buffers; `raw` is live (see
        // `filter_intersection`).
        unsafe { rtcFilterOcclusion(self.raw, &fargs) };
        valid != 0
    }

    /// Mark lane `i` occluded by setting its `tfar` to `-inf` (embree's
    /// occlusion convention).
    pub fn set_occluded(&mut self, i: usize) {
        assert!(i < self.len(), "occluded index out of bounds");
        // SAFETY: just checked `i < len`.
        unsafe { self.set_occluded_unchecked(i) }
    }

    /// Convenience: [`filter_occlusion`](Self::filter_occlusion) then, on
    /// survival, [`set_occluded`](Self::set_occluded).
    ///
    /// Runs the candidate occluder (`ray`, `hit`) through the geometry's
    /// occlusion filter and the context filter; if it survives, marks lane `i`
    /// occluded. Returns `true` if the lane was marked occluded, `false` if the
    /// filter rejected the occluder.
    pub fn filter_and_set_occluded(&mut self, i: usize, ray: &mut Ray, hit: &mut Hit) -> bool {
        if self.filter_occlusion(ray, hit) {
            self.set_occluded(i);
            true
        } else {
            false
        }
    }

    /// Set lane `i`'s packet-ray `tfar` (candidate distance before a packet
    /// filter, or to restore it after a rejection).
    pub fn set_tfar(&mut self, i: usize, tfar: f32) {
        assert!(i < self.len(), "tfar index out of bounds");
        // SAFETY: just checked `i < len`.
        unsafe { self.set_tfar_unchecked(i, tfar) }
    }

    // --- Unchecked gather/scatter primitives for the proven-in-range lane
    // handles (see `IntersectFunctionNArgs`). The public methods above keep
    // their bounds check; these omit it and are `#[inline(always)]`.

    /// # Safety: `i < self.len()`.
    #[inline(always)]
    unsafe fn ray_unchecked(&self, i: usize) -> Ray { self.rays().gather_unchecked(i) }

    /// # Safety: `i < self.len()`.
    #[inline(always)]
    unsafe fn set_occluded_unchecked(&mut self, i: usize) {
        self.rays().set_tfar_unchecked(i, f32::NEG_INFINITY);
    }

    /// # Safety: `i < self.len()`.
    #[inline(always)]
    unsafe fn set_tfar_unchecked(&mut self, i: usize, tfar: f32) {
        self.rays().set_tfar_unchecked(i, tfar);
    }

    /// Iterate the **active** lanes (`valid_n()[i] != 0`), skipping inactive
    /// ones. Each [`OccludedLane`] handle carries its index; see
    /// [`IntersectFunctionNArgs::for_each_active_lane`] for the rationale (a
    /// safe lending `for` iterator is not expressible, so this is a
    /// closure).
    #[inline(always)]
    pub fn for_each_active_lane(&mut self, mut f: impl for<'b> FnMut(OccludedLane<'a, 'b, D>)) {
        let n = self.len();
        for i in 0..n {
            // SAFETY: `i < n`; direct validity-mask read, no checked index.
            if unsafe { *self.valid_n.ptr.add(i) } != 0 {
                f(OccludedLane {
                    args: &mut *self,
                    i,
                });
            }
        }
    }

    /// Packet occlusion filter: ONE `rtcFilterOcclusion` call (`N = len()`)
    /// using the packet's own ray block. Same `hits` / `valid` contract as
    /// [`IntersectFunctionNArgs::filter_intersection_n`]. Set active lanes'
    /// `tfar` via [`set_tfar`](Self::set_tfar) first; mark survivors
    /// occluded with [`set_occluded`](Self::set_occluded) and restore
    /// `tfar` on rejected lanes.
    pub fn filter_occlusion_n(&mut self, hits: &mut [Hit], valid: &mut [i32]) {
        let n = self.len();
        assert_eq!(hits.len(), n, "hits length must equal packet width");
        assert_eq!(valid.len(), n, "valid length must equal packet width");

        // N-wide SoA candidate-hit scratch (see filter_intersection_n for layout).
        let mut scratch = [0u32; 8 * 16];
        {
            let mut hn = HitN {
                ptr: scratch.as_mut_ptr() as *mut RTCHitN,
                len: n,
                marker: PhantomData,
            };
            for i in 0..n {
                if valid[i] == 0 {
                    continue;
                }
                hn.set_normal(i, [hits[i].Ng_x, hits[i].Ng_y, hits[i].Ng_z]);
                hn.set_uv(i, [hits[i].u, hits[i].v]);
                hn.set_prim_id(i, hits[i].primID);
                hn.set_geom_id(i, hits[i].geomID);
                hn.set_inst_id(i, hits[i].instID[0]);
            }
        }

        let fargs = RTCFilterFunctionNArguments {
            valid: valid.as_mut_ptr(),
            // SAFETY: `raw` is the live args pointer for this callback invocation.
            geometryUserPtr: unsafe { (*self.raw).geometryUserPtr },
            context: unsafe { (*self.raw).context },
            // Occlusion args carry a plain `ray` pointer (N-wide SoA).
            ray: unsafe { (*self.raw).ray },
            hit: scratch.as_mut_ptr() as *mut RTCHitN,
            N: n as u32,
        };
        // SAFETY: `ray` is the packet's N-wide SoA ray block; `hit` is our N-wide SoA
        // candidate scratch; `valid` has N entries; `raw` is live.
        unsafe { rtcFilterOcclusion(self.raw, &fargs) };

        let hn = HitN {
            ptr: scratch.as_mut_ptr() as *mut RTCHitN,
            len: n,
            marker: PhantomData,
        };
        for i in 0..n {
            if valid[i] == 0 {
                continue;
            }
            let ng = hn.normal(i);
            hits[i].Ng_x = ng[0];
            hits[i].Ng_y = ng[1];
            hits[i].Ng_z = ng[2];
            hits[i].u = hn.u(i);
            hits[i].v = hn.v(i);
            hits[i].primID = hn.prim_id(i);
            hits[i].geomID = hn.geom_id(i);
            hits[i].instID[0] = hn.inst_id(i);
        }
    }
}

/// A single active lane of an occluded callback's packet, yielded by
/// [`OccludedFunctionNArgs::for_each_active_lane`]. Its index is already known
/// in-range and active.
pub struct OccludedLane<'a, 'b, D: UserData> {
    args: &'b mut OccludedFunctionNArgs<'a, D>,
    i: usize,
}

impl<'a, 'b, D: UserData> OccludedLane<'a, 'b, D> {
    // The per-lane operations call the `*_unchecked` primitives directly: the
    // index is in range by construction (`for_each_active_lane` is the only
    // constructor), so the bounds check is omitted structurally.

    /// This lane's index in the packet.
    pub fn index(&self) -> usize { self.i }

    /// Gather this lane's ray.
    #[inline(always)]
    pub fn ray(&self) -> Ray {
        // SAFETY: `self.i` is in range by construction (see above).
        unsafe { self.args.ray_unchecked(self.i) }
    }

    /// Run a candidate through the occlusion filter chain (see
    /// [`OccludedFunctionNArgs::filter_occlusion`]).
    #[inline(always)]
    pub fn filter_occlusion(&mut self, ray: &mut Ray, hit: &mut Hit) -> bool {
        self.args.filter_occlusion(ray, hit)
    }

    /// Mark this lane occluded (see [`OccludedFunctionNArgs::set_occluded`]).
    #[inline(always)]
    pub fn set_occluded(&mut self) {
        // SAFETY: `self.i` is in range by construction (see above).
        unsafe { self.args.set_occluded_unchecked(self.i) }
    }

    /// Set this lane's packet-ray `tfar`.
    #[inline(always)]
    pub fn set_tfar(&mut self, tfar: f32) {
        // SAFETY: `self.i` is in range by construction (see above).
        unsafe { self.args.set_tfar_unchecked(self.i, tfar) }
    }

    /// Geometry ID being tested.
    pub fn geom_id(&self) -> u32 { self.args.geom_id() }

    /// Primitive ID being tested.
    pub fn prim_id(&self) -> u32 { self.args.prim_id() }

    /// Per-callback user data.
    pub fn user_data(&self) -> Option<&D> { self.args.user_data() }
}

mod trampoline {
    use super::*;

    /// Helper function to convert a Rust closure to `RTCFilterFunctionN`
    /// callback for intersect.
    pub(crate) fn intersect_filter_function<F, D>() -> RTCFilterFunctionN
    where
        D: UserData,
        F: for<'a> Fn(RayN<'a>, HitN<'a>, ValidityN<'a>, &mut IntersectContext, Option<&D>)
            + Send
            + Sync
            + 'static,
    {
        unsafe extern "C" fn inner<F, D>(args: *const RTCFilterFunctionNArguments)
        where
            D: UserData,
            F: for<'a> Fn(RayN<'a>, HitN<'a>, ValidityN<'a>, &mut IntersectContext, Option<&D>)
                + Send
                + Sync
                + 'static,
        {
            let site = &*((*args).geometryUserPtr as *const CallSite);
            let slot = site.slots[CbKind::IntersectFilter as usize];
            if slot.closure.is_null() {
                return;
            }

            // SAFETY: `closure` is the boxed `F` (stable until Drop, which cannot run while
            // a trampoline does). For a ZST `F`, this reads no memory.
            let cb = &*(slot.closure as *const F);
            let user_data = if slot.user_data.is_null() {
                None
            } else {
                // SAFETY: bound at registration with this exact `D` (the setter is generic
                // over the same `D` as this monomorphized trampoline), so the cast is sound
                // by construction, no runtime type check needed.
                Some(&*(slot.user_data as *const D))
            };

            let len = (*args).N as usize;
            cb(
                RayN {
                    ptr: (*args).ray,
                    len,
                    marker: PhantomData,
                },
                HitN {
                    ptr: (*args).hit,
                    len,
                    marker: PhantomData,
                },
                ValidityN {
                    ptr: (*args).valid,
                    len,
                    marker: PhantomData,
                },
                &mut *((*args).context as *mut IntersectContext),
                user_data,
            );
        }
        Some(inner::<F, D>)
    }

    /// Helper function to convert a Rust closure to `RTCFilterFunctionN`
    /// callback for occluded.
    pub(crate) fn occluded_filter_function<F, D>() -> RTCFilterFunctionN
    where
        D: UserData,
        F: for<'a> Fn(RayN<'a>, HitN<'a>, ValidityN<'a>, &mut IntersectContext, Option<&D>)
            + Send
            + Sync
            + 'static,
    {
        unsafe extern "C" fn inner<F, D>(args: *const RTCFilterFunctionNArguments)
        where
            D: UserData,
            F: for<'a> Fn(RayN<'a>, HitN<'a>, ValidityN<'a>, &mut IntersectContext, Option<&D>)
                + Send
                + Sync
                + 'static,
        {
            let site = &*((*args).geometryUserPtr as *const CallSite);
            let slot = site.slots[CbKind::OccludedFilter as usize];
            if slot.closure.is_null() {
                return;
            }

            // SAFETY: `closure` is the boxed `F` (stable until Drop, which cannot run while
            // a trampoline does). For a ZST `F`, this reads no memory.
            let cb = &*(slot.closure as *const F);
            let user_data = if slot.user_data.is_null() {
                None
            } else {
                // SAFETY: bound at registration with this exact `D` (the setter is generic
                // over the same `D` as this monomorphized trampoline), so the cast is sound
                // by construction, no runtime type check needed.
                Some(&*(slot.user_data as *const D))
            };

            let len = (*args).N as usize;
            cb(
                RayN {
                    ptr: (*args).ray,
                    len,
                    marker: PhantomData,
                },
                HitN {
                    ptr: (*args).hit,
                    len,
                    marker: PhantomData,
                },
                ValidityN {
                    ptr: (*args).valid,
                    len,
                    marker: PhantomData,
                },
                &mut *((*args).context as *mut IntersectContext),
                user_data,
            );
        }
        Some(inner::<F, D>)
    }

    /// Helper function to convert a Rust closure to `RTCIntersectFunctionN`
    /// callback.
    pub(crate) fn intersect_function<F, D>() -> RTCIntersectFunctionN
    where
        D: UserData,
        F: for<'a> Fn(&mut IntersectFunctionNArgs<'a, D>) + Send + Sync + 'static,
    {
        unsafe extern "C" fn inner<F, D>(args: *const RTCIntersectFunctionNArguments)
        where
            D: UserData,
            F: for<'a> Fn(&mut IntersectFunctionNArgs<'a, D>) + Send + Sync + 'static,
        {
            let site = &*((*args).geometryUserPtr as *const CallSite);
            let slot = site.slots[CbKind::UserIntersect as usize];
            if slot.closure.is_null() {
                return;
            }

            // SAFETY: `closure` is the boxed `F` (stable until Drop, which cannot run while
            // a trampoline does). For a ZST `F`, this reads no memory.
            let cb = &*(slot.closure as *const F);
            let user_data = if slot.user_data.is_null() {
                None
            } else {
                // SAFETY: bound at registration with this exact `D` (the setter is generic
                // over the same `D` as this monomorphized trampoline), so the cast is sound
                // by construction, no runtime type check needed.
                Some(&*(slot.user_data as *const D))
            };
            let len = (*args).N as usize;

            cb(&mut IntersectFunctionNArgs {
                raw: args,
                valid_n: ValidityN {
                    ptr: (*args).valid,
                    len,
                    marker: PhantomData,
                },
                context: &mut *((*args).context as *mut IntersectContext),
                geom_id: (*args).geomID,
                prim_id: (*args).primID,
                user_data,
            })
        }

        Some(inner::<F, D>)
    }

    /// Helper function to convert a Rust closure to `RTCBoundsFunction`
    /// callback.
    pub(crate) fn bounds_function<F, D>() -> RTCBoundsFunction
    where
        D: UserData,
        F: Fn(&mut Bounds, u32, u32, Option<&D>) + Send + Sync + 'static,
    {
        unsafe extern "C" fn inner<F, D>(args: *const RTCBoundsFunctionArguments)
        where
            D: UserData,
            F: Fn(&mut Bounds, u32, u32, Option<&D>) + Send + Sync + 'static,
        {
            let site = &*((*args).geometryUserPtr as *const CallSite);
            let slot = site.slots[CbKind::UserBounds as usize];
            if slot.closure.is_null() {
                return;
            }

            // SAFETY: `closure` is the boxed `F` (stable until Drop, which cannot run while
            // a trampoline does). For a ZST `F`, this reads no memory.
            let cb = &*(slot.closure as *const F);
            let user_data = if slot.user_data.is_null() {
                None
            } else {
                // SAFETY: bound at registration with this exact `D` (the setter is generic
                // over the same `D` as this monomorphized trampoline), so the cast is sound
                // by construction, no runtime type check needed.
                Some(&*(slot.user_data as *const D))
            };

            cb(
                &mut *(*args).bounds_o,
                (*args).primID,
                (*args).timeStep,
                user_data,
            );
        }

        Some(inner::<F, D>)
    }

    /// Helper function to convert a Rust closure to `RTCOccludedFunctionN`
    /// callback.
    pub(crate) fn occluded_function<F, D>() -> RTCOccludedFunctionN
    where
        D: UserData,
        F: for<'a> Fn(&mut OccludedFunctionNArgs<'a, D>) + Send + Sync + 'static,
    {
        unsafe extern "C" fn inner<F, D>(args: *const RTCOccludedFunctionNArguments)
        where
            D: UserData,
            F: for<'a> Fn(&mut OccludedFunctionNArgs<'a, D>) + Send + Sync + 'static,
        {
            let site = &*((*args).geometryUserPtr as *const CallSite);
            let slot = site.slots[CbKind::UserOccluded as usize];
            if slot.closure.is_null() {
                return;
            }

            // SAFETY: `closure` is the boxed `F` (stable until Drop, which cannot run while
            // a trampoline does). For a ZST `F`, this reads no memory.
            let cb = &*(slot.closure as *const F);
            let user_data = if slot.user_data.is_null() {
                None
            } else {
                // SAFETY: bound at registration with this exact `D` (the setter is generic
                // over the same `D` as this monomorphized trampoline), so the cast is sound
                // by construction, no runtime type check needed.
                Some(&*(slot.user_data as *const D))
            };

            cb(&mut OccludedFunctionNArgs {
                raw: args,
                valid_n: ValidityN {
                    ptr: (*args).valid,
                    len: (*args).N as usize,
                    marker: PhantomData,
                },
                context: &mut *((*args).context as *mut IntersectContext),
                geom_id: (*args).geomID,
                prim_id: (*args).primID,
                user_data,
            })
        }

        Some(inner::<F, D>)
    }

    /// Helper function to convert a Rust closure to `RTCDisplacementFunctionN`
    /// callback.
    pub(crate) fn displacement_function<F, D>() -> RTCDisplacementFunctionN
    where
        D: UserData,
        F: for<'a> Fn(RTCGeometry, Vertices<'a>, u32, u32, Option<&D>) + Send + Sync + 'static,
    {
        unsafe extern "C" fn inner<F, D>(args: *const RTCDisplacementFunctionNArguments)
        where
            D: UserData,
            F: for<'a> Fn(RTCGeometry, Vertices<'a>, u32, u32, Option<&D>) + Send + Sync + 'static,
        {
            let site = &*((*args).geometryUserPtr as *const CallSite);
            let slot = site.slots[CbKind::Displacement as usize];
            if slot.closure.is_null() {
                return;
            }

            // SAFETY: `closure` is the boxed `F` (stable until Drop, which cannot run while
            // a trampoline does). For a ZST `F`, this reads no memory.
            let cb = &*(slot.closure as *const F);
            let user_data = if slot.user_data.is_null() {
                None
            } else {
                // SAFETY: bound at registration with this exact `D` (the setter is generic
                // over the same `D` as this monomorphized trampoline), so the cast is sound
                // by construction, no runtime type check needed.
                Some(&*(slot.user_data as *const D))
            };

            let len = (*args).N as usize;
            let vertices = Vertices {
                len,
                u: (*args).u,
                v: (*args).v,
                ng_x: (*args).Ng_x,
                ng_y: (*args).Ng_y,
                ng_z: (*args).Ng_z,
                p_x: (*args).P_x,
                p_y: (*args).P_y,
                p_z: (*args).P_z,
                marker: PhantomData,
            };
            cb(
                (*args).geometry,
                vertices,
                (*args).primID,
                (*args).timeStep,
                user_data,
            );
        }

        Some(inner::<F, D>)
    }
}

/// Struct holding data for a set of vertices in SoA layout.
/// This is used as a parameter to the callback function set by
/// [`GeometryBuilder::set_displacement_function`].
pub struct Vertices<'a> {
    /// The number of vertices.
    len: usize,
    /// The u coordinates of points to displace.
    u: *const f32,
    /// The v coordinates of points to displace.
    v: *const f32,
    /// The x components of normal of vertices to displace (normalized).
    ng_x: *const f32,
    ///The y component of normal of vertices to displace (normalized).
    ng_y: *const f32,
    /// The z component of normal of vertices to displace (normalized).
    ng_z: *const f32,
    /// The x components of points to displace.
    p_x: *mut f32,
    /// The y components of points to displace.
    p_y: *mut f32,
    /// The z components of points to displace.
    p_z: *mut f32,
    /// To make sure we don't outlive the lifetime of the pointers.
    marker: PhantomData<&'a mut f32>,
}

impl<'a> Vertices<'a> {
    pub fn into_iter_mut(self) -> VerticesIterMut<'a> {
        VerticesIterMut {
            inner: self,
            cur: 0,
        }
    }
}

/// Mutable iterator over a geometry's [`Vertices`], yielding each vertex in
/// turn.
pub struct VerticesIterMut<'a> {
    inner: Vertices<'a>,
    cur: usize,
}

impl<'a> Iterator for VerticesIterMut<'a> {
    type Item = ([f32; 2], [f32; 3], [&'a mut f32; 3]);

    fn next(&mut self) -> Option<Self::Item> {
        if self.cur < self.inner.len {
            unsafe {
                let u = *self.inner.u.add(self.cur);
                let v = *self.inner.v.add(self.cur);
                let ng_x = *self.inner.ng_x.add(self.cur);
                let ng_y = *self.inner.ng_y.add(self.cur);
                let ng_z = *self.inner.ng_z.add(self.cur);
                let p_x = self.inner.p_x.add(self.cur);
                let p_y = self.inner.p_y.add(self.cur);
                let p_z = self.inner.p_z.add(self.cur);
                self.cur += 1;
                Some((
                    [u, v],
                    [ng_x, ng_y, ng_z],
                    [&mut *p_x, &mut *p_y, &mut *p_z],
                ))
            }
        } else {
            None
        }
    }
}

impl<'a> ExactSizeIterator for VerticesIterMut<'a> {
    fn len(&self) -> usize { self.inner.len - self.cur }
}

/// Struct holding data for validity masks used in the callback function set by
/// [`GeometryBuilder::set_intersect_filter_function`],
/// [`GeometryBuilder::set_occluded_filter_function`],
/// [`GeometryBuilder::set_intersect_function`] and
/// [`GeometryBuilder::set_occluded_function`].
///
/// - 0 means it is invalid
/// - -1 means the ray/hit is valid
pub struct ValidityN<'a> {
    ptr: *const i32,
    len: usize,
    marker: PhantomData<&'a [i32]>,
}

/// Shared iterator over a [`ValidityN`]'s lanes, yielding each lane's flag.
pub struct ValidityNIter<'a, 'b> {
    inner: &'b ValidityN<'a>,
    cur: usize,
}

impl<'a> ValidityN<'a> {
    pub fn iter<'b>(&'b self) -> ValidityNIter<'a, 'b> {
        ValidityNIter {
            inner: self,
            cur: 0,
        }
    }

    pub fn iter_mut(&mut self) -> ValidityNIterMut<'_> {
        ValidityNIterMut {
            ptr: self.ptr as *mut i32,
            len: self.len,
            cur: 0,
            _marker: PhantomData,
        }
    }

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

    pub const fn is_empty(&self) -> bool { self.len == 0 }

    /// Read lane `i`'s validity flag (`-1` valid, `0` invalid) **with no bounds
    /// check**.
    ///
    /// The unchecked counterpart of [`Index`]: a filter callback iterating over
    /// an already-proven-in-range lane index can skip the per-access `assert!`
    /// the [`Index`] impl does unconditionally (including in release).
    /// `#[inline(always)]` so it lowers to a single load.
    ///
    /// # Safety
    ///
    /// `i < self.len()`.
    #[inline(always)]
    pub unsafe fn get_unchecked(&self, i: usize) -> i32 { *self.ptr.add(i) }

    /// Set lane `i`'s validity flag (e.g. `0` to reject the lane) **with no
    /// bounds check**; the unchecked counterpart of [`IndexMut`].
    ///
    /// # Safety
    ///
    /// `i < self.len()`. (Like the [`IndexMut`] impl, this writes through the
    /// view's pointer, which embree provides with write provenance for filter
    /// callbacks.)
    #[inline(always)]
    pub unsafe fn set_unchecked(&mut self, i: usize, valid: i32) {
        *(self.ptr.add(i) as *mut i32) = valid;
    }
}

impl<'a> Index<usize> for ValidityN<'a> {
    type Output = i32;

    fn index(&self, index: usize) -> &Self::Output {
        assert!(index < self.len, "index out of bounds");
        unsafe { &*self.ptr.add(index) }
    }
}

impl<'a> IndexMut<usize> for ValidityN<'a> {
    fn index_mut(&mut self, index: usize) -> &mut Self::Output {
        assert!(index < self.len, "index out of bounds");
        unsafe { &mut *(self.ptr.add(index) as *mut i32) }
    }
}

impl<'a, 'b> Iterator for ValidityNIter<'a, 'b> {
    type Item = i32;

    fn next(&mut self) -> Option<Self::Item> {
        if self.cur < self.inner.len {
            unsafe {
                let valid = *self.inner.ptr.add(self.cur);
                self.cur += 1;
                Some(valid)
            }
        } else {
            None
        }
    }
}

/// Mutable iterator over a [`ValidityN`]'s lanes. Like [`std::slice::IterMut`],
/// it owns the raw pointer and a `PhantomData<&'b mut i32>` borrow rather than
/// the `ValidityN`, and yields `&'b mut i32` tied to that borrow -- so a
/// yielded reference cannot outlive the iterator's borrow of the `ValidityN`
/// (which would otherwise let safe code alias a lane).
pub struct ValidityNIterMut<'b> {
    ptr: *mut i32,
    len: usize,
    cur: usize,
    _marker: PhantomData<&'b mut i32>,
}

impl<'b> Iterator for ValidityNIterMut<'b> {
    type Item = &'b mut i32;

    fn next(&mut self) -> Option<Self::Item> {
        if self.cur < self.len {
            // SAFETY: `cur < len` keeps the pointer in range, and `cur` only ever
            // advances, so each lane is yielded at most once -- the returned
            // `&'b mut` never aliases another. `'b` is the borrow of the
            // `ValidityN` this iterator was created from.
            unsafe {
                let p = self.ptr.add(self.cur);
                self.cur += 1;
                Some(&mut *p)
            }
        } else {
            None
        }
    }
}

#[cfg(test)]
mod validity_oob_tests {
    //! `ValidityN` lane indexing must be unconditional (not `debug_assert!`),
    //! so an out-of-bounds lane panics in release too. Pure-Rust (no FFI):
    //! a view over a stack `[i32]`.
    use super::*;

    fn validity_over(buf: &[i32]) -> ValidityN<'_> {
        ValidityN {
            ptr: buf.as_ptr(),
            len: buf.len(),
            marker: PhantomData,
        }
    }

    #[test]
    #[should_panic(expected = "index out of bounds")]
    fn validity_index_out_of_bounds_panics() {
        let buf = [-1i32; 4];
        let v = validity_over(&buf);
        let _ = v[4];
    }

    #[test]
    #[should_panic(expected = "index out of bounds")]
    fn validity_index_mut_out_of_bounds_panics() {
        let buf = [-1i32; 4];
        let mut v = validity_over(&buf);
        v[4] = 0; // index_mut: the assert fires before any write
    }

    #[test]
    fn validity_index_in_bounds_ok() {
        let buf = [-1i32, 0, -1, 0];
        let v = validity_over(&buf);
        assert_eq!(v[0], -1);
        assert_eq!(v[3], 0);
    }

    // A view with write provenance (derived from a `&mut`), so `iter_mut`'s
    // cast-back-to-`*mut` writes are sound (Miri-clean).
    fn validity_over_mut(buf: &mut [i32]) -> ValidityN<'_> {
        ValidityN {
            ptr: buf.as_mut_ptr() as *const i32,
            len: buf.len(),
            marker: PhantomData,
        }
    }

    #[test]
    fn iter_mut_writes_each_lane_once() {
        let mut buf = [-1i32; 4];
        {
            let mut v = validity_over_mut(&mut buf);
            for (k, lane) in v.iter_mut().enumerate() {
                *lane = k as i32;
            }
        }
        // Each lane got a distinct `&mut` (no aliasing); the `'b`-tied lifetime is
        // what prevents a yielded reference from escaping the iterator.
        assert_eq!(buf, [0, 1, 2, 3]);
    }

    // The unchecked accessors (the perf escape hatch for filter callbacks) must
    // agree with the checked `Index`/`IndexMut`, including write-back.
    #[test]
    fn get_set_unchecked_matches_checked() {
        let mut buf = [-1i32, 0, -1, 0];
        let mut v = validity_over_mut(&mut buf);
        for i in 0..v.len() {
            assert_eq!(unsafe { v.get_unchecked(i) }, v[i]);
        }
        unsafe { v.set_unchecked(1, -1) };
        unsafe { v.set_unchecked(2, 0) };
        assert_eq!(v[1], -1);
        assert_eq!(v[2], 0);
        assert_eq!(buf, [-1, -1, 0, 0]);
    }
}