lfo.hpp

Go to the documentation of this file.

// sbl/dsp/comp/lfo.hpp — Low Frequency Oscillator (Audio Stack — Compositions)
//
// Sub-audio modulation source. Composes PhaseAccumulator + WavetableReader
// with amplitude scaling. Output is normalized bipolar (-depth to +depth).
//
// The LFO outputs a domain-neutral signal — it doesn't know what it's
// modulating. The conversion to domain-specific units (Hz, octaves, etc.)
// belongs at the modulation application point, not here. This matches the
// analog modular convention: LFO outputs a voltage, the destination module
// interprets it via its exponential converter (V/Oct) or linear VCA.
//
// Signal-unit inputs (FDP-052):
//   lfo.set_rate_su(0.5f);         // [0,1] → 0.05–30 Hz (exponential)
//   lfo.set_depth_su(0.8f);        // [0,1] → output amplitude
//
// Depth controls output amplitude: 1.0 = full ±1.0 swing. Do NOT encode
// destination units into depth. Apply domain conversion at the destination:
//
//   lfo.set_depth_su(1.0f);        // ±1.0 normalized signal
//   filter.process(buf, n, lfo_buf, 2.0f);  // ±2 octaves around smoothed center
//
// See FDP-031 (Signal layer) and FDP-052 for architectural rationale.
 
#ifndef SBL_DSP_COMP_LFO_HPP_
#define SBL_DSP_COMP_LFO_HPP_
 
#include <cstdint>
 
#include <sbl/dsp/math/fast_math.hpp>
#include <sbl/dsp/primitives/phase_accumulator.hpp>
#include <sbl/dsp/primitives/wavetable_reader.hpp>
#include <sbl/dsp/types/fixed.hpp>
 
namespace sbl::dsp::comp {
 
struct LfoTestAccess;
 
template<uint16_t TableSize>
class Lfo {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    // ── Configuration ───────────────────────────────────────────
 
    /** @brief Set wavetable (must have guard points for interpolation) */
    void set_wavetable(const float* table) { reader_.set_table(table); }
 
    /** @brief Set phase increment directly */
    void set_increment(uint32_t inc) { phase_.set_increment(inc); }
 
    // ── Signal-unit inputs ──────────────────────────────────────
 
    /**
     * @brief Set LFO rate from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — exponential map to 0.05–30 Hz
     *
     * Exponential mapping gives fine resolution at low rates (slow sweeps)
     * and coarser control at high rates (fast vibrato/tremolo).
     */
    void set_rate_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        float hz = kMinRateHz * math::fast_exp2f(su * kRateOctaves);
        set_rate(hz);
    }
 
    /**
     * @brief Set output amplitude from normalized [0,1] signal unit
     * @param su Unipolar [0,1] — linear map to depth 0–1
     */
    void set_depth_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        set_depth(su);
    }
 
    // ── Processing ──────────────────────────────────────────────
 
    /**
     * @brief Generate modulation signal (bipolar: -depth to +depth)
     * @param out Output buffer (float)
     * @param frames Number of samples
     */
    void process(float* out, uint16_t frames) {
        for (uint16_t i = 0; i < frames; ++i) {
            phase_.advance();
            out[i] = reader_.read(phase_.phase()) * depth_;
        }
    }
 
    /** @brief Hard sync — reset phase to zero */
    void sync() { phase_.reset(); }
 
    // ── Queries ─────────────────────────────────────────────────
 
    /** @brief Current LFO value (bipolar, float) */
    float value() const {
        return reader_.read(phase_.phase()) * depth_;
    }
 
    /** @brief Current phase */
    uint32_t phase() const { return phase_.phase(); }
 
    /** @brief Current phase increment */
    uint32_t increment() const { return phase_.increment(); }
 
private:
    friend struct LfoTestAccess;
 
    // ── Rate mapping constants ──────────────────────────────────
    static constexpr float kMinRateHz = 0.05f;
    static constexpr float kMaxRateHz = 30.0f;
    static constexpr float kRateOctaves = 9.228819f;  // log2(30/0.05)
 
    // ── Engineering-unit setters (private — use _su inputs) ─────
 
    void set_rate(float freq_hz) {
        phase_.set_increment(
            primitives::PhaseAccumulator::freq_to_inc(freq_hz, types::SAMPLE_RATE_F));
    }
 
    void set_depth(float depth) { depth_ = depth; }
 
    // ── State ───────────────────────────────────────────────────
    primitives::PhaseAccumulator phase_;
    primitives::WavetableReader<TableSize> reader_;
    float depth_ = 1.0f;
};
 
} // namespace sbl::dsp::comp
 
#endif // SBL_DSP_COMP_LFO_HPP_