lfo.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/signal/lfo_sampling.hpp>
#include <pulp/signal/mod_tools.hpp>
#include <pulp/signal/rng.hpp>
 
#include <algorithm>
#include <cmath>
#include <cstdint>
 
namespace pulp::signal {

// `LfoWave`, the effect-wave vocabulary, lives with the stateless sampling
// functions (`lfo_wave`, `lfo_wave_mean`, `lfo_wave_bandlimited`) that share
// it; this header carries the stateful oscillator built on them.
 
namespace detail {

enum class LfoConvention : std::uint8_t { toolkit, effect };

template <typename SampleType, LfoConvention Convention>
class BasicLfoT {
public:
    static constexpr bool kEffectConvention = Convention == LfoConvention::effect;
 
    enum class Wave : std::uint8_t {
        sine,
        triangle,
        saw_up,
        saw_down,
        square,
        sh_random,
        smooth_random,
    };

    enum class Mode : std::uint8_t { free, retrig, one_shot };
 
    enum class FadeCurve : std::uint8_t { linear, quadratic };
 
    enum class Stage : std::uint8_t { delay, fade_in, sustain, fade_out, done };

    static constexpr double kMinRateHz = 0.001;

    static constexpr double kMaxRateFraction = 0.45;

    static constexpr double kMaxRateHz = 200.0;

    static constexpr int kDefaultRandomSegments = 4;
 
    static constexpr int kMaxRandomSegments = 16;

    static constexpr int kMaxRepeatCount = 128;
 
    // ── lifecycle ────────────────────────────────────────────────────────────
 
    void prepare(double sample_rate) {
        sample_rate_ = sample_rate > 0.0 ? sample_rate : 1.0;
        update_increment_();
        update_stage_lengths_();
        reset();
    }

    void reset() {
        phase_ = 0.0;
        cycles_ = 0;
        seed_chains_();
        restart_lifecycle_();
    }

    void retrigger() {
        if (mode_ == Mode::free) return;
        phase_ = 0.0;
        cycles_ = 0;
        restart_lifecycle_();
    }
 
    // ── rate ─────────────────────────────────────────────────────────────────

    void set_rate_hz(double hz) {
        requested_rate_hz_ = hz;
        update_increment_();
    }

    void set_period_samples(double samples) {
        const double min_period = 1.0 / kMaxRateFraction;
        increment_ = 1.0 / std::max(samples, min_period);
        rate_hz_ = increment_ * sample_rate_;
        requested_rate_hz_ = rate_hz_;
    }
 
    double rate_hz() const { return rate_hz_; }
    double period_samples() const { return increment_ > 0.0 ? 1.0 / increment_ : 0.0; }
 
    // ── shape ────────────────────────────────────────────────────────────────
 
    void set_wave(Wave w) requires (!kEffectConvention) {
        wave_ = w;
        update_increment_();
    }
    void set_wave(LfoWave w) requires kEffectConvention {
        morph_enabled_ = false;
        switch (w) {
            case LfoWave::sine: wave_ = Wave::sine; break;
            case LfoWave::triangle: wave_ = Wave::triangle; break;
            case LfoWave::saw_up: wave_ = Wave::saw_up; break;
            case LfoWave::saw_down: wave_ = Wave::saw_down; break;
            case LfoWave::square: wave_ = Wave::square; break;
            case LfoWave::sample_hold: wave_ = Wave::sh_random; break;
            case LfoWave::smooth_random: wave_ = Wave::smooth_random; break;
        }
        update_increment_();
    }
    Wave wave() const requires (!kEffectConvention) { return wave_; }
    LfoWave wave() const requires kEffectConvention {
        switch (wave_) {
            case Wave::sine: return LfoWave::sine;
            case Wave::triangle: return LfoWave::triangle;
            case Wave::saw_up: return LfoWave::saw_up;
            case Wave::saw_down: return LfoWave::saw_down;
            case Wave::square: return LfoWave::square;
            case Wave::sh_random: return LfoWave::sample_hold;
            case Wave::smooth_random: return LfoWave::smooth_random;
        }
        return LfoWave::sine;
    }

