audionimbus 0.14.0

//! Spatial audio simulation (direct simulation, reflections, pathing).
//!
//! # Multi-Threading Architecture
//!
//! Simulations are designed to run on separate threads from audio processing.
//! Different simulation types can run concurrently without blocking each other.
//! For example, [`Simulator::run_direct`] and [`Simulator::run_reflections`] can be called from
//! separate threads simultaneously.
//!
//! Running a simulation may take 50-500ms.
//! For this reason, a typical architecture is to run a dedicated simulation thread (or one per
//! simulation type) alongside the main real-time audio thread.
//! Simulation outputs are then passed down from the simulation thread(s) to the audio thread via
//! lock-free communication (triple buffer, lock-free queue).
//!
//! ```text
//! ┌────────────────────────────┐       ┌──────────────────┐       ┌─────────────────┐
//! │ Simulation thread(s)       │       │ Lock-free        │       │ Audio thread    │
//! │                            │──────▶│ communication    │──────▶│ (real-time)     │
//! │                            │       │                  │       │                 │
//! │ Source::set_inputs         │       │ Triple buffer    │       │ Apply effects   │
//! │ Simulator::run_direct      │       │ or               │       │                 │
//! │ Simulator::run_reflections │       │ lock-free queue  │       │                 │
//! │ Simulator::run_pathing     │       │                  │       │                 │
//! │ Source::get_outputs        │       │                  │       │                 │
//! └────────────────────────────┘       └──────────────────┘       └─────────────────┘
//!  Can take 50-500ms                    Non-blocking               Must complete in
//!  Can block                                                       a few ms
//! ```
//!
//! Never set inputs ([`Source::set_inputs`], [`Source::set_inputs_subset`], etc.) or retrieve
//! outputs ([`Source::get_outputs`], [`Source::get_outputs_subset`], etc.) from an audio thread as
//! it will block and cause audio glitches.
//!
//! Refer to the `wiring` feature to help set up this architecture and avoid common pitfalls.

use crate::Sealed;
use crate::audio_settings::AudioSettings;
use crate::baking::{BakedDataIdentifier, BakedDataVariation};
pub use crate::callback::PathingVisualizationCallback;
use crate::context::Context;
use crate::device::open_cl::OpenClDevice;
use crate::device::radeon_rays::RadeonRaysDevice;
use crate::device::true_audio_next::TrueAudioNextDevice;
use crate::effect::reflections::ReflectionEffectType;
use crate::effect::{
    Convolution, DirectEffectParams, Hybrid, Parametric, PathEffectParams, ReflectionEffectParams,
    TrueAudioNext,
};
use crate::error::{SteamAudioError, to_option_error};
use crate::geometry::{CoordinateSystem, Scene};
use crate::model::air_absorption::AirAbsorptionModel;
use crate::model::deviation::DeviationModel;
use crate::model::directivity::Directivity;
use crate::model::distance_attenuation::DistanceAttenuationModel;
use crate::probe::ProbeBatch;
use crate::ray_tracing::{CustomRayTracer, DefaultRayTracer, Embree, RadeonRays, RayTracer};
use std::collections::HashMap;
use std::hash::{Hash, Hasher};
use std::marker::PhantomData;
use std::sync::{Arc, Mutex, MutexGuard};

/// Marker type indicating that direct sound simulation is enabled.
#[derive(Default, Copy, Clone, Debug)]
pub struct Direct;

/// Marker type indicating that reflection simulation is enabled.
#[derive(Default, Copy, Clone, Debug)]
pub struct Reflections;

/// Marker type indicating that pathing simulation is enabled.
#[derive(Default, Copy, Clone, Debug)]
pub struct Pathing;

/// Provider of [`SimulationFlags`].
pub trait SimulationFlagsProvider {
    /// Returns the simulation flags associated with this type.
    fn flags() -> SimulationFlags;
}

impl SimulationFlagsProvider for Direct {
    fn flags() -> SimulationFlags {
        SimulationFlags::DIRECT
    }
}

impl SimulationFlagsProvider for Reflections {
    fn flags() -> SimulationFlags {
        SimulationFlags::REFLECTIONS
    }
}

impl SimulationFlagsProvider for Pathing {
    fn flags() -> SimulationFlags {
        SimulationFlags::PATHING
    }
}

impl SimulationFlagsProvider for () {
    fn flags() -> SimulationFlags {
        SimulationFlags::empty()
    }
}

/// Manages direct and indirect sound propagation simulation for multiple sources.
///
/// Your application will typically create one simulator object and use it to run simulations with different source and listener parameters between consecutive simulation runs.
/// The simulator can also be reused across scene changes.
///
/// `Simulator` is a reference-counted handle to an underlying Steam Audio object.
/// Cloning it is cheap; it produces a new handle pointing to the same underlying object, while
/// incrementing a reference count.
/// The underlying object is destroyed when all handles are dropped.
///
/// # Examples
///
/// Basic simulation workflow (shown with direct sound; reflections and pathing follow a similar pattern):
///
/// ```
/// # use audionimbus::*;
/// # let context = Context::default();
/// let audio_settings = AudioSettings::default();
///
/// // Create a simulator.
/// let settings = SimulationSettings::new(&audio_settings)
///     .with_direct(DirectSimulationSettings {
///         max_num_occlusion_samples: 4,
///     });
/// let mut simulator = Simulator::try_new(&context, &settings)?;
///
/// // Set up a scene.
/// let scene = Scene::try_new(&context)?;
///
/// // ... add and commit geometry to the scene ...
///
/// simulator.set_scene(&scene);
/// simulator.commit();
///
/// let mut source = Source::try_new(&simulator)?;
/// simulator.add_source(&source);
///
/// // Configure simulation parameters.
/// let simulation_inputs = SimulationInputs {
///     source: CoordinateSystem::default(),
///     parameters: SimulationParameters::new()
///         .with_direct(DirectSimulationParameters::new()
///             .with_distance_attenuation(DistanceAttenuationModel::default()))
/// };
/// source.set_direct_inputs(&simulation_inputs);
///
/// // Set shared parameters.
/// let shared_inputs = SimulationSharedInputs::new(CoordinateSystem::default());
/// simulator.set_shared_direct_inputs(&shared_inputs);
///
/// // Run the simulation.
/// simulator.run_direct();
///
/// // Get results.
/// let outputs = source.get_outputs()?;
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[derive(Debug)]
pub struct Simulator<T: RayTracer, D = (), R = (), P = (), RE = ()> {
    inner: audionimbus_sys::IPLSimulator,
    shared: Arc<Mutex<SimulatorShared<T>>>,

    /// Audio settings used to create this simulator.
    audio_settings: AudioSettings,

    /// The maximum number of occlusion samples specified during creation.
    max_num_occlusion_samples: Option<u32>,

    /// The maximum number of rays specified during creation.
    max_num_rays: Option<u32>,

    /// The maximum duration specified during creation.
    max_duration: Option<f32>,

    /// Synchronization lock for direct simulation operations.
    direct_lock: Option<Arc<Mutex<()>>>,

    /// Synchronization lock for reflections simulation operations.
    reflections_lock: Option<Arc<Mutex<()>>>,

    /// Synchronization lock for pathing simulation operations.
    pathing_lock: Option<Arc<Mutex<()>>>,

    _open_cl_device: Option<OpenClDevice>,
    _radeon_rays_device: Option<RadeonRaysDevice>,
    _true_audio_next_device: Option<TrueAudioNextDevice>,
    _ray_tracer: PhantomData<T>,
    _direct: PhantomData<D>,
    _reflections: PhantomData<R>,
    _pathing: PhantomData<P>,
    _reflection_effect: PhantomData<RE>,
}

/// Shared ownership of [`Simulator`] data across clones.
#[derive(Debug)]
struct SimulatorShared<T: RayTracer> {
    /// Number of probes after the last commit.
    /// Used to ensure the simulator has probes before running pathing.
    committed_num_probes: usize,

    /// Pending probe batches to be committed.
    pending_probe_batches: HashMap<audionimbus_sys::IPLProbeBatch, usize>,

    /// The scene currently visible to simulation after the last simulator commit.
    committed_scene: Option<Scene<T>>,

    /// The next scene to become visible after the next simulator commit.
    pending_scene: Option<Scene<T>>,
}

impl<T: RayTracer> Default for SimulatorShared<T> {
    fn default() -> Self {
        Self {
            committed_num_probes: 0,
            pending_probe_batches: HashMap::new(),
            committed_scene: None,
            pending_scene: None,
        }
    }
}

