beat_clock.hpp

Go to the documentation of this file.

// sbl/patterns/timing/beat_clock.hpp — Tick-based beat clock
//
// Simple BPM-driven clock for sequencers, LED pulse, and gate timing.
// Call advance() once per control tick (e.g., 200 Hz timer ISR).
// The clock tracks bar and beat boundaries and provides a configurable
// gate-off point within each bar.
//
// Not tied to any hardware — pure tick counting with integer math.
// For audio-rate timing, use PhaseAccumulator instead.
//
// Usage:
//   sbl::patterns::timing::BeatClock clock(200);  // 200 Hz tick rate
//   clock.set_bpm(120);                            // 120 BPM, 4/4 time
//   // In your control ISR:
//   bool new_bar = clock.advance();
//   if (clock.at_beat()) { /* flash LED */ }
//   if (clock.at_gate_off()) { /* release gate */ }
 
#pragma once
 
#include <cstdint>
 
namespace sbl {
namespace patterns {
namespace timing {
 
class BeatClock {
public:
    /// Construct with tick rate (Hz) and time signature.
    explicit BeatClock(uint16_t tick_rate_hz, uint8_t beats_per_bar = 4)
        : tick_rate_hz_(tick_rate_hz)
        , beats_per_bar_(beats_per_bar)
    {
        set_bpm(120);
    }
 
    /// Set tempo. Recalculates all derived tick counts.
    void set_bpm(uint16_t bpm) {
        if (bpm == 0) bpm = 1;
        bpm_ = bpm;
        ticks_per_bar_ = (static_cast<uint32_t>(tick_rate_hz_) * 60 * beats_per_bar_) / bpm_;
        ticks_per_beat_ = ticks_per_bar_ / beats_per_bar_;
        gate_off_tick_ = (ticks_per_bar_ * gate_percent_) / 100;
    }
 
    /// Set gate duration as percentage of bar (0-100). Default 75%.
    void set_gate_percent(uint8_t percent) {
        if (percent > 100) percent = 100;
        gate_percent_ = percent;
        gate_off_tick_ = (ticks_per_bar_ * gate_percent_) / 100;
    }
 
    /// Advance one tick. Returns true on bar boundary (tick wraps to 0).
    bool advance() {
        if (++tick_ >= ticks_per_bar_) {
            tick_ = 0;
            return true;
        }
        return false;
    }
 
    /// True when current tick is on a beat boundary.
    bool at_beat() const {
        return ticks_per_beat_ > 0 && (tick_ % ticks_per_beat_) == 0;
    }
 
    /// True at the gate-off point within the bar.
    bool at_gate_off() const { return tick_ == gate_off_tick_; }
 
    /// Reset tick counter to start of bar.
    void reset() { tick_ = 0; }
 
    // Read-only accessors
    uint16_t bpm()            const { return bpm_; }
    uint32_t tick()           const { return tick_; }
    uint32_t ticks_per_bar()  const { return ticks_per_bar_; }
    uint32_t ticks_per_beat() const { return ticks_per_beat_; }
    uint8_t  beats_per_bar()  const { return beats_per_bar_; }
 
private:
    uint16_t tick_rate_hz_;
    uint8_t  beats_per_bar_;
    uint8_t  gate_percent_ = 75;
    uint16_t bpm_ = 120;
    uint32_t tick_ = 0;
    uint32_t ticks_per_bar_ = 0;
    uint32_t ticks_per_beat_ = 0;
    uint32_t gate_off_tick_ = 0;
};
 
} // namespace timing
} // namespace patterns
} // namespace sbl