    void set_shape_morph(float m) {
        shape_morph_ = std::clamp(m, 0.0f, 3.0f);
        morph_enabled_ = true;
    }
 
    void set_shape_morph_enabled(bool on) { morph_enabled_ = on; }
    bool shape_morph_enabled() const { return morph_enabled_; }

    void set_pulse_width(float pw) { pulse_width_ = std::clamp(pw, 0.05f, 0.95f); }

    void set_tri_bias(float b) { tri_bias_ = std::clamp(b, -1.0f, 1.0f); }

    void set_random_blend(float b) { random_blend_ = std::clamp(b, 0.0f, 1.0f); }

    void set_random_segments(int n) { segments_ = std::clamp(n, 1, kMaxRandomSegments); }

    void set_seed(std::uint32_t s) {
        seed_ = s;
        if constexpr (kEffectConvention) reset();
    }
 
    // ── phase & stereo ───────────────────────────────────────────────────────

    void set_phase_offset(double cycles01) { phase_offset_ = wrap01(cycles01); }

    void set_stereo_offset(double cycles01) {
        if constexpr (kEffectConvention)
            phase_offset_ = wrap01(cycles01);
        else
            stereo_offset_ = wrap01(cycles01);
    }
 
    // ── lifecycle shaping ────────────────────────────────────────────────────

    void set_delay_ms(double ms) {
        delay_ms_ = std::clamp(ms, 0.0, 120000.0);
        update_stage_lengths_();
        restart_if_idle_();
    }

    void set_fade_in_ms(double ms) {
        fade_in_ms_ = std::clamp(ms, 0.0, 120000.0);
        update_stage_lengths_();
        restart_if_idle_();
    }

    void set_fade_out_ms(double ms, bool enabled) {
        fade_out_ms_ = std::clamp(ms, 0.0, 120000.0);
        fade_out_enabled_ = enabled;
        update_stage_lengths_();
    }
 
    void set_fade_curve(FadeCurve c) { fade_curve_ = c; }

    void set_repeat_count(int n) { repeat_count_ = std::clamp(n, 0, kMaxRepeatCount); }
 
    void set_mode(Mode m) { mode_ = m; }
    Mode mode() const { return mode_; }
 
    // ── sampling without aliasing ────────────────────────────────────────────

    void set_band_limited(bool on)
        requires(!kEffectConvention)
    {
        band_limited_ = on;
    }
    bool band_limited() const
        requires(!kEffectConvention)
    {
        return band_limited_;
    }

    SampleType next_mean(int samples)
        requires(!kEffectConvention)
    {
        if (samples <= 0) {
            const double p = wrap01(phase_ + static_cast<double>(phase_offset_));
            update_chain_(chains_[0], p);
            return static_cast<SampleType>(envelope_() * shape_(p, chains_[0]));
        }
        const double span = static_cast<double>(samples) * increment_;
        const bool deterministic =
            random_blend_ <= 0.0f && wave_ != Wave::sh_random && wave_ != Wave::smooth_random;
        const int limit = effective_repeat_();
        const bool ends_this_block =
            limit > 0 && cycles_ + static_cast<long long>(std::floor(phase_ + span)) >= limit;
        if (stage_ != Stage::sustain || !deterministic || ends_this_block) {
            double acc = 0.0;
            for (int i = 0; i < samples; ++i)
                acc += static_cast<double>(next());
            return static_cast<SampleType>(acc / static_cast<double>(samples));
        }
        // Each output sample stands for the half-sample on either side of its
        // phase, so the mean of the next N outputs is the integral from half a
        // step before the first to half a step before the one after the last.
        const double p = wrap01(phase_ + static_cast<double>(phase_offset_)) - 0.5 * increment_;
        const float env = envelope_();
        const double mean =
            morph_enabled_ ? morph_mean_(p, p + span) : wave_mean_(wave_, p, p + span);
        phase_ += span;
        if (phase_ >= 1.0) {
            const double whole = std::floor(phase_);
            phase_ -= whole;
            cycles_ += static_cast<long long>(whole);
            on_cycles_completed_();
        }
        return static_cast<SampleType>(static_cast<double>(env) * mean);
    }
 