impl<T, D, R, P, RE> Simulator<T, D, R, P, RE>
where
    T: RayTracer,
    D: 'static,
    R: 'static,
    P: 'static,
    RE: 'static,
{
    /// Creates a new [`Simulator`] and returns a handle to it.
    ///
    /// # Errors
    ///
    /// Returns [`SteamAudioError`] if creation fails.
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// let settings = SimulationSettings::new(&audio_settings)
    ///     .with_direct(DirectSimulationSettings {
    ///         max_num_occlusion_samples: 4,
    ///     })
    ///     .with_reflections(ConvolutionSettings {
    ///         max_num_rays: 4096,
    ///         num_diffuse_samples: 32,
    ///         max_duration: 2.0,
    ///         max_num_sources: 8,
    ///         num_threads: 2,
    ///         max_order: 1,
    ///     })
    ///     .with_pathing(PathingSimulationSettings {
    ///         num_visibility_samples: 4,
    ///     });
    /// let simulator = Simulator::try_new(&context, &settings)?;
    /// # Ok::<(), audionimbus::SteamAudioError>(())
    /// ```
    pub fn try_new(
        context: &Context,
        settings: &SimulationSettings<T, D, R, P, RE>,
    ) -> Result<Self, SteamAudioError> {
        let direct_lock = if std::any::TypeId::of::<D>() == std::any::TypeId::of::<Direct>() {
            Some(Arc::new(Mutex::new(())))
        } else {
            None
        };

        let reflections_lock =
            if std::any::TypeId::of::<R>() == std::any::TypeId::of::<Reflections>() {
                Some(Arc::new(Mutex::new(())))
            } else {
                None
            };

        let pathing_lock = if std::any::TypeId::of::<P>() == std::any::TypeId::of::<Pathing>() {
            Some(Arc::new(Mutex::new(())))
        } else {
            None
        };

        let mut ffi_settings = settings.to_ffi();

        let mut simulator = Self {
            inner: std::ptr::null_mut(),
            // Safety: thread safety is upheld by the `unsafe impl Send + Sync` on `Simulator`.
            #[allow(clippy::arc_with_non_send_sync)]
            shared: Arc::new(Mutex::new(SimulatorShared::default())),
            audio_settings: settings.audio_settings(),
            max_num_occlusion_samples: settings.max_num_occlusion_samples(),
            max_num_rays: settings.max_num_rays(),
            max_duration: settings.max_duration(),
            direct_lock,
            reflections_lock,
            pathing_lock,
            _open_cl_device: settings.open_cl_device.clone(),
            _radeon_rays_device: settings.radeon_rays_device.clone(),
            _true_audio_next_device: settings.true_audio_next_device.clone(),
            _ray_tracer: PhantomData,
            _direct: PhantomData,
            _reflections: PhantomData,
            _pathing: PhantomData,
            _reflection_effect: PhantomData,
        };

        let status = unsafe {
            audionimbus_sys::iplSimulatorCreate(
                context.raw_ptr(),
                &mut ffi_settings,
                simulator.raw_ptr_mut(),
            )
        };

        if let Some(error) = to_option_error(status) {
            return Err(error);
        }

        Ok(simulator)
    }

    /// Specifies the scene within which all subsequent simulations should be run.
    ///
    /// Call [`Self::commit`] after calling this function for the changes to take effect.
    ///
    /// This function cannot be called while any simulation is running. Either will block until the
    /// other finishes.
    pub fn set_scene(&mut self, scene: &Scene<T>) {
        let previous_pending_scene = {
            let mut shared = self.shared.lock().unwrap();
            let is_noop = shared.pending_scene.as_ref() == Some(scene)
                || (shared.pending_scene.is_none()
                    && shared.committed_scene.as_ref() == Some(scene));

            if is_noop {
                return;
            }

            shared.pending_scene.replace(scene.clone())
        };

        let _guards = self.acquire_all_locks();
        let simulator = self.raw_ptr();
        let lock_handles = self.lock_handles();

        if let Some(previous_pending_scene) = previous_pending_scene {
            previous_pending_scene.unregister_simulator(simulator, 1);
        }

        scene.register_simulator(simulator, &lock_handles, 1);

        unsafe { audionimbus_sys::iplSimulatorSetScene(self.raw_ptr(), scene.raw_ptr()) }
    }

    /// Adds a probe batch for use in subsequent simulations.
    /// Sources that require baked data can then use the data contained in the specified probe batch.
    ///
    /// Call [`Self::commit`] after calling this function for the changes to take effect.
    ///
    /// This function cannot be called while any simulation is running. Either will block until the
    /// other finishes.
    pub fn add_probe_batch(&mut self, probe_batch: &ProbeBatch) {
        let _guards = self.acquire_all_locks();
        let raw_ptr = probe_batch.raw_ptr();

        unsafe {
            audionimbus_sys::iplSimulatorAddProbeBatch(self.raw_ptr(), probe_batch.raw_ptr());
        }

        let mut shared = self.shared.lock().unwrap();
        shared
            .pending_probe_batches
            .insert(raw_ptr, probe_batch.committed_num_probes());
    }

    /// Removes a probe batch from use in subsequent simulations.
    /// Sources that require baked data will then stop using the data contained in the specified probe batch.
    ///
    /// Call [`Self::commit`] after calling this function for the changes to take effect.
    ///
    /// This function cannot be called while any simulation is running. Either will block until the
    /// other finishes.
    pub fn remove_probe_batch(&mut self, probe_batch: &ProbeBatch) {
        let _guards = self.acquire_all_locks();
        let raw_ptr = probe_batch.raw_ptr();

        unsafe {
            audionimbus_sys::iplSimulatorRemoveProbeBatch(self.raw_ptr(), probe_batch.raw_ptr());
        }

        let mut shared = self.shared.lock().unwrap();
        shared.pending_probe_batches.remove(&raw_ptr);
    }

    /// Adds a source to the set of sources processed by a simulator in subsequent simulations.
    ///
    /// Call [`Self::commit`] after calling this function for the changes to take effect.
    pub fn add_source<SrcD, SrcR, SrcP, SrcRE>(&self, source: &Source<SrcD, SrcR, SrcP, SrcRE>)
    where
        SrcD: DirectCompatible<D> + 'static,
        SrcR: ReflectionsCompatible<R> + 'static,
        SrcP: PathingCompatible<P> + 'static,
        SrcRE: ReflectionEffectCompatible<SrcR, RE> + 'static,
    {
        unsafe {
            audionimbus_sys::iplSourceAdd(source.raw_ptr(), self.raw_ptr());
        }
    }

    /// Removes a source from the set of sources processed by a simulator in subsequent simulations.
    ///
    /// Call [`Self::commit`] after calling this function for the changes to take effect.
    pub fn remove_source<SrcD, SrcR, SrcP, SrcRE>(&self, source: &Source<SrcD, SrcR, SrcP, SrcRE>)
    where
        SrcD: DirectCompatible<D> + 'static,
        SrcR: ReflectionsCompatible<R> + 'static,
        SrcP: PathingCompatible<P> + 'static,
        SrcRE: ReflectionEffectCompatible<SrcR, RE> + 'static,
    {
        unsafe {
            audionimbus_sys::iplSourceRemove(source.raw_ptr(), self.raw_ptr());
        }
    }

    /// Commits changes to the scene or probe batches used for simulation.
    ///
    /// Call this function after calling [`Self::set_scene`], [`Self::add_probe_batch`], or [`Self::remove_probe_batch`] for the changes to take effect.
    ///
    /// This function cannot be called while any simulation is running. Either will block until the
    /// other finishes.
    pub fn commit(&self) {
        let _guards = self.acquire_all_locks();
        let simulator = self.raw_ptr();

        unsafe { audionimbus_sys::iplSimulatorCommit(self.raw_ptr()) }

        let previous_committed_scene = {
            let mut shared = self.shared.lock().unwrap();
            shared.committed_num_probes = shared.pending_probe_batches.values().sum();

            if let Some(pending_scene) = shared.pending_scene.take() {
                shared.committed_scene.replace(pending_scene)
            } else {
                None
            }
        };

        if let Some(previous_committed_scene) = previous_committed_scene {
            previous_committed_scene.unregister_simulator(simulator, 1);
        }
    }

    /// Specifies simulation parameters that are not associated with any particular source.
    ///
    /// Convenience method abstracting the more expressive [`Self::set_shared_inputs_subset`].
    ///
    /// Also see:
    /// - [`Self::set_shared_direct_inputs`]
    /// - [`Self::set_shared_reflections_inputs`]
    /// - [`Self::set_shared_pathing_inputs`]
    ///
    /// # Threading Considerations
    ///
    /// This method will block if a simulation is currently running for the
    /// specified type(s).
    /// Call this from the same thread that runs the corresponding simulation(s) to avoid blocking.
    ///
    /// It is safe to call this method concurrently with simulations of different types.
    /// For example, setting `DIRECT` shared inputs while a `REFLECTIONS` simulation is running
    /// will not block.
    ///
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// # let simulation_settings = SimulationSettings::new(&audio_settings)
    /// #     .with_direct(DirectSimulationSettings { max_num_occlusion_samples: 4 })
    /// #     .with_reflections(ConvolutionSettings {
    /// #         max_num_rays: 4096,
    /// #         num_diffuse_samples: 32,
    /// #         max_duration: 2.0,
    /// #         max_num_sources: 8,
    /// #         num_threads: 2,
    /// #         max_order: 1,
    /// #     });
    /// # let simulator = Simulator::try_new(&context, &simulation_settings)?;
    /// let shared_inputs = SimulationSharedInputs::new(CoordinateSystem::default())
    ///     .with_reflections(ReflectionsSharedInputs {
    ///         num_rays: 4096,
    ///         num_bounces: 16,
    ///         duration: 2.0,
    ///         order: 1,
    ///         irradiance_min_distance: 1.0,
    ///     });
    /// simulator.set_shared_inputs(&shared_inputs)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Arguments
    ///
    /// - `shared_inputs`: the shared input parameters to set.
    ///
    /// # Errors
    ///
    /// Returns [`ParameterValidationError`] if any parameters exceed the maximums set during
    /// simulator initialization.
    pub fn set_shared_inputs<InD, InR, InP>(
        &self,
        shared_inputs: &SimulationSharedInputs<InD, InR, InP>,
    ) -> Result<(), ParameterValidationError>
    where
        D: DirectCompatible<D> + SimulationFlagsProvider,
        R: ReflectionsCompatible<R> + ReflectionsCompatible<InR> + SimulationFlagsProvider,
        P: PathingCompatible<P> + SimulationFlagsProvider,
        InD: DirectCompatible<D> + SimulationFlagsProvider,
        InR: ReflectionsCompatible<R> + SimulationFlagsProvider,
        InP: PathingCompatible<P> + SimulationFlagsProvider,
    {
        self.set_shared_inputs_subset::<D, R, P, InD, InR, InP>(shared_inputs)
    }

    /// Specifies simulation parameters that are not associated with any particular source.
    ///
    /// Only blocks for the requested simulation types, allowing concurrent setting of shared
    /// parameters across simulation threads.
    ///
    /// The last three generic parameters `InD`, `InR`, and `InP` can be inferred from the
    /// `shared_inputs` argument using `_`.
    ///
    /// Also see:
    /// - [`Self::set_shared_direct_inputs`]
    /// - [`Self::set_shared_reflections_inputs`]
    /// - [`Self::set_shared_pathing_inputs`]
    ///
    /// # Threading Considerations
    ///
    /// This method will block if a simulation is currently running for the
    /// specified type(s).
    /// Call this from the same thread that runs the corresponding simulation(s) to avoid blocking.
    ///
    /// It is safe to call this method concurrently with simulations of different types.
    /// For example, setting `DIRECT` shared inputs while a `REFLECTIONS` simulation is running
    /// will not block.
    ///
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// # let simulation_settings = SimulationSettings::new(&audio_settings)
    /// #     .with_direct(DirectSimulationSettings { max_num_occlusion_samples: 4 })
    /// #     .with_reflections(ConvolutionSettings {
    /// #         max_num_rays: 4096,
    /// #         num_diffuse_samples: 32,
    /// #         max_duration: 2.0,
    /// #         max_num_sources: 8,
    /// #         num_threads: 2,
    /// #         max_order: 1,
    /// #     });
    /// # let simulator = Simulator::try_new(&context, &simulation_settings)?;
    /// let shared_inputs = SimulationSharedInputs::new(CoordinateSystem::default())
    ///     .with_reflections(ReflectionsSharedInputs {
    ///         num_rays: 4096,
    ///         num_bounces: 16,
    ///         duration: 2.0,
    ///         order: 1,
    ///         irradiance_min_distance: 1.0,
    ///     });
    ///
    /// // Direct simulation thread...
    /// simulator.set_shared_inputs_subset::<Direct, (), (), _, _, _>(&shared_inputs)?;
    ///
    /// // Reflections simulation thread... Does not block the direct thread.
    /// simulator.set_shared_inputs_subset::<(), Reflections, (), _, _, _>(&shared_inputs)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Arguments
    ///
    /// - `shared_inputs`: the shared input parameters to set.
    ///
    /// # Errors
    ///
    /// Returns [`ParameterValidationError`] if any parameters exceed the maximums set during
    /// simulator initialization.
    pub fn set_shared_inputs_subset<SubD, SubR, SubP, InD, InR, InP>(
        &self,
        // `InD` and `InP` are intentionally loosely constrained here.
        // `SimulationSharedInputs` does not contain any Direct- or Pathing-specific data.
        // Allowing arbitrary `InD` and `InP` avoids forcing callers to construct a value via
        // `SimulationSharedInputs::with_direct` and `SimulationSharedInputs::with_pathing`, which
        // would add unnecessary boilerplate with no semantic benefit.
        shared_inputs: &SimulationSharedInputs<InD, InR, InP>,
    ) -> Result<(), ParameterValidationError>
    where
        SubD: DirectCompatible<D> + SimulationFlagsProvider,
        SubR: ReflectionsCompatible<R> + ReflectionsCompatible<InR> + SimulationFlagsProvider,
        SubP: PathingCompatible<P> + SimulationFlagsProvider,
        InD: DirectCompatible<D> + SimulationFlagsProvider,
        InR: ReflectionsCompatible<R> + SimulationFlagsProvider,
        InP: PathingCompatible<P> + SimulationFlagsProvider,
    {
        self.validate_shared_inputs(shared_inputs)?;

        let simulation_flags = SubD::flags() | SubR::flags() | SubP::flags();

        let _guards = self.acquire_locks_for_flags(simulation_flags);

        unsafe {
            audionimbus_sys::iplSimulatorSetSharedInputs(
                self.raw_ptr(),
                simulation_flags.into(),
                &mut audionimbus_sys::IPLSimulationSharedInputs::from(shared_inputs),
            );
        }

        Ok(())
    }

    /// Acquires locks for the simulation types specified in the given flags.
    fn acquire_locks_for_flags(&self, flags: SimulationFlags) -> Vec<MutexGuard<'_, ()>> {
        let mut locks = Vec::new();

        if flags.contains(SimulationFlags::DIRECT)
            && let Some(lock) = &self.direct_lock
        {
            locks.push(lock);
        }

        if flags.contains(SimulationFlags::REFLECTIONS)
            && let Some(lock) = &self.reflections_lock
        {
            locks.push(lock);
        }

        if flags.contains(SimulationFlags::PATHING)
            && let Some(lock) = &self.pathing_lock
        {
            locks.push(lock);
        }

        // Match scene commit lock ordering to avoid deadlocks.
        locks.sort_unstable_by_key(|lock| Arc::as_ptr(lock) as usize);
        locks.into_iter().map(|lock| lock.lock().unwrap()).collect()
    }

    /// Acquires locks for all simulation types enabled on this simulator.
    fn acquire_all_locks(&self) -> Vec<MutexGuard<'_, ()>> {
        let mut locks: Vec<_> = [
            self.direct_lock.as_ref(),
            self.reflections_lock.as_ref(),
            self.pathing_lock.as_ref(),
        ]
        .into_iter()
        .flatten()
        .collect();
        // Match scene commit lock ordering to avoid deadlocks.
        locks.sort_unstable_by_key(|lock| Arc::as_ptr(lock) as usize);
        locks.into_iter().map(|lock| lock.lock().unwrap()).collect()
    }

    /// Returns this simulator's simulation locks in a stable order.
    fn lock_handles(&self) -> Vec<Arc<Mutex<()>>> {
        let mut locks: Vec<_> = [
            self.direct_lock.as_ref(),
            self.reflections_lock.as_ref(),
            self.pathing_lock.as_ref(),
        ]
        .into_iter()
        .flatten()
        .cloned()
        .collect();
        locks.sort_unstable_by_key(|lock| Arc::as_ptr(lock) as usize);
        locks
    }

    /// Validates shared simulation inputs against the limits set during initialization.
    fn validate_shared_inputs<InD, InR, InP>(
        &self,
        shared_inputs: &SimulationSharedInputs<InD, InR, InP>,
    ) -> Result<(), ParameterValidationError>
    where
        InD: DirectCompatible<D>,
        InR: ReflectionsCompatible<R>,
        InP: PathingCompatible<P>,
    {
        let Some(reflections_inputs) = &shared_inputs.reflections_shared_inputs else {
            return Ok(());
        };

        // Validate num_rays.
        if let Some(max) = self.max_num_rays
            && reflections_inputs.num_rays > max
        {
            return Err(ParameterValidationError::NumRaysExceedsMax {
                requested: reflections_inputs.num_rays,
                max,
            });
        }

        // Validate duration.
        if let Some(max) = self.max_duration
            && reflections_inputs.duration > max
        {
            return Err(ParameterValidationError::DurationExceedsMax {
                requested: reflections_inputs.duration,
                max,
            });
        }

        Ok(())
    }

    /// Returns the raw FFI pointer to the underlying simulator.
    ///
    /// This is intended for internal use and advanced scenarios.
    pub const fn raw_ptr(&self) -> audionimbus_sys::IPLSimulator {
        self.inner
    }

    /// Returns a mutable reference to the raw FFI pointer.
    ///
    /// This is intended for internal use and advanced scenarios.
    pub const fn raw_ptr_mut(&mut self) -> &mut audionimbus_sys::IPLSimulator {
        &mut self.inner
    }
}

impl<T: RayTracer, D, R, P, RE> Simulator<T, D, R, P, RE> {
    /// Returns the audio settings used to create this simulator.
    pub const fn audio_settings(&self) -> AudioSettings {
        self.audio_settings
    }
}

impl<T, R, P, RE> Simulator<T, Direct, R, P, RE>
where
    T: RayTracer,
    R: 'static,
    P: 'static,
    RE: 'static,
{
    /// Specifies direct simulation parameters that are not associated with any particular source.
    ///
    /// Convenience method abstracting the more expressive [`Self::set_shared_inputs_subset`].
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// # let simulation_settings = SimulationSettings::new(&audio_settings)
    /// #     .with_direct(DirectSimulationSettings {
    /// #         max_num_occlusion_samples: 4,
    /// #     });
    /// # let simulator = Simulator::try_new(&context, &simulation_settings)?;
    /// let shared_inputs = SimulationSharedInputs::new(CoordinateSystem::default());
    /// simulator.set_shared_direct_inputs(&shared_inputs)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Arguments
    ///
    /// - `shared_inputs`: the shared input parameters to set.
    ///
    /// # Errors
    ///
    /// Returns [`ParameterValidationError`] if any parameters exceed the maximums set during
    /// simulator initialization.
    pub fn set_shared_direct_inputs<InD, InR, InP>(
        &self,
        shared_inputs: &SimulationSharedInputs<InD, InR, InP>,
    ) -> Result<(), ParameterValidationError>
    where
        InD: DirectCompatible<Direct> + SimulationFlagsProvider,
        InR: ReflectionsCompatible<R> + SimulationFlagsProvider,
        InP: PathingCompatible<P> + SimulationFlagsProvider,
        (): ReflectionsCompatible<R> + ReflectionsCompatible<InR>,
        (): PathingCompatible<P> + PathingCompatible<InP>,
    {
        self.set_shared_inputs_subset::<Direct, (), (), InD, InR, InP>(shared_inputs)
    }

    /// Runs a direct simulation for all sources added to the simulator.
    ///
    /// This may include distance attenuation, air absorption, directivity, occlusion, and transmission.
    ///
    /// # Performance Considerations
    ///
    /// This function should not be called from the audio processing thread if occlusion
    /// and/or transmission are enabled, as these calculations can be CPU-intensive.
    pub fn run_direct(&self) {
        let _guard = self
            .direct_lock
            .as_ref()
            .expect("direct_lock must exist when direct simulation is enabled")
            .lock()
            .unwrap();

        unsafe {
            audionimbus_sys::iplSimulatorRunDirect(self.raw_ptr());
        }
    }
}

impl<T, D, P, RE> Simulator<T, D, Reflections, P, RE>
where
    T: RayTracer,
    D: 'static,
    P: 'static,
    RE: 'static,
{
    /// Specifies reflections simulation parameters that are not associated with any particular source.
    ///
    /// Convenience method abstracting the more expressive [`Self::set_shared_inputs_subset`].
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// # let simulation_settings = SimulationSettings::new(&audio_settings)
    /// #     .with_reflections(ConvolutionSettings {
    /// #         max_num_rays: 4096,
    /// #         num_diffuse_samples: 32,
    /// #         max_duration: 2.0,
    /// #         max_num_sources: 8,
    /// #         num_threads: 1,
    /// #         max_order: 1,
    /// #     });
    /// # let simulator = Simulator::try_new(&context, &simulation_settings)?;
    /// let shared_inputs = SimulationSharedInputs::new(CoordinateSystem::default())
    ///     .with_reflections(ReflectionsSharedInputs {
    ///         num_rays: 4096,
    ///         num_bounces: 16,
    ///         duration: 2.0,
    ///         order: 1,
    ///         irradiance_min_distance: 1.0,
    ///     });
    /// simulator.set_shared_reflections_inputs(&shared_inputs)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Arguments
    ///
    /// - `shared_inputs`: the shared input parameters to set.
    ///
    /// # Errors
    ///
    /// Returns [`ParameterValidationError`] if any parameters exceed the maximums set during
    /// simulator initialization.
    pub fn set_shared_reflections_inputs<InD, InP>(
        &self,
        shared_inputs: &SimulationSharedInputs<InD, Reflections, InP>,
    ) -> Result<(), ParameterValidationError>
    where
        InD: DirectCompatible<D> + SimulationFlagsProvider,
        InP: PathingCompatible<P> + SimulationFlagsProvider,
        (): DirectCompatible<D> + DirectCompatible<InD>,
        (): PathingCompatible<P> + PathingCompatible<InP>,
    {
        self.set_shared_inputs_subset::<(), Reflections, (), InD, Reflections, InP>(shared_inputs)
    }

    /// Runs a reflections simulation for all sources added to the simulator.
    ///
    /// # Performance Considerations
    ///
    /// This function is CPU-intensive and should be called from a dedicated simulation thread
    /// to avoid blocking either the audio processing thread or the game's main update thread.
    ///
    /// # Errors
    ///
    /// Returns [`SimulationError::ReflectionsWithoutScene`] if no scene was set.
    ///
    /// Reflection simulation requires a [`Scene`] to be set on the simulator via
    /// [`Simulator::set_scene`] and committed via [`Simulator::commit`] before
    /// running simulations.
    pub fn run_reflections(&self) -> Result<(), SimulationError> {
        let _guard = self
            .reflections_lock
            .as_ref()
            .expect("reflections_lock must exist when reflections simulation is enabled")
            .lock()
            .unwrap();

        let shared = self.shared.lock().unwrap();
        if shared.committed_scene.is_none() {
            return Err(SimulationError::ReflectionsWithoutScene);
        }

        unsafe {
            audionimbus_sys::iplSimulatorRunReflections(self.raw_ptr());
        }

        Ok(())
    }
}

