critical_damp.hpp

Go to the documentation of this file.

// sbl/dsp/critical_damp.hpp — Critically damped 2nd-order parameter smoother
//
// Two cascaded one-pole filters with identical coefficients, producing a
// second-order system with repeated real poles. This gives:
//
//   - No overshoot (critically damped, ζ = 1)
//   - Zero-velocity arrival (smooth settling, no abrupt stop)
//   - Faster initial response than a single one-pole at the same settling time
//
// The step response is: y[n] = 1 - (1 + a·n)·(1-a)^n
//
// Unlike OnePole, which puts the biggest step at the first sample (exactly
// where clicks live for nonlinear parameters), CriticalDamp distributes
// the change more evenly — the second stage smooths the first stage's
// exponential attack into a gentle S-curve.
//
// Primary use: filter coefficient smoothing inside widgets (SVF, Ladder).
// For simple linear parameters (gain, amplitude), OnePole is sufficient.
//
// Inspired by the Mutable Instruments parameter smoothing approach.
 
#ifndef SBL_DSP_PRIMITIVES_CRITICAL_DAMP_HPP_
#define SBL_DSP_PRIMITIVES_CRITICAL_DAMP_HPP_
 
#include <cstdint>
 
#include <sbl/dsp/math/fast_math.hpp>
 
namespace sbl::dsp::primitives {
 
class CriticalDamp {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /**
     * @brief Set settling time in milliseconds
     * @param ms Time for 95% settling (0 = instant)
     * @param rate_hz Update rate in Hz (e.g., 1000 for block-rate, 48000 for audio-rate)
     *
     * Computes the per-pole coefficient for a two-stage cascade.
     * The combined system reaches 95% of a step change in `ms` milliseconds.
     */
    void set_time_ms(float ms, float rate_hz) {
        if (ms <= 0.0f) {
            coeff_ = 1.0f;
            return;
        }
        float n = ms * rate_hz * 0.001f;
        if (n < 0.5f) {
            coeff_ = 1.0f;
            return;
        }
        // k = 4.6 for 95% settling of cascaded 2nd-order system
        // (vs k = 3.0 for single one-pole)
        // Derived from: (1 + a·N)·(1-a)^N = 0.05
        coeff_ = math::one_minus_exp_neg(4.6f / n);
    }
 
    /**
     * @brief Set coefficient directly (advanced use)
     * @param a Per-pole coefficient [0, 1]
     */
    void set_coefficient(float a) { coeff_ = a; }
 
    /**
     * @brief Process one sample toward target
     * @param target The value to approach
     * @return Smoothed value
     */
    float process(float target) {
        state1_ += coeff_ * (target - state1_);
        state2_ += coeff_ * (state1_ - state2_);
        return state2_;
    }
 
    /**
     * @brief Fill buffer with smoothed trajectory toward target
     * @param buf Output buffer (filled with per-sample smoothed values)
     * @param frames Number of samples
     * @param target Target value
     *
     * Useful for generating per-sample coefficient ramps inside filter widgets.
     */
    void process(float* buf, uint16_t frames, float target) {
        for (uint16_t i = 0; i < frames; ++i) {
            buf[i] = process(target);
        }
    }
 
    /** @brief Current output value */
    float value() const { return state2_; }
 
    /** @brief Current per-pole coefficient */
    float coefficient() const { return coeff_; }
 
    /** @brief Reset to zero */
    void reset() {
        state1_ = 0.0f;
        state2_ = 0.0f;
    }
 
    /** @brief Reset to specific value (both stages) */
    void reset(float val) {
        state1_ = val;
        state2_ = val;
    }
 
private:
    float coeff_ = 0.0f;
    float state1_ = 0.0f;
    float state2_ = 0.0f;
};
 
} // namespace sbl::dsp::primitives
 
#endif // SBL_DSP_PRIMITIVES_CRITICAL_DAMP_HPP_