merge.hpp

Go to the documentation of this file.

// sbl/control/merge.hpp — Merge primitives: one parameter, several sources (FDP-074)
//
// The merge step runs once per control tick (Stage::Merge) and is the only
// writer of each bridged level. These primitives decide that level when more
// than one source can drive a parameter. Plain summation (pitch = knob +
// V/Oct + MIDI) needs no type.
//
//   Priority<N>  the highest-priority active source wins
//   Latest<N>    the last source to move wins
//   Pickup       a takeover source must reach the held value before it captures it
//
// All work on su floats, hold no pointers, allocate nothing, and run in one
// context (the control tick).
//
// Usage:
//   sbl::control::Pickup fold;                  // knob vs. MIDI CC
//   // Stage::Drain, on the CC:     fold.hold(cc_su);
//   // Stage::Merge, every tick:    s_fold_su = fold.process(knob.value());
//   // UI slot:                     led = fold.caught();
 
#ifndef SBL_CONTROL_MERGE_HPP_
#define SBL_CONTROL_MERGE_HPP_
 
#include <cstdint>
 
namespace sbl::control {
 
// ─── Priority ────────────────────────────────────────────────────────
 
/**
 * @brief The highest-priority active source wins
 *
 * Source 0 is the highest priority. Each source reports a value and whether
 * it is active (a MIDI source while its gate is high; a knob always). With
 * no source active, the last resolved value holds.
 */
template<uint8_t N>
class Priority {
    static_assert(N > 0, "Priority needs at least one source");
 
public:
    void set(uint8_t source, float value, bool active) {
        if (source >= N) return;
        values_[source] = value;
        active_[source] = active;
        resolve();
    }
 
    float value() const { return value_; }
 
    /// Winning source index, or -1 if none is active (value() is holding).
    int8_t winner() const { return winner_; }
 
private:
    void resolve() {
        winner_ = -1;
        for (uint8_t i = 0; i < N; ++i) {
            if (active_[i]) {
                winner_ = static_cast<int8_t>(i);
                value_ = values_[i];
                return;
            }
        }
    }
 
    float values_[N]{};
    bool active_[N]{};
    float value_ = 0.0f;
    int8_t winner_ = -1;
};
 
// ─── Latest ──────────────────────────────────────────────────────────
 
/**
 * @brief The last source to move wins
 *
 * Continuous sources (a pot polled every tick) report through update(): a
 * report counts as a write only when the source has moved more than the
 * threshold since its own last write, so a resting knob's noise cannot take
 * the parameter from a CC. The first report from a source sets its baseline
 * without taking ownership. Event sources (a CC) report through write():
 * every call is a write.
 */
template<uint8_t N>
class Latest {
    static_assert(N > 0, "Latest needs at least one source");
 
public:
    explicit Latest(float threshold = 0.001f) : threshold_(threshold) {}
 
    void update(uint8_t source, float value) {
        if (source >= N) return;
        if (!seen_[source]) {
            seen_[source] = true;
            last_[source] = value;
            return;
        }
        float moved = value - last_[source];
        if (moved < 0.0f) moved = -moved;
        if (moved > threshold_) take(source, value);
    }
 
    void write(uint8_t source, float value) {
        if (source >= N) return;
        seen_[source] = true;
        take(source, value);
    }
 
    float value() const { return value_; }
 
    /// Source that wrote last, or -1 before any write.
    int8_t owner() const { return owner_; }
 
private:
    void take(uint8_t source, float value) {
        last_[source] = value;
        value_ = value;
        owner_ = static_cast<int8_t>(source);
    }
 
    float last_[N]{};
    bool seen_[N]{};
    float threshold_;
    float value_ = 0.0f;
    int8_t owner_ = -1;
};
 
// ─── Pickup ──────────────────────────────────────────────────────────
 
/**
 * @brief A takeover source must reach the held value before it captures it
 *
 * When another source sets the parameter (hold()), the takeover source — a
 * knob — is ignored until it crosses the held value or comes within the
 * window of it. From then on the parameter follows the knob until the next
 * hold(). Without a hold the knob drives the parameter directly.
 */
class Pickup {
public:
    explicit Pickup(float window = 0.01f) : window_(window) {}
 
    /// Another source set the parameter; the takeover source must now reach it.
    void hold(float value) {
        value_ = value;
        armed_ = true;
        side_known_ = false;
    }
 
    /// Feed the takeover source (every tick). Returns the parameter value.
    float process(float source) {
        if (armed_) {
            const float d = source - value_;
            const bool above = d > 0.0f;
            const bool within = (d <= window_) && (d >= -window_);
            const bool crossed = side_known_ && (above != above_);
            if (!within && !crossed) {
                above_ = above;
                side_known_ = true;
                return value_;
            }
            armed_ = false;
        }
        value_ = source;
        return value_;
    }
 
    /// True while the takeover source drives the parameter.
    bool caught() const { return !armed_; }
 
    float value() const { return value_; }
 
    /// Hand the parameter to the takeover source now (e.g. a panel reset).
    void release() { armed_ = false; }
 
private:
    float window_;
    float value_ = 0.0f;
    bool armed_ = false;
    bool above_ = false;
    bool side_known_ = false;
};
 
} // namespace sbl::control
 
#endif // SBL_CONTROL_MERGE_HPP_