impl<T, D, R, RE> Simulator<T, D, R, Pathing, RE>
where
    T: RayTracer,
    D: 'static,
    R: 'static,
    RE: 'static,
{
    /// Specifies pathing simulation parameters that are not associated with any particular source.
    ///
    /// Convenience method abstracting the more expressive [`Self::set_shared_inputs_subset`].
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// # let simulation_settings = SimulationSettings::new(&audio_settings)
    /// #     .with_pathing(PathingSimulationSettings {
    /// #         num_visibility_samples: 4,
    /// #     });
    /// # let simulator = Simulator::try_new(&context, &simulation_settings)?;
    /// let shared_inputs = SimulationSharedInputs::new(CoordinateSystem::default());
    /// simulator.set_shared_pathing_inputs(&shared_inputs)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Arguments
    ///
    /// - `shared_inputs`: the shared input parameters to set.
    ///
    /// # Errors
    ///
    /// Returns [`ParameterValidationError`] if any parameters exceed the maximums set during
    /// simulator initialization.
    pub fn set_shared_pathing_inputs<InD, InR, InP>(
        &self,
        shared_inputs: &SimulationSharedInputs<InD, InR, InP>,
    ) -> Result<(), ParameterValidationError>
    where
        InD: DirectCompatible<D> + SimulationFlagsProvider,
        InR: ReflectionsCompatible<R> + SimulationFlagsProvider,
        InP: PathingCompatible<Pathing> + SimulationFlagsProvider,
        (): DirectCompatible<D> + DirectCompatible<InD>,
        (): ReflectionsCompatible<R> + ReflectionsCompatible<InR>,
    {
        self.set_shared_inputs_subset::<(), (), Pathing, InD, InR, InP>(shared_inputs)
    }

    /// Runs a pathing simulation for all sources added to the simulator.
    ///
    /// # Performance Considerations
    ///
    /// This function is CPU-intensive and should be called from a dedicated simulation thread
    /// to avoid blocking either the audio processing thread or the game's main update thread.
    ///
    /// # Errors
    ///
    /// Returns [`SimulationError::PathingWithoutProbes`] if no probes were committed.
    ///
    /// Pathing requires at least one probe batch to be added to the simulator
    /// via [`Simulator::add_probe_batch`] and committed via [`Simulator::commit`] before running
    /// simulations.
    pub fn run_pathing(&self) -> Result<(), SimulationError> {
        let _guard = self
            .pathing_lock
            .as_ref()
            .expect("pathing_lock must exist when pathing simulation is enabled")
            .lock()
            .unwrap();

        let shared = self.shared.lock().unwrap();
        if shared.committed_num_probes == 0 {
            return Err(SimulationError::PathingWithoutProbes);
        }

        unsafe {
            audionimbus_sys::iplSimulatorRunPathing(self.raw_ptr());
        }

        Ok(())
    }
}

impl<T: RayTracer, D, R, P, RE> Drop for Simulator<T, D, R, P, RE> {
    fn drop(&mut self) {
        unsafe { audionimbus_sys::iplSimulatorRelease(&raw mut self.inner) }
    }
}

unsafe impl<T: RayTracer, D, R, P, RE> Send for Simulator<T, D, R, P, RE> {}
unsafe impl<T: RayTracer, D, R, P, RE> Sync for Simulator<T, D, R, P, RE> {}

impl<T, D, R, P, RE> Clone for Simulator<T, D, R, P, RE>
where
    T: RayTracer,
    D: 'static,
    R: 'static,
    P: 'static,
    RE: 'static,
{
    /// Retains an additional reference to the simulator.
    ///
    /// The returned [`Simulator`] shares the same underlying Steam Audio object.
    fn clone(&self) -> Self {
        // SAFETY: The simulator will not be destroyed until all references are released.
        Self {
            inner: unsafe { audionimbus_sys::iplSimulatorRetain(self.inner) },
            shared: Arc::clone(&self.shared),
            audio_settings: self.audio_settings,
            max_num_occlusion_samples: self.max_num_occlusion_samples,
            max_num_rays: self.max_num_rays,
            max_duration: self.max_duration,
            direct_lock: self.direct_lock.clone(),
            reflections_lock: self.reflections_lock.clone(),
            pathing_lock: self.pathing_lock.clone(),
            _open_cl_device: self._open_cl_device.clone(),
            _radeon_rays_device: self._radeon_rays_device.clone(),
            _true_audio_next_device: self._true_audio_next_device.clone(),
            _ray_tracer: PhantomData,
            _direct: PhantomData,
            _reflections: PhantomData,
            _pathing: PhantomData,
            _reflection_effect: PhantomData,
        }
    }
}

impl<T, D, R, P, RE> PartialEq for Simulator<T, D, R, P, RE>
where
    T: RayTracer,
    D: 'static,
    R: 'static,
    P: 'static,
    RE: 'static,
{
    fn eq(&self, other: &Self) -> bool {
        self.raw_ptr() == other.raw_ptr()
    }
}

impl<T, D, R, P, RE> Eq for Simulator<T, D, R, P, RE>
where
    T: RayTracer,
    D: 'static,
    R: 'static,
    P: 'static,
    RE: 'static,
{
}

impl<T, D, R, P, RE> Hash for Simulator<T, D, R, P, RE>
where
    T: RayTracer,
    D: 'static,
    R: 'static,
    P: 'static,
    RE: 'static,
{
    fn hash<H: Hasher>(&self, state: &mut H) {
        std::ptr::hash(self.raw_ptr(), state);
    }
}

/// Settings used to create a [`Simulator`].
///
/// # Examples
///
/// ```
/// # use audionimbus::*;
/// let audio_settings = AudioSettings::default();
/// let settings = SimulationSettings::new(&audio_settings)
///     .with_direct(DirectSimulationSettings {
///         max_num_occlusion_samples: 4,
///     })
///     .with_reflections(ConvolutionSettings {
///         max_num_rays: 4096,
///         num_diffuse_samples: 32,
///         max_duration: 2.0,
///         max_num_sources: 8,
///         num_threads: 2,
///         max_order: 1,
///     })
///     .with_pathing(PathingSimulationSettings {
///         num_visibility_samples: 4,
///     });
/// # Ok::<(), audionimbus::SteamAudioError>(())
/// ```
#[derive(Clone, Debug)]
pub struct SimulationSettings<T: RayTracer, D = (), R = (), P = (), RE = ()> {
    settings: audionimbus_sys::IPLSimulationSettings,
    open_cl_device: Option<OpenClDevice>,
    radeon_rays_device: Option<RadeonRaysDevice>,
    true_audio_next_device: Option<TrueAudioNextDevice>,
    _ray_tracer: PhantomData<T>,
    _direct: PhantomData<D>,
    _reflections: PhantomData<R>,
    _pathing: PhantomData<P>,
    _reflection_effect: PhantomData<RE>,
}

impl SimulationSettings<DefaultRayTracer, (), (), (), ()> {
    /// Creates new simulation settings with all simulations disabled by default.
    pub fn new(audio_settings: &AudioSettings) -> Self {
        let settings = audionimbus_sys::IPLSimulationSettings {
            flags: audionimbus_sys::IPLSimulationFlags(0),
            sceneType: audionimbus_sys::IPLSceneType::IPL_SCENETYPE_DEFAULT,
            reflectionType:
                audionimbus_sys::IPLReflectionEffectType::IPL_REFLECTIONEFFECTTYPE_CONVOLUTION,
            maxNumOcclusionSamples: 0,
            maxNumRays: 0,
            numDiffuseSamples: 0,
            maxDuration: 0.0,
            maxOrder: 0,
            maxNumSources: 0,
            numThreads: 0,
            rayBatchSize: 0,
            numVisSamples: 0,
            samplingRate: audio_settings.sampling_rate as i32,
            frameSize: audio_settings.frame_size as i32,
            openCLDevice: std::ptr::null_mut(),
            radeonRaysDevice: std::ptr::null_mut(),
            tanDevice: std::ptr::null_mut(),
        };

        Self {
            settings,
            open_cl_device: None,
            radeon_rays_device: None,
            true_audio_next_device: None,
            _ray_tracer: PhantomData,
            _direct: PhantomData,
            _reflections: PhantomData,
            _pathing: PhantomData,
            _reflection_effect: PhantomData,
        }
    }
}

impl<D, R, P, RE> SimulationSettings<DefaultRayTracer, D, R, P, RE> {
    /// Switches to the Embree ray tracer.
    pub fn with_embree(self) -> SimulationSettings<Embree, D, R, P, RE> {
        let Self {
            mut settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            ..
        } = self;
        settings.sceneType = Embree::scene_type();

        SimulationSettings {
            settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            _ray_tracer: PhantomData,
            _direct: PhantomData,
            _reflections: PhantomData,
            _pathing: PhantomData,
            _reflection_effect: PhantomData,
        }
    }

    /// Switches to the Radeon Rays ray tracer.
    ///
    /// # Arguments
    ///
    /// - `open_cl_device`: The OpenCL device to use.
    /// - `radeon_rays_device`: The Radeon Rays device to use.
    pub fn with_radeon_rays(
        self,
        open_cl_device: OpenClDevice,
        radeon_rays_device: RadeonRaysDevice,
    ) -> SimulationSettings<RadeonRays, D, R, P, RE> {
        let Self {
            mut settings,
            true_audio_next_device,
            ..
        } = self;
        settings.sceneType = RadeonRays::scene_type();
        settings.openCLDevice = open_cl_device.raw_ptr();
        settings.radeonRaysDevice = radeon_rays_device.raw_ptr();

        SimulationSettings {
            settings,
            open_cl_device: Some(open_cl_device),
            radeon_rays_device: Some(radeon_rays_device),
            true_audio_next_device,
            _ray_tracer: PhantomData,
            _direct: PhantomData,
            _reflections: PhantomData,
            _pathing: PhantomData,
            _reflection_effect: PhantomData,
        }
    }

    /// Switches to a custom ray tracer.
    ///
    /// # Arguments
    ///
    /// - `ray_batch_size`: The number of rays that will be passed to the callbacks every time rays need to be traced.
    pub fn with_custom_ray_tracer(
        self,
        ray_batch_size: u32,
    ) -> SimulationSettings<CustomRayTracer, D, R, P, RE> {
        let Self {
            mut settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            ..
        } = self;
        settings.sceneType = CustomRayTracer::scene_type();
        settings.rayBatchSize = ray_batch_size as i32;

        SimulationSettings {
            settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            _ray_tracer: PhantomData,
            _direct: PhantomData,
            _reflections: PhantomData,
            _pathing: PhantomData,
            _reflection_effect: PhantomData,
        }
    }
}

impl<T: RayTracer, D, R, P, RE> SimulationSettings<T, D, R, P, RE> {
    /// Enables direct simulation.
    pub fn with_direct(
        self,
        direct_settings: DirectSimulationSettings,
    ) -> SimulationSettings<T, Direct, R, P, RE> {
        let Self {
            mut settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            _ray_tracer,
            _reflections,
            _pathing,
            _reflection_effect,
            ..
        } = self;

        settings.flags |= audionimbus_sys::IPLSimulationFlags::IPL_SIMULATIONFLAGS_DIRECT;
        settings.maxNumOcclusionSamples = direct_settings.max_num_occlusion_samples as i32;

        SimulationSettings {
            settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            _ray_tracer,
            _direct: PhantomData,
            _reflections,
            _pathing,
            _reflection_effect,
        }
    }

    /// Enables reflections simulation.
    pub fn with_reflections<A: ReflectionsAlgorithm>(
        self,
        algorithm_settings: A,
    ) -> SimulationSettings<T, D, Reflections, P, A::EffectType> {
        algorithm_settings.apply(self)
    }

    /// Enables pathing simulation.
    pub fn with_pathing(
        self,
        pathing_settings: PathingSimulationSettings,
    ) -> SimulationSettings<T, D, R, Pathing, RE> {
        let Self {
            mut settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            _ray_tracer,
            _direct,
            _reflections,
            _reflection_effect,
            ..
        } = self;

        settings.flags |= audionimbus_sys::IPLSimulationFlags::IPL_SIMULATIONFLAGS_PATHING;
        settings.numVisSamples = pathing_settings.num_visibility_samples as i32;

        SimulationSettings {
            settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            _ray_tracer,
            _direct,
            _reflections,
            _pathing: PhantomData,
            _reflection_effect,
        }
    }

    /// Returns the audio settings stored in these simulation settings.
    pub const fn audio_settings(&self) -> AudioSettings {
        AudioSettings {
            sampling_rate: self.settings.samplingRate as u32,
            frame_size: self.settings.frameSize as u32,
        }
    }

    /// Converts the settings to the FFI representation.
    pub const fn to_ffi(&self) -> audionimbus_sys::IPLSimulationSettings {
        self.settings
    }

    /// Returns the maximum number of occlusion samples allowed, if direct simulation is enabled.
    const fn max_num_occlusion_samples(&self) -> Option<u32> {
        if self.settings.flags.0 & audionimbus_sys::IPLSimulationFlags::IPL_SIMULATIONFLAGS_DIRECT.0
            != 0
        {
            Some(self.settings.maxNumOcclusionSamples as u32)
        } else {
            None
        }
    }

    /// Returns the maximum number of rays allowed, if reflections simulation is enabled.
    const fn max_num_rays(&self) -> Option<u32> {
        if self.settings.flags.0
            & audionimbus_sys::IPLSimulationFlags::IPL_SIMULATIONFLAGS_REFLECTIONS.0
            != 0
        {
            Some(self.settings.maxNumRays as u32)
        } else {
            None
        }
    }

    /// Returns the maximum duration allowed, if reflections simulation is enabled.
    const fn max_duration(&self) -> Option<f32> {
        if self.settings.flags.0
            & audionimbus_sys::IPLSimulationFlags::IPL_SIMULATIONFLAGS_REFLECTIONS.0
            != 0
        {
            Some(self.settings.maxDuration)
        } else {
            None
        }
    }
}

// SAFETY: The raw pointers in IPLSimulationSettings point to devices owned by the struct and
// remain valid for its lifetime.
unsafe impl<T: RayTracer, D, R, P, RE> Send for SimulationSettings<T, D, R, P, RE> {}
unsafe impl<T: RayTracer, D, R, P, RE> Sync for SimulationSettings<T, D, R, P, RE> {}

/// Settings used for direct path simulation.
#[derive(Debug, Copy, Clone)]
pub struct DirectSimulationSettings {
    /// The maximum number of point samples to consider when calculating occlusion using the volumetric occlusion algorithm.
    /// Different sources can use different numbers of samples, and the number of samples can change between simulation runs, but this is the maximum value.
    /// Increasing this value results in smoother occlusion transitions, at the cost of increased CPU usage.
    pub max_num_occlusion_samples: u32,
}

impl Default for DirectSimulationSettings {
    fn default() -> Self {
        Self {
            max_num_occlusion_samples: 32,
        }
    }
}

/// Algorithm used for reflections simulation.
///
/// See:
/// - [`ConvolutionSettings`]
/// - [`ParametricSettings`]
/// - [`HybridSettings`]
/// - [`TrueAudioNextSettings`]
pub trait ReflectionsAlgorithm: Sealed {
    /// The type of the algorithm.
    type EffectType: ReflectionEffectType;

    /// Applies the algorithm settings to the specified simulation settings.
    fn apply<T: RayTracer, D, R, P, RE>(
        self,
        settings: SimulationSettings<T, D, R, P, RE>,
    ) -> SimulationSettings<T, D, Reflections, P, Self::EffectType>;
}

/// Settings for multi-channel convolution reverb.
#[derive(Debug, Copy, Clone)]
pub struct ConvolutionSettings {
    /// The maximum number of rays to trace from the listener when simulating reflections.
    /// You can use different numbers of rays between simulation runs, but this is the maximum value.
    /// Increasing this value results in more accurate reflections, at the cost of increased CPU usage.
    pub max_num_rays: u32,

    /// The number of directions to sample when generating diffusely reflected rays.
    /// Increasing this value may increase the accuracy of diffuse reflections.
    pub num_diffuse_samples: u32,

