polyblep_osc.hpp

Go to the documentation of this file.

// sbl/widgets/source/polyblep_osc.hpp — PolyBLEP oscillator (Audio Stack — Widgets)
//
// Band-limited saw, square, triangle, and pulse waveforms using polynomial
// band-limited step (PolyBLEP) correction at discontinuities. Zero flash
// cost — no lookup tables needed.
//
// Saw/Square/Pulse use 2nd-order PolyBLEP at step discontinuities.
// Triangle uses 4th-order Integrated PolyBLEP at slope discontinuities,
// directly band-limiting the naive triangle without a post-filter.
//
// Adapted from Mutable Instruments Plaits oscillator.h and Warps
// oscillator.cc (MIT license, Copyright 2014-2016 Emilie Gillet).
// PolyBLEP math from stmlib/dsp/polyblep.h.
//
// Usage:
//   sbl::widgets::source::PolyBlepOsc osc;
//   osc.set_waveform(Waveform::Saw);
//   osc.set_frequency(440.0f);
//   osc.process(buf, frames);
 
#pragma once
 
#include <cstdint>
 
#include <sbl/dsp/polyblep.hpp>
#include <sbl/dsp/pitch.hpp>
 
namespace sbl::widgets::source {
 
enum class Waveform : uint8_t {
    Saw,
    Square,
    Triangle,
    Pulse,
};
 
class PolyBlepOsc {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /** @brief Set active waveform */
    void set_waveform(Waveform w) { waveform_ = w; }
 
    /**
     * @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) {
        frequency_ = freq_hz / sr;
    }
 
    /**
     * @brief Set frequency from MIDI note number (requires FPU)
     * @param midi_note MIDI note (69 = A4 = 440 Hz)
     * @param sample_rate Sample rate
     */
    void set_note(float midi_note, float sample_rate = 48000.0f) {
        frequency_ = dsp::note_to_frequency(midi_note) / sample_rate;
    }
 
    /**
     * @brief Set pulse width (only affects Pulse waveform)
     * @param pw Pulse width, clamped to [0.05, 0.95]. Default 0.5.
     */
    void set_pulse_width(float pw) {
        pw_ = (pw < 0.05f) ? 0.05f : (pw > 0.95f) ? 0.95f : pw;
    }
 
    /** @brief Set output amplitude (0.0 = silence, 1.0 = full scale) */
    void set_amplitude(float amp) { amplitude_ = amp; }
 
    /**
     * @brief Generate audio samples
     * @param out Output buffer (float, [-1.0, 1.0])
     * @param frames Number of samples
     */
    void process(float* out, uint16_t frames) {
        uint16_t pos = 0;
        while (pos < frames) {
            uint16_t n = frames - pos;
            if (n > MAX_BLOCK) n = MAX_BLOCK;
            render_float(out + pos, n);
            if (amplitude_ != 1.0f) {
                for (uint16_t i = 0; i < n; ++i) {
                    out[pos + i] *= amplitude_;
                }
            }
            pos += n;
        }
    }
 
    /** @brief Hard sync — reset phase to zero */
    void sync() {
        phase_ = 0.0f;
        next_sample_ = 0.0f;
        high_ = true;
    }
 
    /** @brief Reset phase to a specific value (0.0–1.0) */
    void sync(float phase) {
        phase_ = phase;
        next_sample_ = 0.0f;
    }
 
    /** @brief Current phase as uint32_t (for API compatibility with WavetableOsc) */
    uint32_t phase() const {
        return static_cast<uint32_t>(phase_ * 4294967296.0f);
    }
 
    /** @brief Current normalized frequency (freq_hz / sample_rate) */
    float frequency() const { return frequency_; }
 
private:
    static constexpr uint16_t MAX_BLOCK = 48;
 
    float phase_ = 0.0f;
    float frequency_ = 0.0f;
    float pw_ = 0.5f;
    float next_sample_ = 0.0f;
    bool high_ = true;
    Waveform waveform_ = Waveform::Saw;
    float amplitude_ = 1.0f;
 
