scanning_osc.hpp

Go to the documentation of this file.

// sbl/widgets/source/scanning_osc.hpp — Scanning wavetable oscillator (Audio Stack — Widgets)
//
// Crossfades between multiple registered wavetables via a scan position.
// Composes PhaseAccumulator + lut::crossfade into a morphing oscillator.
//
// Usage:
//   sbl::widgets::source::ScanningOsc<256, 4> osc;
//   osc.add_table(sbl::dsp::lut::saw_256);
//   osc.add_table(sbl::dsp::lut::square_256);
//   osc.add_table(sbl::dsp::lut::triangle_256);
//   osc.add_table(sbl::dsp::lut::sin_256);
//   osc.set_scan(0.0f);       // Pure saw
//   osc.set_scan(1.0f);       // Pure sin
//   osc.set_scan(0.5f);       // Crossfade midpoint
//   osc.set_frequency(440.0f);
//   osc.process(buf, frames);
 
#pragma once
 
#include <cstdint>
 
#include <sbl/dsp/phase.hpp>
#include <sbl/dsp/lut.hpp>
#include <sbl/dsp/pitch.hpp>
 
namespace sbl::widgets::source {
 
template<uint16_t TableSize, uint8_t MaxTables = 8>
class ScanningOsc {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /**
     * @brief Register a wavetable in scan order
     * @param table Pointer to float table data (must have guard points)
     * @return true if added, false if at capacity
     */
    bool add_table(const float* table) {
        if (count_ >= MaxTables) return false;
        tables_[count_++] = table;
        return true;
    }
 
    /**
     * @brief Set scan position
     * @param position 0.0 = first table, 1.0 = last table
     */
    void set_scan(float position) { scan_pos_ = position; }
 
    /**
     * @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) {
        phase_.set_increment(dsp::PhaseAccumulator::freq_to_inc(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) {
        phase_.set_increment(dsp::note_to_phase_increment(midi_note, sample_rate));
    }
 
    /** @brief Set phase increment directly */
    void set_increment(uint32_t inc) { phase_.set_increment(inc); }
 
    /** @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) {
        if (count_ == 0) {
            for (uint16_t i = 0; i < frames; ++i) out[i] = 0.0f;
            return;
        }
 
        // Precompute scan table pair and balance
        uint8_t idx_a;
        uint8_t idx_b;
        float balance;
        compute_scan(idx_a, idx_b, balance);
 
        const float* ta = tables_[idx_a];
        const float* tb = tables_[idx_b];
 
        for (uint16_t i = 0; i < frames; ++i) {
            phase_.advance();
            float s;
            if (idx_a == idx_b) {
                s = dsp::lut::lookup_linear<TableSize>(ta, phase_.phase());
            } else {
                s = dsp::lut::crossfade<TableSize>(ta, tb, phase_.phase(), balance);
            }
            out[i] = s * amplitude_;
        }
    }
 
    /** @brief Hard sync — reset phase to zero */
    void sync() { phase_.reset(); }
 
    /** @brief Current phase */
    uint32_t phase() const { return phase_.phase(); }
 
    /** @brief Current phase increment */
    uint32_t increment() const { return phase_.increment(); }
 
    /** @brief Number of registered tables */
    uint8_t table_count() const { return count_; }
 
private:
    void compute_scan(uint8_t& idx_a, uint8_t& idx_b, float& balance) const {
        if (count_ == 1) {
            idx_a = 0;
            idx_b = 0;
            balance = 0.0f;
            return;
        }
        // Scale scan_pos [0.0, 1.0] across (count_-1) intervals
        float pos = scan_pos_;
        if (pos < 0.0f) pos = 0.0f;
        if (pos > 1.0f) pos = 1.0f;
        float scaled = pos * static_cast<float>(count_ - 1);
        idx_a = static_cast<uint8_t>(scaled);
        if (idx_a >= count_ - 1) {
            idx_a = count_ - 2;
            idx_b = count_ - 1;
            balance = 1.0f;
        } else {
            idx_b = idx_a + 1;
            balance = scaled - static_cast<float>(idx_a);
        }
    }
 
    dsp::PhaseAccumulator phase_;
    const float* tables_[MaxTables] = {};
    float amplitude_ = 1.0f;
    float scan_pos_ = 0.0f;
    uint8_t count_ = 0;
};
 
} // namespace sbl::widgets::source