    /// The maximum length (in seconds) of impulse responses generated by reflection simulations.
    /// You can change this value betweeen simulation runs, but this is the maximum value.
    /// Increasing this value results in longer, more accurate reverb tails, at the cost of increased CPU and memory usage.
    pub max_duration: f32,

    /// The maximum number of sources for which reflection simulations will be run at any given time.
    pub max_num_sources: u32,

    /// The number of threads used for real-time reflection simulations.
    pub num_threads: u32,

    /// The maximum Ambisonic order of impulse responses generated by reflection simulations.
    ///
    /// This value is fixed for the lifetime of the simulator and determines how much memory
    /// is allocated.
    /// Higher orders result in more accurate directional variation in the simulated reflections,
    /// at the cost of increased CPU and memory usage.
    ///
    /// The actual order used per simulation run can be set independently via
    /// [`ReflectionsSharedInputs::order`], as long as it does not exceed this value.
    pub max_order: u32,
}

impl ReflectionsAlgorithm for ConvolutionSettings {
    type EffectType = Convolution;

    fn apply<T: RayTracer, D, R, P, RE>(
        self,
        simulation_settings: SimulationSettings<T, D, R, P, RE>,
    ) -> SimulationSettings<T, D, Reflections, P, Self::EffectType> {
        let SimulationSettings {
            mut settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            _ray_tracer,
            _direct,
            _pathing,
            ..
        } = simulation_settings;

        settings.flags |= audionimbus_sys::IPLSimulationFlags::IPL_SIMULATIONFLAGS_REFLECTIONS;
        settings.reflectionType =
            audionimbus_sys::IPLReflectionEffectType::IPL_REFLECTIONEFFECTTYPE_CONVOLUTION;
        settings.maxNumRays = self.max_num_rays as i32;
        settings.numDiffuseSamples = self.num_diffuse_samples as i32;
        settings.maxDuration = self.max_duration;
        settings.maxNumSources = self.max_num_sources as i32;
        settings.numThreads = self.num_threads as i32;
        settings.maxOrder = self.max_order as i32;

        SimulationSettings {
            settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            _ray_tracer,
            _direct,
            _reflections: PhantomData,
            _pathing,
            _reflection_effect: PhantomData,
        }
    }
}

impl Default for ConvolutionSettings {
    fn default() -> Self {
        Self {
            max_num_rays: 256,
            num_diffuse_samples: 256,
            max_duration: 2.0,
            max_num_sources: 64,
            num_threads: 4,
            max_order: 2,
        }
    }
}

/// Settings for parametric (or artificial) reverb, using feedback delay networks.
#[derive(Debug, Copy, Clone)]
pub struct ParametricSettings {
    /// The maximum number of rays to trace from the listener when simulating reflections.
    /// You can use different numbers of rays between simulation runs, but this is the maximum value.
    /// Increasing this value results in more accurate reflections, at the cost of increased CPU usage.
    pub max_num_rays: u32,

    /// The number of directions to sample when generating diffusely reflected rays.
    /// Increasing this value may increase the accuracy of diffuse reflections.
    pub num_diffuse_samples: u32,

    /// The maximum length (in seconds) of impulse responses generated by reflection simulations.
    /// You can change this value betweeen simulation runs, but this is the maximum value.
    /// Increasing this value results in longer, more accurate reverb tails, at the cost of increased CPU and memory usage.
    pub max_duration: f32,

    /// The maximum number of sources for which reflection simulations will be run at any given time.
    pub max_num_sources: u32,

    /// The number of threads used for real-time reflection simulations.
    pub num_threads: u32,

    /// The maximum Ambisonic order of impulse responses generated by reflection simulations.
    ///
    /// This value is fixed for the lifetime of the simulator and determines how much memory
    /// is allocated.
    /// Higher orders result in more accurate directional variation in the simulated reflections,
    /// at the cost of increased CPU and memory usage.
    ///
    /// The actual order used per simulation run can be set independently via
    /// [`ReflectionsSharedInputs::order`], as long as it does not exceed this value.
    pub max_order: u32,
}

impl ReflectionsAlgorithm for ParametricSettings {
    type EffectType = Parametric;

    fn apply<T: RayTracer, D, R, P, RE>(
        self,
        simulation_settings: SimulationSettings<T, D, R, P, RE>,
    ) -> SimulationSettings<T, D, Reflections, P, Self::EffectType> {
        let SimulationSettings {
            mut settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            _ray_tracer,
            _direct,
            _pathing,
            ..
        } = simulation_settings;

        settings.flags |= audionimbus_sys::IPLSimulationFlags::IPL_SIMULATIONFLAGS_REFLECTIONS;
        settings.reflectionType =
            audionimbus_sys::IPLReflectionEffectType::IPL_REFLECTIONEFFECTTYPE_PARAMETRIC;
        settings.maxNumRays = self.max_num_rays as i32;
        settings.numDiffuseSamples = self.num_diffuse_samples as i32;
        settings.maxDuration = self.max_duration;
        settings.maxNumSources = self.max_num_sources as i32;
        settings.numThreads = self.num_threads as i32;
        settings.maxOrder = self.max_order as i32;

        SimulationSettings {
            settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            _ray_tracer,
            _direct,
            _reflections: PhantomData,
            _pathing,
            _reflection_effect: PhantomData,
        }
    }
}

/// Settings for a hybrid of convolution and parametric reverb.
#[derive(Debug, Copy, Clone)]
pub struct HybridSettings {
    /// The maximum number of rays to trace from the listener when simulating reflections.
    /// You can use different numbers of rays between simulation runs, but this is the maximum value.
    /// Increasing this value results in more accurate reflections, at the cost of increased CPU usage.
    pub max_num_rays: u32,

    /// The number of directions to sample when generating diffusely reflected rays.
    /// Increasing this value may increase the accuracy of diffuse reflections.
    pub num_diffuse_samples: u32,

    /// The maximum length (in seconds) of impulse responses generated by reflection simulations.
    /// You can change this value betweeen simulation runs, but this is the maximum value.
    /// Increasing this value results in longer, more accurate reverb tails, at the cost of increased CPU and memory usage.
    pub max_duration: f32,

    /// The maximum number of sources for which reflection simulations will be run at any given time.
    pub max_num_sources: u32,

    /// The number of threads used for real-time reflection simulations.
    pub num_threads: u32,

    /// The maximum Ambisonic order of impulse responses generated by reflection simulations.
    ///
    /// This value is fixed for the lifetime of the simulator and determines how much memory
    /// is allocated.
    /// Higher orders result in more accurate directional variation in the simulated reflections,
    /// at the cost of increased CPU and memory usage.
    ///
    /// The actual order used per simulation run can be set independently via
    /// [`ReflectionsSharedInputs::order`], as long as it does not exceed this value.
    pub max_order: u32,
}

impl ReflectionsAlgorithm for HybridSettings {
    type EffectType = Hybrid;

    fn apply<T: RayTracer, D, R, P, RE>(
        self,
        simulation_settings: SimulationSettings<T, D, R, P, RE>,
    ) -> SimulationSettings<T, D, Reflections, P, Self::EffectType> {
        let SimulationSettings {
            mut settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            _ray_tracer,
            _direct,
            _pathing,
            ..
        } = simulation_settings;

        settings.flags |= audionimbus_sys::IPLSimulationFlags::IPL_SIMULATIONFLAGS_REFLECTIONS;
        settings.reflectionType =
            audionimbus_sys::IPLReflectionEffectType::IPL_REFLECTIONEFFECTTYPE_HYBRID;
        settings.maxNumRays = self.max_num_rays as i32;
        settings.numDiffuseSamples = self.num_diffuse_samples as i32;
        settings.maxDuration = self.max_duration;
        settings.maxNumSources = self.max_num_sources as i32;
        settings.numThreads = self.num_threads as i32;
        settings.maxOrder = self.max_order as i32;

        SimulationSettings {
            settings,
            open_cl_device,
            radeon_rays_device,
            true_audio_next_device,
            _ray_tracer,
            _direct,
            _reflections: PhantomData,
            _pathing,
            _reflection_effect: PhantomData,
        }
    }
}

/// Settings for a multi-channel convolution reverb, using AMD TrueAudio Next for GPU acceleration.
#[derive(Debug, Clone)]
pub struct TrueAudioNextSettings {
    /// The maximum number of rays to trace from the listener when simulating reflections.
    /// You can use different numbers of rays between simulation runs, but this is the maximum value.
    /// Increasing this value results in more accurate reflections, at the cost of increased CPU usage.
    pub max_num_rays: u32,

    /// The number of directions to sample when generating diffusely reflected rays.
    /// Increasing this value may increase the accuracy of diffuse reflections.
    pub num_diffuse_samples: u32,

    /// The maximum length (in seconds) of impulse responses generated by reflection simulations.
    /// You can change this value betweeen simulation runs, but this is the maximum value.
    /// Increasing this value results in longer, more accurate reverb tails, at the cost of increased CPU and memory usage.
    pub max_duration: f32,

    /// The maximum number of sources for which reflection simulations will be run at any given time.
    pub max_num_sources: u32,

    /// The number of threads used for real-time reflection simulations.
    pub num_threads: u32,

    /// The OpenCL device being used.
    pub open_cl_device: OpenClDevice,

    /// The TrueAudio Next device being used.
    pub true_audio_next_device: TrueAudioNextDevice,

    /// The maximum Ambisonic order of impulse responses generated by reflection simulations.
    ///
    /// This value is fixed for the lifetime of the simulator and determines how much memory
    /// is allocated.
    /// Higher orders result in more accurate directional variation in the simulated reflections,
    /// at the cost of increased CPU and memory usage.
    ///
    /// The actual order used per simulation run can be set independently via
    /// [`ReflectionsSharedInputs::order`], as long as it does not exceed this value.
    pub max_order: u32,
}

impl ReflectionsAlgorithm for TrueAudioNextSettings {
    type EffectType = TrueAudioNext;

    fn apply<T: RayTracer, D, R, P, RE>(
        self,
        simulation_settings: SimulationSettings<T, D, R, P, RE>,
    ) -> SimulationSettings<T, D, Reflections, P, Self::EffectType> {
        let SimulationSettings {
            mut settings,
            radeon_rays_device,
            _ray_tracer,
            _direct,
            _pathing,
            ..
        } = simulation_settings;

        settings.flags |= audionimbus_sys::IPLSimulationFlags::IPL_SIMULATIONFLAGS_REFLECTIONS;
        settings.reflectionType =
            audionimbus_sys::IPLReflectionEffectType::IPL_REFLECTIONEFFECTTYPE_TAN;
        settings.openCLDevice = self.open_cl_device.raw_ptr();
        settings.tanDevice = self.true_audio_next_device.raw_ptr();
        settings.maxNumRays = self.max_num_rays as i32;
        settings.numDiffuseSamples = self.num_diffuse_samples as i32;
        settings.maxDuration = self.max_duration;
        settings.maxNumSources = self.max_num_sources as i32;
        settings.numThreads = self.num_threads as i32;
        settings.maxOrder = self.max_order as i32;

        SimulationSettings {
            settings,
            open_cl_device: Some(self.open_cl_device),
            radeon_rays_device,
            true_audio_next_device: Some(self.true_audio_next_device),
            _ray_tracer,
            _direct,
            _reflections: PhantomData,
            _pathing,
            _reflection_effect: PhantomData,
        }
    }
}

impl Sealed for ConvolutionSettings {}
impl Sealed for ParametricSettings {}
impl Sealed for HybridSettings {}
impl Sealed for TrueAudioNextSettings {}

/// Settings used for pathing simulation.
#[derive(Debug, Copy, Clone)]
pub struct PathingSimulationSettings {
    /// The number of point samples to consider when calculating probe-to-probe visibility for pathing simulations.
    /// Baked paths may end up being occluded by dynamic objects, in which case you can configure the simulator to look for alternate paths in real time.
    /// This process will involve checking visibility between probes.
    pub num_visibility_samples: u32,
}

impl Default for PathingSimulationSettings {
    fn default() -> Self {
        Self {
            num_visibility_samples: 16,
        }
    }
}

bitflags::bitflags! {
    /// Flags indicating which types of simulation should be enabled.
    #[derive(Copy, Clone, Debug)]
    pub struct SimulationFlags: u32 {
        /// Enable direct simulation.
        /// This includes distance attenuation, air absorption, directivity, occlusion, and transmission.
        const DIRECT = 1 << 0;

        /// Enable reflections simulation.
        /// This includes both real-time and baked simulation.
        const REFLECTIONS = 1 << 1;

        /// Enable pathing simulation.
        const PATHING = 1 << 2;
    }
}

impl From<SimulationFlags> for audionimbus_sys::IPLSimulationFlags {
    fn from(simulation_flags: SimulationFlags) -> Self {
        Self(simulation_flags.bits() as _)
    }
}

/// Trait used to validate simulation flags in [`Source::set_inputs`] and [`Source::get_outputs`].
pub trait SimulationType: Sealed {
    const FLAG: SimulationFlags;
}

impl Sealed for Direct {}
impl SimulationType for Direct {
    const FLAG: SimulationFlags = SimulationFlags::DIRECT;
}

impl Sealed for Reflections {}
impl SimulationType for Reflections {
    const FLAG: SimulationFlags = SimulationFlags::REFLECTIONS;
}

impl Sealed for Pathing {}
impl SimulationType for Pathing {
    const FLAG: SimulationFlags = SimulationFlags::PATHING;
}

impl Sealed for () {}
impl SimulationType for () {
    const FLAG: SimulationFlags = SimulationFlags::empty();
}

/// Trait ensuring Source's Direct type is compatible with Simulator's Direct type.
pub trait DirectCompatible<SimD> {}
impl DirectCompatible<Direct> for Direct {}
impl DirectCompatible<Direct> for () {}
impl DirectCompatible<()> for () {}

/// Trait ensuring Source's Reflections type is compatible with Simulator's Reflections type.
pub trait ReflectionsCompatible<SimR> {}
impl ReflectionsCompatible<Reflections> for Reflections {}
impl ReflectionsCompatible<Reflections> for () {}
impl ReflectionsCompatible<()> for () {}

/// Trait ensuring Source's Pathing type is compatible with Simulator's Pathing type.
pub trait PathingCompatible<SimP> {}
impl PathingCompatible<Pathing> for Pathing {}
impl PathingCompatible<Pathing> for () {}
impl PathingCompatible<()> for () {}

/// Trait ensuring reflection effect compatibility.
///
/// If the source participates in reflections, its `RE` must match the simulator's.
pub trait ReflectionEffectCompatible<SrcR, SimRE> {}
impl<SrcRE, SimRE> ReflectionEffectCompatible<(), SimRE> for SrcRE {}
impl<SimRE> ReflectionEffectCompatible<Reflections, SimRE> for SimRE {}

/// A sound source, for the purposes of simulation.
///
/// This object is used to specify various parameters for direct and indirect sound propagation simulation, and to retrieve the simulation results.
///
/// `Source` is a reference-counted handle to an underlying Steam Audio object.
/// Cloning it is cheap; it produces a new handle pointing to the same underlying object, while
/// incrementing a reference count.
/// The underlying object is destroyed when all handles are dropped.
///
/// Generic over the types of simulation that may be run for this source.
#[derive(Debug)]
pub struct Source<D = (), R = (), P = (), RE = ()> {
    inner: audionimbus_sys::IPLSource,
    shared: Arc<Mutex<SourceShared>>,

    /// The maximum number of occlusion samples specified during creation of the [Simulator].
    max_num_occlusion_samples: Option<u32>,

    /// Reference to the simulator's direct simulation lock.
    /// Used to synchronize access to direct simulation data.
    direct_lock: Option<Arc<Mutex<()>>>,

    /// Reference to the simulator's reflections simulation lock.
    /// Used to synchronize access to reflections simulation data.
    reflections_lock: Option<Arc<Mutex<()>>>,

    /// Reference to the simulator's pathing simulation lock.
    /// Used to synchronize access to pathing simulation data.
    pathing_lock: Option<Arc<Mutex<()>>>,

    _direct: PhantomData<D>,
    _reflections: PhantomData<R>,
    _pathing: PhantomData<P>,
    _reflection_effect: PhantomData<RE>,
}

