morph_osc.hpp

Go to the documentation of this file.

// sbl/dsp/modules/morph_osc.hpp — Morphable PolyBLEP oscillator (Audio Stack — Modules)
//
// Continuously morphs between three band-limited waveforms using
// equal-power crossfade across three dedicated PolyBLEP oscillators.
// Each oscillator runs its own waveform at all times — no waveform
// swaps means no stale PolyBLEP state, no phase discontinuities.
//
// Default morph map (thin → fat):
//   Triangle (0.0) → Pulse (0.5) → Saw (1.0)
//
// The morph knob is a synthesis philosophy dial:
//   CCW = West Coast (triangle through wavefolder = Buchla)
//   Noon = bridge (pulse = transition zone)
//   CW  = East Coast (saw through filter = Moog)
//
// Pulse width affects the pulse oscillator across the morph range.
//
// AnalogDrift provides organic character — each oscillator drifts
// independently, creating subtle beating and movement when multiple
// voices are active in the crossfade region.
//
// Wavefold is deliberately excluded — it's a waveshape-domain operation
// that belongs in a separate widget (Shaper). Compose them:
//   MorphOsc → Shaper → Ladder → Delay → Reverb
//
// See FDP-034 for design rationale.
//
// Usage:
//   sbl::dsp::modules::MorphOsc osc;
//   osc.set_pitch_su(0.5f);        // mid-range pitch
//   osc.set_morph_su(0.3f);        // between triangle and pulse
//   osc.set_pulse_width_su(0.5f);  // centered
//   osc.process(buf, frames);
//
//   // With per-sample FM modulation:
//   osc.process(buf, n, fm_buf, 1.0f);  // ±1 octave FM
 
#ifndef SBL_DSP_MODULES_MORPH_OSC_HPP_
#define SBL_DSP_MODULES_MORPH_OSC_HPP_
 
#include <cstdint>
#include <cmath>
 
#include <sbl/dsp/widgets/polyblep_osc.hpp>
#include <sbl/dsp/math/interpolate.hpp>
#include <sbl/dsp/math/pitch.hpp>
#include <sbl/dsp/comp/analog_drift.hpp>
#include <sbl/dsp/types/fixed.hpp>
 
namespace sbl::dsp::modules {
 
struct MorphOscTestAccess;
 
/// Morphable PolyBLEP oscillator with three dedicated voices.
///
/// @tparam MaxFrames Maximum block size for internal scratch buffers.
///         Default 48 matches standard DMA block size.
template <uint16_t MaxFrames = 48>
class MorphOsc {
    // ---- Parameter range constants ----
    static constexpr float kMinNote = 24.0f;             // C1 (~32.7 Hz)
    static constexpr float kMaxNote = 120.0f;            // C9 (~8372 Hz)
    static constexpr float kNoteRange = kMaxNote - kMinNote;  // 96 semitones
    static constexpr float kMaxDriftSemitones = 0.10f;   // ±10 cents max
    static constexpr float kMinPW = 0.05f;
    static constexpr float kMaxPW = 0.95f;
 
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    // ---- Signal-unit inputs ----
 
    /// Set pitch from normalized signal. [0,1] → C1–C9 (MIDI 24–120).
    void set_pitch_su(float su) {
        su = (su < 0.0f) ? 0.0f : (su > 1.0f) ? 1.0f : su;
        float note = math::note_of_su(su);
        set_frequency(math::note_to_frequency(note));
    }
 
    /// Set morph position from normalized signal. [0,1] → triangle→pulse→saw.
    void set_morph_su(float su) {
        set_morph(su);
    }
 
    /// Set pulse width from normalized signal. [0,1] → [0.05, 0.95].
    void set_pulse_width_su(float su) {
        su = (su < 0.0f) ? 0.0f : (su > 1.0f) ? 1.0f : su;
        set_pulse_width(kMinPW + su * (kMaxPW - kMinPW));
    }
 
    /// Set analog drift amount from normalized signal. [0,1] → [0, 0.10] semitones.
    void set_drift_amount_su(float su) {
        su = (su < 0.0f) ? 0.0f : (su > 1.0f) ? 1.0f : su;
        set_drift_amount(su * kMaxDriftSemitones);
    }
 
    /// Set output amplitude from normalized signal. [0,1] → [0, 1].
    void set_amplitude_su(float su) {
        su = (su < 0.0f) ? 0.0f : (su > 1.0f) ? 1.0f : su;
        set_amplitude(su);
    }
 
    // ---- Non-signal configuration (kept public) ----
 
    /// Set detune offset in cents (±1200). Applied as a frequency ratio.
    void set_detune_cents(float cents) { detune_cents_ = cents; }
 
