hysteresis_quantizer.hpp

Go to the documentation of this file.

// sbl/dsp/hysteresis_quantizer.hpp — Stepped quantizer with dead zones
//
// Maps a continuous input (0-65535) to discrete steps with hysteresis
// at each boundary. Once settled on a step, the input must move past
// the boundary by a configurable margin before the step changes.
// This eliminates jitter when a knob sits right at a transition point.
//
// Hysteresis is specified as a fraction of step width (0-255 maps to
// 0-100% of step width, default 26 ≈ 10%). Values above ~50% cause
// the dead zones to overlap, which isn't harmful but makes transitions
// feel sluggish.
//
// Inspired by Mutable Instruments stmlib (MIT).
//
// Usage:
//   sbl::dsp::HysteresisQuantizer q;
//   int step = q.process(adc_value, 8);  // 8 steps, returns 0-7
 
#pragma once
 
#include <cstdint>
 
namespace sbl::dsp {
 
class HysteresisQuantizer {
public:
    /// Process a raw value into a quantized step index.
    /// @param value  Input value (0-65535, typically from ADC or pot).
    /// @param n_steps Number of output steps (2-256).
    /// @return Step index (0 to n_steps-1).
    int process(uint16_t value, uint8_t n_steps) {
        if (n_steps < 2) return 0;
 
        // Raw quantization: which step would this value fall in?
        int raw_step = (static_cast<uint32_t>(value) * n_steps) >> 16;
        if (raw_step >= n_steps) raw_step = n_steps - 1;
 
        // First call or step count changed — snap immediately
        if (!initialized_ || n_steps != last_n_steps_) {
            step_ = raw_step;
            initialized_ = true;
            last_n_steps_ = n_steps;
            return step_;
        }
 
        // Same step — no change needed
        if (raw_step == step_) return step_;
 
        // Different step — check if we've crossed the hysteresis band.
        // Step width in the 0-65535 space:
        uint32_t step_width = 65536u / n_steps;
        // Hysteresis margin: fraction of step width (hysteresis_/256)
        uint32_t margin = (step_width * hysteresis_) >> 8;
 
        if (raw_step > step_) {
            // Moving up: value must exceed upper boundary + margin
            uint32_t threshold = static_cast<uint32_t>(step_ + 1) * step_width + margin;
            if (value >= threshold) {
                step_ = raw_step;
            }
        } else {
            // Moving down: value must go below lower boundary - margin
            uint32_t boundary = static_cast<uint32_t>(step_) * step_width;
            if (boundary >= margin && value <= boundary - margin) {
                step_ = raw_step;
            } else if (boundary < margin && value == 0) {
                step_ = 0;
            }
        }
 
        return step_;
    }
 
    /// Current quantized step (valid after first process() call).
    int step() const { return step_; }
 
    /// Set hysteresis amount (0-255). 0 = no hysteresis, 26 ≈ 10%, 128 = 50%.
    void set_hysteresis(uint8_t h) { hysteresis_ = h; }
 
    /// Reset — next process() call will snap to the raw value.
    void reset() { initialized_ = false; }
 
private:
    int step_ = 0;
    uint8_t hysteresis_ = 26;  // ~10% of step width
    uint8_t last_n_steps_ = 0;
    bool initialized_ = false;
};
 
} // namespace sbl::dsp