segment.hpp

Go to the documentation of this file.

// sbl/dsp/segment.hpp — Multi-segment envelope generator (float)
//
// SegmentGenerator advances through a sequence of timed segments, each
// interpolating between a start level and a target level with a curve-shaped
// phase. An optional sustain index causes the generator to hold after that
// segment completes, resuming on gate_off().
//
// The curve engine is selected at compile time via template parameter —
// zero runtime overhead, no vtables.
//
// All values are float: levels [0.0, 1.0], curve [-1.0, 1.0], time in ms.
//
// See FDP-014 and FDP-016 for design rationale.
 
#pragma once
 
#include <cstdint>
 
#include <sbl/dsp/warp.hpp>
 
namespace sbl::dsp {
 
// ─── Segment ──────────────────────────────────────────────────────────
 
struct Segment {
    float target;      // Target level [0.0, 1.0]
    float curve;       // Shape: -1.0 = concave, 0.0 = linear, 1.0 = convex
    float time_ms;     // Duration in milliseconds (0 = instant)
};
 
// ─── State ────────────────────────────────────────────────────────────
 
enum class SegmentState : uint8_t {
    Idle,       // Output held at 0, waiting for gate_on
    Running,    // Advancing through a timed segment
    Sustain,    // Holding level until gate_off
    Complete    // All segments finished, output held at final level
};
 
// ─── SegmentGenerator ─────────────────────────────────────────────────
//
// Template on CurveEngine for compile-time selection of curve shaping.
// Default is FloatRationalWarp (zero flash, analytical, good character).
 
template<typename CurveEngine = FloatDefaultWarp>
class SegmentGenerator {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    static constexpr uint8_t MAX_SEGMENTS = 8;
 
    // ── Configuration ─────────────────────────────────────────────
 
    /// Configure the segment sequence.
    /// @param segments  Array of segments (copied internally, up to MAX_SEGMENTS)
    /// @param count     Number of segments
    /// @param sustain_index  Segment index to hold at (-1 = no sustain)
    void configure(const Segment* segments, uint8_t count, int8_t sustain_index = -1) {
        segment_count_ = (count > MAX_SEGMENTS) ? MAX_SEGMENTS : count;
        for (uint8_t i = 0; i < segment_count_; ++i) {
            segments_[i] = segments[i];
        }
        sustain_index_ = sustain_index;
        reset();
    }
 
    void set_sample_rate(uint32_t sr) { sample_rate_ = static_cast<float>(sr); }
 
    // ── Gate control ──────────────────────────────────────────────
 
    /// Start the envelope from segment 0. If already running, restarts
    /// from the current level (retrigger behavior).
    void gate_on() {
        if (segment_count_ == 0) return;
        start_level_ = (state_ == SegmentState::Idle) ? 0.0f : level_;
        state_ = SegmentState::Running;
        begin_segment(0);
    }
 
    /// Release the envelope. If in sustain, jumps to the next segment
    /// (typically release). If running pre-sustain, jumps to release.
    /// If no sustain configured, does nothing.
    void gate_off() {
        if (sustain_index_ < 0) return;
 
        uint8_t release_index = static_cast<uint8_t>(sustain_index_ + 1);
        if (release_index >= segment_count_) return;
 
        if (state_ == SegmentState::Sustain ||
            (state_ == SegmentState::Running && current_index_ <= sustain_index_)) {
            start_level_ = level_;
            state_ = SegmentState::Running;
            begin_segment(release_index);
        }
    }
 
    /// Retrigger: restart from current level without requiring gate_off first.
    void retrigger() {
        if (segment_count_ == 0) return;
        start_level_ = level_;
        state_ = SegmentState::Running;
        begin_segment(0);
    }
 
    // ── Processing ────────────────────────────────────────────────
 
    /// Fill output buffer with envelope levels (float [0.0, 1.0]).
    void process(float* out, uint16_t frames) {
        for (uint16_t i = 0; i < frames; ++i) {
            if (state_ == SegmentState::Running) {
                float next_phase = phase_ + phase_increment_;
                if (next_phase >= 1.0f) {
                    // Segment complete — snap to target
                    level_ = segments_[current_index_].target;
                    start_level_ = level_;
                    advance_to_next();
                } else {
                    phase_ = next_phase;
                    level_ = compute_level(phase_);
                }
            }
            out[i] = level_;
        }
    }
 
    // ── Queries ───────────────────────────────────────────────────
 
    float level() const { return level_; }
 
    bool active() const {
        return state_ != SegmentState::Idle && state_ != SegmentState::Complete;
    }
 
    SegmentState state() const { return state_; }
    uint8_t current_segment_index() const { return current_index_; }
 
private:
    // ── Segment storage ───────────────────────────────────────────
    Segment segments_[MAX_SEGMENTS] = {};
    uint8_t segment_count_ = 0;
    int8_t sustain_index_ = -1;
 
    // ── Runtime state ─────────────────────────────────────────────
    uint8_t current_index_ = 0;
    SegmentState state_ = SegmentState::Idle;
    float level_ = 0.0f;
    float start_level_ = 0.0f;
    float phase_ = 0.0f;
    float phase_increment_ = 0.0f;
    float sample_rate_ = 48000.0f;
 
    // ── Internal helpers ──────────────────────────────────────────
 
    void reset() {
        state_ = SegmentState::Idle;
        level_ = 0.0f;
        start_level_ = 0.0f;
        current_index_ = 0;
        phase_ = 0.0f;
        phase_increment_ = 0.0f;
    }
 
    void begin_segment(uint8_t index) {
        current_index_ = index;
        phase_ = 0.0f;
 
        // Instant segment: snap to target and advance
        if (segments_[index].time_ms <= 0.0f) {
            level_ = segments_[index].target;
            start_level_ = level_;
            advance_to_next();
            return;
        }
 
        float time_samples = segments_[index].time_ms * 0.001f * sample_rate_;
        phase_increment_ = 1.0f / time_samples;
    }
 
    void advance_to_next() {
        // Check for sustain hold
        if (current_index_ == sustain_index_) {
            state_ = SegmentState::Sustain;
            return;
        }
 
        // Move to next segment
        uint8_t next = current_index_ + 1;
        if (next >= segment_count_) {
            state_ = SegmentState::Complete;
            return;
        }
 
        begin_segment(next);
    }
 
    float compute_level(float phase) const {
        float warped = CurveEngine::warp(phase, segments_[current_index_].curve);
        return start_level_ + (segments_[current_index_].target - start_level_) * warped;
    }
};
 
} // namespace sbl::dsp