    // -------------------------------------------------------------------------
    // Dispatch to waveform-specific float render
    // -------------------------------------------------------------------------
    void render_float(float* out, uint16_t frames) {
        switch (waveform_) {
            case Waveform::Saw:      render_saw_f(out, frames); break;
            case Waveform::Square:   render_square_f(out, frames, 0.5f); break;
            case Waveform::Triangle: render_triangle_f(out, frames); break;
            case Waveform::Pulse:    render_square_f(out, frames, pw_); break;
        }
    }
 
    // -------------------------------------------------------------------------
    // Saw — single discontinuity at phase wrap (Warps lines 141-155)
    // -------------------------------------------------------------------------
    void render_saw_f(float* out, uint16_t frames) {
        using namespace dsp::polyblep;
        float phase = phase_;
        float next = next_sample_;
        float freq = frequency_;
 
        for (uint16_t i = 0; i < frames; ++i) {
            float this_sample = next;
            next = 0.0f;
 
            phase += freq;
            if (phase >= 1.0f) {
                phase -= 1.0f;
                float t = phase / freq;
                this_sample -= this_blep(t);
                next -= next_blep(t);
            }
            next += phase;
            this_sample = 2.0f * this_sample - 1.0f;
 
            out[i] = clamp(this_sample);
        }
        phase_ = phase;
        next_sample_ = next;
    }
 
    // -------------------------------------------------------------------------
    // Square / Pulse — two edges per cycle
    // -------------------------------------------------------------------------
    void render_square_f(float* out, uint16_t frames, float pw) {
        using namespace dsp::polyblep;
        float phase = phase_;
        float next = next_sample_;
        float freq = frequency_;
        bool high = high_;
 
        float fall_at = pw;
 
        for (uint16_t i = 0; i < frames; ++i) {
            float this_sample = next;
            next = 0.0f;
 
            phase += freq;
 
            // Falling edge at duty cycle boundary
            if (high && phase >= fall_at) {
                float t = (phase - fall_at) / freq;
                this_sample -= this_blep(t);
                next -= next_blep(t);
                high = false;
            }
            // Rising edge at phase wrap
            if (phase >= 1.0f) {
                phase -= 1.0f;
                float t = phase / freq;
                this_sample += this_blep(t);
                next += next_blep(t);
                high = true;
            }
 
            next += high ? 1.0f : 0.0f;
            this_sample = 2.0f * this_sample - 1.0f;
 
            out[i] = clamp(this_sample);
        }
        phase_ = phase;
        next_sample_ = next;
        high_ = high;
    }
 
    // -------------------------------------------------------------------------
    // Triangle — Integrated PolyBLEP on slope discontinuities
    // -------------------------------------------------------------------------
    void render_triangle_f(float* out, uint16_t frames) {
        using namespace dsp::polyblep;
        float phase = phase_;
        float next = next_sample_;
        float freq = frequency_;
        bool high = high_;
 
        constexpr float slope_up = 2.0f;
        constexpr float slope_down = 2.0f;
        const float discontinuity = (slope_up + slope_down) * freq;
 
        for (uint16_t i = 0; i < frames; ++i) {
            float this_sample = next;
            next = 0.0f;
 
            phase += freq;
 
            // Slope change at midpoint (rising → falling)
            if (high ^ (phase < 0.5f)) {
                float t = (phase - 0.5f) / freq;
                this_sample -= this_integrated_blep(t) * discontinuity;
                next -= next_integrated_blep(t) * discontinuity;
                high = phase < 0.5f;
            }
            // Slope change at wrap (falling → rising)
            if (phase >= 1.0f) {
                phase -= 1.0f;
                float t = phase / freq;
                this_sample += this_integrated_blep(t) * discontinuity;
                next += next_integrated_blep(t) * discontinuity;
                high = true;
            }
 
            // Naive triangle: rises [0, 0.5) then falls [0.5, 1.0)
            next += high
                ? phase * slope_up
                : 1.0f - (phase - 0.5f) * slope_down;
 
            out[i] = clamp(2.0f * this_sample - 1.0f);
        }
        phase_ = phase;
        next_sample_ = next;
        high_ = high;
    }
 
    // -------------------------------------------------------------------------
    // Float clamp to [-1, 1]
    // -------------------------------------------------------------------------
    static float clamp(float s) {
        return (s > 1.0f) ? 1.0f : (s < -1.0f) ? -1.0f : s;
    }
};
 
} // namespace sbl::widgets::source