scale_quantizer.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/signal/detail/modular_sequencing_common.hpp>
 
#include <algorithm>
#include <cmath>
#include <cstdint>
 
namespace pulp::signal {
 
// ── Quantizer ─────────────────────────────────────────────────────────────

enum class QuantizeMode {
    edo,         
    scale_mask,  
};

template <typename SampleType = float>
class QuantizeScaleT {
public:
    static constexpr int kDefaultEdo = 12;
    static constexpr int kMaxEdo = 48;

    static constexpr std::uint16_t kMajorMask = 0b0000'1010'1011'0101u;

    static constexpr double kHystCents = 20.0;

    static constexpr double kMaxHystCents = 1200.0;

    static constexpr double kMaxHystSteps = 0.45;

    static constexpr double kMaxAbsSteps = 4096.0;
 
    void prepare(double sample_rate) {
        sample_rate_ = sample_rate > 0.0 ? sample_rate : sample_rate_;
    }
 
    void set_mode(QuantizeMode mode) { mode_ = mode; }
    QuantizeMode mode() const { return mode_; }
 
    void set_edo(int n) { edo_ = std::clamp(n, 1, kMaxEdo); }
    int edo() const { return edo_; }
 
    void set_scale_mask(std::uint16_t mask) { mask_ = static_cast<std::uint16_t>(mask & 0x0FFFu); }
    std::uint16_t scale_mask() const { return mask_; }
 
    void set_root_pc(int pc) { root_pc_ = ((pc % 12) + 12) % 12; }
    int root_pc() const { return root_pc_; }
 
    void set_hysteresis_cents(double cents) {
        hyst_cents_ = seq_detail::clamp_finite(cents, 0.0, kMaxHystCents);
    }
    double hysteresis_cents() const { return hyst_cents_; }

    void apply_reset_edge() { have_latch_ = false; }
 
    void reset() {
        have_latch_ = false;
        latched_step_ = 0;
    }
 
    static constexpr int latency_samples() { return 0; }

    int latched_step() const { return latched_step_; }

    SampleType process(SampleType cv_volts) {
        const int divisions = (mode_ == QuantizeMode::edo) ? edo_ : 12;
        const double in_steps = static_cast<double>(cv_volts) * static_cast<double>(divisions);
        const int step = latch(in_steps, divisions);
        const int out_step = (mode_ == QuantizeMode::edo) ? step : snap_to_mask(step);
        return static_cast<SampleType>(static_cast<double>(out_step) /
                                       static_cast<double>(divisions));
    }
 
private:
    static int round_half_up(double x) {
        return static_cast<int>(
            std::floor(seq_detail::clamp_finite(x, -kMaxAbsSteps, kMaxAbsSteps) + 0.5));
    }
 
    int latch(double in_steps, int divisions) {
        const int candidate = round_half_up(in_steps);
        if (!have_latch_) {
            have_latch_ = true;
            latched_step_ = candidate;
            return latched_step_;
        }
 
        // One step spans 1200/divisions cents, so the window in steps is
        // `cents · divisions / 1200`. At 12-TET and the 20-cent default this is
        // 0.2 of a semitone, matching the spec's worked example. The cap only
        // engages above EDO-30 — see `kMaxHystSteps` for why it has to.
        const double window = std::min(hyst_cents_ * static_cast<double>(divisions) / 1200.0,
                                       kMaxHystSteps);
        const double here = static_cast<double>(latched_step_);
        if (candidate > latched_step_ && in_steps < here + 0.5 + window) return latched_step_;
        if (candidate < latched_step_ && in_steps > here - 0.5 - window) return latched_step_;
 
        latched_step_ = candidate;
        return latched_step_;
    }
 
    bool allowed(int semitone) const {
        int pc = (semitone - root_pc_) % 12;
        if (pc < 0) pc += 12;
        return ((mask_ >> pc) & 1u) != 0u;
    }
 
    int snap_to_mask(int semitone) const {
        // An empty mask has no enabled pitch class to snap to. Passing the
        // chromatic step through is the only answer that keeps the output in
        // tune; silently substituting a scale would hide the misconfiguration.
        if (mask_ == 0u) return semitone;
        for (int d = 0; d <= 12; ++d) {
            if (allowed(semitone + d)) return semitone + d;  // ties resolve upward
            if (d > 0 && allowed(semitone - d)) return semitone - d;
        }
        return semitone;
    }
 
    double sample_rate_ = 44100.0;
    QuantizeMode mode_ = QuantizeMode::scale_mask;
    int edo_ = kDefaultEdo;
    std::uint16_t mask_ = kMajorMask;
    int root_pc_ = 0;
    double hyst_cents_ = kHystCents;
 
    bool have_latch_ = false;
    int latched_step_ = 0;
};
 
using QuantizeScale = QuantizeScaleT<float>;
using QuantizeScale64 = QuantizeScaleT<double>;
 
}  // namespace pulp::signal