audionimbus 0.13.0

//! Global context management and configuration.

use crate::error::{to_option_error, SteamAudioError};
use crate::version::SteamAudioVersion;

/// A context object, which controls low-level operations of Steam Audio.
///
/// Typically, a context is specified once during the execution of the client program, before calling any other API functions.
///
/// # Examples
///
/// ```
/// use audionimbus::{Context, ContextSettings, SimdLevel};
///
/// // Create with default settings.
/// let context = Context::default();
///
/// // Or with custom settings.
/// let settings = ContextSettings::new().with_simd_level(SimdLevel::AVX2);
/// let context = Context::try_new(&settings)?;
/// # Ok::<(), audionimbus::SteamAudioError>(())
/// ```
#[derive(Debug)]
pub struct Context(pub(crate) audionimbus_sys::IPLContext);

impl Context {
    /// Creates a new context with the given [`ContextSettings`].
    ///
    /// # Errors
    ///
    /// Returns [`SteamAudioError`] if context creation fails, typically due to:
    /// - Incompatible API version
    /// - Memory allocation failure
    /// - External dependency initialization failure
    pub fn try_new(settings: &ContextSettings) -> Result<Self, SteamAudioError> {
        let mut context = Self(std::ptr::null_mut());

        let status = unsafe {
            audionimbus_sys::iplContextCreate(
                &mut audionimbus_sys::IPLContextSettings::from(settings),
                context.raw_ptr_mut(),
            )
        };

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

        Ok(context)
    }

    /// Returns the raw FFI pointer to the underlying Steam Audio context.
    ///
    /// # Safety
    ///
    /// This is intended for internal use and advanced scenarios. The returned pointer
    /// must not outlive the `Context` object.
    pub const fn raw_ptr(&self) -> audionimbus_sys::IPLContext {
        self.0
    }

    /// Returns a mutable reference to the raw FFI pointer.
    ///
    /// # Safety
    ///
    /// This is intended for internal use and advanced scenarios. The returned pointer
    /// must not outlive the `Context` object.
    pub const fn raw_ptr_mut(&mut self) -> &mut audionimbus_sys::IPLContext {
        &mut self.0
    }
}

impl Default for Context {
    fn default() -> Self {
        let settings = ContextSettings::default();
        Self::try_new(&settings).expect("failed to create default context")
    }
}

impl Drop for Context {
    fn drop(&mut self) {
        unsafe { audionimbus_sys::iplContextRelease(&raw mut self.0) }
    }
}

unsafe impl Send for Context {}
unsafe impl Sync for Context {}

impl Clone for Context {
    /// Retains an additional reference to the context.
    ///
    /// The returned [`Context`] shares the same underlying Steam Audio object.
    /// The context will not be destroyed until all clones are dropped.
    fn clone(&self) -> Self {
        // SAFETY: iplContextRetain increments the reference count of the underlying
        // Steam Audio context and returns a new handle to it. The context will not
        // be destroyed until all references are released.
        Self(unsafe { audionimbus_sys::iplContextRetain(self.0) })
    }
}

/// Settings used to create a [`Context`].
pub struct ContextSettings {
    /// The API version.
    ///
    /// Context creation will fail if `phonon.dll` does not implement a compatible version of the API.
    /// Typically, this should be set to [`SteamAudioVersion::default()`].
    version: SteamAudioVersion,

    /// If `Some`, Steam Audio will call this function to record log messages generated by certain operations.
    ///
    /// See macro [`log_callback`](crate::log_callback) to easily define a log callback using
    /// Rust-friendly types. For instance:
    ///
    /// ```
    /// # use audionimbus::{log_callback, Context, ContextSettings};
    /// let settings = ContextSettings::new().with_log_callback(log_callback!(|level, message| {
    ///     println!("{level:?}: {message}");
    /// }));
    /// let context = Context::try_new(&settings)?;
    /// # Ok::<(), audionimbus::SteamAudioError>(())
    /// ```
    log_callback: Option<
        unsafe extern "C" fn(
            level: audionimbus_sys::IPLLogLevel,
            message: *const std::os::raw::c_char,
        ),
    >,

