ladder.hpp

Go to the documentation of this file.

// sbl/dsp/modules/ladder.hpp — Moog-style Ladder Filter (Audio Stack — Modules)
//
// 4-pole (24 dB/oct) resonant lowpass filter modeled on the Moog transistor
// ladder topology. Uses the Huovilainen nonlinear digital model with tanh
// saturation per stage, feedback delay compensation, and 4x internal
// oversampling with 2-stage decimation (pair-average 4→2, Hann 2→1).
//
// The Moog ladder's character comes from three properties:
//   1. Steep 24 dB/oct rolloff — dramatic filter sweeps
//   2. Tanh nonlinearities — warm saturation that depends on input level
//   3. Input-side gain compensation — the feedback topology naturally
//      attenuates passband gain by 1/(1+k); we compensate by driving
//      the input harder (like an analog Moog), and the tanh stages
//      naturally limit the resonant peak — no output clipping possible
//
// The drive parameter controls how hard the input hits the tanh stages.
// Higher drive = more harmonics = fatter, more saturated sound. This is
// how the analog Moog behaves — the saturation is part of the filter,
// not a separate effect.
//
// Self-oscillation: at resonance = 1.0, the filter self-oscillates,
// producing a sine wave at the cutoff frequency. This is the hallmark
// Moog behavior.
//
// 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/drive)
//   and parameter conditioning (CriticalDamp for filter coefficients,
//   OnePole for drive). Applications pass normalized pot/CV values directly.
//
// Reference: Huovilainen, A. (2004). "Non-linear Digital Implementation
// of the Moog Ladder Filter." DAFx-04.
//
// See FDP-032 for design rationale.
//
// Usage:
//   sbl::dsp::modules::Ladder 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_drive_su(0.3f);        // [0,1] → 1.0–4.0 drive
//   filter.process(buf, frames);      // per-sample smoothed coefficients
//
//   // Per-sample modulated filtering (LFO → cutoff):
//   filter.process(buf, n, cv_buf, 3.0f);  // ±3 oct around smoothed center
 
#ifndef SBL_DSP_MODULES_LADDER_HPP_
#define SBL_DSP_MODULES_LADDER_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/primitives/parameter_smoother.hpp>
#include <sbl/dsp/math/exp_mod.hpp>
#include <sbl/dsp/types/fixed.hpp>
#include <sbl/dsp/math/constants.hpp>
 
namespace sbl::dsp::modules {
 
class Ladder {
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)
    static constexpr float kMinDrive = 1.0f;
    static constexpr float kMaxDrive = 4.0f;
 
    // === 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 drive from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linearly mapped to 1.0–4.0 drive
     *
     * First call auto-initializes. Subsequent calls smooth via
     * OnePole (20ms settling).
     */
    void set_drive_su(float su) {
        su = math::clamp01(su);
        float drive = kMinDrive + su * (kMaxDrive - kMinDrive);
        target_drive_ = drive;
        ensure_smoothers();
        if (!drive_init_) {
            op_drive_.reset(drive);
            drive_ = drive;
            drive_init_ = true;
        }
    }
 
    /**
     * @brief Process a block of audio samples in-place (4-pole lowpass)
     *
     * Per-sample CriticalDamp/OnePole smoothing for cutoff, resonance,
     * and drive. 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 drive_target = target_drive_;
        float sr_os = types::SAMPLE_RATE_F * static_cast<float>(OS_FACTOR);
        float s0 = stage_[0], s1 = stage_[1];
        float s2 = stage_[2], s3 = stage_[3];
        float d = delay_;
        float dp = decim_prev_;
 
        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);
            float drive = op_drive_.process(drive_target);
 
            // Apply modulation if provided
            float freq = (cutoff_mod != nullptr)
                ? math::exp_mod(center, cutoff_mod[i], mod_depth,
                                kMinFreqHz, kMaxFreqHz)
                : center;
 
            // Compute Ladder coefficients from smoothed values
            float g = compute_g(freq, sr_os);
            float k = q * 6.0f;
            float gain_comp = 1.0f + k * 0.5f;
            float total_drive = drive * gain_comp;
            if (total_drive > MAX_INPUT_DRIVE) total_drive = MAX_INPUT_DRIVE;
 
            float x = buf[i] * total_drive;
 
            // 4x oversampled with 2-stage decimation (4→2→1).
            float os_out[OS_FACTOR];
            for (int os = 0; os < OS_FACTOR; ++os) {
                float feedback = d * k;
                float input = math::fast_tanhf(x - feedback);
 
                s0 += g * (input - math::fast_tanhf(s0));
                s1 += g * (math::fast_tanhf(s0) - math::fast_tanhf(s1));
                s2 += g * (math::fast_tanhf(s1) - math::fast_tanhf(s2));
                s3 += g * (math::fast_tanhf(s2) - math::fast_tanhf(s3));
 
                d = s3;
                os_out[os] = s3;
            }
 
            // 2-stage: pair average (4→2), then Hann (2→1)
            float half0 = (os_out[0] + os_out[1]) * 0.5f;
            float half1 = (os_out[2] + os_out[3]) * 0.5f;
            buf[i] = 0.25f * dp + 0.5f * half0 + 0.25f * half1;
            dp = half1;
        }
 
        stage_[0] = s0; stage_[1] = s1;
        stage_[2] = s2; stage_[3] = s3;
        delay_ = d;
        decim_prev_ = dp;
 
        // Sync cached coefficients with final smoothed state
        sync_cached_coefficients();
    }
 
    /** @brief Reset filter state (audio state only, not parameter smoothers) */
    void reset() {
        stage_[0] = stage_[1] = stage_[2] = stage_[3] = 0.0f;
        delay_ = 0.0f;
        decim_prev_ = 0.0f;
    }
 
private:
    // Test-only access to engineering-unit setters
    friend struct LadderTestAccess;
 