/// Shared ownership of [`Source`] data across clones.
#[derive(Default, Debug)]
struct SourceShared {
    /// Stored deviation model to keep `callback` and `user_data` alive.
    /// Only used when pathing simulation is enabled.
    deviation_model: Option<DeviationModel>,

    /// When pathing is enabled, a reference to the probe batch within which to find paths.
    /// It keeps the probe batch alive as long as the source is alive.
    _pathing_probes: Option<ProbeBatch>,
}

impl<D, R, P, RE> Source<D, R, P, RE>
where
    D: 'static,
    R: 'static,
    P: 'static,
    RE: 'static,
{
    /// Creates a new source and returns a handle to it.
    ///
    /// Convenience method abstracting the more expressive [`Self::try_new_subset`].
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// # let simulation_settings = SimulationSettings::new(&audio_settings)
    /// #     .with_direct(DirectSimulationSettings { max_num_occlusion_samples: 4 });
    /// # let simulator = Simulator::try_new(&context, &simulation_settings)?;
    /// // The source's type parameters determine which simulations may be run.
    /// let source = Source::<Direct, (), ()>::try_new(&simulator)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`SteamAudioError`] if creation fails.
    pub fn try_new<T>(simulator: &Simulator<T, D, R, P, RE>) -> Result<Self, SteamAudioError>
    where
        T: RayTracer,
        D: 'static + DirectCompatible<D> + SimulationFlagsProvider,
        R: 'static + ReflectionsCompatible<R> + SimulationFlagsProvider,
        P: 'static + PathingCompatible<P> + SimulationFlagsProvider,
        RE: 'static + ReflectionEffectCompatible<R, RE>,
    {
        Self::try_new_subset::<T, D, R, P, RE>(simulator)
    }

    /// Creates a new source and returns a handle to it.
    ///
    /// Generics specify which types of simulation may be run for this source.
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// let simulation_settings = SimulationSettings::new(&audio_settings)
    ///     .with_direct(DirectSimulationSettings { max_num_occlusion_samples: 4 })
    ///     .with_reflections(ConvolutionSettings {
    ///         max_num_rays: 4096,
    ///         num_diffuse_samples: 32,
    ///         max_duration: 2.0,
    ///         max_num_sources: 8,
    ///         num_threads: 1,
    ///         max_order: 1,
    ///     });
    /// let simulator = Simulator::try_new(&context, &simulation_settings)?;
    ///
    /// // The simulator supports both direct and reflections, but this source
    /// // only participates in direct simulation.
    /// let source = Source::<Direct, (), ()>::try_new_subset(&simulator)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`SteamAudioError`] if creation fails.
    pub fn try_new_subset<T, SimD, SimR, SimP, SimRE>(
        simulator: &Simulator<T, SimD, SimR, SimP, SimRE>,
    ) -> Result<Self, SteamAudioError>
    where
        T: RayTracer,
        SimD: 'static,
        SimR: 'static,
        SimP: 'static,
        SimRE: 'static,
        D: 'static + DirectCompatible<SimD> + SimulationFlagsProvider,
        R: 'static + ReflectionsCompatible<SimR> + SimulationFlagsProvider,
        P: 'static + PathingCompatible<SimP> + SimulationFlagsProvider,
        RE: 'static + ReflectionEffectCompatible<R, SimRE>,
    {
        let mut inner = std::ptr::null_mut();

        let simulation_flags = D::flags() | R::flags() | P::flags();

        let status = unsafe {
            audionimbus_sys::iplSourceCreate(
                simulator.raw_ptr(),
                &mut audionimbus_sys::IPLSourceSettings {
                    flags: simulation_flags.into(),
                },
                &mut inner,
            )
        };

        if let Some(error) = to_option_error(status) {
            return Err(error);
        }

        let direct_lock = simulator.direct_lock.clone();
        let reflections_lock = simulator.reflections_lock.clone();
        let pathing_lock = simulator.pathing_lock.clone();

        let source = Self {
            inner,
            shared: Arc::new(Mutex::new(SourceShared::default())),
            max_num_occlusion_samples: simulator.max_num_occlusion_samples,
            direct_lock,
            reflections_lock,
            pathing_lock,
            _direct: PhantomData,
            _reflections: PhantomData,
            _pathing: PhantomData,
            _reflection_effect: PhantomData,
        };

        Ok(source)
    }

    /// Specifies simulation parameters for a source.
    ///
    /// Convenience method abstracting the more expressive [`Self::set_inputs_subset`].
    ///
    /// Also see:
    /// - [`Self::set_direct_inputs`]
    /// - [`Self::set_reflections_inputs`]
    /// - [`Self::set_pathing_inputs`]
    ///
    /// # Threading Considerations
    ///
    /// This method will block if a simulation is currently running for the
    /// specified type(s).
    /// Call this from the same thread that runs the corresponding simulation(s) to avoid blocking.
    ///
    /// It is safe to call this method concurrently with simulations of different types.
    /// For example, setting `DIRECT` inputs while a `REFLECTIONS` simulation is running
    /// will not block.
    ///
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// # let simulation_settings = SimulationSettings::new(&audio_settings)
    /// #     .with_direct(DirectSimulationSettings { max_num_occlusion_samples: 4 });
    /// # let simulator = Simulator::try_new(&context, &simulation_settings)?;
    /// let source = Source::try_new(&simulator)?;
    /// let inputs = SimulationInputs {
    ///     source: CoordinateSystem::default(),
    ///     parameters: SimulationParameters::new()
    ///         .with_direct(DirectSimulationParameters::new()
    ///             .with_distance_attenuation(DistanceAttenuationModel::default()))
    /// };
    /// source.set_inputs(&inputs)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Arguments
    ///
    /// - `inputs`: the input parameters to set.
    ///
    /// # Errors
    ///
    /// Returns [`ParameterValidationError`] if any parameters exceed the maximums
    /// set during simulator initialization.
    pub fn set_inputs<InD, InR, InP>(
        &self,
        inputs: &SimulationInputs<InD, InR, InP>,
    ) -> Result<(), ParameterValidationError>
    where
        D: DirectCompatible<D> + DirectCompatible<InD> + SimulationFlagsProvider,
        R: ReflectionsCompatible<R> + ReflectionsCompatible<InR> + SimulationFlagsProvider,
        P: PathingCompatible<P> + PathingCompatible<InP> + SimulationFlagsProvider,
        InD: DirectCompatible<D> + SimulationFlagsProvider,
        InR: ReflectionsCompatible<R> + SimulationFlagsProvider,
        InP: PathingCompatible<P> + SimulationFlagsProvider,
    {
        self.set_inputs_subset::<D, R, P, InD, InR, InP>(inputs)
    }

    /// Specifies parts or all of the simulation parameters for a source.
    ///
    /// Only blocks for the requested simulation types, allowing concurrent setting of parameters
    /// across simulation threads.
    ///
    /// For example, `set_inputs_subset::<Direct, (), ()>()` and
    /// `set_inputs_subset::<(), Reflections, ()>()` can be called simultaneously without blocking
    /// each other.
    ///
    /// MUST NOT be called from a real-time audio thread.
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// # let simulation_settings = SimulationSettings::new(&audio_settings)
    /// #     .with_direct(DirectSimulationSettings { max_num_occlusion_samples: 4 })
    /// #     .with_reflections(ConvolutionSettings {
    /// #         max_num_rays: 4096,
    /// #         num_diffuse_samples: 32,
    /// #         max_duration: 2.0,
    /// #         max_num_sources: 8,
    /// #         num_threads: 1,
    /// #         max_order: 1,
    /// #     });
    /// # let simulator = Simulator::try_new(&context, &simulation_settings)?;
    /// # let source = Source::try_new(&simulator)?;
    /// # let inputs = SimulationInputs {
    /// #     source: CoordinateSystem::default(),
    /// #     parameters: SimulationParameters::new()
    /// #         .with_direct(DirectSimulationParameters::new()
    /// #             .with_distance_attenuation(DistanceAttenuationModel::default()))
    /// #         .with_reflections(ConvolutionParameters {
    /// #             baked_data_identifier: None,
    /// #         })
    /// # };
    /// // Direct simulation thread...
    /// source.set_inputs_subset::<Direct, (), (), _, _, _>(&inputs)?;
    ///
    /// // Reflections simulation thread... Does not block the direct thread.
    /// source.set_inputs_subset::<(), Reflections, (), _, _, _>(&inputs)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Arguments
    ///
    /// - `inputs`: the input parameters to set.
    ///
    /// # Errors
    ///
    /// Returns [`ParameterValidationError`] if any parameters exceed the maximums
    /// set during simulator initialization.
    pub fn set_inputs_subset<SubD, SubR, SubP, InD, InR, InP>(
        &self,
        inputs: &SimulationInputs<InD, InR, InP>,
    ) -> Result<(), ParameterValidationError>
    where
        SubD: DirectCompatible<D> + DirectCompatible<InD> + SimulationFlagsProvider,
        SubR: ReflectionsCompatible<R> + ReflectionsCompatible<InR> + SimulationFlagsProvider,
        SubP: PathingCompatible<P> + PathingCompatible<InP> + SimulationFlagsProvider,
        InD: DirectCompatible<D> + SimulationFlagsProvider,
        InR: ReflectionsCompatible<R> + SimulationFlagsProvider,
        InP: PathingCompatible<P> + SimulationFlagsProvider,
    {
        self.validate_inputs(inputs)?;

        let simulation_flags = SubD::flags() | SubR::flags() | SubP::flags();

        let mut ffi_inputs = inputs.to_ffi();

        let mut shared = self.shared.lock().unwrap();
        (shared.deviation_model, shared._pathing_probes) = inputs
            .parameters
            .pathing_simulation
            .as_ref()
            .map(|p| (Some(p.deviation.clone()), Some(p.pathing_probes.clone())))
            .unwrap_or_default();

        let _guards = self.acquire_locks_for_flags(simulation_flags);

        unsafe {
            audionimbus_sys::iplSourceSetInputs(
                self.raw_ptr(),
                simulation_flags.into(),
                &mut ffi_inputs,
            );
        }

        Ok(())
    }

    /// Retrieves simulation results for a source.
    ///
    /// Convenience method abstracting the more expressive [`Self::get_outputs_subset`].
    ///
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// Also see:
    /// - [`Self::get_direct_outputs`]
    /// - [`Self::get_reflections_outputs`]
    /// - [`Self::get_pathing_outputs`]
    ///
    /// # Errors
    ///
    /// Returns a [`SteamAudioError`] on failure to allocate sufficient memory for the
    /// [`SimulationOutputs`].
    pub fn get_outputs(&self) -> Result<SimulationOutputs<D, R, P, RE>, SteamAudioError>
    where
        D: DirectCompatible<D> + SimulationFlagsProvider,
        R: ReflectionsCompatible<R> + SimulationFlagsProvider,
        P: PathingCompatible<P> + SimulationFlagsProvider,
        RE: ReflectionEffectCompatible<R, RE>,
    {
        self.get_outputs_subset::<D, R, P>()
    }

    /// Retrieves parts or all of the simulation results for a source.
    ///
    /// Only blocks for the requested simulation types, allowing concurrent retrieval across
    /// simulation threads.
    ///
    /// For example, `get_outputs_subset::<Direct, (), ()>()` and
    /// `get_outputs_subset::<(), Reflections, ()>()` can be called simultaneously without blocking
    /// each other.
    ///
    /// MUST NOT be called from a real-time audio thread.
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Errors
    ///
    /// Returns a [`SteamAudioError`] on failure to allocate sufficient memory for the
    /// [`SimulationOutputs`].
    pub fn get_outputs_subset<OutD, OutR, OutP>(
        &self,
    ) -> Result<SimulationOutputs<OutD, OutR, OutP, RE>, SteamAudioError>
    where
        OutD: DirectCompatible<D> + SimulationFlagsProvider,
        OutR: ReflectionsCompatible<R> + SimulationFlagsProvider,
        OutP: PathingCompatible<P> + SimulationFlagsProvider,
        RE: ReflectionEffectCompatible<OutR, RE>,
    {
        let simulation_flags = OutD::flags() | OutR::flags() | OutP::flags();

        let _guards = self.acquire_locks_for_flags(simulation_flags);

        let simulation_outputs = SimulationOutputs::try_allocate(self)?;

        unsafe {
            audionimbus_sys::iplSourceGetOutputs(
                self.raw_ptr(),
                simulation_flags.into(),
                simulation_outputs.raw_ptr(),
            );
        }

        Ok(simulation_outputs)
    }

    /// Acquires locks for the simulation types specified in the given flags.
    fn acquire_locks_for_flags(&self, flags: SimulationFlags) -> Vec<MutexGuard<'_, ()>> {
        let mut guards = Vec::new();

        if flags.contains(SimulationFlags::DIRECT)
            && let Some(lock) = &self.direct_lock
        {
            guards.push(lock.lock().unwrap());
        }

        if flags.contains(SimulationFlags::REFLECTIONS)
            && let Some(lock) = &self.reflections_lock
        {
            guards.push(lock.lock().unwrap());
        }

        if flags.contains(SimulationFlags::PATHING)
            && let Some(lock) = &self.pathing_lock
        {
            guards.push(lock.lock().unwrap());
        }

        guards
    }

    /// Validates simulation parameters against the limits set during simulator initialization.
    fn validate_inputs<InD, InR, InP>(
        &self,
        inputs: &SimulationInputs<InD, InR, InP>,
    ) -> Result<(), ParameterValidationError>
    where
        InD: DirectCompatible<D>,
        InR: ReflectionsCompatible<R>,
        InP: PathingCompatible<P>,
    {
        let Some(direct_params) = &inputs.parameters.direct_simulation else {
            return Ok(());
        };

        let Some(occlusion) = &direct_params.occlusion else {
            return Ok(());
        };

        let OcclusionAlgorithm::Volumetric {
            num_occlusion_samples,
            ..
        } = occlusion.algorithm
        else {
            return Ok(());
        };

        let Some(max) = self.max_num_occlusion_samples else {
            return Ok(());
        };

        if num_occlusion_samples > max {
            return Err(ParameterValidationError::OcclusionSamplesExceedsMax {
                requested: num_occlusion_samples,
                max,
            });
        }

        Ok(())
    }
}

impl<D, R, P, RE> Source<D, R, P, RE> {
    /// Returns the raw FFI pointer to the underlying source.
    ///
    /// This is intended for internal use and advanced scenarios.
    pub const fn raw_ptr(&self) -> audionimbus_sys::IPLSource {
        self.inner
    }

    /// Returns a mutable reference to the raw FFI pointer.
    ///
    /// This is intended for internal use and advanced scenarios.
    pub const fn raw_ptr_mut(&mut self) -> &mut audionimbus_sys::IPLSource {
        &mut self.inner
    }
}

impl<R, P, RE> Source<Direct, R, P, RE>
where
    R: 'static,
    P: 'static,
    RE: 'static + ReflectionEffectCompatible<R, RE>,
    (): ReflectionsCompatible<R>,
    (): PathingCompatible<P>,
{
    /// Specifies direct simulation parameters for a source.
    ///
    /// Convenience method abstracting the more expressive [`Self::set_inputs_subset`].
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// # let simulation_settings = SimulationSettings::new(&audio_settings)
    /// #     .with_direct(DirectSimulationSettings { max_num_occlusion_samples: 4 });
    /// # let simulator = Simulator::try_new(&context, &simulation_settings)?;
    /// # let source = Source::try_new(&simulator)?;
    /// let inputs = SimulationInputs {
    ///     source: CoordinateSystem::default(),
    ///     parameters: SimulationParameters::new()
    ///         .with_direct(DirectSimulationParameters::new()
    ///             .with_distance_attenuation(DistanceAttenuationModel::default())),
    /// };
    /// source.set_direct_inputs(&inputs)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Arguments
    ///
    /// - `inputs`: the input parameters to set.
    ///
    /// # Errors
    ///
    /// Returns [`ParameterValidationError`] if any parameters exceed the maximums
    /// set during simulator initialization.
    pub fn set_direct_inputs<InR, InP>(
        &self,
        inputs: &SimulationInputs<Direct, InR, InP>,
    ) -> Result<(), ParameterValidationError>
    where
        InR: ReflectionsCompatible<R> + SimulationFlagsProvider,
        InP: PathingCompatible<P> + SimulationFlagsProvider,
        (): ReflectionsCompatible<InR>,
        (): PathingCompatible<InP>,
    {
        self.set_inputs_subset::<Direct, (), (), Direct, InR, InP>(inputs)
    }

    /// Retrieves direct simulation results for a source.
    ///
    /// Convenience method abstracting the more expressive [`Self::get_outputs_subset`].
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Errors
    ///
    /// Returns a [`SteamAudioError`] on failure to allocate sufficient memory for the
    /// [`SimulationOutputs`].
    pub fn get_direct_outputs(&self) -> Result<DirectEffectParams, SteamAudioError> {
        self.get_outputs_subset::<Direct, (), ()>()
            .map(|outputs| outputs.direct())
    }
}