    Stage stage() const { return stage_; }
    bool finished() const { return stage_ == Stage::done; }
    long long cycles_completed() const { return cycles_; }
    double phase() const {
        if constexpr (kEffectConvention)
            return wrap01(phase_ + static_cast<double>(phase_offset_));
        return phase_;
    }
 
    // ── output ───────────────────────────────────────────────────────────────

    SampleType next() {
        if constexpr (kEffectConvention) advance_();
        const float env = envelope_();
        const double p = wrap01(phase_ + static_cast<double>(phase_offset_));
        update_chain_(chains_[0], p);
        if constexpr (kEffectConvention)
            return static_cast<SampleType>(static_cast<double>(env)
                                           * legacy_effect_shape_(p, chains_[0]));
        const float value = shape_(p, chains_[0]);
        advance_();
        return static_cast<SampleType>(env * value);
    }

    SampleType next_unipolar() { return static_cast<SampleType>(bi_to_uni(static_cast<float>(next()))); }

    void next_stereo(SampleType& left, SampleType& right) {
        const float env = envelope_();
        const double pl = wrap01(phase_ + static_cast<double>(phase_offset_));
        update_chain_(chains_[0], pl);
        const float l = shape_(pl, chains_[0]);
        float r = l;
        if (stereo_offset_ != 0.0f) {
            const double pr = wrap01(pl + static_cast<double>(stereo_offset_));
            update_chain_(chains_[1], pr);
            r = shape_(pr, chains_[1]);
        }
        left = static_cast<SampleType>(env * l);
        right = static_cast<SampleType>(env * r);
        advance_();
    }

    void next_quadrature(SampleType& sine_out, SampleType& cosine_out) {
        if constexpr (kEffectConvention) advance_();
        const float env = envelope_();
        const double p = wrap01(phase_ + static_cast<double>(phase_offset_));
        update_chain_(chains_[0], p);
        const double angle = 6.283185307179586477 * p;
        if constexpr (kEffectConvention) {
            sine_out = static_cast<SampleType>(static_cast<double>(env) * std::sin(angle));
            cosine_out = static_cast<SampleType>(static_cast<double>(env) * std::cos(angle));
            return;
        }
        sine_out = static_cast<SampleType>(env * static_cast<float>(std::sin(angle)));
        cosine_out = static_cast<SampleType>(env * static_cast<float>(std::cos(angle)));
        advance_();
    }
 
private:
    struct RandomChain {
        Xorshift32 rng{};
        float sh = 0.0f;
        float glide_prev = 0.0f;
        float glide_next = 0.0f;
        float seg_frac = 0.0f;
        int seg_index = -1;
        float prev_phase = 2.0f;
        bool primed = false;
 
        float smooth() const {
            const float w = 0.5f - 0.5f * std::cos(3.14159265358979324f * seg_frac);
            return glide_prev + (glide_next - glide_prev) * w;
        }
    };
 
    static double wrap01(double x) { return x - std::floor(x); }
    static float wrap01(float x) { return x - std::floor(x); }
 
    void update_increment_() {
        const double max_rate = kEffectConvention
                                    ? kMaxRateHz
                                    : kMaxRateFraction * sample_rate_;
        const double min_rate = kEffectConvention ? 0.0 : kMinRateHz;
        rate_hz_ = std::clamp(requested_rate_hz_, min_rate,
                              std::max(min_rate, max_rate));
        increment_ = rate_hz_ / sample_rate_;
    }
 