    /// If `Some`, Steam Audio will call this function whenever it needs to allocate memory.
    ///
    /// See macro [`allocate_callback`](crate::allocate_callback) to easily define a memory allocation callback.
    /// For instance:
    ///
    /// ```
    /// # use audionimbus::{allocate_callback, free_callback, Context, ContextSettings};
    /// # free_callback!(my_free, |ptr| {
    /// #   // ...
    /// # });
    /// use std::alloc::{alloc, Layout};
    /// use std::ffi::c_void;
    ///
    /// let settings = ContextSettings::new()
    ///     .with_allocate_callback(allocate_callback!(|size, alignment| {
    ///         unsafe {
    ///             let layout = Layout::from_size_align_unchecked(size, alignment);
    ///             alloc(layout) as *mut c_void
    ///         }
    ///     }))
    ///     .with_free_callback(my_free);
    /// let context = Context::try_new(&settings)?;
    /// # Ok::<(), audionimbus::SteamAudioError>(())
    /// ```
    allocate_callback:
        Option<unsafe extern "C" fn(size: usize, alignment: usize) -> *mut std::ffi::c_void>,

    /// If `Some`, Steam Audio will call this function whenever it needs to free memory.
    ///
    /// See macro [`free_callback`](crate::free_callback) to easily define a callback function to free memory.
    /// For instance:
    ///
    /// ```
    /// # use audionimbus::{free_callback, allocate_callback, Context, ContextSettings};
    /// # use std::alloc::{alloc, Layout};
    /// # use std::ffi::c_void;
    /// # allocate_callback!(my_allocator, |size, alignment| {
    /// #     unsafe {
    /// #         let layout = Layout::from_size_align_unchecked(size, alignment);
    /// #         alloc(layout) as *mut c_void
    /// #     }
    /// # });
    /// let settings = ContextSettings::new()
    ///     .with_allocate_callback(my_allocator)
    ///     .with_free_callback(free_callback!(|ptr| {
    ///         // ...
    ///     }));
    /// let context = Context::try_new(&settings)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    free_callback: Option<unsafe extern "C" fn(memory_block: *mut std::ffi::c_void)>,

    /// The maximum SIMD instruction set level that Steam Audio should use.
    ///
    /// Steam Audio automatically chooses the best instruction set to use based on the user’s CPU, but you can prevent it from using certain newer instruction sets using this parameter.
    /// For example, with some workloads, AVX512 instructions consume enough power that the CPU clock speed will be throttled, resulting in lower performance than expected.
    /// If you observe this in your application, set this parameter to [`SimdLevel::AVX2`] or lower.
    simd_level: SimdLevel,

    /// Additional flags for modifying the behavior of the created context.
    flags: ContextFlags,
}

impl ContextSettings {
    /// Creates new [`ContextSettings`] with default values.
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets the API version for this context.
    ///
    /// Context creation will fail if `phonon.dll` does not implement a compatible version of the API.
    /// Typically, this should be set to [`SteamAudioVersion::default()`].
    ///
    /// # Examples
    ///
    /// ```
    /// use audionimbus::{Context, ContextSettings, SteamAudioVersion};
    ///
    /// let settings = ContextSettings::new().with_version(SteamAudioVersion::default());
    /// let context = Context::try_new(&settings)?;
    /// # Ok::<(), audionimbus::SteamAudioError>(())
    /// ```
    pub fn with_version(mut self, version: SteamAudioVersion) -> Self {
        self.version = version;
        self
    }

    /// Sets a callback function for logging Steam Audio messages.
    ///
    /// Use the [`log_callback!`](crate::log_callback) macro to easily define a log callback
    /// with Rust-friendly types instead of manually creating an `extern "C"` function.
    ///
    /// # Examples
    ///
    /// ```
    /// use audionimbus::{log_callback, Context, ContextSettings};
    ///
    /// let settings = ContextSettings::new().with_log_callback(log_callback!(|level, message| {
    ///     println!("{level:?}: {message}");
    /// }));
    /// let context = Context::try_new(&settings)?;
    /// # Ok::<(), audionimbus::SteamAudioError>(())
    /// ```
    pub fn with_log_callback(
        mut self,
        log_callback: unsafe extern "C" fn(
            level: audionimbus_sys::IPLLogLevel,
            message: *const std::os::raw::c_char,
        ),
    ) -> Self {
        self.log_callback = Some(log_callback);
        self
    }

