supersaw_osc.hpp

Go to the documentation of this file.

// sbl/widgets/source/supersaw_osc.hpp — SuperSaw oscillator (Audio Stack — Widgets)
//
// Three PolyBLEP saws — center pitch plus two detuned copies — with
// configurable stereo spread. The classic JP-8000 "super saw" sound,
// scaled to 3 oscillators for embedded CPU budgets.
//
// Detuned copies are offset symmetrically in cents from the center
// pitch. Stereo spread pans them into the stereo field: 0% = mono,
// 100% = hard L/R. The center always stays centered.
//
// Float-domain rendering pipeline: PolyBLEP renders to float,
// pan_mix() accumulates in float, output is float.
//
// Usage:
//   sbl::widgets::source::SuperSawOsc osc;
//   osc.set_note(60.0f);           // Middle C
//   osc.set_detune(15.0f);         // 15 cents spread
//   osc.set_stereo_spread(0.5f);   // 50% stereo width
//
//   // In audio callback:
//   float left[48] = {}, right[48] = {};
//   osc.process_stereo(left, right, frames);  // accumulates into L/R
 
#pragma once
 
#include <cstdint>
 
#include <sbl/dsp/stereo.hpp>
#include <sbl/widgets/source/polyblep_osc.hpp>
 
namespace sbl::widgets::source {
 
class SuperSawOsc {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    SuperSawOsc() {
        set_amplitude(amplitude_);
    }
 
    /**
     * @brief Set pitch from MIDI note number
     * @param midi_note MIDI note (69 = A4 = 440 Hz)
     * @param sample_rate Sample rate (default 48000)
     */
    void set_note(float midi_note, float sample_rate = 48000.0f) {
        note_ = midi_note;
        sample_rate_ = sample_rate;
        recompute_frequencies();
    }
 
    /**
     * @brief Set frequency in Hz
     * @param freq_hz Frequency in Hz (e.g., 440.0f)
     * @param sr Sample rate (default 48000)
     */
    void set_frequency(float freq_hz, float sr = 48000.0f) {
        center_.set_frequency(freq_hz, sr);
        note_ = 69.0f + 12.0f * log2f(freq_hz / 440.0f);
        sample_rate_ = sr;
        recompute_detuned();
    }
 
    /**
     * @brief Set detune spread in cents
     * @param cents Detune spread in cents (0–50 typical)
     */
    void set_detune(float cents) {
        detune_cents_ = cents;
        recompute_detuned();
    }
 
    /**
     * @brief Set stereo spread
     * @param spread 0.0 = mono (all center), 1.0 = hard L/R
     */
    void set_stereo_spread(float spread) {
        if (spread == stereo_spread_) return;
        stereo_spread_ = spread;
        recompute_pan();
    }
 
    /**
     * @brief Set output amplitude
     *
     * Amplitude is distributed equally across the 3 oscillators
     * so their sum doesn't exceed the specified level.
     *
     * @param amp Float amplitude (default 1.0)
     */
    void set_amplitude(float amp) {
        amplitude_ = amp;
        float per_osc = amp / 3.0f;
        center_.set_amplitude(per_osc);
        left_.set_amplitude(per_osc);
        right_.set_amplitude(per_osc);
    }
 
    /**
     * @brief Render into stereo float buffers (accumulating)
     *
     * ACCUMULATES into left[] and right[] — caller must zero the
     * buffers before the first voice when mixing multiple SuperSaws.
     *
     * @param left  Left output buffer (float, += semantics)
     * @param right Right output buffer (float, += semantics)
     * @param frames Number of samples
     */
    void process_stereo(float* left, float* right, uint16_t frames) {
        uint16_t n = (frames > MAX_BLOCK) ? MAX_BLOCK : frames;
 
        float fbuf[MAX_BLOCK];
        float fleft[MAX_BLOCK] = {};
        float fright[MAX_BLOCK] = {};
 
        // Center → center pan
        center_.process(fbuf, n);
        dsp::stereo::pan_mix(fbuf, fleft, fright, panf_center_, n);
 
        // Left-detuned → left pan
        left_.process(fbuf, n);
        dsp::stereo::pan_mix(fbuf, fleft, fright, panf_left_, n);
 
        // Right-detuned → right pan
        right_.process(fbuf, n);
        dsp::stereo::pan_mix(fbuf, fleft, fright, panf_right_, n);
 
        // Accumulate into output
        for (uint16_t i = 0; i < n; ++i) {
            left[i]  += fleft[i];
            right[i] += fright[i];
        }
    }
 
    /**
     * @brief Render mono (sum of all 3 saws)
     *
     * Does NOT accumulate — overwrites output.
     *
     * @param out Output buffer (float, overwritten)
     * @param frames Number of samples
     */
    void process(float* out, uint16_t frames) {
        uint16_t n = (frames > MAX_BLOCK) ? MAX_BLOCK : frames;
 
        center_.process(out, n);
 
        float buf[MAX_BLOCK];
        left_.process(buf, n);
        for (uint16_t i = 0; i < n; ++i) out[i] += buf[i];
 
        right_.process(buf, n);
        for (uint16_t i = 0; i < n; ++i) out[i] += buf[i];
    }
 
    /** @brief Hard sync — reset all oscillator phases */
    void sync() {
        center_.sync();
        left_.sync();
        right_.sync();
    }
 
    /** @brief Current center frequency (normalized, for diagnostics) */
    float frequency() const { return center_.frequency(); }
 
    /** @brief Current detune in cents */
    float detune() const { return detune_cents_; }
 
    /** @brief Current stereo spread */
    float stereo_spread() const { return stereo_spread_; }
 
private:
    static constexpr uint16_t MAX_BLOCK = 48;
 
    PolyBlepOsc center_;
    PolyBlepOsc left_;
    PolyBlepOsc right_;
 
    float note_ = 60.0f;
    float sample_rate_ = 48000.0f;
    float detune_cents_ = 0.0f;
    float stereo_spread_ = 0.0f;
    float amplitude_ = 1.0f;
 
    // Pan gains for stereo pipeline
    dsp::stereo::PanGain panf_center_ = dsp::stereo::constant_power(0.5f);
    dsp::stereo::PanGain panf_left_   = dsp::stereo::constant_power(0.5f);
    dsp::stereo::PanGain panf_right_  = dsp::stereo::constant_power(0.5f);
 
    void recompute_frequencies() {
        center_.set_note(note_, sample_rate_);
        recompute_detuned();
    }
 
    void recompute_detuned() {
        float offset = detune_cents_ / 100.0f;  // cents → semitones
        left_.set_note(note_ - offset, sample_rate_);
        right_.set_note(note_ + offset, sample_rate_);
    }
 
    void recompute_pan() {
        float half = stereo_spread_ * 0.5f;
        panf_center_ = dsp::stereo::constant_power(0.5f);
        panf_left_   = dsp::stereo::constant_power(0.5f - half);
        panf_right_  = dsp::stereo::constant_power(0.5f + half);
    }
};
 
} // namespace sbl::widgets::source