ladder_filter.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/signal/denormal.hpp>
#include <pulp/signal/fast_math.hpp>
 
#include <cmath>
#include <cstddef>
#include <algorithm>
#include <type_traits>
 
namespace pulp::signal {
 
// Nonlinear ladder filter (4-pole, 24 dB/octave)
// Non-linear, self-oscillating at high resonance.
//
// RT contract: setters, process paths, and reset are scalar/fixed-array only
// and allocate no memory.
//
// One voice is bound by the latency of its serial stage chain, so separate
// instances in a voice loop are fast only when the compiler happens to
// vectorize across them (it may not without FMA contraction). For many voices
// in lockstep, LadderBankT runs them as explicit SIMD lanes with identical
// output.
template <typename SampleType = float>
class LadderFilterT {
public:
    void set_sample_rate(SampleType sr) { sample_rate_ = sr; }
    void set_frequency(SampleType hz) { cutoff_ = hz; update(); }
    void set_resonance(SampleType r) {
        resonance_ = std::clamp(r, SampleType{0.0f}, SampleType{1.0f});
        update();
    }

    SampleType process(SampleType input) {
        return process_with_profile<kDefaultLadderSaturation>(input);
    }

    SampleType process_reference(SampleType input) {
        return process_with_profile<LadderSaturation::exact>(input);
    }

    SampleType process_realtime_efficient(SampleType input) {
        return process_with_profile<LadderSaturation::realtime_efficient>(input);
    }

    void process(SampleType* buffer, int num_samples) {
        for (int i = 0; i < num_samples; ++i)
            buffer[i] = process(buffer[i]);
    }

    void process_reference(SampleType* buffer, std::size_t num_samples) {
        for (std::size_t i = 0; i < num_samples; ++i)
            buffer[i] = process_reference(buffer[i]);
    }

    void process_realtime_efficient(SampleType* buffer, std::size_t num_samples) {
        for (std::size_t i = 0; i < num_samples; ++i)
            buffer[i] = process_realtime_efficient(buffer[i]);
    }
 
    void reset() {
        for (auto& s : stage_) s = 0;
        for (auto& s : saturated_stage_) s = 0;
    }

    static SampleType stage_coefficient(SampleType cutoff_hz, SampleType sample_rate) {
        return SampleType{1.0f} -
               std::exp(SampleType{-2.0f} * SampleType{3.14159265f} * cutoff_hz / sample_rate);
    }

    template <LadderSaturation Saturation> static SampleType saturate(SampleType x) {
        if constexpr (std::is_same_v<SampleType, float>)
            return ladder_tanh_profiled<Saturation>(x);
        else
            return std::tanh(x);
    }
 
  private:
    template <LadderSaturation Saturation> SampleType process_with_profile(SampleType input) {
        // Non-linear feedback
        SampleType feedback =
            resonance_ * SampleType{4.0f} * (stage_[3] - input * SampleType{0.5f});
        SampleType x = input - feedback;
 
        // Cache each snapped stage's saturation. The next stage and next sample
        // reuse exactly that value, avoiding repeated transcendental calls.
        SampleType saturated_prev = saturate<Saturation>(x);
        for (int i = 0; i < 4; ++i) {
            // Snap each ladder stage: at high resonance the stages self-
            // oscillate and their tails otherwise decay into denormals with
            // no FTZ guard. No-op above 1e-15.
            stage_[i] = snap_to_zero(
                stage_[i] + g_ * (saturated_prev - saturated_stage_[i]));
            saturated_stage_[i] = saturate<Saturation>(stage_[i]);
            saturated_prev = saturated_stage_[i];
        }
 
        return stage_[3];
    }
 
    SampleType sample_rate_ = SampleType{44100.0f};
    SampleType cutoff_ = SampleType{1000.0f};
    SampleType resonance_ = SampleType{0.0f};
    SampleType g_ = 0;
    SampleType stage_[4] = {};
    SampleType saturated_stage_[4] = {};
 
    void update() {
        g_ = stage_coefficient(cutoff_, sample_rate_);
    }
};
 
using LadderFilter = LadderFilterT<float>;
using LadderFilter64 = LadderFilterT<double>;
 
} // namespace pulp::signal