envelope_curve.h

/*
 * Copyright © 2026 Synthstrom Audible Limited
 *
 * This file is part of The Synthstrom Audible Deluge Firmware.
 *
 * The Synthstrom Audible Deluge Firmware is free software: you can redistribute it and/or modify it under the
 * terms of the GNU General Public License as published by the Free Software Foundation,
 * either version 3 of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along with this program.
 * If not, see <https://www.gnu.org/licenses/>.
 */
 
#pragma once
 
#include <algorithm>
#include <bit>
#include <cmath>
#include <cstdint>
 
namespace deluge::modulation {

[[gnu::always_inline]] constexpr float fastExp2(float x) {
    int32_t whole = static_cast<int32_t>(x); // truncates toward zero
    float frac = x - static_cast<float>(whole);
    if (frac < 0.f) { // floor for negative inputs, so frac is in [0, 1)
        frac += 1.f;
        whole -= 1;
    }
    // Weighted least-squares fit of 2^f to polynomial on [0, 1]
    float p = 0.00185888436f;
    p = p * frac + 0.00903089405f;
    p = p * frac + 0.0557939352f;
    p = p * frac + 0.240164314f;
    p = p * frac + 0.693151594f;
    p = p * frac + 1.f;
    return std::bit_cast<float>(std::bit_cast<int32_t>(p) + (whole << 23));
}

class EnvelopeCurve {
public:
    constexpr EnvelopeCurve() : EnvelopeCurve(0.f) {}
    constexpr explicit EnvelopeCurve(float k)
        : k_(k), floor_(fastExp2(-k)), scale_((k == 0.f) ? 1.f : 1.f / (1.f - fastExp2(-k))) {}

    [[gnu::always_inline]] constexpr float falling(float x) const {
        if (k_ == 0.f) {
            return 1.f - x;
        }
        return (fastExp2(-k_ * x) - floor_) * scale_;
    }

    [[gnu::always_inline]] constexpr float rising(float x) const { return 1.f - falling(x); }

    float risingInverse(float value) const {
        value = std::clamp(value, 0.f, 1.f);
        if (k_ == 0.f) {
            return value;
        }
        float x = -std::log2((1.f - value) / scale_ + floor_) / k_;
        return std::clamp(x, 0.f, 1.f);
    }
 
    constexpr float k() const { return k_; }
 
private:
    float k_;
    float floor_; // 2^-k, the unnormalised curve's value at x = 1
    float scale_; // 1 / (1 - 2^-k)
};

struct EnvelopeShape {
    EnvelopeCurve attack{4.f};
    EnvelopeCurve decay{8.f};
    EnvelopeCurve release{8.f};

    static constexpr int32_t kMinCurve = -50;
    static constexpr int32_t kMaxCurve = 50;
    static constexpr int32_t kClassicCurve = 32;
    static constexpr EnvelopeShape fromCurve(int32_t curve) {
        float k = static_cast<float>(curve) * 0.25f;
        return {.attack = EnvelopeCurve{k * 0.5f}, .decay = EnvelopeCurve{k}, .release = EnvelopeCurve{k}};
    }
};

inline constexpr EnvelopeShape kClassicEnvelopeShape{};
inline constexpr EnvelopeShape kAudioClipEnvelopeShape{.release = EnvelopeCurve{4.f}};
 
enum class EnvelopeMode : uint8_t {
    ADSR,
    AHD,
    AR,
    MPE,
};
constexpr int32_t kNumEnvelopeModes = 4;

enum class EnvelopeFollow : uint8_t {
    Z, 
    Y, 
};
constexpr int32_t kNumEnvelopeFollows = 2;

struct EnvelopeConfig {
    EnvelopeMode mode{EnvelopeMode::ADSR};
    EnvelopeFollow follow{EnvelopeFollow::Z};
    int8_t curve{EnvelopeShape::kClassicCurve};
    EnvelopeShape shape{}; // derived from curve; call setCurve() rather than writing either directly
 
    constexpr void setCurve(int32_t newCurve) {
        curve = static_cast<int8_t>(std::clamp(newCurve, EnvelopeShape::kMinCurve, EnvelopeShape::kMaxCurve));
        shape = EnvelopeShape::fromCurve(curve);
    }
    constexpr bool isDefault() const {
        return mode == EnvelopeMode::ADSR && follow == EnvelopeFollow::Z && curve == EnvelopeShape::kClassicCurve;
    }
};
 
inline constexpr EnvelopeConfig kAudioClipEnvelopeConfig{.shape = kAudioClipEnvelopeShape};
 
char const* envelopeModeToString(EnvelopeMode mode);
EnvelopeMode stringToEnvelopeMode(char const* string);
char const* envelopeFollowToString(EnvelopeFollow follow);
EnvelopeFollow stringToEnvelopeFollow(char const* string);
 
} // namespace deluge::modulation