envelope.hpp

Go to the documentation of this file.

// sbl/widgets/mod/envelope.hpp — Envelope widget (Audio Stack — Widgets)
//
// Pre-composed envelope shapes built on SegmentGenerator. Factory functions
// create common configurations (ADSR, AR, AHR, AD) with a single call.
// For custom multi-segment envelopes, use custom().
//
// The curve engine is selected at compile time. Default is FloatRationalWarp.
//
// Output is float [0.0, 1.0] — SegmentGenerator operates natively in float.
//
// See FDP-014 and FDP-016 for design rationale.
 
#pragma once
 
#include <cstdint>
 
#include <sbl/dsp/segment.hpp>
 
namespace sbl::widgets::mod {
 
template<typename CurveEngine = dsp::FloatDefaultWarp>
class Envelope {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    // ── Factory functions ─────────────────────────────────────────
    //
    // Each factory returns a fully configured Envelope ready for gate_on().
    // The curve parameter applies to all segments (use custom() for per-segment curves).
    // Curve: -1.0 = concave (fast start), 0.0 = linear, 1.0 = convex (slow start).
 
    /// Attack-Decay-Sustain-Release envelope.
    /// @param sustain Sustain level [0.0, 1.0]
    /// @param curve   Shape [-1.0, 1.0]: -1 = concave, 0 = linear, 1 = convex
    static Envelope adsr(float attack_ms, float decay_ms,
                         float sustain, float release_ms,
                         float curve = 0.0f) {
        Envelope env;
        dsp::Segment segs[] = {
            {1.0f, curve, attack_ms},
            {sustain, curve, decay_ms},
            {0.0f, curve, release_ms},
        };
        env.gen_.configure(segs, 3, 1);
        return env;
    }
 
    /// Attack-Release envelope (sustain at peak until gate_off).
    static Envelope ar(float attack_ms, float release_ms,
                       float curve = 0.0f) {
        Envelope env;
        dsp::Segment segs[] = {
            {1.0f, curve, attack_ms},
            {0.0f, curve, release_ms},
        };
        env.gen_.configure(segs, 2, 0);
        return env;
    }
 
    /// Attack-Hold-Release envelope (timed hold, no gate sustain).
    static Envelope ahr(float attack_ms, float hold_ms,
                        float release_ms, float curve = 0.0f) {
        Envelope env;
        dsp::Segment segs[] = {
            {1.0f, curve, attack_ms},
            {1.0f, 0.0f, hold_ms},
            {0.0f, curve, release_ms},
        };
        env.gen_.configure(segs, 3, -1);
        return env;
    }
 
    /// Attack-Decay envelope (one-shot, no sustain or release).
    static Envelope ad(float attack_ms, float decay_ms,
                       float curve = 0.0f) {
        Envelope env;
        dsp::Segment segs[] = {
            {1.0f, curve, attack_ms},
            {0.0f, curve, decay_ms},
        };
        env.gen_.configure(segs, 2, -1);
        return env;
    }
 
    /// Custom multi-segment envelope.
    static Envelope custom(const dsp::Segment* segments, uint8_t count,
                           int8_t sustain_index = -1) {
        Envelope env;
        env.gen_.configure(segments, count, sustain_index);
        return env;
    }
 
    // ── Control ───────────────────────────────────────────────────
 
    void set_sample_rate(uint32_t sr) { gen_.set_sample_rate(sr); }
 
    void gate_on()   { gen_.gate_on(); }
    void gate_off()  { gen_.gate_off(); }
    void retrigger() { gen_.retrigger(); }
 
    // ── Processing ────────────────────────────────────────────────
 
    /// Generate envelope output (float [0.0, 1.0]).
    void process(float* out, uint16_t frames) {
        gen_.process(out, frames);
    }
 
    // ── Queries ───────────────────────────────────────────────────
 
    float level() const                    { return gen_.level(); }
    bool active() const                    { return gen_.active(); }
    dsp::SegmentState state() const        { return gen_.state(); }
 
private:
    dsp::SegmentGenerator<CurveEngine> gen_;
};
 
} // namespace sbl::widgets::mod