SmoothedValue.h

Go to the documentation of this file.

// DSPark -- Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi -- MIT License
 
#pragma once
 
#include "DspMath.h"
 
#include <cmath>
#include <algorithm>
#include <span>
 
namespace dspark {
 
template <FloatType T>
class SmoothedValue
{
public:
    enum class SmoothingType
    {
        Exponential,  
        Linear,       
        Disabled,     
        Chase         
    };
 
    SmoothedValue(const SmoothedValue&) = delete;
    SmoothedValue& operator=(const SmoothedValue&) = delete;
 
    SmoothedValue() noexcept { prepare(sampleRate_, rampTimeMs_); }
 
    void prepare(double sampleRate, double rampTimeMs = 20.0) noexcept
    {
        sampleRate_ = std::max(1.0, sampleRate);
        rampTimeMs_ = std::max(0.1, rampTimeMs);
 
        // Exponential: 1-pole coefficient
        const double tau = rampTimeMs_ / 1000.0;
        expCoeff_ = std::exp(-1.0 / (sampleRate_ * tau));
 
        // Linear: Rate of change per sample (Rate Limiter)
        linearRate_ = 1000.0 / (rampTimeMs_ * sampleRate_);
 
        // Chase: Sample-rate correction ratio relative to 44.1kHz base
        const double srRatio = 44100.0 / sampleRate_;
        chaseMultDecay_ = std::pow(0.9999, srRatio);
        chaseAddDecay_ = 0.01 * srRatio;
    }
 
    void setSmoothingType(SmoothingType type) noexcept { type_ = type; }
 
    [[nodiscard]] SmoothingType getSmoothingType() const noexcept { return type_; }
 
    void setTargetValue(T newTarget) noexcept
    {
        if (newTarget != newTarget) return; // NaN guard
        if (newTarget != target_)
        {
            target_ = newTarget;
            if (type_ == SmoothingType::Chase)
                chaseSpeed_ = 2500.0; // Reset chase velocity on target change
        }
    }
 
    [[nodiscard]] T getNextValue() noexcept
    {
        const double target = static_cast<double>(target_);
        if (current_ == target) return target_;
 
        switch (type_)
        {
            case SmoothingType::Exponential:
            {
                current_ = target + expCoeff_ * (current_ - target);
                break;
            }
            case SmoothingType::Linear:
            {
                if (current_ < target)
                    current_ = std::min(current_ + linearRate_, target);
                else
                    current_ = std::max(current_ - linearRate_, target);
                break;
            }
            case SmoothingType::Disabled:
            {
                current_ = target;
                break;
            }
            case SmoothingType::Chase:
            {
                chaseSpeed_ = std::max(350.0, std::min(2500.0, chaseSpeed_ * chaseMultDecay_ - chaseAddDecay_));
                current_ = (current_ * chaseSpeed_ + target) / (chaseSpeed_ + 1.0);
                break;
            }
        }
 
        // Exact arrival: snap once within a relative epsilon of the target.
        // Relative because with large magnitudes (e.g. a frequency of 10000)
        // a purely absolute threshold would be finer than the float ulp.
        const double eps = kEpsilon * std::max(1.0, std::abs(target));
        if (std::abs(current_ - target) < eps)
            current_ = target;
 
        return static_cast<T>(current_);
    }
 
    void processBlock(std::span<T> buffer) noexcept
    {
        const double target = static_cast<double>(target_);
        const size_t n = buffer.size();
        if (current_ == target)
        {
            std::fill(buffer.begin(), buffer.end(), target_);
            return;
        }
 
        // Work on locals: the compiler cannot prove the span does not alias
        // the members, so member accesses would be re-loaded each iteration.
        // The per-sample arrival snap matches getNextValue(); once settled,
        // the rest of the block is a plain fill.
        double current = current_;
        const double eps = kEpsilon * std::max(1.0, std::abs(target));
        size_t i = 0;
 
        switch (type_)
        {
            case SmoothingType::Exponential:
            {
                const double coeff = expCoeff_;
                for (; i < n; ++i)
                {
                    current = target + coeff * (current - target);
                    if (std::abs(current - target) < eps) { current = target; break; }
                    buffer[i] = static_cast<T>(current);
                }
                break;
            }
 
            case SmoothingType::Linear:
            {
                const double rate = linearRate_;
                for (; i < n; ++i)
                {
                    if (current < target)      current = std::min(current + rate, target);
                    else if (current > target) current = std::max(current - rate, target);
                    if (std::abs(current - target) < eps) { current = target; break; }
                    buffer[i] = static_cast<T>(current);
                }
                break;
            }
 
            case SmoothingType::Disabled:
                current = target;
                break;
 
            case SmoothingType::Chase:
            {
                double speed = chaseSpeed_;
                const double multDecay = chaseMultDecay_;
                const double addDecay  = chaseAddDecay_;
                for (; i < n; ++i)
                {
                    speed = std::max(350.0, std::min(2500.0, speed * multDecay - addDecay));
                    current = (current * speed + target) / (speed + 1.0);
                    if (std::abs(current - target) < eps) { current = target; break; }
                    buffer[i] = static_cast<T>(current);
                }
                chaseSpeed_ = speed;
                break;
            }
        }
 
        // Settled (or Disabled): the remainder of the block is the target.
        for (; i < n; ++i)
            buffer[i] = target_;
 
        current_ = current;
    }
 
    [[nodiscard]] T getCurrentValue() const noexcept { return static_cast<T>(current_); }
 
    [[nodiscard]] T getTargetValue() const noexcept { return target_; }
 
    [[nodiscard]] bool isSmoothing() const noexcept { return current_ != static_cast<double>(target_); }
 
    void skip() noexcept { current_ = static_cast<double>(target_); chaseSpeed_ = 350.0; }
 
    void reset(T value = T(0)) noexcept
    {
        target_ = value;
        current_ = static_cast<double>(value);
        chaseSpeed_ = 350.0;
    }
 
    void setRampTime(double sampleRate, double rampTimeMs) noexcept
    {
        prepare(sampleRate, rampTimeMs);
    }
 
private:
    double current_{ 0.0 };
    T target_{ T(0) };
    SmoothingType type_{ SmoothingType::Exponential };
 
    // DSP coefficients (double: recursive state and its drivers, see @class)
    double expCoeff_{ 0.0 };
    double linearRate_{ 0.0 };
 
    // Chase state & coefficients
    double chaseSpeed_{ 350.0 };
    double chaseMultDecay_{ 0.9999 };
    double chaseAddDecay_{ 0.01 };
 
    double sampleRate_{ 44100.0 };
    double rampTimeMs_{ 20.0 };
 
    static constexpr double kEpsilon = 1e-7; 
};
 
} // namespace dspark