sesh_sdk/

vec.rs

//! Vector operations for batch audio processing.
//!
//! Each op has two code paths: an inline Rust fallback (always available) and a
//! host-accelerated import (used when `sesh_vec_version() > 0`). The SDK selects
//! the path at runtime. Plugin authors call the same functions regardless of platform.

use std::sync::atomic::{AtomicU32, Ordering};

// ---------------------------------------------------------------------------
// Host capability detection
// ---------------------------------------------------------------------------

extern "C" {
    fn sesh_vec_version() -> u32;
}

/// Cached host vec version. 0 = not yet queried, u32::MAX = stubs (web).
static HOST_VEC_VERSION: AtomicU32 = AtomicU32::new(0);

fn host_version() -> u32 {
    let v = HOST_VEC_VERSION.load(Ordering::Relaxed);
    if v != 0 {
        return v;
    }
    let v = unsafe { sesh_vec_version() };
    // Store non-zero so we don't re-query. If host returns 0, store a sentinel.
    let store = if v == 0 { u32::MAX } else { v };
    HOST_VEC_VERSION.store(store, Ordering::Relaxed);
    v
}

#[inline]
fn use_host_ops() -> bool {
    host_version() > 0 && host_version() != u32::MAX
}

// ---------------------------------------------------------------------------
// Host imports (C ABI, raw pointers)
// ---------------------------------------------------------------------------

extern "C" {
    fn sesh_vec_copy_host(dst: *mut f32, src: *const f32, len: u32);
    fn sesh_vec_fill_host(dst: *mut f32, value: f32, len: u32);
    fn sesh_vec_add_host(dst: *mut f32, a: *const f32, b: *const f32, len: u32);
    fn sesh_vec_add_scalar_host(dst: *mut f32, value: f32, len: u32);
    fn sesh_vec_mul_host(dst: *mut f32, a: *const f32, b: *const f32, len: u32);
    fn sesh_vec_mul_scalar_host(dst: *mut f32, value: f32, len: u32);
    fn sesh_vec_mul_add_host(dst: *mut f32, src: *const f32, gain: f32, len: u32);
    fn sesh_vec_clamp_host(dst: *mut f32, src: *const f32, min: f32, max: f32, len: u32);
    fn sesh_vec_ring_write_host(
        buf: *mut f32, buf_len: u32, pos: *mut u32, src: *const f32, len: u32,
    );
    fn sesh_vec_ring_read_host(
        buf: *const f32, buf_len: u32, pos: u32, dst: *mut f32, offset: u32, len: u32,
    );
    fn sesh_vec_delay_read_host(
        buf: *const f32, buf_len: u32, pos: u32, dst: *mut f32, time: *const f32, len: u32,
    );
    fn sesh_vec_osc_host(
        phase: *mut f32, dst: *mut f32, freq: f32, waveform: u32, sample_rate: f32, len: u32,
    );
    fn sesh_vec_biquad_host(
        state: *mut f32, dst: *mut f32, src: *const f32,
        cutoff: *const f32, q: *const f32, gain: *const f32,
        filter_type: u32, sample_rate: f32, len: u32,
    );
    fn sesh_vec_envelope_host(
        state: *mut f32, dst: *mut f32, src: *const f32,
        attack: *const f32, release: *const f32,
        mode: u32, sample_rate: f32, len: u32,
    );
    fn sesh_vec_tanh_host(dst: *mut f32, src: *const f32, drive: *const f32, len: u32);
    fn sesh_vec_hard_clip_host(dst: *mut f32, src: *const f32, threshold: *const f32, len: u32);
}

// ---------------------------------------------------------------------------
// Enums and state types
// ---------------------------------------------------------------------------

/// Oscillator waveform shape.
#[repr(u32)]
#[derive(Clone, Copy)]
pub enum Waveform {
    Sine = 0,
    Triangle = 1,
    Saw = 2,
    Square = 3,
}