    /** @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;
    }
 
    /** @brief Set drive — immediate, no smoothing (private) */
    void set_drive(float drive) {
        target_drive_ = drive;
        op_drive_.reset(drive);
        drive_ = drive;
        drive_init_ = true;
    }
 
    void apply_cutoff(float freq_hz) {
        cutoff_hz_ = freq_hz;
        update_g();
    }
 
    void apply_resonance(float q) {
        k_ = q * 6.0f;
        gain_comp_ = 1.0f + k_ * 0.5f;
    }
 
    /// Compute one-pole stage gain from frequency
    static float compute_g(float freq_hz, float sr) {
        float fc = freq_hz / sr;
        if (fc > 0.497f) fc = 0.497f;
        if (fc < 0.0f) fc = 0.0f;
        // Huovilainen stage coefficient: 1 - exp(-2π·fc)
        // Using fast_exp2f: exp(-x) = 2^(-x/ln2)
        constexpr float inv_ln2 = 1.4426950f;  // 1/ln(2)
        return 1.0f - math::fast_exp2f(-math::TWO_PI * fc * inv_ln2);
    }
 
    void update_g() {
        g_ = compute_g(cutoff_hz_, types::SAMPLE_RATE_F * static_cast<float>(OS_FACTOR));
    }
 
    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);
            op_drive_.set_time_ms(20.0f, types::SAMPLE_RATE_F);
            cd_cutoff_.reset(target_freq_hz_);
            cd_resonance_.reset(target_q_);
            op_drive_.reset(target_drive_);
            smoothers_configured_ = true;
            update_g();
        }
    }
 
    void sync_cached_coefficients() {
        float q = cd_resonance_.value();
        k_ = q * 6.0f;
        gain_comp_ = 1.0f + k_ * 0.5f;
        cutoff_hz_ = cd_cutoff_.value();
        drive_ = op_drive_.value();
        update_g();
    }
 
    static constexpr int OS_FACTOR = 4;
    static constexpr float OS_RECIP = 1.0f / static_cast<float>(OS_FACTOR);
    static constexpr float MAX_INPUT_DRIVE = 6.0f;  // Cap total (drive * gain_comp)
 
    float stage_[4] = {};      // One-pole state per stage
    float delay_ = 0.0f;       // Feedback delay (z^-1)
    float g_ = 0.0f;           // Stage coefficient
    float k_ = 0.0f;           // Feedback amount (0-6)
    float gain_comp_ = 1.0f;   // Precomputed resonance gain compensation
    float drive_ = 1.0f;       // Input drive
    float cutoff_hz_ = 1000.0f;
    float decim_prev_ = 0.0f;  // History for 2-stage decimation Hann window
 
    // CriticalDamp smoothers for _su() inputs (FDP-052)
    primitives::CriticalDamp cd_cutoff_;
    primitives::CriticalDamp cd_resonance_;
    primitives::ParameterSmoother op_drive_;
    float target_freq_hz_ = 1000.0f;
    float target_q_ = 0.0f;
    float target_drive_ = 1.0f;
    bool cutoff_init_ = false;
    bool reso_init_ = false;
    bool drive_init_ = false;
    bool smoothers_configured_ = false;
};
 
} // namespace sbl::dsp::modules
 
#endif // SBL_DSP_MODULES_LADDER_HPP_