mod_tools.hpp

Go to the documentation of this file.

#pragma once

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

inline constexpr float kCurveSpan = 8.0f;

inline float stage_curve(float p, float curve) {
    const float t = std::clamp(p, 0.0f, 1.0f);
    const float k = kCurveSpan * std::clamp(curve, -1.0f, 1.0f);
    if (std::abs(k) < 1.0e-4f) return t; // linear limit
    return (1.0f - std::exp(-k * t)) / (1.0f - std::exp(-k));
}

inline float curve_rise(float p, float curve) { return stage_curve(p, -curve); }

inline float curve_fall(float p, float curve) { return 1.0f - stage_curve(p, curve); }

inline float smoothstep(float p) {
    const float t = std::clamp(p, 0.0f, 1.0f);
    return t * t * (3.0f - 2.0f * t);
}

inline float bi_to_uni(float x) { return x * 0.5f + 0.5f; }

inline float uni_to_bi(float x) { return x * 2.0f - 1.0f; }

enum class SlewMode : std::uint8_t { linear, exponential };
 
template <typename SampleType = float>
class SlewLimiterT {
public:
    using Mode = SlewMode;
    static constexpr double kSettleEpsilon = 1e-9;
 
    SlewLimiterT() { update_coefficients(); }
 
    void prepare(double sample_rate) {
        if (std::isfinite(sample_rate) && sample_rate > 0.0)
            sample_rate_ = sample_rate;
        update_coefficients();
    }
 
    void set_mode(Mode mode) { mode_ = mode; }
    Mode mode() const { return mode_; }

    void set_time_ms(double ms) {
        rise_ms_ = fall_ms_ = finite_time(ms);
        update_coefficients();
    }
 
    void set_rise_ms(double ms) {
        rise_ms_ = finite_time(ms);
        update_coefficients();
    }
    void set_fall_ms(double ms) {
        fall_ms_ = finite_time(ms);
        update_coefficients();
    }
 
    void set_times_ms(SampleType rise, SampleType fall) {
        rise_ms_ = finite_time(static_cast<double>(rise));
        fall_ms_ = finite_time(static_cast<double>(fall));
        update_coefficients();
    }
 
    double rise_ms() const { return rise_ms_; }
    double fall_ms() const { return fall_ms_; }
 
    void set_immediate(SampleType value) {
        const double v = static_cast<double>(value);
        value_ = std::isfinite(v) ? v : 0.0;
        target_ = value_;
        linear_step_ = 0.0;
    }
    void reset(SampleType value = SampleType{0}) { set_immediate(value); }
 
    SampleType value() const { return static_cast<SampleType>(value_); }
    SampleType current() const { return value(); }
    bool settled() const { return value_ == target_; }
 
    SampleType process(SampleType input) {
        const double in = static_cast<double>(input);
        if (!std::isfinite(in)) {
            reset();
            return SampleType{0};
        }
        const double delta = in - value_;
        if (delta == 0.0) return static_cast<SampleType>(value_);
        const bool rising = delta > 0.0;
 
        if (mode_ == Mode::linear) {
            if (in != target_) {
                target_ = in;
                const double samples = rising ? rise_samples_ : fall_samples_;
                linear_step_ = samples > 0.0 ? 1.0 / samples : 0.0;
            }
            if (linear_step_ <= 0.0)
                value_ = in;
            else if (rising)
                value_ = std::min(value_ + linear_step_, in);
            else
                value_ = std::max(value_ - linear_step_, in);
        } else {
            target_ = in;
            const double coefficient = rising ? rise_coeff_ : fall_coeff_;
            value_ += coefficient * delta;
            if (std::abs(in - value_) < kSettleEpsilon) value_ = in;
        }
        value_ = snap_to_zero(value_);
        return static_cast<SampleType>(value_);
    }
 
private:
    static double finite_time(double ms) {
        return std::isfinite(ms) ? std::max(0.0, ms) : 0.0;
    }
    void update_coefficients() {
        rise_samples_ = units::ms_to_samples(rise_ms_, sample_rate_);
        fall_samples_ = units::ms_to_samples(fall_ms_, sample_rate_);
        rise_coeff_ = units::ms_to_onepole_coef(rise_ms_, sample_rate_);
        fall_coeff_ = units::ms_to_onepole_coef(fall_ms_, sample_rate_);
    }
 
