EnvelopeGenerator.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 "AudioSpec.h"
 
#include <algorithm>
#include <cmath>
 
namespace dspark {
 
template <FloatType T>
class ADSREnvelope
{
public:
    enum class State { Idle, Attack, Decay, Sustain, Release };
 
    ADSREnvelope() noexcept { recalculate(); }
 
    void prepare(double sampleRate) noexcept
    {
        if (sampleRate <= 0.0) return;
        sampleRate_ = sampleRate;
        recalculate();
    }
 
    void prepare(const AudioSpec& spec) noexcept { prepare(spec.sampleRate); }
 
    // -- Parameters (in milliseconds) ------------------------------------------
 
    void setAttack(T ms) noexcept  { attackMs_ = std::max(ms, T(0.01)); recalculate(); }
 
    void setDecay(T ms) noexcept   { decayMs_ = std::max(ms, T(0.01)); recalculate(); }
 
    void setSustain(T level) noexcept { sustainLevel_ = std::clamp(level, T(0), T(1)); }
 
    void setRelease(T ms) noexcept { releaseMs_ = std::max(ms, T(0.01)); recalculate(); }
 
    void setParameters(T attackMs, T decayMs, T sustain, T releaseMs) noexcept
    {
        attackMs_     = std::max(attackMs, T(0.01));
        decayMs_      = std::max(decayMs, T(0.01));
        sustainLevel_ = std::clamp(sustain, T(0), T(1));
        releaseMs_    = std::max(releaseMs, T(0.01));
        recalculate();
    }
 
    void setCurvature(T curve) noexcept
    {
        curve = std::clamp(curve, T(0.1), T(10));
        attackCurve_ = decayCurve_ = releaseCurve_ = curve;
        recalculate();
    }
 
    void setCurvature(T attackCurve, T decayCurve, T releaseCurve) noexcept
    {
        attackCurve_  = std::clamp(attackCurve,  T(0.1), T(10));
        decayCurve_   = std::clamp(decayCurve,   T(0.1), T(10));
        releaseCurve_ = std::clamp(releaseCurve, T(0.1), T(10));
        recalculate();
    }
 
    // -- Trigger ---------------------------------------------------------------
 
    void noteOn() noexcept
    {
        state_ = State::Attack;
    }
 
    void noteOff() noexcept
    {
        if (state_ != State::Idle)
            state_ = State::Release;
    }
 
    void reset() noexcept
    {
        state_ = State::Idle;
        currentValue_ = 0.0;
    }
 
    // -- Processing ------------------------------------------------------------
 
    [[nodiscard]] T getNextValue() noexcept
    {
        switch (state_)
        {
            case State::Idle:
                return T(0);
 
            case State::Attack:
                currentValue_ += attackRate_ * (1.0 + kAttack_ - currentValue_);
                if (currentValue_ >= 1.0)
                {
                    currentValue_ = 1.0;
                    state_ = State::Decay;
                }
                break;
 
            case State::Decay:
            {
                const double s = static_cast<double>(sustainLevel_);
                const double prev = currentValue_;
                currentValue_ += decayRate_ * (s - (1.0 - s) * kDecay_ - currentValue_);
                if (currentValue_ <= s)
                {
                    // Normal completion (crossed from above): land exactly on s.
                    // Sustain raised above the current value mid-decay: keep the
                    // value and let the Sustain chase close the gap click-free.
                    if (prev >= s)
                        currentValue_ = s;
                    state_ = State::Sustain;
                }
                break;
            }
 
            case State::Sustain:
                // Chases sustain changes at the decay rate (dynamic modulation).
                currentValue_ += decayRate_ * (static_cast<double>(sustainLevel_) - currentValue_);
                break;
 
            case State::Release:
                currentValue_ += releaseRate_ * (-kRelease_ - currentValue_);
                if (currentValue_ <= kSilence)
                {
                    currentValue_ = 0.0;
                    state_ = State::Idle;
                }
                break;
        }
 
        return static_cast<T>(currentValue_);
    }
 
