phase.hpp

Go to the documentation of this file.

#pragma once
 
#include <array>
#include <cmath>
#include <cstddef>
#include <span>
 
namespace pulp::signal::osc {

enum class PhaseEventKind {
    wrap_forward,  
    wrap_backward, 
    sync,          
};

struct PhaseEvent {
    double frac = 0.0;
    double phase_before = 0.0;
    double phase_after = 0.0;
    PhaseEventKind kind = PhaseEventKind::wrap_forward;
};

class PhaseAccumulator {
public:
    static constexpr int max_events_per_sample = 8;

    void reset(double phase = 0.0) {
        phase_ = wrap_unit(phase);
        count_ = 0;
        truncated_ = false;
    }

    int advance(double increment) {
        count_ = 0;
        truncated_ = false;
        scan(increment, 0.0, 1.0);
        return count_;
    }

    int advance_synced(double increment, double sync_frac, double sync_phase = 0.0) {
        count_ = 0;
        truncated_ = false;
 
        const double f = clamp_unit(sync_frac);
        scan(increment * f, 0.0, f);
 
        const double target = wrap_unit(sync_phase);
        emit(f, phase_, target, PhaseEventKind::sync);
        phase_ = target;
 
        scan(increment * (1.0 - f), f, 1.0 - f);
        return count_;
    }

    double phase() const { return phase_; }

    std::span<const PhaseEvent> events() const {
        return {events_.data(), static_cast<std::size_t>(count_)};
    }

    bool truncated() const { return truncated_; }
 
private:
    void scan(double delta, double t0, double span) {
        // Absorb a non-finite increment here, where the phase is owned, so both
        // advance() and advance_synced() get the same contract. Letting NaN fall
        // through to the comparisons below works — every one fails, so no events
        // are emitted — but an infinity does NOT: floor(inf) is inf, so the
        // magnitude test below takes the truncation path and emits a full budget
        // of wraps at a position no crossing occurred at. A caller that trusts
        // the event list then corrects steps that never happened, and (0 * inf)
        // in its own slope term hands it a NaN besides.
        if (!std::isfinite(delta)) {
            phase_ = 0.0;
            return;
        }
 
        const double p0 = phase_;
        const double raw = p0 + delta;
        const double n = std::floor(raw);
 
        // The `>= 1.0` case is not defensive: for a raw of -1e-20,
        // floor is -1 and `raw - n` rounds to exactly 1.0, which is outside the
        // half-open domain. Snapping to 0 is exact on the circle.
        double wrapped = raw - n;
        if (!(wrapped >= 0.0 && wrapped < 1.0))
            wrapped = 0.0;
 
        int events = 0;
        const double magnitude = std::fabs(n);
        if (magnitude > static_cast<double>(max_events_per_sample)) {
            events = max_events_per_sample;
            truncated_ = true;
        } else if (magnitude >= 1.0) {
            events = static_cast<int>(magnitude);
        }
 
        // p0 is in [0, 1), so raw > 0 whenever delta > 0 and raw < 1 whenever
        // delta < 0. The sign of n therefore names the direction outright, and
        // `delta` is non-zero whenever the loop runs.
        const bool forward = n > 0.0;
        for (int k = 0; k < events; ++k) {
            const double level = forward ? static_cast<double>(k + 1)
                                         : -static_cast<double>(k);
            const double t = (level - p0) / delta;
            emit(t0 + t * span,
                 forward ? 1.0 : 0.0,
                 forward ? 0.0 : 1.0,
                 forward ? PhaseEventKind::wrap_forward
                         : PhaseEventKind::wrap_backward);
        }
 
        phase_ = wrapped;
    }
 
    void emit(double frac, double before, double after, PhaseEventKind kind) {
        if (count_ >= max_events_per_sample) {
            truncated_ = true;
            return;
        }
        events_[static_cast<std::size_t>(count_++)] = PhaseEvent{frac, before, after, kind};
    }

    static double wrap_unit(double x) {
        double w = x - std::floor(x);
        if (!(w >= 0.0 && w < 1.0))
            w = 0.0;
        return w;
    }

    static double clamp_unit(double x) {
        if (!(x > 0.0)) return 0.0;
        if (x > 1.0) return 1.0;
        return x;
    }
 
    double phase_ = 0.0;
    std::array<PhaseEvent, max_events_per_sample> events_{};
    int count_ = 0;
    bool truncated_ = false;
};
 
} // namespace pulp::signal::osc