    double sample_rate_ = 48000.0;
    double rise_ms_ = 10.0;
    double fall_ms_ = 10.0;
    double rise_samples_ = 480.0;
    double fall_samples_ = 480.0;
    double rise_coeff_ = 1.0;
    double fall_coeff_ = 1.0;
    double value_ = 0.0;
    double target_ = 0.0;
    double linear_step_ = 0.0;
    Mode mode_ = Mode::linear;
};
 
using SlewLimiter = SlewLimiterT<float>;
using SlewLimiter64 = SlewLimiterT<double>;

template <typename SampleType = float>
class ConstantTimeSlewLimiterT {
public:
    using Mode = SlewMode;
    static constexpr double kSettleEpsilon = 1e-9;
 
    ConstantTimeSlewLimiterT() { update_coefficients(); }
 
    void prepare(double sample_rate) {
        if (std::isfinite(sample_rate) && sample_rate > 0.0) sample_rate_ = sample_rate;
        update_coefficients();
    }
 
    void set_mode(Mode mode) { mode_ = mode; }
    Mode mode() const { return mode_; }
 
    void set_time_ms(double ms) {
        rise_ms_ = fall_ms_ = finite_time(ms);
        update_coefficients();
    }
    void set_rise_ms(double ms) {
        rise_ms_ = finite_time(ms);
        update_coefficients();
    }
    void set_fall_ms(double ms) {
        fall_ms_ = finite_time(ms);
        update_coefficients();
    }
    void set_times_ms(SampleType rise, SampleType fall) {
        rise_ms_ = finite_time(static_cast<double>(rise));
        fall_ms_ = finite_time(static_cast<double>(fall));
        update_coefficients();
    }
 
    double rise_ms() const { return rise_ms_; }
    double fall_ms() const { return fall_ms_; }
 
    void set_immediate(SampleType value) {
        const double candidate = static_cast<double>(value);
        value_ = std::isfinite(candidate) ? candidate : 0.0;
        target_ = value_;
        linear_step_ = 0.0;
    }
    void reset(SampleType value = SampleType{0}) { set_immediate(value); }
 
    SampleType value() const { return static_cast<SampleType>(value_); }
    SampleType current() const { return value(); }
    bool settled() const { return value_ == target_; }
 
    SampleType process(SampleType input) {
        const double in = static_cast<double>(input);
        if (!std::isfinite(in)) {
            reset();
            return SampleType{0};
        }
        const double delta = in - value_;
        if (delta == 0.0) return value();
        const bool rising = delta > 0.0;
 
        if (mode_ == Mode::linear) {
            if (in != target_) {
                target_ = in;
                const double samples = rising ? rise_samples_ : fall_samples_;
                linear_step_ = samples > 0.0 ? std::abs(delta) / samples : 0.0;
            }
            if (linear_step_ <= 0.0)
                value_ = in;
            else if (rising)
                value_ = std::min(value_ + linear_step_, in);
            else
                value_ = std::max(value_ - linear_step_, in);
        } else {
            target_ = in;
            const double coefficient = rising ? rise_coeff_ : fall_coeff_;
            value_ += coefficient * delta;
            if (std::abs(in - value_) < kSettleEpsilon) value_ = in;
        }
        value_ = snap_to_zero(value_);
        return value();
    }
 
private:
    static double finite_time(double ms) {
        return std::isfinite(ms) ? std::max(0.0, ms) : 0.0;
    }
    void update_coefficients() {
        rise_samples_ = units::ms_to_samples(rise_ms_, sample_rate_);
        fall_samples_ = units::ms_to_samples(fall_ms_, sample_rate_);
        rise_coeff_ = units::ms_to_onepole_coef(rise_ms_, sample_rate_);
        fall_coeff_ = units::ms_to_onepole_coef(fall_ms_, sample_rate_);
    }
 
