knob_gate.hpp

Go to the documentation of this file.

// sbl/components/control/knob_gate.hpp — Anti-jump knob gate
//
// After a mode switch, a knob's position may map to a completely different
// parameter value. KnobGate suppresses the knob's output until the user
// physically moves it past a threshold from its entry position. This
// prevents parameter jumps on mode transitions.
//
// Pair one KnobGate with each knob that has multi-mode mappings.
//
// Usage:
//   sbl::components::control::KnobGate gate;
//   // On mode switch:
//   gate.arm(knob.value());
//   // In your control loop:
//   gate.update(knob.value());
//   if (gate.live()) {
//       apply_parameter(knob.scaled(...));
//   }
 
#pragma once
 
#include <cstdint>
 
namespace sbl {
namespace components {
namespace control {
 
class KnobGate {
public:
    /// @param threshold Movement required to unlock (0-65535). Default ~3%.
    explicit KnobGate(uint16_t threshold = 2000)
        : threshold_(threshold) {}
 
    /// Lock the gate and record current knob position.
    void arm(uint16_t entry_value) {
        entry_ = entry_value;
        live_ = false;
    }
 
    /// Check if knob has moved enough from entry position to unlock.
    void update(uint16_t current_value) {
        if (live_) return;
        int32_t d = static_cast<int32_t>(current_value) - static_cast<int32_t>(entry_);
        if (d < 0) d = -d;
        if (d > static_cast<int32_t>(threshold_)) {
            live_ = true;
        }
    }
 
    /// True when the gate is open (output allowed).
    bool live() const { return live_; }
 
    /// Force the gate open (e.g., for the initial mode that needs no gating).
    void force_live() { live_ = true; }
 
    /// Set threshold (0-65535).
    void set_threshold(uint16_t t) { threshold_ = t; }
 
private:
    uint16_t threshold_;
    uint16_t entry_ = 0;
    bool live_ = true;  // Start live (not armed)
};
 
} // namespace control
} // namespace components
} // namespace sbl