    void update_stage_lengths_() {
        delay_samples_ = static_cast<long long>(std::lround(delay_ms_ * 0.001 * sample_rate_));
        fade_in_samples_ = static_cast<long long>(std::lround(fade_in_ms_ * 0.001 * sample_rate_));
        fade_out_samples_ = static_cast<long long>(std::lround(fade_out_ms_ * 0.001 * sample_rate_));
    }
 
    void seed_chains_() {
        chains_[0] = RandomChain{};
        chains_[1] = RandomChain{};
        chains_[0].rng.seed(static_cast<std::uint32_t>(mix64(seed_) & 0xFFFFFFFFu));
        chains_[1].rng.seed(static_cast<std::uint32_t>(mix64(seed_ ^ 0x5DEECE66Du) >> 32));
    }
 
    void restart_lifecycle_() {
        stage_pos_ = 0;
        fade_out_start_ = 1.0f;
        if (delay_samples_ > 0) stage_ = Stage::delay;
        else if (fade_in_samples_ > 0) stage_ = Stage::fade_in;
        else stage_ = Stage::sustain;
    }

    void restart_if_idle_() {
        if (stage_pos_ == 0 && cycles_ == 0 && phase_ == 0.0) restart_lifecycle_();
    }
 
    int effective_repeat_() const {
        if (mode_ == Mode::one_shot && repeat_count_ == 0) return 1;
        return repeat_count_;
    }
 
    float fade_shape_(float t) const {
        const float c = std::clamp(t, 0.0f, 1.0f);
        return fade_curve_ == FadeCurve::quadratic ? c * c : c;
    }
 
    float envelope_() const {
        switch (stage_) {
            case Stage::delay:
                return 0.0f;
            case Stage::fade_in:
                if (fade_in_samples_ <= 0) return 1.0f;
                return fade_shape_(static_cast<float>(stage_pos_)
                                   / static_cast<float>(fade_in_samples_));
            case Stage::sustain:
                return 1.0f;
            case Stage::fade_out:
                if (fade_out_samples_ <= 0) return 0.0f;
                return fade_out_start_
                       * (1.0f - fade_shape_(static_cast<float>(stage_pos_)
                                             / static_cast<float>(fade_out_samples_)));
            case Stage::done:
            default:
                return 0.0f;
        }
    }
 
    void advance_() {
        const Stage before = stage_;
        advance_lifecycle_();
        if (before == Stage::delay || before == Stage::done) return;
        advance_phase_();
    }
 
    void advance_lifecycle_() {
        switch (stage_) {
            case Stage::delay:
                if (++stage_pos_ >= delay_samples_) {
                    stage_ = fade_in_samples_ > 0 ? Stage::fade_in : Stage::sustain;
                    stage_pos_ = 0;
                }
                return;
            case Stage::fade_in:
                if (++stage_pos_ >= fade_in_samples_) {
                    stage_ = Stage::sustain;
                    stage_pos_ = 0;
                }
                return;
            case Stage::fade_out:
                if (++stage_pos_ >= fade_out_samples_) {
                    stage_ = Stage::done;
                    stage_pos_ = 0;
                }
                return;
            case Stage::sustain:
            case Stage::done:
            default:
                return;
        }
    }
 
    void advance_phase_() {
        phase_ += increment_;
        if (phase_ >= 1.0) {
            const double whole = std::floor(phase_);
            phase_ -= whole;
            cycles_ += static_cast<long long>(whole);
            on_cycles_completed_();
        }
    }
 
    void on_cycles_completed_() {
        const int limit = effective_repeat_();
        if (limit <= 0 || cycles_ < limit) return;
        if (stage_ == Stage::fade_out || stage_ == Stage::done) return;
        if (fade_out_enabled_ && fade_out_samples_ > 0) {
            fade_out_start_ = envelope_();
            stage_ = Stage::fade_out;
            stage_pos_ = 0;
        } else {
            stage_ = Stage::done;
            stage_pos_ = 0;
        }
    }
 
