cc_mapper.hpp

Go to the documentation of this file.

// sbl/control/cc_mapper.hpp — Declarative MIDI CC routing (FDP-075)
//
// A constexpr table replaces the per-CC switch: each row routes one
// controller on one channel to an app-defined target through a curve. Curves
// are LUTE cam tables (the same vocabulary as knob macros) or linear.
//
// Dispatch is event-driven, inside the control tick's drain loop, after the
// CC store (MidiConverter) has taken the event — converter before mapper. The
// store stays the only CC state: a Paired14 row reads the other half of its
// pair from it. Values are absolute; every matching row fires, so a CC with
// two rows fans out to two targets.
//
// The sink is the app's write into the merge layer (FDP-074), e.g.
// pickups[param].hold(value).
//
// Usage:
//   enum class Param : uint8_t { Pitch, Timbre };
//   constexpr sbl::control::CcEntry<Param> kCcMap[] = {
//       { 0, 86, Param::Pitch,  sbl::control::kCcLinear,   sbl::control::CcFlags::None },
//       { 0, 87, Param::Timbre, {cam::timbre_256, 256},    sbl::control::CcFlags::None },
//   };
//   sbl::control::CcMapper<Param> mapper{kCcMap, write_param, nullptr};
//
//   // drain loop, per ControlChange event:
//   converter.cc(e.cc_number(), e.cc_value());
//   mapper.on_cc(e.channel, e.cc_number(), e.cc_value(), converter);
 
#ifndef SBL_CONTROL_CC_MAPPER_HPP_
#define SBL_CONTROL_CC_MAPPER_HPP_
 
#include <cstddef>
#include <cstdint>
 
#include <sbl/control/cam.hpp>
 
namespace sbl::control {
 
/// A LUTE cam table (size + 1 entries, guard point included), or linear when table is null.
struct CcCurve {
    const float* table = nullptr;
    uint16_t size = 0;
};
 
inline constexpr CcCurve kCcLinear{};
 
enum class CcFlags : uint8_t {
    None     = 0,
    Paired14 = 1 << 0,  ///< 14-bit: `cc` is the MSB (0–31), cc + 32 the LSB
};
 
/// Row channel that matches every channel.
inline constexpr uint8_t kAnyChannel = 0xFF;
 
template<typename Target>
struct CcEntry {
    uint8_t channel;  ///< 0–15, or kAnyChannel
    uint8_t cc;       ///< controller number (the MSB for Paired14)
    Target target;
    CcCurve curve;
    CcFlags flags;
};
 
template<typename Target>
class CcMapper {
public:
    /// The app's write into the merge layer. value_su is the curve output.
    using Sink = void (*)(void* context, Target target, float value_su);
 
    template<size_t N>
    CcMapper(const CcEntry<Target> (&table)[N], Sink sink, void* context)
        : table_(table), count_(N), sink_(sink), context_(context) {}
 
    /**
     * @brief Route one ControlChange event
     *
     * Call after `store` has taken the event. `store` provides
     * `float cc(uint8_t number) const` in [0, 1] and supplies the other half
     * of a 14-bit pair. Returns the number of rows dispatched.
     */
    template<typename Store>
    uint8_t on_cc(uint8_t channel, uint8_t cc, uint8_t value, const Store& store) const {
        uint8_t hits = 0;
        for (size_t i = 0; i < count_; ++i) {
            const CcEntry<Target>& e = table_[i];
            if (e.channel != kAnyChannel && e.channel != channel) continue;
 
            float t;
            if (e.flags == CcFlags::Paired14) {
                const uint8_t lsb_cc = static_cast<uint8_t>(e.cc + 32);
                if (cc != e.cc && cc != lsb_cc) continue;
                const uint8_t msb = (cc == e.cc) ? value : to7(store.cc(e.cc));
                const uint8_t lsb = (cc == lsb_cc) ? value : to7(store.cc(lsb_cc));
                t = static_cast<float>((static_cast<uint16_t>(msb) << 7) | lsb) *
                    (1.0f / 16383.0f);
            } else {
                if (cc != e.cc) continue;
                t = static_cast<float>(value) * (1.0f / 127.0f);
            }
 
            const float v = e.curve.table ? cam_evaluate(e.curve.table, e.curve.size, t) : t;
            sink_(context_, e.target, v);
            ++hits;
        }
        return hits;
    }
 
    size_t size() const { return count_; }
 
private:
    static uint8_t to7(float su) {
        const float c = su * 127.0f + 0.5f;
        return c <= 0.0f ? 0 : (c >= 127.0f ? 127 : static_cast<uint8_t>(c));
    }
 
    const CcEntry<Target>* table_;
    size_t count_;
    Sink sink_;
    void* context_;
};
 
} // namespace sbl::control
 
#endif // SBL_CONTROL_CC_MAPPER_HPP_