/// Biquad filter type.
#[repr(u32)]
#[derive(Clone, Copy)]
pub enum FilterType {
    Lowpass = 0,
    Highpass = 1,
    Bandpass = 2,
    Notch = 3,
    /// Parametric EQ band — boost/cut at cutoff frequency.
    Peak = 4,
    /// Boost/cut below cutoff frequency.
    LowShelf = 5,
    /// Boost/cut above cutoff frequency.
    HighShelf = 6,
}

/// Internal state for a biquad filter (two-sample history).
#[repr(C)]
pub struct BiquadState {
    pub x1: f32,
    pub x2: f32,
    pub y1: f32,
    pub y2: f32,
}

impl BiquadState {
    pub const fn new() -> Self {
        Self { x1: 0.0, x2: 0.0, y1: 0.0, y2: 0.0 }
    }
}

/// Envelope follower detection mode.
#[repr(u32)]
#[derive(Clone, Copy)]
pub enum EnvelopeMode {
    /// Track instantaneous peaks.
    Peak = 0,
    /// Track root-mean-square level.
    Rms = 1,
}

/// Internal state for an envelope follower.
#[repr(C)]
pub struct EnvelopeState {
    pub current: f32,
}

impl EnvelopeState {
    pub const fn new() -> Self {
        Self { current: 0.0 }
    }
}

// ===========================================================================
// Math ops
// ===========================================================================

/// Copy `src` into `dst`.
pub fn vec_copy(dst: &mut [f32], src: &[f32]) {
    let len = dst.len().min(src.len());
    if use_host_ops() {
        unsafe { sesh_vec_copy_host(dst.as_mut_ptr(), src.as_ptr(), len as u32) }
    } else {
        dst[..len].copy_from_slice(&src[..len]);
    }
}

/// Fill `dst` with a constant value.
pub fn vec_fill(dst: &mut [f32], value: f32) {
    let len = dst.len();
    if use_host_ops() {
        unsafe { sesh_vec_fill_host(dst.as_mut_ptr(), value, len as u32) }
    } else {
        for s in dst.iter_mut() {
            *s = value;
        }
    }
}

/// Element-wise addition: `dst[i] = a[i] + b[i]`.
pub fn vec_add(dst: &mut [f32], a: &[f32], b: &[f32]) {
    let len = dst.len().min(a.len()).min(b.len());
    if use_host_ops() {
        unsafe { sesh_vec_add_host(dst.as_mut_ptr(), a.as_ptr(), b.as_ptr(), len as u32) }
    } else {
        for i in 0..len {
            dst[i] = a[i] + b[i];
        }
    }
}

/// Add scalar to every element: `dst[i] += value`.
pub fn vec_add_scalar(dst: &mut [f32], value: f32) {
    let len = dst.len();
    if use_host_ops() {
        unsafe { sesh_vec_add_scalar_host(dst.as_mut_ptr(), value, len as u32) }
    } else {
        for s in dst.iter_mut() {
            *s += value;
        }
    }
}

/// Element-wise multiplication: `dst[i] = a[i] * b[i]`.
pub fn vec_mul(dst: &mut [f32], a: &[f32], b: &[f32]) {
    let len = dst.len().min(a.len()).min(b.len());
    if use_host_ops() {
        unsafe { sesh_vec_mul_host(dst.as_mut_ptr(), a.as_ptr(), b.as_ptr(), len as u32) }
    } else {
        for i in 0..len {
            dst[i] = a[i] * b[i];
        }
    }
}

/// Multiply every element by scalar: `dst[i] *= value`.
pub fn vec_mul_scalar(dst: &mut [f32], value: f32) {
    let len = dst.len();
    if use_host_ops() {
        unsafe { sesh_vec_mul_scalar_host(dst.as_mut_ptr(), value, len as u32) }
    } else {
        for s in dst.iter_mut() {
            *s *= value;
        }
    }
}

/// Multiply and accumulate: `dst[i] += src[i] * gain`.
pub fn vec_mul_add(dst: &mut [f32], src: &[f32], gain: f32) {
    let len = dst.len().min(src.len());
    if use_host_ops() {
        unsafe { sesh_vec_mul_add_host(dst.as_mut_ptr(), src.as_ptr(), gain, len as u32) }
    } else {
        for i in 0..len {
            dst[i] += src[i] * gain;
        }
    }
}

