svf.hpp

Go to the documentation of this file.

// sbl/dsp/widgets/svf.hpp — State Variable Filter (Audio Stack — Widgets)
//
// Zero-delay feedback (ZDF) SVF based on Andrew Simper's topology, as
// documented in Vadim Zavalishin's "The Art of VA Filter Design."
// Reference implementation: Mutable Instruments stmlib/dsp/filter.h (MIT).
//
// Unconditionally stable at all cutoff and resonance settings — no clamping
// needed, no oversampling required. This replaces the previous Chamberlin
// SVF which was unstable at high cutoff + resonance near Nyquist.
//
// Uses float state variables — STM32H7 (Cortex-M7) has hardware FPU with
// single-cycle float ops.
//
// Signal Unit API (FDP-052):
//   Widgets expose normalized [0,1] inputs via _su() methods. The widget
//   owns internal mapping (exp curve for cutoff, linear for resonance) and
//   parameter conditioning (CriticalDamp smoothing — no overshoot, zero-
//   velocity arrival). Applications pass normalized pot/CV values directly.
//
// Usage:
//   sbl::dsp::widgets::Svf filter;
//   filter.set_cutoff_su(0.5f);       // [0,1] → 20–20000 Hz (exp mapped)
//   filter.set_resonance_su(0.7f);    // [0,1] → internally mapped
//   filter.set_mode(FilterMode::LowPass);
//   filter.process(buf, frames);      // per-sample smoothed coefficients
//
// process() with optional modulation parameters provides per-sample exponential
// cutoff modulation from a normalized signal [-1, 1]. Uses exp_mod() internally.
// See FDP-031 for architecture rationale.
 
#ifndef SBL_DSP_WIDGETS_SVF_HPP_
#define SBL_DSP_WIDGETS_SVF_HPP_
 
#include <cstdint>
 
#include <sbl/dsp/primitives/critical_damp.hpp>
#include <sbl/dsp/math/clamp.hpp>
#include <sbl/dsp/math/fast_math.hpp>
#include <sbl/dsp/math/exp_mod.hpp>
#include <sbl/dsp/types/fixed.hpp>
 
namespace sbl::dsp::widgets {
 
enum class FilterMode : uint8_t {
    LowPass,
    HighPass,
    BandPass,
    Notch,
};
 
class Svf {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    // === Frequency range constants (for test helpers) ===
    static constexpr float kMinFreqHz = 20.0f;
    static constexpr float kMaxFreqHz = 20000.0f;
    static constexpr float kCutoffOctaves = 9.965784f;  // log2(20000/20)
 
    // === Signal Unit API (FDP-052) ===
 
    /**
     * @brief Set cutoff frequency from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — exponentially mapped to 20–20000 Hz
     *
     * First call auto-initializes (no ramp from 0). Subsequent calls
     * smooth via CriticalDamp (30ms settling, no overshoot).
     */
    void set_cutoff_su(float su) {
        su = math::clamp01(su);
        float hz = math::su_to_hz(su, kMinFreqHz, kCutoffOctaves);
        target_freq_hz_ = hz;
        ensure_smoothers();
        if (!cutoff_init_) {
            cd_cutoff_.reset(hz);
            apply_cutoff(hz);
            cutoff_init_ = true;
        }
    }
 
    /**
     * @brief Set resonance from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — 0 = flat, 1 = self-oscillation
     *
     * First call auto-initializes. Subsequent calls smooth via
     * CriticalDamp (20ms settling, no overshoot).
     */
    void set_resonance_su(float su) {
        su = math::clamp01(su);
        target_q_ = su;
        ensure_smoothers();
        if (!reso_init_) {
            cd_resonance_.reset(su);
            apply_resonance(su);
            reso_init_ = true;
        }
    }
 
    /**
     * @brief Set resonance compensation strength
     *
     * Controls how much the input signal is attenuated as resonance
     * increases: gain = 1 / (1 + q * k). This prevents the resonant
     * peak from clipping during filter sweeps.
     *
     *   k = 0   No compensation (default)
     *   k = 2   Gentle drop (~33% volume at full resonance)
     *   k = 4   Strong drop (~20% volume at full resonance)
     *
     * @param k Compensation amount (0.0 = off)
     */
    void set_resonance_compensation(float k) {
        comp_k_ = k;
        update_comp_gain();
    }
 
    /** @brief Set filter output mode */
    void set_mode(FilterMode mode) { mode_ = mode; }
 
