phaser_stages.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/signal/denormal.hpp>
#include <pulp/signal/lfo.hpp>
#include <pulp/signal/tpt_filter.hpp>
 
#include <algorithm>
#include <array>
#include <cmath>
#include <cstdint>
 
namespace pulp::signal {

template <typename SampleType = float>
class PhaserStagesT {
public:
    using Wave = LfoWave;
 
    // ── Calibration constants (the table in the file doc block) ────────────

    static constexpr int kMinStages = 4;
    static constexpr int kMaxStages = 12;
    static constexpr int kStageCountDefault = 4;

    static constexpr double kFeedbackMax = 0.9;
    static constexpr double kColorOffFeedback = 0.0;
    static constexpr double kColorOnFeedback = 0.65;

    static constexpr double kSweepRangeRatio = 1.0;

    static constexpr double kSweepFloorHz = 20.0;

    static constexpr double kSweepCeilingRatio = 0.45;

    static constexpr double kStaggerDefault = 1.0;
    static constexpr double kStaggerMin = 0.85;
    static constexpr double kStaggerMax = 1.15;

    static constexpr double kMixDefault = 0.5;

    static constexpr double kRateDefaultHz = 0.5;
 
    // ── Notch laws (shipped, so tests compute expectations from them) ──────

    static constexpr double kPi = 3.14159265358979323846;

    static double notch_frequency_analog_hz(int k, int stages, double fc_hz) {
        return fc_hz * std::tan(odd_phase_fraction(k, stages));
    }

    static double notch_frequency_hz(int k, int stages, double fc_hz,
                                     double sample_rate) {
        const double prewarped = std::tan(kPi * fc_hz / sample_rate);
        return sample_rate / kPi *
               std::atan(prewarped * std::tan(odd_phase_fraction(k, stages)));
    }

    static constexpr int notch_count(int stages) { return stages / 2; }

    static constexpr double worst_case_gain() {
        return 1.0 / (1.0 - kFeedbackMax);
    }

    static constexpr int latency_samples() { return 0; }
 
    // ── Lifecycle ─────────────────────────────────────────────────────────

    PhaserStagesT() {
        set_stagger_ratio(kStaggerDefault);
        set_wave(Wave::triangle);
        set_rate_hz(kRateDefaultHz);
        prepare(44100.0);
    }

    void prepare(double sample_rate) {
        if (sample_rate > 0.0) sample_rate_ = sample_rate;
        for (auto& channel : stages_)
            for (auto& stage : channel)
                stage.prepare(static_cast<SampleType>(sample_rate_));
        for (auto& lfo : lfo_) lfo.prepare(sample_rate_);
        reset();
    }

    void reset() {
        for (auto& channel : stages_)
            for (auto& stage : channel) stage.reset();
        feedback_state_.fill(SampleType{0});
        for (auto& lfo : lfo_) lfo.reset();
        for (int ch = 0; ch < kChannels; ++ch) sweep_hz_[ch] = center_hz_;
    }
 
    // ── Parameters ────────────────────────────────────────────────────────

    void set_stage_count(int n) {
        const int clamped = std::clamp(n, kMinStages, kMaxStages);
        stage_count_ = clamped - (clamped % 2);
    }
    int stage_count() const { return stage_count_; }

    void set_rate_hz(double hz) {
        if (!std::isfinite(hz)) return;
        for (auto& lfo : lfo_) lfo.set_rate_hz(hz);
    }
    double rate_hz() const { return lfo_[0].rate_hz(); }

    void set_depth(float depth01) {
        if (!std::isfinite(static_cast<double>(depth01))) return;
        depth_ = std::clamp(static_cast<double>(depth01), 0.0, 1.0);
    }
    double depth() const { return depth_; }

    void set_center_hz(double fc) {
        if (!std::isfinite(fc)) return;
        center_hz_ = clamp_hz(fc);
    }
    double center_hz() const { return center_hz_; }

    void set_feedback(float fb) {
        if (!std::isfinite(static_cast<double>(fb))) return;
        feedback_ = std::clamp(static_cast<double>(fb), -kFeedbackMax,
                               kFeedbackMax);
    }
    double feedback() const { return feedback_; }

    void set_mix(float mix01) {
        if (!std::isfinite(static_cast<double>(mix01))) return;
        mix_ = std::clamp(static_cast<double>(mix01), 0.0, 1.0);
    }
    double mix() const { return mix_; }

    void set_stereo_spread(float cycles01) {
        if (!std::isfinite(static_cast<double>(cycles01))) return;
        spread_ = std::clamp(static_cast<double>(cycles01), 0.0, 0.5);
        lfo_[1].set_stereo_offset(spread_);
    }
    double stereo_spread() const { return spread_; }