/// Clamp: `dst[i] = clamp(src[i], min, max)`.
pub fn vec_clamp(dst: &mut [f32], src: &[f32], min: f32, max: f32) {
    let len = dst.len().min(src.len());
    if use_host_ops() {
        unsafe { sesh_vec_clamp_host(dst.as_mut_ptr(), src.as_ptr(), min, max, len as u32) }
    } else {
        for i in 0..len {
            dst[i] = src[i].clamp(min, max);
        }
    }
}

// ===========================================================================
// Circular buffer ops
// ===========================================================================

/// Write `src` into circular buffer `buf` starting at `*pos`, wrapping at `buf.len()`.
/// Advances `*pos` by `src.len()`.
pub fn vec_ring_write(buf: &mut [f32], pos: &mut usize, src: &[f32]) {
    let buf_len = buf.len();
    let frames = src.len();
    if use_host_ops() {
        let mut pos32 = *pos as u32;
        unsafe {
            sesh_vec_ring_write_host(
                buf.as_mut_ptr(), buf_len as u32, &mut pos32, src.as_ptr(), frames as u32,
            );
        }
        *pos = pos32 as usize;
    } else {
        for i in 0..frames {
            buf[(*pos + i) % buf_len] = src[i];
        }
        *pos = (*pos + frames) % buf_len;
    }
}

/// Read `dst.len()` contiguous samples from circular buffer at `pos - offset`, wrapping.
pub fn vec_ring_read(buf: &[f32], pos: usize, dst: &mut [f32], offset: usize) {
    let buf_len = buf.len();
    let frames = dst.len();
    if use_host_ops() {
        unsafe {
            sesh_vec_ring_read_host(
                buf.as_ptr(), buf_len as u32, pos as u32,
                dst.as_mut_ptr(), offset as u32, frames as u32,
            );
        }
    } else {
        let start = (pos + buf_len - offset) % buf_len;
        for i in 0..frames {
            dst[i] = buf[(start + i) % buf_len];
        }
    }
}

// ===========================================================================
// Delay op
// ===========================================================================

/// Per-sample modulated delay read with linear interpolation.
///
/// For each sample `i`, reads from circular buffer at a fractional offset
/// `time[i]` samples behind where the write head was at sample `i`.
/// `pos` should be the write head position *after* the most recent `vec_ring_write`.
pub fn vec_delay_read(buf: &[f32], pos: usize, dst: &mut [f32], time: &[f32]) {
    let buf_len = buf.len();
    let frames = dst.len().min(time.len());
    if use_host_ops() {
        unsafe {
            sesh_vec_delay_read_host(
                buf.as_ptr(), buf_len as u32, pos as u32,
                dst.as_mut_ptr(), time.as_ptr(), frames as u32,
            );
        }
    } else {
        for i in 0..frames {
            // The write head was at (pos - frames + i) when sample i was written.
            let write_pos_at_i = (pos + buf_len - frames + i) % buf_len;

            let delay_int = time[i] as usize;
            let delay_frac = time[i] - delay_int as f32;

            let idx1 = (write_pos_at_i + buf_len - delay_int) % buf_len;
            let idx2 = (idx1 + buf_len - 1) % buf_len;

            dst[i] = buf[idx1] + delay_frac * (buf[idx2] - buf[idx1]);
        }
    }
}

// ===========================================================================
// Oscillator
// ===========================================================================

/// Fill `dst` with oscillator output. Advances `*phase`. `freq` is in Hz.
pub fn vec_osc(
    phase: &mut f32,
    dst: &mut [f32],
    freq: f32,
    waveform: Waveform,
    sample_rate: f32,
) {
    let frames = dst.len();
    if use_host_ops() {
        unsafe {
            sesh_vec_osc_host(
                phase as *mut f32, dst.as_mut_ptr(),
                freq, waveform as u32, sample_rate, frames as u32,
            );
        }
    } else {
        let phase_inc = freq / sample_rate;
        for i in 0..frames {
            dst[i] = match waveform {
                Waveform::Sine => (*phase * std::f32::consts::TAU).sin(),
                Waveform::Triangle => 4.0 * (*phase - (*phase + 0.5).floor()).abs() - 1.0,
                Waveform::Saw => 2.0 * (*phase - (*phase + 0.5).floor()),
                Waveform::Square => if *phase % 1.0 < 0.5 { 1.0 } else { -1.0 },
            };
            *phase += phase_inc;
            if *phase >= 1.0 {
                *phase -= 1.0;
            }
        }
    }
}