    /// Sets a callback function for custom memory allocation.
    ///
    /// Use the [`allocate_callback!`](crate::allocate_callback) macro to easily define
    /// an allocation callback with Rust-friendly types instead of manually creating an
    /// `extern "C"` function.
    ///
    /// # Examples
    ///
    /// ```
    /// use audionimbus::{allocate_callback, free_callback, Context, ContextSettings};
    /// use std::alloc::{alloc, Layout};
    /// use std::ffi::c_void;
    ///
    /// let settings = ContextSettings::new()
    ///     .with_allocate_callback(allocate_callback!(|size, alignment| {
    ///         unsafe {
    ///             let layout = Layout::from_size_align_unchecked(size, alignment);
    ///             alloc(layout) as *mut c_void
    ///         }
    ///     }))
    ///     .with_free_callback(free_callback!(|ptr| {
    ///         // Free the memory...
    ///     }));
    /// let context = Context::try_new(&settings)?;
    /// # Ok::<(), audionimbus::SteamAudioError>(())
    /// ```
    pub fn with_allocate_callback(
        mut self,
        allocate_callback: unsafe extern "C" fn(
            size: usize,
            alignment: usize,
        ) -> *mut std::ffi::c_void,
    ) -> Self {
        self.allocate_callback = Some(allocate_callback);
        self
    }

    /// Sets a callback function for custom memory deallocation.
    ///
    /// Use the [`free_callback!`](crate::free_callback) macro to easily define a free
    /// callback with Rust-friendly types instead of manually creating an `extern "C"` function.
    ///
    /// # Examples
    ///
    /// ```
    /// use audionimbus::{allocate_callback, free_callback, Context, ContextSettings};
    /// use std::alloc::{alloc, Layout};
    /// use std::ffi::c_void;
    ///
    /// let settings = ContextSettings::new()
    ///     .with_allocate_callback(allocate_callback!(|size, alignment| {
    ///         unsafe {
    ///             let layout = Layout::from_size_align_unchecked(size, alignment);
    ///             alloc(layout) as *mut c_void
    ///         }
    ///     }))
    ///     .with_free_callback(free_callback!(|ptr| {
    ///         // Free the memory...
    ///     }));
    /// let context = Context::try_new(&settings)?;
    /// # Ok::<(), audionimbus::SteamAudioError>(())
    /// ```
    pub fn with_free_callback(
        mut self,
        free_callback: unsafe extern "C" fn(memory_block: *mut std::ffi::c_void),
    ) -> Self {
        self.free_callback = Some(free_callback);
        self
    }

    /// Sets the maximum SIMD instruction set level to use.
    ///
    /// Steam Audio automatically chooses the best instruction set based on the CPU, but you
    /// can limit it to prevent issues. For example, AVX512 instructions may cause CPU
    /// throttling with some workloads, reducing performance. If you observe this, set the
    /// level to [`SimdLevel::AVX2`] or lower.
    ///
    /// # Examples
    ///
    /// ```
    /// use audionimbus::{Context, ContextSettings, SimdLevel};
    ///
    /// let settings = ContextSettings::new().with_simd_level(SimdLevel::AVX2);
    /// let context = Context::try_new(&settings)?;
    /// # Ok::<(), audionimbus::SteamAudioError>(())
    /// ```
    pub fn with_simd_level(mut self, simd_level: SimdLevel) -> Self {
        self.simd_level = simd_level;
        self
    }

