one_pole.hpp

Go to the documentation of this file.

// sbl/dsp/one_pole.hpp — Single-pole IIR filter
//
// Classic one-pole lowpass: y[n] = a * x[n] + (1-a) * y[n-1]
//
// Float-native. Coefficient range [0.0, 1.0]: 0 = hold, 1 = passthrough.
// Cold-path set_frequency() computes coefficient from cutoff frequency.
//
// Usage:
//   sbl::dsp::OnePole lp;
//   lp.set_coefficient(0.125f);       // Direct coefficient
//   lp.set_frequency(1000.0f, 48000); // 1 kHz at 48 kHz
//   float y = lp.process(x);          // Single sample
//   lp.process(buf, frames);          // In-place block
 
#pragma once
 
#include <cstdint>
 
namespace sbl::dsp {
 
class OnePole {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /**
     * @brief Set filter coefficient directly
     *
     * a = 0.0 → no filtering (hold previous output), 1.0 → full passthrough.
     * For audio-rate smoothing: ~0.03-0.12. For parameter smoothing: ~0.002-0.008.
     */
    void set_coefficient(float a) { coeff_ = a; }
 
    /**
     * @brief Compute coefficient from cutoff frequency (cold path)
     *
     * Uses approximation of 1 - exp(-2pi * fc / sr).
     *
     * @param freq_hz Cutoff frequency in Hz
     * @param sr Sample rate
     */
    void set_frequency(float freq_hz, uint32_t sr = 48000) {
        float w = 6.2831853f * freq_hz / static_cast<float>(sr);
        if (w >= 1.0f) {
            coeff_ = 1.0f;
        } else {
            // Padé-like: exp(-x) ≈ 1/(1 + x + x²/2 + x³/6)
            float x2 = w * w;
            float denom = 1.0f + w + x2 * 0.5f + x2 * w * 0.166667f;
            coeff_ = 1.0f - 1.0f / denom;
        }
    }
 
    /**
     * @brief Process a single sample
     * @param x Input sample
     * @return Filtered output
     */
    float process(float x) {
        // y = a*x + (1-a)*y = y + a*(x - y)
        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:
    float coeff_ = 0.0f;
    float state_ = 0.0f;
};
 
} // namespace sbl::dsp