    /**
     * @brief Process a block of audio samples in-place
     *
     * ZDF SVF with per-sample CriticalDamp coefficient smoothing.
     * When cutoff_mod is provided, exponential modulation is applied
     * around the smoothed cutoff center per-sample.
     *
     * @param buf        Float audio buffer (modified in-place)
     * @param frames     Number of samples
     * @param cutoff_mod Cutoff modulation signal [-1,1] (nullptr = no modulation)
     * @param mod_depth  Modulation depth in octaves (e.g., 2.0 = ±2 octaves)
     */
    void process(float* buf, uint16_t frames,
                 const float* cutoff_mod = nullptr, float mod_depth = 0.0f) {
        ensure_smoothers();
        float freq_target = target_freq_hz_;
        float q_target = target_q_;
        float sr = types::SAMPLE_RATE_F;
        float ck = comp_k_;
        float s1 = state_1_, s2 = state_2_;
 
        for (uint16_t i = 0; i < frames; ++i) {
            // Advance coefficient smoothers
            float center = cd_cutoff_.process(freq_target);
            float q = cd_resonance_.process(q_target);
 
            // Apply modulation if provided
            float freq = (cutoff_mod != nullptr)
                ? math::exp_mod(center, cutoff_mod[i], mod_depth,
                                kMinFreqHz, kMaxFreqHz)
                : center;
 
            // Compute ZDF coefficients
            float f = freq / sr;
            if (f > 0.497f) f = 0.497f;
            float g = math::fast_tan_pif(f);
            float r = (1.0f - q) * 2.0f;
            float h = 1.0f / (1.0f + r * g + g * g);
 
            // Resonance compensation
            float comp = (ck > 0.0f) ? 1.0f / (1.0f + q * ck) : 1.0f;
 
            // ZDF SVF tick
            float x = buf[i] * comp;
            float hp = (x - r * s1 - g * s1 - s2) * h;
            float bp = g * hp + s1;
            s1 = g * hp + bp;
            float lp = g * bp + s2;
            s2 = g * bp + lp;
 
            switch (mode_) {
                case FilterMode::LowPass:  buf[i] = lp; break;
                case FilterMode::HighPass:  buf[i] = hp; break;
                case FilterMode::BandPass:  buf[i] = bp; break;
                case FilterMode::Notch:     buf[i] = lp + hp; break;
                default:                    buf[i] = lp; break;
            }
        }
        state_1_ = s1;
        state_2_ = s2;
 
        // Sync cached coefficients with final smoothed state
        sync_cached_coefficients();
    }
 
    /** @brief Reset filter state (audio state only, not parameter smoothers) */
    void reset() {
        state_1_ = 0.0f;
        state_2_ = 0.0f;
    }
 
private:
    // Test-only access to engineering-unit setters
    friend struct SvfTestAccess;
 
    /** @brief Set cutoff in Hz — immediate, no smoothing (private) */
    void set_cutoff(float freq_hz) {
        target_freq_hz_ = freq_hz;
        cd_cutoff_.reset(freq_hz);
        apply_cutoff(freq_hz);
        cutoff_init_ = true;
    }
 
    /** @brief Set resonance 0–1 — immediate, no smoothing (private) */
    void set_resonance(float q) {
        target_q_ = q;
        cd_resonance_.reset(q);
        apply_resonance(q);
        reso_init_ = true;
    }
 
    void apply_cutoff(float freq_hz) {
        float f = freq_hz / types::SAMPLE_RATE_F;
        if (f > 0.497f) f = 0.497f;
        g_ = math::fast_tan_pif(f);
        h_ = 1.0f / (1.0f + r_ * g_ + g_ * g_);
    }
 
    void apply_resonance(float q) {
        q_ = q;
        r_ = (1.0f - q) * 2.0f;
        h_ = 1.0f / (1.0f + r_ * g_ + g_ * g_);
        update_comp_gain();
    }
 
    void update_comp_gain() {
        comp_gain_ = (comp_k_ > 0.0f)
            ? 1.0f / (1.0f + q_ * comp_k_)
            : 1.0f;
    }
 
    void ensure_smoothers() {
        if (!smoothers_configured_) {
            cd_cutoff_.set_time_ms(30.0f, types::SAMPLE_RATE_F);
            cd_resonance_.set_time_ms(20.0f, types::SAMPLE_RATE_F);
            cd_cutoff_.reset(target_freq_hz_);
            cd_resonance_.reset(target_q_);
            smoothers_configured_ = true;
        }
    }
 
    void sync_cached_coefficients() {
        q_ = cd_resonance_.value();
        r_ = (1.0f - q_) * 2.0f;
        float f = cd_cutoff_.value() / types::SAMPLE_RATE_F;
        if (f > 0.497f) f = 0.497f;
        g_ = math::fast_tan_pif(f);
        h_ = 1.0f / (1.0f + r_ * g_ + g_ * g_);
        comp_gain_ = (comp_k_ > 0.0f) ? 1.0f / (1.0f + q_ * comp_k_) : 1.0f;
    }
 
    // ZDF coefficients (cached for modulated process fallback)
    float g_ = 0.0f;         // tan(π·f) — frequency coefficient
    float r_ = 1.0f;         // Damping (2.0 = flat, 0.0 = self-oscillation)
    float h_ = 0.0f;         // 1 / (1 + r·g + g²)
    float q_ = 0.0f;         // Resonance (0.0–1.0), cached for compensation
    float comp_k_ = 0.0f;    // Compensation strength (0 = off)
    float comp_gain_ = 1.0f; // Precomputed: 1 / (1 + q * k)
    float state_1_ = 0.0f;
    float state_2_ = 0.0f;
    FilterMode mode_ = FilterMode::LowPass;
 
    // CriticalDamp smoothers for _su() inputs (FDP-052)
    primitives::CriticalDamp cd_cutoff_;
    primitives::CriticalDamp cd_resonance_;
    float target_freq_hz_ = 0.0f;
    float target_q_ = 0.0f;
    bool cutoff_init_ = false;
    bool reso_init_ = false;
    bool smoothers_configured_ = false;
};
 
} // namespace sbl::dsp::widgets
 
#endif // SBL_DSP_WIDGETS_SVF_HPP_