    /// Set drift control rate in Hz. Call once at init.
    void set_drift_rate(float hz) {
        drift_pulse_.set_rate(hz);
        drift_tri_.set_rate(hz);
        drift_saw_.set_rate(hz);
    }
 
    /// Advance drift state by one control tick. Call at control rate (~200 Hz).
    /// The ratios are applied internally on the next process() call.
    void tick_drift() {
        if (drift_amount_ > 0.0f) {
            drift_ratio_pulse_  = math::semitones_to_ratio(
                drift_pulse_.process(drift_amount_));
            drift_ratio_tri_ = math::semitones_to_ratio(
                drift_tri_.process(drift_amount_));
            drift_ratio_saw_ = math::semitones_to_ratio(
                drift_saw_.process(drift_amount_));
        } else {
            drift_ratio_pulse_  = 1.0f;
            drift_ratio_tri_ = 1.0f;
            drift_ratio_saw_ = 1.0f;
        }
    }
 
    /// Reset all oscillator phases and drift state to zero.
    void reset() {
        pulse_osc_.sync();
        tri_osc_.sync();
        saw_osc_.sync();
        drift_pulse_.reset();
        drift_tri_.reset();
        drift_saw_.reset();
        drift_ratio_pulse_  = 1.0f;
        drift_ratio_tri_ = 1.0f;
        drift_ratio_saw_ = 1.0f;
    }
 
    /// Render block, optionally with per-sample FM modulation.
    ///
    /// When fm_mod is provided, per-sample exponential FM is applied around
    /// the stored frequency (set via set_pitch_su / set_frequency):
    ///   freq = apply_detune(freq_hz_) * 2^(fm_mod[i] * fm_depth)
    ///
    /// @param out      Output buffer
    /// @param frames   Number of samples
    /// @param fm_mod   FM modulation signal [-1,1] (nullptr = no modulation)
    /// @param fm_depth FM depth in octaves (e.g., 1.0 = ±1 octave)
    void process(float* out, uint16_t frames,
                 const float* fm_mod = nullptr, float fm_depth = 0.0f) {
        uint16_t n = (frames > MaxFrames) ? MaxFrames : frames;
 
        if (fm_mod != nullptr) {
            // Per-sample FM modulation
            float base = apply_detune(freq_hz_);
            float g_tri, g_pulse, g_saw;
            compute_gains(g_tri, g_pulse, g_saw);
            float comp = compute_morph_compensation();
 
            for (uint16_t i = 0; i < n; ++i) {
                float freq = base * math::fast_exp2f(fm_mod[i] * fm_depth);
                if (freq < 0.1f) freq = 0.1f;
 
                if (g_tri > 0.0f) {
                    tri_osc_.set_frequency(freq * drift_ratio_tri_);
                    tri_osc_.process(buf_tri_ + i, 1);
                }
                if (g_pulse > 0.0f) {
                    pulse_osc_.set_frequency(freq * drift_ratio_pulse_);
                    pulse_osc_.process(buf_pulse_ + i, 1);
                }
                if (g_saw > 0.0f) {
                    saw_osc_.set_frequency(freq * drift_ratio_saw_);
                    saw_osc_.process(buf_saw_ + i, 1);
                }
            }
 
            // Mix with computed gains + morph compensation
            for (uint16_t i = 0; i < n; ++i) {
                float s = 0.0f;
                if (g_tri > 0.0f) s += buf_tri_[i] * g_tri;
                if (g_pulse > 0.0f) s += buf_pulse_[i] * g_pulse;
                if (g_saw > 0.0f) s += buf_saw_[i] * g_saw;
                s *= comp;
                if (s > 1.0f) s = 1.0f;
                else if (s < -1.0f) s = -1.0f;
                out[i] = s;
            }
        } else {
            // No modulation — block render at current frequency
            float freq = apply_detune(freq_hz_);
            pulse_osc_.set_frequency(freq * drift_ratio_pulse_);
            tri_osc_.set_frequency(freq * drift_ratio_tri_);
            saw_osc_.set_frequency(freq * drift_ratio_saw_);
 
            render_morphed(out, n);
        }
    }
 
private:
    // ---- Engineering-unit setters (private, used by _su methods and tests) ----
 
    /// Set base frequency in Hz.
    void set_frequency(float hz) { freq_hz_ = hz; }
 
    /// Set morph position [0.0, 1.0].
    void set_morph(float morph) {
        morph_ = (morph < 0.0f) ? 0.0f : (morph > 1.0f) ? 1.0f : morph;
    }
 
    /// Set pulse width [0.05, 0.95]. Affects the pulse oscillator.
    void set_pulse_width(float pw) {
        pulse_osc_.set_pulse_width(pw);
    }
 