    void update_chain_(RandomChain& c, double phase) {
        const auto p = static_cast<float>(phase);
        if (!c.primed || p < c.prev_phase) {
            c.sh = c.rng.next_bipolar();
            c.primed = true;
        }
        c.prev_phase = p;
        const float scaled = p * static_cast<float>(segments_);
        int seg = static_cast<int>(scaled);
        seg = std::clamp(seg, 0, segments_ - 1);
        if (seg != c.seg_index) {
            c.glide_prev = c.seg_index < 0 ? c.rng.next_bipolar() : c.glide_next;
            c.glide_next = c.rng.next_bipolar();
            c.seg_index = seg;
        }
        c.seg_frac = std::clamp(scaled - static_cast<float>(seg), 0.0f, 1.0f);
    }
 
    static constexpr LfoWave sampling_wave_(Wave w) noexcept {
        switch (w) {
        case Wave::sine:
            return LfoWave::sine;
        case Wave::triangle:
            return LfoWave::triangle;
        case Wave::saw_up:
            return LfoWave::saw_up;
        case Wave::saw_down:
            return LfoWave::saw_down;
        case Wave::square:
            return LfoWave::square;
        case Wave::sh_random:
            return LfoWave::sample_hold;
        case Wave::smooth_random:
        default:
            return LfoWave::smooth_random;
        }
    }
 
    LfoShapeParams shape_params_() const noexcept {
        LfoShapeParams params;
        params.pulse_width = static_cast<double>(pulse_width_);
        params.triangle_peak =
            static_cast<double>(std::clamp(0.5f + 0.5f * tri_bias_, 1.0e-4f, 1.0f - 1.0e-4f));
        return params;
    }
 
    double wave_mean_(Wave w, double from, double to) const noexcept {
        return lfo_wave_mean(sampling_wave_(w), from, to, shape_params_());
    }
 
    double morph_mean_(double from, double to) const noexcept {
        static constexpr Wave kMorphOrder[4] = {Wave::sine, Wave::triangle, Wave::saw_up,
                                                Wave::square};
        int index = static_cast<int>(shape_morph_);
        index = std::clamp(index, 0, 2);
        const double w = static_cast<double>(shape_morph_ - static_cast<float>(index));
        const double a = wave_mean_(kMorphOrder[index], from, to);
        if (w <= 0.0)
            return a;
        const double b = wave_mean_(kMorphOrder[index + 1], from, to);
        return a + w * (b - a);
    }
 
    float pure_wave_(Wave w, double phase, const RandomChain& c) const {
        if constexpr (!kEffectConvention) {
            if (band_limited_ && w != Wave::sine && w != Wave::sh_random &&
                w != Wave::smooth_random)
                return static_cast<float>(
                    lfo_wave_bandlimited(sampling_wave_(w), phase, increment_, shape_params_()));
        }
        const auto p = static_cast<float>(phase);
        switch (w) {
            case Wave::sine:
                return static_cast<float>(std::sin(6.283185307179586477 * phase));
            case Wave::triangle: {
                if constexpr (kEffectConvention) {
                    if (p < 0.25f) return 4.0f * p;
                    if (p < 0.75f) return 2.0f - 4.0f * p;
                    return 4.0f * p - 4.0f;
                }
                const float peak = std::clamp(0.5f + 0.5f * tri_bias_, 1.0e-4f, 1.0f - 1.0e-4f);
                if (p < peak) return -1.0f + 2.0f * (p / peak);
                return 1.0f - 2.0f * ((p - peak) / (1.0f - peak));
            }
            case Wave::saw_up:
                return 2.0f * p - 1.0f;
            case Wave::saw_down:
                return 1.0f - 2.0f * p;
            case Wave::square:
                return p < pulse_width_ ? 1.0f : -1.0f;
            case Wave::sh_random:
                return c.sh;
            case Wave::smooth_random:
            default:
                return c.smooth();
        }
    }