// ===========================================================================
// Filter
// ===========================================================================

/// Biquad filter with per-sample modulation of cutoff, Q, and gain.
///
/// `cutoff` is in Hz, `q` is the Q factor, `gain` is in dB (used for Peak/Shelf types).
/// Coefficients are recomputed each sample from the parameter buffers.
pub fn vec_biquad(
    state: &mut BiquadState,
    dst: &mut [f32],
    src: &[f32],
    cutoff: &[f32],
    q: &[f32],
    gain: &[f32],
    filter_type: FilterType,
    sample_rate: f32,
) {
    let frames = dst.len().min(src.len()).min(cutoff.len()).min(q.len()).min(gain.len());
    if use_host_ops() {
        unsafe {
            sesh_vec_biquad_host(
                state as *mut BiquadState as *mut f32,
                dst.as_mut_ptr(), src.as_ptr(),
                cutoff.as_ptr(), q.as_ptr(), gain.as_ptr(),
                filter_type as u32, sample_rate, frames as u32,
            );
        }
    } else {
        for i in 0..frames {
            let w0 = std::f32::consts::TAU * cutoff[i] / sample_rate;
            let cos_w0 = w0.cos();
            let sin_w0 = w0.sin();
            let alpha = sin_w0 / (2.0 * q[i]);
            let a_db = gain[i];
            let a_lin = 10.0f32.powf(a_db / 40.0);

            let (b0, b1, b2, a0, a1, a2) = match filter_type {
                FilterType::Lowpass => {
                    let b1 = 1.0 - cos_w0;
                    let b0 = b1 / 2.0;
                    (b0, b1, b0, 1.0 + alpha, -2.0 * cos_w0, 1.0 - alpha)
                }
                FilterType::Highpass => {
                    let b1 = -(1.0 + cos_w0);
                    let b0 = (1.0 + cos_w0) / 2.0;
                    (b0, b1, b0, 1.0 + alpha, -2.0 * cos_w0, 1.0 - alpha)
                }
                FilterType::Bandpass => {
                    (alpha, 0.0, -alpha, 1.0 + alpha, -2.0 * cos_w0, 1.0 - alpha)
                }
                FilterType::Notch => {
                    (1.0, -2.0 * cos_w0, 1.0, 1.0 + alpha, -2.0 * cos_w0, 1.0 - alpha)
                }
                FilterType::Peak => {
                    (
                        1.0 + alpha * a_lin,
                        -2.0 * cos_w0,
                        1.0 - alpha * a_lin,
                        1.0 + alpha / a_lin,
                        -2.0 * cos_w0,
                        1.0 - alpha / a_lin,
                    )
                }
                FilterType::LowShelf => {
                    let two_sqrt_a_alpha = 2.0 * a_lin.sqrt() * alpha;
                    (
                        a_lin * ((a_lin + 1.0) - (a_lin - 1.0) * cos_w0 + two_sqrt_a_alpha),
                        2.0 * a_lin * ((a_lin - 1.0) - (a_lin + 1.0) * cos_w0),
                        a_lin * ((a_lin + 1.0) - (a_lin - 1.0) * cos_w0 - two_sqrt_a_alpha),
                        (a_lin + 1.0) + (a_lin - 1.0) * cos_w0 + two_sqrt_a_alpha,
                        -2.0 * ((a_lin - 1.0) + (a_lin + 1.0) * cos_w0),
                        (a_lin + 1.0) + (a_lin - 1.0) * cos_w0 - two_sqrt_a_alpha,
                    )
                }
                FilterType::HighShelf => {
                    let two_sqrt_a_alpha = 2.0 * a_lin.sqrt() * alpha;
                    (
                        a_lin * ((a_lin + 1.0) + (a_lin - 1.0) * cos_w0 + two_sqrt_a_alpha),
                        -2.0 * a_lin * ((a_lin - 1.0) + (a_lin + 1.0) * cos_w0),
                        a_lin * ((a_lin + 1.0) + (a_lin - 1.0) * cos_w0 - two_sqrt_a_alpha),
                        (a_lin + 1.0) - (a_lin - 1.0) * cos_w0 + two_sqrt_a_alpha,
                        2.0 * ((a_lin - 1.0) - (a_lin + 1.0) * cos_w0),
                        (a_lin + 1.0) - (a_lin - 1.0) * cos_w0 - two_sqrt_a_alpha,
                    )
                }
            };

            // Normalize coefficients.
            let b0 = b0 / a0;
            let b1 = b1 / a0;
            let b2 = b2 / a0;
            let a1 = a1 / a0;
            let a2 = a2 / a0;

            let x0 = src[i];
            let y0 = b0 * x0 + b1 * state.x1 + b2 * state.x2
                - a1 * state.y1 - a2 * state.y2;

            state.x2 = state.x1;
            state.x1 = x0;
            state.y2 = state.y1;
            state.y1 = y0;

            dst[i] = y0;
        }
    }
}