impl<D, P, RE> Source<D, Reflections, P, RE>
where
    D: 'static,
    P: 'static,
    RE: 'static + ReflectionEffectType + ReflectionEffectCompatible<Reflections, RE>,
    (): DirectCompatible<D>,
    (): PathingCompatible<P>,
{
    /// Specifies reflections simulation parameters for a source.
    ///
    /// Convenience method abstracting the more expressive [`Self::set_inputs_subset`].
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// # let simulation_settings = SimulationSettings::new(&audio_settings)
    /// #     .with_reflections(ConvolutionSettings {
    /// #         max_num_rays: 4096,
    /// #         num_diffuse_samples: 32,
    /// #         max_duration: 2.0,
    /// #         max_num_sources: 8,
    /// #         num_threads: 2,
    /// #         max_order: 1,
    /// #     });
    /// # let simulator = Simulator::try_new(&context, &simulation_settings)?;
    /// # let source = Source::try_new(&simulator)?;
    /// let inputs = SimulationInputs {
    ///     source: CoordinateSystem::default(),
    ///     parameters: SimulationParameters::new()
    ///         .with_reflections(ConvolutionParameters {
    ///             baked_data_identifier: None,
    ///         })
    /// };
    /// source.set_reflections_inputs(&inputs)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Arguments
    ///
    /// - `inputs`: the input parameters to set.
    ///
    /// # Errors
    ///
    /// Returns [`ParameterValidationError`] if any parameters exceed the maximums
    /// set during simulator initialization.
    pub fn set_reflections_inputs<InD, InP>(
        &self,
        inputs: &SimulationInputs<InD, Reflections, InP>,
    ) -> Result<(), ParameterValidationError>
    where
        InD: DirectCompatible<D> + SimulationFlagsProvider,
        InP: PathingCompatible<P> + SimulationFlagsProvider,
        (): DirectCompatible<InD>,
        (): PathingCompatible<InP>,
    {
        self.set_inputs_subset::<(), Reflections, (), InD, Reflections, InP>(inputs)
    }

    /// Retrieves reflections simulation results for a source.
    ///
    /// Convenience method abstracting the more expressive [`Self::get_outputs_subset`].
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Errors
    ///
    /// Returns a [`SteamAudioError`] on failure to allocate sufficient memory for the
    /// [`SimulationOutputs`].
    pub fn get_reflections_outputs(&self) -> Result<ReflectionEffectParams<RE>, SteamAudioError> {
        self.get_outputs_subset::<(), Reflections, ()>()
            .map(|outputs| outputs.reflections())
    }
}

impl<D, R, RE> Source<D, R, Pathing, RE>
where
    D: 'static,
    R: 'static,
    RE: 'static + ReflectionEffectCompatible<R, RE>,
    (): DirectCompatible<D>,
    (): ReflectionsCompatible<R>,
{
    /// Specifies pathing simulation parameters for a source.
    ///
    /// Convenience method abstracting the more expressive [`Self::set_inputs_subset`].
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Examples
    ///
    /// ```
    /// # use audionimbus::*;
    /// # let context = Context::default();
    /// # let audio_settings = AudioSettings::default();
    /// # let simulation_settings = SimulationSettings::new(&audio_settings)
    /// #     .with_pathing(PathingSimulationSettings {
    /// #         num_visibility_samples: 4,
    /// #     });
    /// # let simulator = Simulator::try_new(&context, &simulation_settings)?;
    /// # let source = Source::try_new(&simulator)?;
    /// # let pathing_probes = ProbeBatch::try_new(&context).unwrap();
    /// let inputs = SimulationInputs {
    ///     source: CoordinateSystem::default(),
    ///     parameters: SimulationParameters::new()
    ///         .with_pathing(PathingSimulationParameters {
    ///             pathing_probes,
    ///             visibility_radius: 1.0,
    ///             visibility_threshold: 10.0,
    ///             visibility_range: 10.0,
    ///             pathing_order: 1,
    ///             enable_validation: true,
    ///             find_alternate_paths: true,
    ///             deviation: DeviationModel::default(),
    ///         }),
    /// };
    /// source.set_pathing_inputs(&inputs)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    ///
    /// # Arguments
    ///
    /// - `inputs`: the input parameters to set.
    ///
    /// # Errors
    ///
    /// Returns [`ParameterValidationError`] if any parameters exceed the maximums
    /// set during simulator initialization.
    pub fn set_pathing_inputs<InD, InR>(
        &self,
        inputs: &SimulationInputs<InD, InR, Pathing>,
    ) -> Result<(), ParameterValidationError>
    where
        InD: DirectCompatible<D> + SimulationFlagsProvider,
        InR: ReflectionsCompatible<R> + SimulationFlagsProvider,
        (): DirectCompatible<InD>,
        (): ReflectionsCompatible<InR>,
    {
        self.set_inputs_subset::<(), (), Pathing, InD, InR, Pathing>(inputs)
    }

    /// Retrieves pathing simulation results for a source.
    ///
    /// Convenience method abstracting the more expressive [`Self::get_outputs_subset`].
    /// See the [module-level documentation](crate::simulation) for threading guidelines.
    ///
    /// # Errors
    ///
    /// Returns a [`SteamAudioError`] on failure to allocate sufficient memory for the
    /// [`SimulationOutputs`].
    pub fn get_pathing_outputs(&self) -> Result<PathEffectParams, SteamAudioError> {
        self.get_outputs_subset::<(), (), Pathing>()
            .map(|outputs| outputs.pathing())
    }
}

impl<D, R, P, RE> Drop for Source<D, R, P, RE> {
    fn drop(&mut self) {
        unsafe { audionimbus_sys::iplSourceRelease(&raw mut self.inner) }
    }
}

unsafe impl<D, R, P, RE> Send for Source<D, R, P, RE> {}
unsafe impl<D, R, P, RE> Sync for Source<D, R, P, RE> {}

impl<D, R, P, RE> Clone for Source<D, R, P, RE> {
    /// Retains an additional reference to the source.
    ///
    /// The returned [`Source`] shares the same underlying Steam Audio object.
    fn clone(&self) -> Self {
        // SAFETY: The source will not be destroyed until all references are released.
        Self {
            inner: unsafe { audionimbus_sys::iplSourceRetain(self.inner) },
            max_num_occlusion_samples: self.max_num_occlusion_samples,
            shared: Arc::clone(&self.shared),
            direct_lock: self.direct_lock.clone(),
            reflections_lock: self.reflections_lock.clone(),
            pathing_lock: self.pathing_lock.clone(),
            _direct: PhantomData,
            _reflections: PhantomData,
            _pathing: PhantomData,
            _reflection_effect: PhantomData,
        }
    }
}

impl<D, R, P, RE> PartialEq for Source<D, R, P, RE> {
    fn eq(&self, other: &Self) -> bool {
        self.raw_ptr() == other.raw_ptr()
    }
}

impl<D, R, P, RE> Eq for Source<D, R, P, RE> {}

impl<D, R, P, RE> Hash for Source<D, R, P, RE> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        std::ptr::hash(self.raw_ptr(), state);
    }
}

/// Simulation inputs for a source.
#[derive(Clone, Default, Debug)]
pub struct SimulationInputs<D = (), R = (), P = ()> {
    /// The position and orientation of this source.
    pub source: CoordinateSystem,

    /// Simulation parameters for the source.
    pub parameters: SimulationParameters<D, R, P>,
}

impl<D, R, P> SimulationInputs<D, R, P> {
    fn to_ffi(&self) -> audionimbus_sys::IPLSimulationInputs {
        let mut flags = audionimbus_sys::IPLSimulationFlags(0);

        let source = self.source.into();

        if self.parameters.direct_simulation.is_some() {
            flags |= audionimbus_sys::IPLSimulationFlags::IPL_SIMULATIONFLAGS_DIRECT;
        }
        let direct_data = DirectSimulationData::from_params(&self.parameters.direct_simulation);

        if self.parameters.reflections_simulation.is_some() {
            flags |= audionimbus_sys::IPLSimulationFlags::IPL_SIMULATIONFLAGS_REFLECTIONS;
        }
        let reflections_data = self.parameters.reflections_simulation.unwrap_or_default();

        if self.parameters.pathing_simulation.is_some() {
            flags |= audionimbus_sys::IPLSimulationFlags::IPL_SIMULATIONFLAGS_PATHING;
        }
        let pathing_data =
            PathingSimulationData::from_params(self.parameters.pathing_simulation.as_ref());

        audionimbus_sys::IPLSimulationInputs {
            flags,
            directFlags: direct_data.flags,
            source,
            distanceAttenuationModel: direct_data.distance_attenuation_model,
            airAbsorptionModel: direct_data.air_absorption_model,
            directivity: direct_data.directivity,
            occlusionType: direct_data.occlusion_type,
            occlusionRadius: direct_data.occlusion_radius,
            numOcclusionSamples: direct_data.num_occlusion_samples,
            numTransmissionRays: direct_data.num_transmission_rays,
            reverbScale: reflections_data.reverb_scale,
            hybridReverbTransitionTime: reflections_data.hybrid_reverb_transition_time,
            hybridReverbOverlapPercent: reflections_data.hybrid_reverb_overlap_percent,
            baked: reflections_data.baked,
            bakedDataIdentifier: reflections_data.baked_data_identifier.into(),
            pathingProbes: pathing_data.pathing_probes,
            visRadius: pathing_data.visibility_radius,
            visThreshold: pathing_data.visibility_threshold,
            visRange: pathing_data.visibility_range,
            pathingOrder: pathing_data.pathing_order,
            enableValidation: pathing_data.enable_validation,
            findAlternatePaths: pathing_data.find_alternate_paths,
            deviationModel: &pathing_data.deviation_model as *const _ as *mut _,
        }
    }
}

/// Simulation parameters for a source.
#[derive(Clone, Default, Debug)]
pub struct SimulationParameters<D = (), R = (), P = ()> {
    /// If `Some`, enables direct simulation.
    /// This includes distance attenuation, air absorption, directivity, occlusion, and transmission.
    direct_simulation: Option<DirectSimulationParameters>,

    /// If `Some`, enables reflections simulation.
    /// This includes both real-time and baked simulation.
    reflections_simulation: Option<ReflectionsSimulationData>,

    /// If `Some`, enables pathing simulation.
    pathing_simulation: Option<PathingSimulationParameters>,

    _direct: PhantomData<D>,
    _reflections: PhantomData<R>,
    _pathing: PhantomData<P>,
}

impl SimulationParameters {
    /// Creates new [`SimulationParameters`].
    pub fn new() -> Self {
        Self {
            direct_simulation: None,
            reflections_simulation: None,
            pathing_simulation: None,
            _direct: PhantomData,
            _reflections: PhantomData,
            _pathing: PhantomData,
        }
    }
}

impl<D, R, P> SimulationParameters<D, R, P> {
    /// Returns the direct simulation parameters for this source, if direct simulation is enabled.
    pub fn direct_simulation_parameters(&self) -> Option<&DirectSimulationParameters> {
        self.direct_simulation.as_ref()
    }

    /// Enables direct simulation with the specified parameters.
    pub fn with_direct(
        self,
        params: DirectSimulationParameters,
    ) -> SimulationParameters<Direct, R, P> {
        let Self {
            reflections_simulation,
            pathing_simulation,
            _reflections,
            _pathing,
            ..
        } = self;

        SimulationParameters {
            direct_simulation: Some(params),
            reflections_simulation,
            pathing_simulation,
            _direct: PhantomData,
            _reflections,
            _pathing,
        }
    }

    /// Enables reflections simulation with the specified parameters.
    pub fn with_reflections<Params: ReflectionsSimulationParameters>(
        self,
        params: Params,
    ) -> SimulationParameters<D, Reflections, P> {
        let Self {
            direct_simulation,
            pathing_simulation,
            _direct,
            _pathing,
            ..
        } = self;

        SimulationParameters {
            direct_simulation,
            reflections_simulation: Some(params.into_data()),
            pathing_simulation,
            _direct,
            _reflections: PhantomData,
            _pathing,
        }
    }

    /// Enables pathing simulation with the specified parameters.
    pub fn with_pathing(
        self,
        params: PathingSimulationParameters,
    ) -> SimulationParameters<D, R, Pathing> {
        let Self {
            direct_simulation,
            reflections_simulation,
            _direct,
            _reflections,
            ..
        } = self;

        SimulationParameters {
            direct_simulation,
            reflections_simulation,
            pathing_simulation: Some(params),
            _direct,
            _reflections,
            _pathing: PhantomData,
        }
    }
}

impl<R, P> SimulationParameters<Direct, R, P> {
    /// Sets the parameters to use for direct simulation.
    pub fn set_direct_simulation_parameters(&mut self, params: DirectSimulationParameters) {
        self.direct_simulation.replace(params);
    }
}

impl<D, P> SimulationParameters<D, Reflections, P> {
    /// Sets the parameters to use for reflections simulation.
    pub fn set_reflections_simulation_parameters<Params: ReflectionsSimulationParameters>(
        &mut self,
        params: Params,
    ) {
        self.reflections_simulation.replace(params.into_data());
    }
}

impl<D, R> SimulationParameters<D, R, Pathing> {
    /// Sets the parameters to use for path simulation.
    pub fn set_pathing_simulation_parameters(&mut self, params: PathingSimulationParameters) {
        self.pathing_simulation.replace(params);
    }
}

/// Direct simulation parameters for a source.
#[derive(Clone, Default, Debug)]
pub struct DirectSimulationParameters {
    /// If `Some`, enables distance attenuation calculations with the specified model.
    pub distance_attenuation: Option<DistanceAttenuationModel>,

    /// If `Some`, enables air absorption calculations with the specified model.
    pub air_absorption: Option<AirAbsorptionModel>,

    /// If `Some`, enables directivity calculations with the specified directivity pattern.
    pub directivity: Option<Directivity>,

    /// If `Some`, enables occlusion simulation.
    pub occlusion: Option<Occlusion>,
}

impl DirectSimulationParameters {
    /// Creates new [`DirectSimulationParameters`] with all calculations disabled by default.
    pub fn new() -> Self {
        Self {
            distance_attenuation: None,
            air_absorption: None,
            directivity: None,
            occlusion: None,
        }
    }

    /// Enables distance attenuation with the specified model.
    pub fn with_distance_attenuation(mut self, model: DistanceAttenuationModel) -> Self {
        self.distance_attenuation = Some(model);
        self
    }

    /// Enables air absorption with the specified model.
    pub fn with_air_absorption(mut self, model: AirAbsorptionModel) -> Self {
        self.air_absorption = Some(model);
        self
    }

    /// Enables directivity with the specified pattern.
    pub fn with_directivity(mut self, directivity: Directivity) -> Self {
        self.directivity = Some(directivity);
        self
    }

    /// Enables occlusion with the specified parameters.
    pub fn with_occlusion(mut self, occlusion: Occlusion) -> Self {
        self.occlusion = Some(occlusion);
        self
    }
}

/// Occlusion parameters.
#[derive(Debug, Copy, Clone)]
pub struct Occlusion {
    /// If `Some`, enables transmission simulation.
    pub transmission: Option<TransmissionParameters>,

    /// The occlusion algorithm to use.
    pub algorithm: OcclusionAlgorithm,
}

impl Occlusion {
    /// Creates a new [`Occlusion`] with transmission simulation disabled by default.
    pub fn new(algorithm: OcclusionAlgorithm) -> Self {
        Self {
            transmission: None,
            algorithm,
        }
    }