    double legacy_effect_shape_(double p, const RandomChain& c) const {
        switch (wave_) {
            case Wave::sine: return std::sin(6.283185307179586477 * p);
            case Wave::triangle:
                if (p < 0.25) return 4.0 * p;
                if (p < 0.75) return 2.0 - 4.0 * p;
                return 4.0 * p - 4.0;
            case Wave::saw_up: return 2.0 * p - 1.0;
            case Wave::saw_down: return 1.0 - 2.0 * p;
            case Wave::square: return p < static_cast<double>(pulse_width_) ? 1.0 : -1.0;
            case Wave::sh_random:
            case Wave::smooth_random:
            default: return static_cast<double>(shape_(p, c));
        }
    }
 
    float morph_shape_(double phase, const RandomChain& c) const {
        static constexpr Wave kMorphOrder[4] = {
            Wave::sine, Wave::triangle, Wave::saw_up, Wave::square};
        int index = static_cast<int>(shape_morph_);
        index = std::clamp(index, 0, 2);
        const float w = shape_morph_ - static_cast<float>(index);
        // Both endpoints of the pair short-circuit, so an integer morph
        // position is the pure wave bit for bit rather than a crossfade that
        // happens to land near it.
        if (w == 0.0f) return pure_wave_(kMorphOrder[index], phase, c);
        if (w == 1.0f) return pure_wave_(kMorphOrder[index + 1], phase, c);
        const float a = pure_wave_(kMorphOrder[index], phase, c);
        const float b = pure_wave_(kMorphOrder[index + 1], phase, c);
        return a + w * (b - a);
    }
 
    float shape_(double phase, const RandomChain& c) const {
        const float base = morph_enabled_ ? morph_shape_(phase, c)
                                          : pure_wave_(wave_, phase, c);
        if (random_blend_ <= 0.0f) return base;
        return base + random_blend_ * (c.sh - base);
    }
 
    RandomChain chains_[2]{};
 
    double sample_rate_ = 48000.0;
    double rate_hz_ = 1.0;
    double requested_rate_hz_ = 1.0;
    double increment_ = 1.0 / 48000.0;
    double phase_ = 0.0;
 
    double delay_ms_ = 0.0;
    double fade_in_ms_ = 0.0;
    double fade_out_ms_ = 0.0;
    long long delay_samples_ = 0;
    long long fade_in_samples_ = 0;
    long long fade_out_samples_ = 0;
    long long stage_pos_ = 0;
 
    double phase_offset_ = 0.0;
    float stereo_offset_ = 0.0f;
    float shape_morph_ = 0.0f;
    float pulse_width_ = 0.5f;
    float tri_bias_ = 0.0f;
    float random_blend_ = 0.0f;
    float fade_out_start_ = 1.0f;
    bool band_limited_ = false;
 
    std::uint32_t seed_ = 0x12345678u;
    int segments_ = 1;
    int repeat_count_ = 0;
    // 64-bit: a free-running LFO at the rate ceiling wraps ~86400 cycles per
    // second at 192 kHz, which overflows a 32-bit counter within hours.
    long long cycles_ = 0;
 
    Wave wave_ = Wave::sine;
    Mode mode_ = Mode::free;
    Stage stage_ = Stage::sustain;
    FadeCurve fade_curve_ = FadeCurve::linear;
    bool morph_enabled_ = false;
    bool fade_out_enabled_ = false;
};
 
} // namespace detail
 
template <typename SampleType = float>
class LfoT : public detail::BasicLfoT<SampleType, detail::LfoConvention::toolkit> {};
template <typename SampleType = float>
class EffectLfoT : public detail::BasicLfoT<SampleType, detail::LfoConvention::effect> {};
using Lfo = LfoT<float>;
using Lfo64 = LfoT<double>;
using EffectLfo = EffectLfoT<float>;
using EffectLfo64 = EffectLfoT<double>;
 
} // namespace pulp::signal