// ===========================================================================
// Dynamics
// ===========================================================================

/// Envelope follower. Tracks amplitude of `src` with attack/release smoothing.
///
/// `attack` and `release` are in seconds (per-sample buffers for modulation).
/// Output in `dst` is the smoothed envelope value.
pub fn vec_envelope(
    state: &mut EnvelopeState,
    dst: &mut [f32],
    src: &[f32],
    attack: &[f32],
    release: &[f32],
    mode: EnvelopeMode,
    sample_rate: f32,
) {
    let frames = dst.len().min(src.len()).min(attack.len()).min(release.len());
    if use_host_ops() {
        unsafe {
            sesh_vec_envelope_host(
                state as *mut EnvelopeState as *mut f32,
                dst.as_mut_ptr(), src.as_ptr(),
                attack.as_ptr(), release.as_ptr(),
                mode as u32, sample_rate, frames as u32,
            );
        }
    } else {
        for i in 0..frames {
            let input_level = match mode {
                EnvelopeMode::Peak => src[i].abs(),
                EnvelopeMode::Rms => src[i] * src[i],
            };

            let att_coeff = (-1.0 / (attack[i] * sample_rate)).exp();
            let rel_coeff = (-1.0 / (release[i] * sample_rate)).exp();

            let coeff = if input_level > state.current { att_coeff } else { rel_coeff };
            state.current = coeff * state.current + (1.0 - coeff) * input_level;

            dst[i] = match mode {
                EnvelopeMode::Peak => state.current,
                EnvelopeMode::Rms => state.current.sqrt(),
            };
        }
    }
}

// ===========================================================================
// Waveshaping
// ===========================================================================

/// Soft saturation: `dst[i] = tanh(src[i] * drive[i])`.
pub fn vec_tanh(dst: &mut [f32], src: &[f32], drive: &[f32]) {
    let len = dst.len().min(src.len()).min(drive.len());
    if use_host_ops() {
        unsafe { sesh_vec_tanh_host(dst.as_mut_ptr(), src.as_ptr(), drive.as_ptr(), len as u32) }
    } else {
        for i in 0..len {
            dst[i] = (src[i] * drive[i]).tanh();
        }
    }
}

/// Hard clipping: clamp `src` to `±threshold[i]`.
pub fn vec_hard_clip(dst: &mut [f32], src: &[f32], threshold: &[f32]) {
    let len = dst.len().min(src.len()).min(threshold.len());
    if use_host_ops() {
        unsafe {
            sesh_vec_hard_clip_host(dst.as_mut_ptr(), src.as_ptr(), threshold.as_ptr(), len as u32)
        }
    } else {
        for i in 0..len {
            dst[i] = src[i].clamp(-threshold[i], threshold[i]);
        }
    }
}