    /// Enables transmission simulation with the specified parameters.
    pub fn with_transmission(mut self, params: TransmissionParameters) -> Self {
        self.transmission = Some(params);
        self
    }
}

/// Transmission parameters.
#[derive(Debug, Copy, Clone)]
pub struct TransmissionParameters {
    /// If simulating transmission, this is the maximum number of surfaces, starting from the closest surface to the listener, whose transmission coefficients will be considered when calculating the total amount of sound transmitted.
    /// Increasing this value will result in more accurate results when multiple surfaces lie between the source and the listener, at the cost of increased CPU usage.
    pub num_transmission_rays: u32,
}

/// Trait implemented by all reflections simulation parameter structs.
#[allow(private_bounds)]
pub trait ReflectionsSimulationParameters: Sealed + IntoSimulationData {}

/// Types that can be converted into [`ReflectionsSimulationData`].
trait IntoSimulationData {
    /// Returns the intermediate representation of reflections simulation parameters.
    fn into_data(self) -> ReflectionsSimulationData;
}

/// Multi-channel convolution reverb parameters.
#[derive(Default, Clone, Debug)]
pub struct ConvolutionParameters {
    /// The optional identifier used to specify which layer of baked data to use for simulating reflections for this source.
    pub baked_data_identifier: Option<BakedDataIdentifier>,
}

impl Sealed for ConvolutionParameters {}
impl ReflectionsSimulationParameters for ConvolutionParameters {}
impl IntoSimulationData for ConvolutionParameters {
    fn into_data(self) -> ReflectionsSimulationData {
        let (baked, baked_data_identifier) = self.baked_data_identifier.map_or(
            (
                audionimbus_sys::IPLbool::IPL_FALSE,
                BakedDataIdentifier::Reflections {
                    variation: BakedDataVariation::Reverb,
                },
            ),
            |id| (audionimbus_sys::IPLbool::IPL_TRUE, id),
        );

        ReflectionsSimulationData {
            baked,
            baked_data_identifier,
            reverb_scale: [0.0; 3],
            hybrid_reverb_transition_time: 0.0,
            hybrid_reverb_overlap_percent: 0.0,
        }
    }
}

/// Parameters for parametric (or artificial) reverb, using feedback delay networks.
#[derive(Clone, Debug)]
pub struct ParametricParameters {
    /// The reverb decay times for each frequency band are scaled by these values.
    /// Set to `[1.0, 1.0, 1.0]` to use the simulated values without modification.
    pub reverb_scale: [f32; 3],

    /// The optional identifier used to specify which layer of baked data to use for simulating reflections for this source.
    pub baked_data_identifier: Option<BakedDataIdentifier>,
}

impl Sealed for ParametricParameters {}
impl ReflectionsSimulationParameters for ParametricParameters {}
impl IntoSimulationData for ParametricParameters {
    fn into_data(self) -> ReflectionsSimulationData {
        let (baked, baked_data_identifier) = self.baked_data_identifier.map_or(
            (
                audionimbus_sys::IPLbool::IPL_FALSE,
                BakedDataIdentifier::Reflections {
                    variation: BakedDataVariation::Reverb,
                },
            ),
            |id| (audionimbus_sys::IPLbool::IPL_TRUE, id),
        );

        ReflectionsSimulationData {
            baked,
            baked_data_identifier,
            reverb_scale: self.reverb_scale,
            hybrid_reverb_transition_time: 0.0,
            hybrid_reverb_overlap_percent: 0.0,
        }
    }
}

impl Default for ParametricParameters {
    fn default() -> Self {
        Self {
            reverb_scale: [1.0, 1.0, 1.0],
            baked_data_identifier: None,
        }
    }
}

/// Parameters for a hybrid of convolution and parametric reverb.
#[derive(Clone, Debug)]
pub struct HybridParameters {
    /// The reverb decay times for each frequency band are scaled by these values.
    /// Set to `[1.0, 1.0, 1.0]` to use the simulated values without modification.
    pub reverb_scale: [f32; 3],

    /// This is the length (in seconds) of impulse response to use for convolution reverb.
    /// The rest of the impulse response will be used for parametric reverb estimation only.
    /// Increasing this value results in more accurate reflections, at the cost of increased CPU usage.
    pub hybrid_reverb_transition_time: f32,

    /// This is the amount of overlap between the convolution and parametric parts.
    /// To ensure smooth transitions from the early convolution part to the late parametric part, the two are cross-faded towards the end of the convolution part.
    /// For example, if `hybrid_reverb_transition_time` is 1.0, and `hybrid_reverb_overlap_percent` is 0.25, then the first 0.75 seconds are pure convolution, the next 0.25 seconds are a blend between convolution and parametric, and the portion of the tail beyond 1.0 second is pure parametric.
    pub hybrid_reverb_overlap_percent: f32,

    /// The optional identifier used to specify which layer of baked data to use for simulating reflections for this source.
    pub baked_data_identifier: Option<BakedDataIdentifier>,
}

impl Sealed for HybridParameters {}
impl ReflectionsSimulationParameters for HybridParameters {}
impl IntoSimulationData for HybridParameters {
    fn into_data(self) -> ReflectionsSimulationData {
        let (baked, baked_data_identifier) = self.baked_data_identifier.map_or(
            (
                audionimbus_sys::IPLbool::IPL_FALSE,
                BakedDataIdentifier::Reflections {
                    variation: BakedDataVariation::Reverb,
                },
            ),
            |id| (audionimbus_sys::IPLbool::IPL_TRUE, id),
        );

        ReflectionsSimulationData {
            baked,
            baked_data_identifier,
            reverb_scale: self.reverb_scale,
            hybrid_reverb_transition_time: self.hybrid_reverb_transition_time,
            hybrid_reverb_overlap_percent: self.hybrid_reverb_overlap_percent,
        }
    }
}

impl Default for HybridParameters {
    fn default() -> Self {
        Self {
            reverb_scale: [1.0, 1.0, 1.0],
            hybrid_reverb_transition_time: 1.0,
            hybrid_reverb_overlap_percent: 0.25,
            baked_data_identifier: None,
        }
    }
}

/// Multi-channel convolution reverb parameters, using AMD TrueAudio Next for GPU acceleration.
#[derive(Default, Clone, Debug)]
pub struct TrueAudioNextParameters {
    /// The optional identifier used to specify which layer of baked data to use for simulating reflections for this source.
    pub baked_data_identifier: Option<BakedDataIdentifier>,
}

impl Sealed for TrueAudioNextParameters {}
impl ReflectionsSimulationParameters for TrueAudioNextParameters {}
impl IntoSimulationData for TrueAudioNextParameters {
    fn into_data(self) -> ReflectionsSimulationData {
        let (baked, baked_data_identifier) = self.baked_data_identifier.map_or(
            (
                audionimbus_sys::IPLbool::IPL_FALSE,
                BakedDataIdentifier::Reflections {
                    variation: BakedDataVariation::Reverb,
                },
            ),
            |id| (audionimbus_sys::IPLbool::IPL_TRUE, id),
        );

        ReflectionsSimulationData {
            baked,
            baked_data_identifier,
            reverb_scale: [0.0; 3],
            hybrid_reverb_transition_time: 0.0,
            hybrid_reverb_overlap_percent: 0.0,
        }
    }
}

/// Pathing simulation parameters for a source.
#[derive(Clone, Debug)]
pub struct PathingSimulationParameters {
    /// The probe batch within which to find paths from this source to the listener.
    pub pathing_probes: ProbeBatch,

    /// When testing for mutual visibility between a pair of probes, each probe is treated as a sphere of this radius (in meters), and point samples are generated within this sphere.
    pub visibility_radius: f32,

    /// When tracing rays to test for mutual visibility between a pair of probes, the fraction of rays that are unoccluded must be greater than this threshold for the pair of probes to be considered mutually visible.
    pub visibility_threshold: f32,

    /// If the distance between two probes is greater than this value, the probes are not considered mutually visible.
    /// Increasing this value can result in simpler paths, at the cost of increased CPU usage.
    pub visibility_range: f32,

    /// The Ambisonic order used for representing path directionality.
    /// Higher values result in more precise spatialization of paths, at the cost of increased CPU usage.
    pub pathing_order: u32,

    /// If `true`, baked paths are tested for visibility.
    /// This is useful if your scene has dynamic objects that might occlude baked paths.
    pub enable_validation: bool,

    /// If `true`, and [`Self::enable_validation`] is `true`, then if a baked path is occluded by dynamic geometry, path finding is re-run in real-time to find alternate paths that take into account the dynamic geometry.
    pub find_alternate_paths: bool,

    /// The deviation model to use for this source.
    pub deviation: DeviationModel,
}

/// Intermediate representation of direct simulation parameters for FFI conversion.
struct DirectSimulationData {
    flags: audionimbus_sys::IPLDirectSimulationFlags,
    distance_attenuation_model: audionimbus_sys::IPLDistanceAttenuationModel,
    air_absorption_model: audionimbus_sys::IPLAirAbsorptionModel,
    directivity: audionimbus_sys::IPLDirectivity,
    occlusion_type: audionimbus_sys::IPLOcclusionType,
    occlusion_radius: f32,
    num_occlusion_samples: i32,
    num_transmission_rays: i32,
}

impl DirectSimulationData {
    /// Converts optional direct simulation parameters into concrete FFI-compatible data.
    fn from_params(params: &Option<DirectSimulationParameters>) -> Self {
        let Some(params) = params else {
            return Self::default();
        };

        let mut flags = audionimbus_sys::IPLDirectSimulationFlags(0);

        let distance_attenuation_model =
            Self::process_distance_attenuation(&params.distance_attenuation, &mut flags);

        let air_absorption_model = Self::process_air_absorption(&params.air_absorption, &mut flags);

        let directivity = Self::process_directivity(&params.directivity, &mut flags);

        let (occlusion_type, occlusion_radius, num_occlusion_samples, num_transmission_rays) =
            Self::process_occlusion(params.occlusion, &mut flags);

        Self {
            flags,
            distance_attenuation_model,
            air_absorption_model,
            directivity,
            occlusion_type,
            occlusion_radius,
            num_occlusion_samples,
            num_transmission_rays,
        }
    }

    /// Processes optional distance attenuation settings and updates flags accordingly.
    fn process_distance_attenuation(
        distance_attenuation: &Option<DistanceAttenuationModel>,
        flags: &mut audionimbus_sys::IPLDirectSimulationFlags,
    ) -> audionimbus_sys::IPLDistanceAttenuationModel {
        if let Some(model) = distance_attenuation {
            *flags |= audionimbus_sys::IPLDirectSimulationFlags::IPL_DIRECTSIMULATIONFLAGS_DISTANCEATTENUATION;
            model.into()
        } else {
            (&DistanceAttenuationModel::default()).into()
        }
    }

    /// Processes optional air absorption settings and updates flags accordingly.
    fn process_air_absorption(
        air_absorption: &Option<AirAbsorptionModel>,
        flags: &mut audionimbus_sys::IPLDirectSimulationFlags,
    ) -> audionimbus_sys::IPLAirAbsorptionModel {
        if let Some(model) = air_absorption {
            *flags |=
                audionimbus_sys::IPLDirectSimulationFlags::IPL_DIRECTSIMULATIONFLAGS_AIRABSORPTION;
            model.into()
        } else {
            (&AirAbsorptionModel::default()).into()
        }
    }

    /// Processes optional directivity settings and updates flags accordingly.
    fn process_directivity(
        directivity: &Option<Directivity>,
        flags: &mut audionimbus_sys::IPLDirectSimulationFlags,
    ) -> audionimbus_sys::IPLDirectivity {
        if let Some(directivity) = directivity {
            *flags |=
                audionimbus_sys::IPLDirectSimulationFlags::IPL_DIRECTSIMULATIONFLAGS_DIRECTIVITY;
            directivity.into()
        } else {
            (&Directivity::default()).into()
        }
    }

    /// Processes optional occlusion settings and updates flags accordingly.
    fn process_occlusion(
        occlusion: Option<Occlusion>,
        flags: &mut audionimbus_sys::IPLDirectSimulationFlags,
    ) -> (audionimbus_sys::IPLOcclusionType, f32, i32, i32) {
        let Some(occlusion) = occlusion else {
            return (
                audionimbus_sys::IPLOcclusionType::IPL_OCCLUSIONTYPE_RAYCAST,
                0.0,
                0,
                0,
            );
        };

        *flags |= audionimbus_sys::IPLDirectSimulationFlags::IPL_DIRECTSIMULATIONFLAGS_OCCLUSION;

        let (occlusion_type, occlusion_radius, num_occlusion_samples) = match occlusion.algorithm {
            OcclusionAlgorithm::Raycast => (
                audionimbus_sys::IPLOcclusionType::IPL_OCCLUSIONTYPE_RAYCAST,
                0.0,
                0,
            ),
            OcclusionAlgorithm::Volumetric {
                radius,
                num_occlusion_samples,
            } => (
                audionimbus_sys::IPLOcclusionType::IPL_OCCLUSIONTYPE_VOLUMETRIC,
                radius,
                num_occlusion_samples,
            ),
        };

        let num_transmission_rays = if let Some(transmission) = occlusion.transmission {
            *flags |=
                audionimbus_sys::IPLDirectSimulationFlags::IPL_DIRECTSIMULATIONFLAGS_TRANSMISSION;
            transmission.num_transmission_rays
        } else {
            0
        };

        (
            occlusion_type,
            occlusion_radius,
            num_occlusion_samples as i32,
            num_transmission_rays as i32,
        )
    }
}

impl Default for DirectSimulationData {
    fn default() -> Self {
        Self {
            flags: audionimbus_sys::IPLDirectSimulationFlags(0),
            distance_attenuation_model: (&DistanceAttenuationModel::default()).into(),
            air_absorption_model: (&AirAbsorptionModel::default()).into(),
            directivity: (&Directivity::default()).into(),
            occlusion_type: audionimbus_sys::IPLOcclusionType::IPL_OCCLUSIONTYPE_RAYCAST,
            occlusion_radius: 0.0,
            num_occlusion_samples: 0,
            num_transmission_rays: 0,
        }
    }
}

/// Intermediate representation of reflections simulation parameters for FFI conversion.
#[derive(Copy, Clone, Debug)]
struct ReflectionsSimulationData {
    baked: audionimbus_sys::IPLbool,
    baked_data_identifier: BakedDataIdentifier,
    reverb_scale: [f32; 3],
    hybrid_reverb_transition_time: f32,
    hybrid_reverb_overlap_percent: f32,
}

impl Default for ReflectionsSimulationData {
    fn default() -> Self {
        Self {
            baked: audionimbus_sys::IPLbool::IPL_FALSE,
            baked_data_identifier: BakedDataIdentifier::Reflections {
                variation: BakedDataVariation::Reverb,
            },
            reverb_scale: [0.0; 3],
            hybrid_reverb_transition_time: 0.0,
            hybrid_reverb_overlap_percent: 0.0,
        }
    }
}

/// Intermediate representation of pathing simulation parameters for FFI conversion.
struct PathingSimulationData {
    pathing_probes: audionimbus_sys::IPLProbeBatch,
    visibility_radius: f32,
    visibility_threshold: f32,
    visibility_range: f32,
    pathing_order: i32,
    enable_validation: audionimbus_sys::IPLbool,
    find_alternate_paths: audionimbus_sys::IPLbool,
    deviation_model: audionimbus_sys::IPLDeviationModel,
}

impl PathingSimulationData {
    /// Converts optional pathing simulation parameters into concrete FFI-compatible data.
    fn from_params(params: Option<&PathingSimulationParameters>) -> Self {
        let Some(params) = params else {
            return Self::default();
        };

        Self {
            pathing_probes: params.pathing_probes.raw_ptr(),
            visibility_radius: params.visibility_radius,
            visibility_threshold: params.visibility_threshold,
            visibility_range: params.visibility_range,
            pathing_order: params.pathing_order as i32,
            enable_validation: if params.enable_validation {
                audionimbus_sys::IPLbool::IPL_TRUE
            } else {
                audionimbus_sys::IPLbool::IPL_FALSE
            },
            find_alternate_paths: if params.find_alternate_paths {
                audionimbus_sys::IPLbool::IPL_TRUE
            } else {
                audionimbus_sys::IPLbool::IPL_FALSE
            },
            deviation_model: (&params.deviation).into(),
        }
    }
}