    /// Sets additional flags for modifying the context's behavior.
    ///
    /// # Arguments
    ///
    /// - `flags`: Additional flags for modifying the behavior of the created context.
    ///
    /// # Examples
    ///
    /// ```
    /// use audionimbus::{Context, ContextFlags, ContextSettings};
    ///
    /// // Enable validation for debugging (significant performance penalty).
    /// let settings = ContextSettings::new().with_flags(ContextFlags::VALIDATION);
    /// let context = Context::try_new(&settings)?;
    /// # Ok::<(), audionimbus::SteamAudioError>(())
    /// ```
    pub fn with_flags(mut self, flags: ContextFlags) -> Self {
        self.flags = flags;
        self
    }
}

impl Default for ContextSettings {
    fn default() -> Self {
        Self {
            version: SteamAudioVersion::default(),
            log_callback: None,
            allocate_callback: None,
            free_callback: None,
            simd_level: SimdLevel::default(),
            flags: ContextFlags::empty(),
        }
    }
}

impl From<&ContextSettings> for audionimbus_sys::IPLContextSettings {
    fn from(settings: &ContextSettings) -> Self {
        Self {
            version: settings.version.into(),
            logCallback: settings.log_callback,
            allocateCallback: settings.allocate_callback,
            freeCallback: settings.free_callback,
            simdLevel: settings.simd_level.into(),
            flags: settings.flags.into(),
        }
    }
}

/// SIMD instruction sets that Steam Audio can attempt to use.
#[derive(Debug, Copy, Clone, Default)]
pub enum SimdLevel {
    /// Intel Streaming SIMD Extensions 2.
    /// Up to 4 simultaneous floating-point operations.
    SSE2 = 0,

    /// Intel Streaming SIMD Extensions 4.2 or older.
    /// Up to 4 simultaneous floating-point operations.
    SSE4 = 1,

    /// Intel Advanced Vector Extensions or older.
    /// Up to 8 simultaneous floating-point operations.
    AVX = 2,

    /// Intel Advanced Vector Extensions 2 or older.
    /// Up to 8 simultaneous floating-point operations.
    AVX2 = 3,

    /// Intel Advanced Vector Extensions 512 or older.
    /// Up to 16 simultaneous floating-point operations.
    #[default]
    AVX512 = 4,
}

impl From<SimdLevel> for audionimbus_sys::IPLSIMDLevel {
    fn from(simd_level: SimdLevel) -> Self {
        match simd_level {
            SimdLevel::SSE2 => Self::IPL_SIMDLEVEL_SSE2,
            SimdLevel::SSE4 => Self::IPL_SIMDLEVEL_SSE4,
            SimdLevel::AVX => Self::IPL_SIMDLEVEL_AVX,
            SimdLevel::AVX2 => Self::IPL_SIMDLEVEL_AVX2,
            SimdLevel::AVX512 => Self::IPL_SIMDLEVEL_AVX512,
        }
    }
}

bitflags::bitflags! {
    /// Additional flags for modifying the behavior of a Steam Audio context.
    #[derive(Debug, Copy, Clone)]
    pub struct ContextFlags: u32 {
        /// All API functions perform extra validation checks.
        /// NOTE: This imposes a significant performance penalty.
        const VALIDATION = 1 << 0;

        /// Force this enum to be 32 bits in size.
        const FORCE_32BIT = 1 << 1;
    }
}

impl From<ContextFlags> for audionimbus_sys::IPLContextFlags {
    fn from(context_flags: ContextFlags) -> Self {
        Self(context_flags.bits() as _)
    }
}

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

    #[test]
    fn test_context_clone() {
        let context = Context::default();
        let clone = context.clone();
        assert_eq!(context.raw_ptr(), clone.raw_ptr());
        drop(context);
        assert!(!clone.raw_ptr().is_null());
    }

    #[test]
    fn test_context_settings_simd_levels() {
        let levels = [
            SimdLevel::SSE2,
            SimdLevel::SSE4,
            SimdLevel::AVX,
            SimdLevel::AVX2,
            SimdLevel::AVX512,
        ];

        for level in levels {
            let settings = ContextSettings::new().with_simd_level(level);
            let result = Context::try_new(&settings);
            assert!(result.is_ok());
        }
    }
}