Phasor.h

Go to the documentation of this file.

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#include "DspMath.h"
#include "AudioSpec.h"
 
#include <cmath>
#include <limits>
 
namespace dspark {
 
template <FloatType T>
class Phasor
{
public:
    void prepare(double sampleRate) noexcept
    {
        if (!(sampleRate > 0.0)) return; // Reject non-positive and NaN
 
        sampleRate_ = sampleRate;
        invSampleRate_ = 1.0 / sampleRate;
        updateIncrement();
    }
 
    void prepare(const AudioSpec& spec) noexcept { prepare(spec.sampleRate); }
 
    void setFrequency(T frequencyHz) noexcept
    {
        if (frequencyHz != frequencyHz) return; // NaN would poison the accumulator
        frequency_ = frequencyHz;
        updateIncrement();
    }
 
    [[nodiscard]] T getFrequency() const noexcept { return frequency_; }
 
    [[nodiscard]] T advance() noexcept
    {
        const T current = currentPhase();
        // wrapUnit has a fast in-range exit, so the common case (|increment| < 1)
        // costs one compare - but unlike an unbounded while-loop it can never
        // hang on a pathological frequency (>> sample rate).
        phase_ = wrapUnit(phase_ + increment_);
        return current;
    }
 
    [[nodiscard]] T advanceWithFM(T fmHz) noexcept
    {
        const T current = currentPhase();
 
        const double modulatedIncrement =
            (static_cast<double>(frequency_) + static_cast<double>(fmHz)) * invSampleRate_;
 
        phase_ = wrapUnit(phase_ + modulatedIncrement);
 
        return current;
    }
 
    [[nodiscard]] T getPhase() const noexcept { return currentPhase(); }
 
    void setPhase(T newPhase) noexcept
    {
        phase_ = wrapUnit(static_cast<double>(newPhase));
    }
 
    void hardSync(T fractionalOffset = T(0)) noexcept
    {
        phase_ = wrapUnit(static_cast<double>(fractionalOffset));
    }
 
    void softSync(T threshold = T(0.5)) noexcept
    {
        if (phase_ >= static_cast<double>(threshold))
            phase_ = 0.0;
    }
 
    void reset(T startPhase = T(0)) noexcept
    {
        phase_ = wrapUnit(static_cast<double>(startPhase));
    }
 
    [[nodiscard]] T getIncrement() const noexcept { return static_cast<T>(increment_); }
 
private:
    void updateIncrement() noexcept
    {
        increment_ = static_cast<double>(frequency_) * invSampleRate_;
    }
 
    [[nodiscard]] T currentPhase() const noexcept
    {
        const T v = static_cast<T>(phase_);
        constexpr T belowOne = T(1) - std::numeric_limits<T>::epsilon() / T(2);
        return (v >= T(1)) ? belowOne : v;
    }
 
    static double wrapUnit(double p) noexcept
    {
        if (p >= 0.0 && p < 1.0) return p; // Fast exit
        // Slow path (rare): sanitise NaN here, where it costs nothing in the
        // common case - otherwise a single NaN input would stick in the
        // recursive accumulator until the next reset.
        if (p != p) return 0.0;
        // std::trunc instead of a cast to int: casting is UB once |p| exceeds
        // INT_MAX, which extreme FM excursions can reach.
        double wrapped = p - std::trunc(p);
        if (wrapped < 0.0) wrapped += 1.0;
        // Guard the contract's half-open range: for tiny negative inputs the
        // addition above rounds to exactly 1.0.
        if (wrapped >= 1.0) wrapped -= 1.0;
        return wrapped;
    }
 
    double sampleRate_ = 48000.0;
    double invSampleRate_ = 1.0 / 48000.0;
 
    T frequency_ = T(0);
    double phase_ = 0.0;
    double increment_ = 0.0;
};
 
} // namespace dspark