    double sample_rate_ = 48000.0;
    double rise_ms_ = 10.0;
    double fall_ms_ = 10.0;
    double rise_samples_ = 480.0;
    double fall_samples_ = 480.0;
    double rise_coeff_ = 1.0;
    double fall_coeff_ = 1.0;
    double value_ = 0.0;
    double target_ = 0.0;
    double linear_step_ = 0.0;
    Mode mode_ = Mode::linear;
};
 
using ConstantTimeSlewLimiter = ConstantTimeSlewLimiterT<float>;
using ConstantTimeSlewLimiter64 = ConstantTimeSlewLimiterT<double>;

template <typename SampleType = float>
class SampleHoldT {
public:
    static constexpr double kDefaultThreshold = 0.5;
 
    void prepare(SampleType sample_rate) { glide_.prepare(sample_rate); }
 
    void set_threshold(SampleType threshold) {
        const double value = static_cast<double>(threshold);
        if (std::isfinite(value)) threshold_ = value;
    }

    void set_glide_ms(SampleType ms) {
        glide_ms_ = std::max(SampleType{0}, ms);
        glide_.set_times_ms(glide_ms_, glide_ms_);
    }
 
    void set_glide_mode(typename SlewLimiterT<SampleType>::Mode m) { glide_.set_mode(m); }
 
    void reset(SampleType value = SampleType{0}) {
        held_ = value;
        prev_clock_ = false;
        glide_.reset(value);
    }

    SampleType process(SampleType input, bool clock) {
        if (clock && !prev_clock_) held_ = input;
        prev_clock_ = clock;
        if (glide_ms_ <= SampleType{0}) {
            glide_.reset(held_);
            return held_;
        }
        return glide_.process(held_);
    }

    SampleType process_signal(SampleType input, SampleType trigger) {
        return process(input, static_cast<double>(trigger) >= threshold_);
    }

    SampleType held() const { return held_; }
    SampleType value() const { return held_; }
 
private:
    SlewLimiterT<SampleType> glide_{};
    SampleType held_ = SampleType{0};
    SampleType glide_ms_ = SampleType{0};
    double threshold_ = kDefaultThreshold;
    bool prev_clock_ = false;
};
 
using SampleHold = SampleHoldT<float>;
using SampleHold64 = SampleHoldT<double>;

template <typename SampleType = float>
class AttenuverterT {
public:
    static constexpr SampleType kMaxGain = SampleType{2};
 
    void set_gain(SampleType g) { gain_ = std::clamp(g, -kMaxGain, kMaxGain); }
    void set_offset(SampleType o) { offset_ = o; }
 
    SampleType process(SampleType x) const { return x * gain_ + offset_; }
    SampleType gain() const { return gain_; }
    SampleType offset() const { return offset_; }
 
private:
    SampleType gain_ = SampleType{1};
    SampleType offset_ = SampleType{0};
};
 
using Attenuverter = AttenuverterT<float>;
using Attenuverter64 = AttenuverterT<double>;

template <typename SampleType = float>
class RectifierT {
public:
    enum class Mode : std::uint8_t { full_wave, half_wave };
 
    void set_mode(Mode m) { mode_ = m; }
 
    SampleType process(SampleType x) const {
        if (mode_ == Mode::full_wave) return std::abs(x);
        return std::max(SampleType{0}, x);
    }
 
private:
    Mode mode_ = Mode::full_wave;
};
 
using Rectifier = RectifierT<float>;
using Rectifier64 = RectifierT<double>;

template <typename SampleType = float>
class ComparatorT {
public:
    static constexpr SampleType kDefaultHysteresisFraction = SampleType{0.05};

    static constexpr SampleType kMinAutoHysteresis = SampleType{0.001};

    void set_threshold(SampleType t) {
        threshold_ = t;
        if (auto_hysteresis_)
            hysteresis_ = std::max(kMinAutoHysteresis,
                                   kDefaultHysteresisFraction * std::abs(t));
    }