    void set_wave(Wave wave) {
        for (auto& lfo : lfo_) lfo.set_wave(wave);
    }
    Wave wave() const { return lfo_[0].wave(); }

    void set_stagger_ratio(double ratio) {
        if (!std::isfinite(ratio)) return;
        stagger_ = std::clamp(ratio, kStaggerMin, kStaggerMax);
        double p = 1.0;
        for (int i = 0; i < kMaxStages; ++i) {
            stagger_pow_[static_cast<std::size_t>(i)] = p;
            p *= stagger_;
        }
    }
    double stagger_ratio() const { return stagger_; }

    void set_seed(std::uint32_t seed) {
        for (auto& lfo : lfo_) lfo.set_seed(seed);
    }

    double sweep_frequency_hz(int channel) const {
        return sweep_hz_[static_cast<std::size_t>(
            std::clamp(channel, 0, kChannels - 1))];
    }
 
    // ── Processing ────────────────────────────────────────────────────────

    void process(const SampleType* in_l, const SampleType* in_r,
                 SampleType* out_l, SampleType* out_r, int n_frames) {
        const double dry = 1.0 - mix_;
        for (int i = 0; i < n_frames; ++i) {
            const SampleType xl = in_l[i];
            const SampleType xr = in_r[i];
            if (!std::isfinite(static_cast<double>(xl)) ||
                !std::isfinite(static_cast<double>(xr))) {
                reset();
                out_l[i] = out_r[i] = SampleType{0};
                continue;
            }
            const double wl = run_cascade(0, advance_sweep(0), xl);
            const double wr = run_cascade(1, advance_sweep(1), xr);
            out_l[i] = static_cast<SampleType>(dry * static_cast<double>(xl) +
                                               mix_ * wl);
            out_r[i] = static_cast<SampleType>(dry * static_cast<double>(xr) +
                                               mix_ * wr);
        }
    }

    void process_mono(const SampleType* in, SampleType* out, int n_frames) {
        const double dry = 1.0 - mix_;
        for (int i = 0; i < n_frames; ++i) {
            const SampleType x = in[i];
            if (!std::isfinite(static_cast<double>(x))) {
                reset();
                out[i] = SampleType{0};
                continue;
            }
            const double w = run_cascade(0, advance_sweep(0), x);
            advance_sweep(1);
            out[i] = static_cast<SampleType>(dry * static_cast<double>(x) +
                                             mix_ * w);
        }
    }
 
private:
    static constexpr int kChannels = 2;

    static double odd_phase_fraction(int k, int stages) {
        return static_cast<double>(2 * k - 1) * kPi /
               (2.0 * static_cast<double>(stages));
    }
 
    double clamp_hz(double hz) const {
        return std::clamp(hz, kSweepFloorHz, kSweepCeilingRatio * sample_rate_);
    }

    double advance_sweep(int ch) {
        const auto c = static_cast<std::size_t>(ch);
        const double lfo = static_cast<double>(lfo_[c].next());
        const double fc =
            clamp_hz(center_hz_ * (1.0 + depth_ * kSweepRangeRatio * lfo));
        sweep_hz_[c] = fc;
        return fc;
    }

    double run_cascade(int ch, double fc, SampleType x) {
        const auto c = static_cast<std::size_t>(ch);
        auto& stages = stages_[c];
        SampleType v = static_cast<SampleType>(
            static_cast<double>(x) +
            feedback_ * static_cast<double>(feedback_state_[c]));
        for (int i = 0; i < stage_count_; ++i) {
            const auto s = static_cast<std::size_t>(i);
            stages[s].set_cutoff(
                static_cast<SampleType>(clamp_hz(fc * stagger_pow_[s])));
            v = stages[s].process_allpass(v);
        }
        feedback_state_[c] = snap_to_zero(v);
        return static_cast<double>(v);
    }
 
    double sample_rate_ = 44100.0;
    double center_hz_ = 400.0;
    double depth_ = 1.0;
    double feedback_ = kColorOffFeedback;
    double mix_ = kMixDefault;
    double spread_ = 0.0;
    double stagger_ = kStaggerDefault;
    int stage_count_ = kStageCountDefault;
 
    std::array<double, kMaxStages> stagger_pow_{};
    std::array<double, kChannels> sweep_hz_{};
    std::array<SampleType, kChannels> feedback_state_{};
    std::array<std::array<TptFilterT<SampleType>, kMaxStages>, kChannels>
        stages_{};
    std::array<EffectLfoT<double>, kChannels> lfo_{};
};
 
using PhaserStages = PhaserStagesT<float>;
using PhaserStages64 = PhaserStagesT<double>;
 
}  // namespace pulp::signal