impl Default for PathingSimulationData {
    fn default() -> Self {
        Self {
            pathing_probes: std::ptr::null_mut(),
            visibility_radius: 0.0,
            visibility_threshold: 0.0,
            visibility_range: 0.0,
            pathing_order: 0,
            enable_validation: audionimbus_sys::IPLbool::IPL_FALSE,
            find_alternate_paths: audionimbus_sys::IPLbool::IPL_FALSE,
            deviation_model: (&DeviationModel::Default).into(),
        }
    }
}

/// The different algorithms for simulating occlusion.
#[derive(Copy, Clone, Debug)]
pub enum OcclusionAlgorithm {
    /// Raycast occlusion.
    /// A single ray is traced from the listener to the source.
    /// If the ray hits a solid object before it reaches the source, the source is considered occluded.
    Raycast,

    /// A volumetric occlusion algorithm that can model partial occlusion.
    /// The source is modeled as a sphere with a configurable radius.
    /// Multiple points are sampled within the volume of this sphere.
    /// Rays are then traced from each sample point to both the source and the listener.
    /// A sample point is considered occluded if either of these two rays is occluded.
    /// The occlusion value for the source is calculated as the fraction of sample points that are unoccluded.
    /// This algorithm allows for smoother transitions in and out of occlusion.
    Volumetric {
        /// The radius of the sphere the source is modeled as.
        radius: f32,

        /// The number of point samples to consider when tracing rays.
        /// This value can change between simulation runs.
        num_occlusion_samples: u32,
    },
}

/// Simulation parameters that are not specific to any source.
#[derive(Default, Clone, Debug)]
pub struct SimulationSharedInputs<D = (), R = (), P = ()> {
    /// The position and orientation of the listener.
    listener: CoordinateSystem,

    /// Reflections shared inputs.
    reflections_shared_inputs: Option<ReflectionsSharedInputs>,

    /// Optional callback for visualizing valid path segments during call to [`Simulator::run_pathing`].
    pathing_visualization_callback: Option<PathingVisualizationCallback>,

    _direct: PhantomData<D>,
    _reflections: PhantomData<R>,
    _pathing: PhantomData<P>,
}

impl SimulationSharedInputs {
    /// Creates new [`SimulationSharedInputs`].
    ///
    /// # Arguments
    ///
    /// - `listener`: The position and orientation of the listener.
    pub fn new(listener: CoordinateSystem) -> Self {
        Self {
            listener,
            reflections_shared_inputs: None,
            pathing_visualization_callback: None,
            _direct: PhantomData,
            _reflections: PhantomData,
            _pathing: PhantomData,
        }
    }
}

impl<D, R, P> SimulationSharedInputs<D, R, P> {
    /// Returns shared simulation inputs with direct simulation.
    pub fn with_direct(self) -> SimulationSharedInputs<Direct, R, P> {
        let Self {
            listener,
            reflections_shared_inputs,
            pathing_visualization_callback,
            _reflections,
            _pathing,
            ..
        } = self;

        SimulationSharedInputs {
            listener,
            reflections_shared_inputs,
            pathing_visualization_callback,
            _direct: PhantomData,
            _reflections,
            _pathing,
        }
    }

    /// Sets the reflections simulation values of the shared inputs.
    pub fn with_reflections(
        self,
        inputs: ReflectionsSharedInputs,
    ) -> SimulationSharedInputs<D, Reflections, P> {
        let Self {
            listener,
            pathing_visualization_callback,
            _direct,
            _pathing,
            ..
        } = self;

        SimulationSharedInputs {
            listener,
            reflections_shared_inputs: Some(inputs),
            pathing_visualization_callback,
            _direct,
            _reflections: PhantomData,
            _pathing,
        }
    }

    /// Sets the pathing simulation values of the shared inputs.
    pub fn with_pathing(self) -> SimulationSharedInputs<D, R, Pathing> {
        let Self {
            listener,
            reflections_shared_inputs,
            pathing_visualization_callback,
            _direct,
            _reflections,
            ..
        } = self;

        SimulationSharedInputs {
            listener,
            reflections_shared_inputs,
            pathing_visualization_callback,
            _direct,
            _reflections,
            _pathing: PhantomData,
        }
    }

    /// Sets the pathing simulation values of the shared inputs, with a pathing visualization
    /// callback.
    ///
    /// # Arguments
    ///
    /// - `pathing_visualization_callback`: Callback for visualizing valid path segments during call to [`Simulator::run_pathing`].
    pub fn with_pathing_visualization_callback(
        self,
        pathing_visualization_callback: PathingVisualizationCallback,
    ) -> SimulationSharedInputs<D, R, Pathing> {
        let Self {
            listener,
            reflections_shared_inputs,
            _direct,
            _reflections,
            ..
        } = self;

        SimulationSharedInputs {
            listener,
            reflections_shared_inputs,
            pathing_visualization_callback: Some(pathing_visualization_callback),
            _direct,
            _reflections,
            _pathing: PhantomData,
        }
    }

    /// Sets the position and orientation of the listener.
    pub const fn set_listener(&mut self, listener: CoordinateSystem) {
        self.listener = listener;
    }
}

impl<D, P> SimulationSharedInputs<D, Reflections, P> {
    /// Sets the shared inputs to use for reflections simulation.
    pub fn set_reflections_shared_inputs(&mut self, shared_inputs: ReflectionsSharedInputs) {
        self.reflections_shared_inputs.replace(shared_inputs);
    }
}

impl<D, R> SimulationSharedInputs<D, R, Pathing> {
    /// Sets the visualization callback to use for pathing simulation.
    pub fn set_pathing_visualization_callback(
        &mut self,
        visualization_callback: PathingVisualizationCallback,
    ) {
        self.pathing_visualization_callback
            .replace(visualization_callback);
    }
}

impl<D, R, P> From<&SimulationSharedInputs<D, R, P>>
    for audionimbus_sys::IPLSimulationSharedInputs
{
    fn from(simulation_shared_inputs: &SimulationSharedInputs<D, R, P>) -> Self {
        let (pathing_visualization_callback, pathing_user_data) = simulation_shared_inputs
            .pathing_visualization_callback
            .as_ref()
            .map_or((None, std::ptr::null_mut()), |callback| {
                let (callback_fn, user_data) = callback.as_raw_parts();
                (Some(callback_fn), user_data)
            });

        let (num_rays, num_bounces, duration, order, irradiance_min_distance) =
            simulation_shared_inputs.reflections_shared_inputs.map_or(
                (0, 0, 0.0, 0, 0.0),
                |inputs| {
                    (
                        inputs.num_rays as i32,
                        inputs.num_bounces as i32,
                        inputs.duration,
                        inputs.order as i32,
                        inputs.irradiance_min_distance,
                    )
                },
            );

        Self {
            listener: simulation_shared_inputs.listener.into(),
            numRays: num_rays,
            numBounces: num_bounces,
            duration,
            order,
            irradianceMinDistance: irradiance_min_distance,
            pathingVisCallback: pathing_visualization_callback,
            pathingUserData: pathing_user_data,
        }
    }
}

/// Reflections shared inputs.
///
/// Used as an argument to [`SimulationSharedInputs::with_reflections`].
#[derive(Debug, Copy, Clone, PartialEq)]
pub struct ReflectionsSharedInputs {
    /// The number of rays to trace from the listener.
    /// Increasing this value results in more accurate reflections, at the cost of increased CPU usage.
    pub num_rays: u32,

    /// The number of times each ray traced from the listener is reflected when it encounters a solid object.
    /// Increasing this value results in longer, more accurate reverb tails, at the cost of increased CPU usage during simulation.
    pub num_bounces: u32,

    /// The duration (in seconds) of the impulse responses generated when simulating reflections.
    /// Increasing this value results in longer, more accurate reverb tails, at the cost of increased CPU usage during audio processing.
    pub duration: f32,

    /// The Ambisonic order of the impulse responses generated when simulating reflections.
    /// Increasing this value results in more accurate directional variation of reflected sound, at the cost of increased CPU usage during audio processing.
    pub order: u32,

    /// When calculating how much sound energy reaches a surface directly from a source, any source that is closer than [`Self::irradiance_min_distance`] to the surface is assumed to be at a distance of [`Self::irradiance_min_distance`], for the purposes of energy calculations.
    pub irradiance_min_distance: f32,
}

/// Simulation results for a source.
#[derive(Debug)]
pub struct SimulationOutputs<D, R, P, RE = ()> {
    inner: *mut audionimbus_sys::IPLSimulationOutputs,

    /// Retained pointer of the [`Source`] it originated from, to ensure the IR pointer remains
    /// valid.
    _source: audionimbus_sys::IPLSource,

    _direct: PhantomData<D>,
    _reflections: PhantomData<R>,
    _pathing: PhantomData<P>,
    _reflection_effect: PhantomData<RE>,
}

impl<D, R, P, RE> SimulationOutputs<D, R, P, RE> {
    fn try_allocate<SourceD, SourceR, SourceP, SourceRE>(
        source: &Source<SourceD, SourceR, SourceP, SourceRE>,
    ) -> Result<Self, SteamAudioError>
    where
        D: DirectCompatible<SourceD>,
        R: ReflectionsCompatible<SourceR>,
        P: PathingCompatible<SourceP>,
        RE: ReflectionEffectCompatible<R, SourceRE>,
        SourceD: 'static,
        SourceR: 'static,
        SourceP: 'static,
        SourceRE: 'static,
    {
        let ptr = unsafe {
            let layout = std::alloc::Layout::new::<audionimbus_sys::IPLSimulationOutputs>();
            let ptr = std::alloc::alloc(layout).cast::<audionimbus_sys::IPLSimulationOutputs>();
            if ptr.is_null() {
                return Err(SteamAudioError::OutOfMemory);
            }
            std::ptr::write(ptr, std::mem::zeroed());
            ptr
        };

        let source = unsafe { audionimbus_sys::iplSourceRetain(source.raw_ptr()) };

        Ok(Self {
            inner: ptr,
            _source: source,
            _direct: PhantomData,
            _reflections: PhantomData,
            _pathing: PhantomData,
            _reflection_effect: PhantomData,
        })
    }

    pub const fn raw_ptr(&self) -> *mut audionimbus_sys::IPLSimulationOutputs {
        self.inner
    }

    pub const fn raw_ptr_mut(&mut self) -> &mut *mut audionimbus_sys::IPLSimulationOutputs {
        &mut self.inner
    }
}

impl<R, P, RE> SimulationOutputs<Direct, R, P, RE> {
    pub fn direct(&self) -> DirectEffectParams {
        unsafe { (*self.inner).direct.into() }
    }
}

impl<D, P, RE> SimulationOutputs<D, Reflections, P, RE>
where
    RE: ReflectionEffectType,
{
    pub fn reflections(&self) -> ReflectionEffectParams<RE> {
        unsafe {
            ReflectionEffectParams::from_ffi_unchecked((*self.inner).reflections, self._source)
        }
    }
}

impl<D, R, RE> SimulationOutputs<D, R, Pathing, RE> {
    pub fn pathing(&self) -> PathEffectParams {
        unsafe { (*self.inner).pathing.into() }
    }
}

unsafe impl<D, R, P, RE> Send for SimulationOutputs<D, R, P, RE> {}

impl<D, R, P, RE> Drop for SimulationOutputs<D, R, P, RE> {
    fn drop(&mut self) {
        unsafe {
            let layout = std::alloc::Layout::new::<audionimbus_sys::IPLSimulationOutputs>();
            std::alloc::dealloc(self.inner.cast::<u8>(), layout);

            audionimbus_sys::iplSourceRelease(&mut self._source);
        }
    }
}

/// Errors that can occur during simulation operations.
#[derive(Copy, Clone, Eq, PartialEq, Debug)]
pub enum SimulationError {
    /// Attempted to run pathing simulation without any probe batches committed.
    ///
    /// Pathing requires at least one probe batch to be added to the simulator
    /// via [`Simulator::add_probe_batch`] and committed via [`Simulator::commit`]
    /// before running simulations.
    PathingWithoutProbes,

    /// Attempted to run reflection simulation without a scene set.
    ///
    /// Reflection simulation requires a [`Scene`] to be set on the simulator via
    /// [`Simulator::set_scene`] and committed via [`Simulator::commit`] before
    /// running simulations.
    ReflectionsWithoutScene,
}

impl std::error::Error for SimulationError {}

impl std::fmt::Display for SimulationError {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        match &self {
            Self::PathingWithoutProbes => {
                write!(f, "running pathing on a simulator with no probes")
            }
            Self::ReflectionsWithoutScene => {
                write!(f, "running reflections on a simulator with no scene set")
            }
        }
    }
}

/// Errors that can occur during parameter validation.
#[derive(Debug, Copy, Clone, PartialEq)]
pub enum ParameterValidationError {
    /// Number of occlusion samples exceeds the maximum set during initialization.
    OcclusionSamplesExceedsMax {
        /// The requested number of samples.
        requested: u32,
        /// The maximum allowed number of samples.
        max: u32,
    },

    /// Number of rays exceeds the maximum set during initialization.
    NumRaysExceedsMax {
        /// The requested number of rays.
        requested: u32,
        /// The maximum allowed number of rays.
        max: u32,
    },

    /// Duration exceeds the maximum set during initialization.
    DurationExceedsMax {
        /// The requested duration in seconds.
        requested: f32,
        /// The maximum allowed duration in seconds.
        max: f32,
    },
}

impl std::error::Error for ParameterValidationError {}

impl std::fmt::Display for ParameterValidationError {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        match self {
            Self::OcclusionSamplesExceedsMax { requested, max } => {
                write!(
                    f,
                    "requested {} occlusion samples, but maximum is {} (set during simulator initialization)",
                    requested, max
                )
            }
            Self::NumRaysExceedsMax { requested, max } => {
                write!(
                    f,
                    "requested {} rays, but maximum is {} (set during simulator initialization)",
                    requested, max
                )
            }
            Self::DurationExceedsMax { requested, max } => {
                write!(
                    f,
                    "requested duration of {}s, but maximum is {}s (set during simulator initialization)",
                    requested, max
                )
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use crate::*;

    mod source {
        use super::*;

        mod clone {
            use super::*;

            #[test]
            fn test_clone() {
                let context = Context::default();
                let audio_settings = AudioSettings::default();
                let simulator_settings = SimulationSettings::new(&audio_settings);
                let simulator = Simulator::try_new(&context, &simulator_settings).unwrap();
                let source = Source::try_new(&simulator).unwrap();
                let clone = source.clone();
                assert_eq!(source.raw_ptr(), clone.raw_ptr());
                drop(source);
                assert!(!clone.raw_ptr().is_null());
            }
        }
    }

    mod simulator {
        use super::*;

        #[test]
        fn test_simulator_clone() {
            let context = Context::default();
            let audio_settings = AudioSettings::default();
            let settings = SimulationSettings::new(&audio_settings);
            let simulator = Simulator::try_new(&context, &settings).unwrap();
            let clone = simulator.clone();
            assert_eq!(simulator.raw_ptr(), clone.raw_ptr());
            drop(simulator);
            assert!(!clone.raw_ptr().is_null());
        }

        #[test]
        fn test_set_scene_is_noop_when_scene_is_already_committed() {
            let context = Context::default();
            let audio_settings = AudioSettings::default();
            let settings = SimulationSettings::new(&audio_settings);
            let mut simulator = Simulator::try_new(&context, &settings).unwrap();
            let scene = Scene::try_new(&context).unwrap();

            simulator.set_scene(&scene);
            simulator.commit();

            {
                let shared = simulator.shared.lock().unwrap();
                assert!(shared.pending_scene.is_none());
                assert_eq!(shared.committed_scene.as_ref(), Some(&scene));
            }

            simulator.set_scene(&scene);

            let shared = simulator.shared.lock().unwrap();
            assert!(shared.pending_scene.is_none());
            assert_eq!(shared.committed_scene.as_ref(), Some(&scene));
        }
    }
}