one_pole.hpp

Go to the documentation of this file.

// sbl/dsp/one_pole.hpp — Single-pole IIR filters (LP and HP)
//
// OnePole (LP):  y[n] = a * x[n] + (1-a) * y[n-1]
// OnePoleHP:     y[n] = x[n] - lp(x[n])  (complement of LP)
//
// Signal processors — cutoff is controlled by a signal (_su).
// Configure frequency range and sample rate, then drive cutoff via
// set_cutoff_su(). Engineering-unit setter is private (TestAccess).
//
// For parameter smoothing (settling time, not frequency), use ParameterSmoother.
//
// Usage:
//   sbl::dsp::OnePole lp;
//   lp.set_range(200.0f, 8000.0f);    // [0,1] maps to this Hz range
//   lp.set_cutoff_su(0.5f);           // → geometric midpoint ~1265 Hz
//   float y = lp.process(x);
//
//   sbl::dsp::OnePoleHP hp;
//   hp.set_range(20.0f, 500.0f);
//   hp.set_cutoff_su(0.3f);
//   float y = hp.process(x);
 
#ifndef SBL_DSP_PRIMITIVES_ONE_POLE_HPP_
#define SBL_DSP_PRIMITIVES_ONE_POLE_HPP_
 
#include <cmath>
#include <cstdint>
 
#include <sbl/dsp/types/fixed.hpp>
#include <sbl/dsp/math/clamp.hpp>
#include <sbl/dsp/math/constants.hpp>
#include <sbl/dsp/math/fast_math.hpp>
 
namespace sbl::dsp::primitives {
 
struct OnePoleTestAccess;
 
class OnePole {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /**
     * @brief Set frequency range for _su mapping (configuration, not a signal)
     *
     * Defines the Hz range that [0, 1] maps to exponentially.
     * Default range is 20–20000 Hz.
     *
     * @param min_hz Frequency at su = 0.0
     * @param max_hz Frequency at su = 1.0
     */
    void set_range(float min_hz, float max_hz) {
        min_hz_ = min_hz;
        octaves_ = std::log2(max_hz / min_hz);
    }
 
    /**
     * @brief Set cutoff frequency via signal unit
     *
     * Maps [0, 1] exponentially across the configured frequency range.
     * su = 0.0 → min_hz, su = 1.0 → max_hz.
     *
     * @param su Unipolar signal [0, 1]
     */
    void set_cutoff_su(float su) {
        set_frequency(math::su_to_hz(math::clamp01(su), min_hz_, octaves_));
    }
 
    /**
     * @brief Set filter coefficient directly
     *
     * a = 0.0 → no filtering (hold previous output), 1.0 → full passthrough.
     */
    void set_coefficient(float a) { coeff_ = a; }
 
    /**
     * @brief Process a single sample
     * @param x Input sample
     * @return Filtered output
     */
    float process(float x) {
        state_ += coeff_ * (x - state_);
        return state_;
    }
 
    /**
     * @brief Process a block of samples in-place
     * @param buf Audio buffer (modified in-place)
     * @param frames Number of samples
     */
    void process(float* buf, uint16_t frames) {
        for (uint16_t i = 0; i < frames; ++i) {
            buf[i] = process(buf[i]);
        }
    }
 
    /** @brief Current filter state (last output) */
    float value() const { return state_; }
 
    /** @brief Current coefficient */
    float coefficient() const { return coeff_; }
 
    /** @brief Reset filter state to zero */
    void reset() { state_ = 0.0f; }
 
    /** @brief Reset filter state to a specific value */
    void reset(float initial) { state_ = initial; }
 
private:
    friend struct OnePoleTestAccess;
 
    /**
     * @brief Compute coefficient from cutoff frequency (internal)
     * @param freq_hz Cutoff frequency in Hz
     */
    void set_frequency(float freq_hz) {
        coeff_ = math::one_minus_exp_neg(math::TWO_PI * freq_hz / types::SAMPLE_RATE_F);
    }
 
    float coeff_ = 0.0f;
    float state_ = 0.0f;
    float min_hz_ = 20.0f;
    float octaves_ = 9.965784f;   ///< log2(20000 / 20)
};
 
/**
 * @brief Test access for OnePole engineering-unit API
 */
struct OnePoleTestAccess {
    static void set_frequency(OnePole& f, float hz) {
        f.set_frequency(hz);
    }
};
 
struct OnePoleHPTestAccess;
 
/**
 * @brief One-pole highpass filter (complement of OnePole LP)
 *
 * Computed as hp = x - lp(x). Same coefficient math as OnePole.
 * Cutoff is controlled by a signal via set_cutoff_su().
 */
class OnePoleHP {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    void set_range(float min_hz, float max_hz) { lp_.set_range(min_hz, max_hz); }
    void set_cutoff_su(float su) { lp_.set_cutoff_su(su); }
    void set_coefficient(float a) { lp_.set_coefficient(a); }
 
    float process(float x) {
        return x - lp_.process(x);
    }
 
    void process(float* buf, uint16_t frames) {
        for (uint16_t i = 0; i < frames; ++i) {
            buf[i] = process(buf[i]);
        }
    }
 
    float coefficient() const { return lp_.coefficient(); }
    void reset() { lp_.reset(); }
    void reset(float initial) { lp_.reset(initial); }
 
private:
    friend struct OnePoleHPTestAccess;
    OnePole lp_;
};
 
/**
 * @brief Test access for OnePoleHP engineering-unit API
 */
struct OnePoleHPTestAccess {
    static void set_frequency(OnePoleHP& f, float hz) {
        OnePoleTestAccess::set_frequency(f.lp_, hz);
    }
};
 
} // namespace sbl::dsp::primitives
 
#endif // SBL_DSP_PRIMITIVES_ONE_POLE_HPP_