phase_accumulator.hpp

Go to the documentation of this file.

// sbl/dsp/primitives/phase_accumulator.hpp — Phase accumulator for oscillators and LFOs
//
// 32-bit phase accumulator with natural wrapping. The full uint32_t range
// maps to one cycle (0 to just-under-2π). Frequency is set via phase
// increment per sample.
//
// Usage:
//   sbl::dsp::PhaseAccumulator phase;
//   phase.set_increment(PhaseAccumulator::freq_to_inc(440.0f));
//   phase.advance();              // single sample
//   uint32_t p = phase.phase();   // read current phase
//
// Block processing:
//   uint32_t buf[BLOCK_SIZE];
//   phase.advance(BLOCK_SIZE, buf);  // fill buffer with per-sample phases
 
#ifndef SBL_DSP_PRIMITIVES_PHASE_ACCUMULATOR_HPP_
#define SBL_DSP_PRIMITIVES_PHASE_ACCUMULATOR_HPP_
 
#include <cstdint>
 
#include <sbl/dsp/math/constants.hpp>
#include <sbl/dsp/types/fixed.hpp>
 
namespace sbl::dsp::primitives {
 
/// Full range of a 32-bit phase accumulator (2^32 as float)
using math::PHASE_ACCUMULATOR_RANGE;
 
class PhaseAccumulator {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    /**
     * @brief Set the phase increment per sample
     *
     * inc = frequency_hz * 2^32 / sample_rate
     * Use freq_to_inc() for Hz input.
     */
    void set_increment(uint32_t inc) { increment_ = inc; }
 
    /** @brief Advance phase by one sample */
    void advance() { phase_ += increment_; }
 
    /**
     * @brief Advance and fill a buffer with per-sample phases
     *
     * Each output element is the phase AFTER advancing. Useful for
     * batch wavetable reads.
     */
    void advance(uint16_t frames, uint32_t* out) {
        for (uint16_t i = 0; i < frames; ++i) {
            phase_ += increment_;
            out[i] = phase_;
        }
    }
 
    /** @brief Current phase value */
    uint32_t phase() const { return phase_; }
 
    /** @brief Current phase increment */
    uint32_t increment() const { return increment_; }
 
    /** @brief Reset phase to zero */
    void reset() { phase_ = 0; }
 
    /** @brief Reset phase to a specific value (for sync) */
    void reset(uint32_t phase) { phase_ = phase; }
 
    /**
     * @brief Convert frequency in Hz to phase increment
     *
     * @param freq_hz Frequency in Hz (e.g., 440.0f)
     * @param sr Sample rate (default: SAMPLE_RATE_F global)
     * @return Phase increment per sample
     */
    static uint32_t freq_to_inc(float freq_hz, float sr = types::SAMPLE_RATE_F) {
        return static_cast<uint32_t>((freq_hz / sr) * PHASE_ACCUMULATOR_RANGE);
    }
 
private:
    uint32_t phase_ = 0;
    uint32_t increment_ = 0;
};
 
} // namespace sbl::dsp::primitives
 
#endif // SBL_DSP_PRIMITIVES_PHASE_ACCUMULATOR_HPP_