    void set_hysteresis(SampleType h) {
        hysteresis_ = std::abs(h);
        auto_hysteresis_ = false;
    }
 
    void reset(bool gate = false) { gate_ = gate; }
 
    bool process(SampleType x) {
        if (!gate_ && x > threshold_ + hysteresis_) gate_ = true;
        else if (gate_ && x < threshold_ - hysteresis_) gate_ = false;
        return gate_;
    }
 
    bool gate() const { return gate_; }
    SampleType hysteresis() const { return hysteresis_; }
 
private:
    SampleType threshold_ = SampleType{0};
    SampleType hysteresis_ = kMinAutoHysteresis;
    bool auto_hysteresis_ = true;
    bool gate_ = false;
};
 
using Comparator = ComparatorT<float>;
using Comparator64 = ComparatorT<double>;

template <typename SampleType = float>
class SignalComparatorT {
public:
    void set_thresholds(double high, double low) {
        high_ = std::isfinite(high) ? high : high_;
        low_ = std::isfinite(low) ? std::min(low, high_ - 1e-9) : low_;
    }
    void set_levels(SampleType low_level, SampleType high_level) {
        if (std::isfinite(static_cast<double>(low_level))) low_level_ = low_level;
        if (std::isfinite(static_cast<double>(high_level))) high_level_ = high_level;
    }
    void reset() { high_state_ = false; }
    SampleType process(SampleType input) {
        const double value = static_cast<double>(input);
        if (!std::isfinite(value)) {
            reset();
            return low_level_;
        }
        if (!high_state_ && value >= high_) high_state_ = true;
        else if (high_state_ && value <= low_) high_state_ = false;
        return high_state_ ? high_level_ : low_level_;
    }
    bool high() const { return high_state_; }
 
private:
    double high_ = 0.5;
    double low_ = 0.25;
    SampleType low_level_ = SampleType{0};
    SampleType high_level_ = SampleType{1};
    bool high_state_ = false;
};
 
using SignalComparator = SignalComparatorT<float>;
using SignalComparator64 = SignalComparatorT<double>;

template <typename SampleType = float>
class QuantizerT {
public:
    void set_range(SampleType lo, SampleType hi) {
        lo_ = lo;
        hi_ = hi;
    }
 
    void set_steps(int n) { steps_ = std::clamp(n, 1, 1024); }
 
    SampleType process(SampleType x) const {
        if (steps_ <= 1) return lo_;
        const SampleType span = hi_ - lo_;
        if (span == SampleType{0}) return lo_;
        const SampleType t = std::clamp((x - lo_) / span, SampleType{0}, SampleType{1});
        const auto divisions = static_cast<SampleType>(steps_ - 1);
        const auto index = static_cast<SampleType>(std::lround(t * divisions));
        return lo_ + index * span / divisions;
    }
 
    int steps() const { return steps_; }
 
private:
    SampleType lo_ = SampleType{0};
    SampleType hi_ = SampleType{1};
    int steps_ = 8;
};
 
using Quantizer = QuantizerT<float>;
using Quantizer64 = QuantizerT<double>;

template <typename SampleType = float>
class CurveT {
public:
    enum class Shape : std::uint8_t { stage_curve, smoothstep };
 
    void set_shape(Shape s) { shape_ = s; }

    void set_curve(SampleType c) { curve_ = std::clamp(c, SampleType{-1}, SampleType{1}); }
 
    SampleType process(SampleType x) const {
        const auto p = static_cast<float>(x);
        if (shape_ == Shape::smoothstep) return static_cast<SampleType>(pulp::signal::smoothstep(p));
        return static_cast<SampleType>(curve_rise(p, static_cast<float>(curve_)));
    }
 
private:
    SampleType curve_ = SampleType{0};
    Shape shape_ = Shape::stage_curve;
};
 
using Curve = CurveT<float>;
using Curve64 = CurveT<double>;
 
} // namespace pulp::signal