    /// Set analog drift amount in semitones.
    void set_drift_amount(float semitones) { drift_amount_ = semitones; }
 
    /// Set output amplitude (0.0 = silence, 1.0 = full scale).
    void set_amplitude(float amp) {
        pulse_osc_.set_amplitude(amp);
        tri_osc_.set_amplitude(amp);
        saw_osc_.set_amplitude(amp);
    }
 
    friend struct MorphOscTestAccess;
 
    // Three dedicated oscillators — waveforms set at construction, never change.
    widgets::PolyBlepOsc pulse_osc_{widgets::Waveform::Pulse};
    widgets::PolyBlepOsc tri_osc_{widgets::Waveform::Triangle};
    widgets::PolyBlepOsc saw_osc_{widgets::Waveform::Saw};
 
    float freq_hz_      = 220.0f;
    float morph_        = 0.0f;
    float detune_cents_ = 0.0f;
 
    // Analog drift — independent per oscillator for three-way beating.
    // Seeds chosen to be coprime and spread across the state space.
    comp::AnalogDrift drift_pulse_{0x12345678u};
    comp::AnalogDrift drift_tri_{0x9ABCDEF0u};
    comp::AnalogDrift drift_saw_{0xDEADBEEFu};
    float drift_amount_    = 0.0f;
    float drift_ratio_pulse_  = 1.0f;
    float drift_ratio_tri_ = 1.0f;
    float drift_ratio_saw_ = 1.0f;
 
    // Internal scratch buffers for three-osc render
    float buf_pulse_[MaxFrames];
    float buf_tri_[MaxFrames];
    float buf_saw_[MaxFrames];
 
    /// Apply detune offset to a base frequency.
    float apply_detune(float hz) const {
        if (detune_cents_ == 0.0f) return hz;
        return hz * math::semitones_to_ratio(detune_cents_ / 100.0f);
    }
 
    /// Compute per-oscillator gains from morph position.
    /// Ordering: Triangle (0.0) → Pulse (0.5) → Saw (1.0)
    void compute_gains(float& g_tri, float& g_pulse, float& g_saw) {
        if (morph_ <= 0.5f) {
            float t = morph_ * 2.0f;
            g_tri = sqrtf(1.0f - t);
            g_pulse = sqrtf(t);
            g_saw = 0.0f;
        } else {
            float t = (morph_ - 0.5f) * 2.0f;
            g_tri = 0.0f;
            g_pulse = sqrtf(1.0f - t);
            g_saw = sqrtf(t);
        }
    }
 
    /// Post-mix gain compensation for equal perceived loudness across morph.
    /// Pulse (RMS=1.0) is louder than tri/saw (RMS=1/√3). Without compensation,
    /// sweeping through the pulse region creates a volume hump. This normalizes
    /// the expected RMS to match the tri/saw level at all morph positions.
    float compute_morph_compensation() const {
        static constexpr float kTriSawRms2 = 1.0f / 3.0f;
        static constexpr float kPulseRms2  = 1.0f;
        float rms2;
        if (morph_ <= 0.5f) {
            float t = morph_ * 2.0f;
            rms2 = (1.0f - t) * kTriSawRms2 + t * kPulseRms2;
        } else {
            float t = (morph_ - 0.5f) * 2.0f;
            rms2 = (1.0f - t) * kPulseRms2 + t * kTriSawRms2;
        }
        return sqrtf(kTriSawRms2 / rms2);
    }
 
    /// Render all active oscillators and mix with morph gains.
    void render_morphed(float* out, uint16_t n) {
        float g_tri, g_pulse, g_saw;
        compute_gains(g_tri, g_pulse, g_saw);
        float comp = compute_morph_compensation();
 
        if (g_tri > 0.0f) tri_osc_.process(buf_tri_, n);
        if (g_pulse > 0.0f) pulse_osc_.process(buf_pulse_, n);
        if (g_saw > 0.0f) saw_osc_.process(buf_saw_, n);
 
        for (uint16_t i = 0; i < n; ++i) {
            float s = 0.0f;
            if (g_tri > 0.0f) s += buf_tri_[i] * g_tri;
            if (g_pulse > 0.0f) s += buf_pulse_[i] * g_pulse;
            if (g_saw > 0.0f) s += buf_saw_[i] * g_saw;
            s *= comp;
            if (s > 1.0f) s = 1.0f;
            else if (s < -1.0f) s = -1.0f;
            out[i] = s;
        }
    }
 
};
 
} // namespace sbl::dsp::modules
 
#endif // SBL_DSP_MODULES_MORPH_OSC_HPP_