cartesian_walk.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/signal/detail/modular_sequencing_common.hpp>
 
#include <algorithm>
#include <cmath>
 
namespace pulp::signal {
 
// ── Cartesian (2-D) sequencer ─────────────────────────────────────────────

enum class CartesianAccess {
    row_major,
    independent,
};

template <typename SampleType = float>
class CartesianWalkT {
public:
    static constexpr int kMaxDim = 8;
    static constexpr int kDefaultDim = 4;

    static constexpr int kMaxOffset = 1000000;
 
    struct Frame {
        SampleType cv = SampleType{0};
        bool gate = false;
    };
 
    void prepare(double sample_rate) {
        sample_rate_ = sample_rate > 0.0 ? sample_rate : sample_rate_;
    }
 
    void set_size(int w, int h) {
        width_ = std::clamp(w, 1, kMaxDim);
        height_ = std::clamp(h, 1, kMaxDim);
        if (x_ >= width_) x_ = 0;
        if (y_ >= height_) y_ = 0;
    }
    int width() const { return width_; }
    int height() const { return height_; }
 
    void set_value(int x, int y, SampleType volts) {
        if (x >= 0 && x < kMaxDim && y >= 0 && y < kMaxDim &&
            std::isfinite(static_cast<double>(volts)))
            value_[y][x] = volts;
    }
    SampleType value(int x, int y) const {
        return (x >= 0 && x < kMaxDim && y >= 0 && y < kMaxDim) ? value_[y][x] : SampleType{0};
    }
 
    void set_access(CartesianAccess mode) { access_ = mode; }
    CartesianAccess access() const { return access_; }

    void set_offsets(int x_cv, int y_cv) {
        x_offset_ = std::clamp(x_cv, -kMaxOffset, kMaxOffset);
        y_offset_ = std::clamp(y_cv, -kMaxOffset, kMaxOffset);
    }

    void apply_reset_edge() {
        x_ = 0;
        y_ = 0;
        cell_x_ = 0;
        cell_y_ = 0;
        started_ = false;
        gate_ = false;
    }
 
    void reset() {
        apply_reset_edge();
        held_ = SampleType{0};
    }
 
    static constexpr int latency_samples() { return 0; }
 
    int x() const { return x_; }
    int y() const { return y_; }
    int cell_x() const { return cell_x_; }
    int cell_y() const { return cell_y_; }
    bool gate() const { return gate_; }
    SampleType cv() const { return held_; }
 
    Frame process(bool run_high, bool reset_edge, bool x_clock_edge, bool y_clock_edge) {
        if (reset_edge) apply_reset_edge();
 
        if (!run_high) {
            gate_ = false;
            return Frame{held_, false};
        }
 
        gate_ = false;
        if (x_clock_edge || y_clock_edge) {
            const int prev_x = cell_x_;
            const int prev_y = cell_y_;
 
            if (!started_) {
                // The downbeat: land on the home cell without advancing.
                started_ = true;
                gate_ = true;
            } else {
                if (access_ == CartesianAccess::row_major) {
                    if (x_clock_edge) {
                        x_ = (x_ + 1) % width_;
                        if (x_ == 0) y_ = (y_ + 1) % height_;
                    }
                } else {
                    if (x_clock_edge) x_ = (x_ + 1) % width_;
                    if (y_clock_edge) y_ = (y_ + 1) % height_;
                }
            }
 
            cell_x_ = wrap(x_ + x_offset_, width_);
            cell_y_ = wrap(y_ + y_offset_, height_);
            held_ = value_[cell_y_][cell_x_];
            if (cell_x_ != prev_x || cell_y_ != prev_y) gate_ = true;
        }
 
        return Frame{held_, gate_};
    }
 
private:
    static int wrap(int v, int m) {
        const int r = v % m;
        return r < 0 ? r + m : r;
    }
 
    double sample_rate_ = 44100.0;
    int width_ = kDefaultDim;
    int height_ = kDefaultDim;
    CartesianAccess access_ = CartesianAccess::independent;
    int x_offset_ = 0;
    int y_offset_ = 0;
    SampleType value_[kMaxDim][kMaxDim]{};
 
    int x_ = 0;
    int y_ = 0;
    int cell_x_ = 0;
    int cell_y_ = 0;
    bool started_ = false;
    bool gate_ = false;
    SampleType held_ = SampleType{0};
};
 
using CartesianWalk = CartesianWalkT<float>;
using CartesianWalk64 = CartesianWalkT<double>;
 
}  // namespace pulp::signal