    void processBlock(T* output, int numSamples) noexcept
    {
        // Each stage runs as a tight loop on locals (stage constants hoisted,
        // recursion state in a register): no state dispatch or member traffic
        // per sample. Arithmetic is sample-exact with getNextValue().
        int i = 0;
        while (i < numSamples)
        {
            switch (state_)
            {
                case State::Idle:
                    while (i < numSamples)
                        output[i++] = T(0);
                    break;
 
                case State::Attack:
                {
                    const double target = 1.0 + kAttack_;
                    const double r = attackRate_;
                    double v = currentValue_;
                    while (i < numSamples)
                    {
                        v += r * (target - v);
                        if (v >= 1.0)
                        {
                            v = 1.0;
                            state_ = State::Decay;
                            output[i++] = T(1);
                            break;
                        }
                        output[i++] = static_cast<T>(v);
                    }
                    currentValue_ = v;
                    break;
                }
 
                case State::Decay:
                {
                    const double s = static_cast<double>(sustainLevel_);
                    const double target = s - (1.0 - s) * kDecay_;
                    const double r = decayRate_;
                    double v = currentValue_;
                    while (i < numSamples)
                    {
                        const double prev = v;
                        v += r * (target - v);
                        if (v <= s)
                        {
                            if (prev >= s)
                                v = s;
                            state_ = State::Sustain;
                            output[i++] = static_cast<T>(v);
                            break;
                        }
                        output[i++] = static_cast<T>(v);
                    }
                    currentValue_ = v;
                    break;
                }
 
                case State::Sustain:
                {
                    const double s = static_cast<double>(sustainLevel_);
                    const double r = decayRate_;
                    double v = currentValue_;
                    while (i < numSamples)
                    {
                        v += r * (s - v);
                        output[i++] = static_cast<T>(v);
                    }
                    currentValue_ = v;
                    break;
                }
 
                case State::Release:
                {
                    const double target = -kRelease_;
                    const double r = releaseRate_;
                    double v = currentValue_;
                    while (i < numSamples)
                    {
                        v += r * (target - v);
                        if (v <= kSilence)
                        {
                            v = 0.0;
                            state_ = State::Idle;
                            output[i++] = T(0);
                            break;
                        }
                        output[i++] = static_cast<T>(v);
                    }
                    currentValue_ = v;
                    break;
                }
            }
        }
    }
 
    // -- Getters ---------------------------------------------------------------
 
    [[nodiscard]] T getCurrentValue() const noexcept { return static_cast<T>(currentValue_); }
 
    [[nodiscard]] State getState() const noexcept { return state_; }
 
    [[nodiscard]] bool isActive() const noexcept { return state_ != State::Idle; }
 
private:
    // Release ends when the value falls below this floor (about -80 dB);
    // the strictly negative release target guarantees it is crossed.
    static constexpr double kSilence = 1e-4;
 
    void recalculate() noexcept
    {
        // Asymptotic one-pole stage design. With ov = exp(-curve), running the
        // recursion v += rate * (target - v) for exactly `samples` steps
        // multiplies the distance to the target by ov. Overshooting the stage
        // endpoint by k = ov / (1 - ov) OF THE STAGE DEPTH makes the endpoint
        // land exactly on the last step, for any curvature:
        //
        //   endpoint = target + depth_to_target * ov  with  target = end + k*depth
        //
        // (A first-order shortcut like target = end + ov breaks the timing
        // contract: at curve 0.1 the stages run ~7x their parameter, and a
        // fixed absolute overshoot makes decay/release durations drift with
        // the sustain level.)
        auto stage = [this](T timeMs, T curve, double& rate, double& k) noexcept {
            const double c = static_cast<double>(curve);
            const double ov = std::exp(-c);
            k = ov / (1.0 - ov);
            const double samples = std::max(sampleRate_ * 0.001 * static_cast<double>(timeMs), 1.0);
            rate = 1.0 - std::exp(-c / samples);
        };
 
        stage(attackMs_,  attackCurve_,  attackRate_,  kAttack_);
        stage(decayMs_,   decayCurve_,   decayRate_,   kDecay_);
        stage(releaseMs_, releaseCurve_, releaseRate_, kRelease_);
    }
 
    double sampleRate_ = 48000.0;
 
    T attackMs_     = T(10);
    T decayMs_      = T(100);
    T sustainLevel_ = T(0.7);
    T releaseMs_    = T(200);
    T attackCurve_  = T(3.0);
    T decayCurve_   = T(3.0);
    T releaseCurve_ = T(3.0);
 
    // Stage coefficients and overshoot fractions (see recalculate()).
    double attackRate_  = 0.0;
    double decayRate_   = 0.0;
    double releaseRate_ = 0.0;
    double kAttack_     = 0.0;
    double kDecay_      = 0.0;
    double kRelease_    = 0.0;
 
    double currentValue_ = 0.0;
    State state_ = State::Idle;
};
 
} // namespace dspark