xinput_mapper/

utils.rs

//! Extra, pure utility helpers for post-processing sticks, buttons, and masks.
//! - Backward-compatible with previous helpers
//! - Adds outer-deadzone, response curve, hysteresis trigger, jitter-tolerant autorepeat

/* ============================== Stick Utilities ============================== */

/// Apply a centered deadzone on an i16 axis.
/// `deadzone` in [0..=32767]. Values within [-deadzone..deadzone] -> 0.
/// Outside, linearly re-scale to full range to preserve reach.
pub fn apply_deadzone_i16(v: i16, deadzone: i16) -> i16 {
    let dz = deadzone.clamp(0, 32767);
    let vi = v as i32;
    let sign = vi.signum();
    let mag = vi.unsigned_abs() as i32;
    if mag <= (dz as i32) {
        0
    } else {
        let rem = 32767 - (dz as i32);
        let adj = ((mag - (dz as i32)) * 32767) / rem.max(1);
        (adj * sign).clamp(-32768, 32767) as i16
    }
}

/// Apply an *outer* deadzone (a.k.a. saturation zone) to compress near extremes.
/// `outer` in [0..=32767]. If outer>0, map [0..(32767-outer)] -> [0..32767].
pub fn apply_outer_deadzone_i16(v: i16, outer: i16) -> i16 {
    let outer = outer.clamp(0, 32767) as i32;
    if outer == 0 {
        return v;
    }
    let vi = v as i32;
    let sign = vi.signum();
    let mag = vi.unsigned_abs() as i32;
    let lim = 32767 - outer;
    let rem = lim.max(1);
    let scaled = (mag.min(lim) * 32767) / rem;
    (scaled * sign).clamp(-32768, 32767) as i16
}

/// Apply a symmetric gamma-like response curve on an i16 axis.
/// `gamma` > 0 (typical range 0.5..3.0). gamma>1: softer center, stronger end; gamma<1: more sensitive center.
pub fn apply_response_curve_i16(v: i16, gamma: f32) -> i16 {
    if gamma <= 0.0 {
        return v;
    }
    let n = (v as f32) / 32767.0; // [-1,1]
    let sign = if n >= 0.0 { 1.0 } else { -1.0 };
    let mag = n.abs().min(1.0);
    let curved = mag.powf(gamma) * sign;
    (curved * 32767.0).round().clamp(-32768.0, 32767.0) as i16
}

/// Convert square stick into circular region while preserving direction.
pub fn square_to_circle(lx: i16, ly: i16) -> (i16, i16) {
    let nx = (lx as f32) / 32767.0;
    let ny = (ly as f32) / 32767.0;
    let sx = (nx * (1.0 - 0.5 * ny * ny).sqrt()).clamp(-1.0, 1.0);
    let sy = (ny * (1.0 - 0.5 * nx * nx).sqrt()).clamp(-1.0, 1.0);
    ((sx * 32767.0).round() as i16, (sy * 32767.0).round() as i16)
}

/// Radial deadzone for a stick. `deadzone` in [0..=32767].
pub fn apply_radial_deadzone(lx: i16, ly: i16, deadzone: i16) -> (i16, i16) {
    let dz = deadzone.clamp(0, 32767) as f32;
    let x = lx as f32;
    let y = ly as f32;
    let r = (x * x + y * y).sqrt();
    if r <= dz {
        return (0, 0);
    }
    let r2 = ((r - dz) * 32767.0) / (32767.0 - dz).max(1.0);
    if r == 0.0 {
        return (0, 0);
    }
    let scale = r2 / r;
    let nx = (x * scale).clamp(-32767.0, 32767.0);
    let ny = (y * scale).clamp(-32767.0, 32767.0);
    (nx.round() as i16, ny.round() as i16)
}

/// Compose helpers for a typical stick pipeline (backward-compatible).
pub fn postprocess_stick(
    lx: i16,
    ly: i16,
    use_circle: bool,
    radial_deadzone_v: i16,
    anti_deadzone_v: i16
) -> (i16, i16) {
    let (mut x, mut y) = if use_circle { square_to_circle(lx, ly) } else { (lx, ly) };
    (x, y) = apply_radial_deadzone(x, y, radial_deadzone_v);
    x = apply_anti_deadzone_i16(x, anti_deadzone_v);
    y = apply_anti_deadzone_i16(y, anti_deadzone_v);
    (x, y)
}

/// Extended pipeline with outer-deadzone and response curve (new API).
pub fn postprocess_stick_ex(
    lx: i16,
    ly: i16,
    use_circle: bool,
    radial_deadzone_v: i16,
    anti_deadzone_v: i16,
    outer_deadzone_v: i16,
    response_gamma: f32
) -> (i16, i16) {
    let (mut x, mut y) = if use_circle { square_to_circle(lx, ly) } else { (lx, ly) };
    (x, y) = apply_radial_deadzone(x, y, radial_deadzone_v);
    x = apply_anti_deadzone_i16(x, anti_deadzone_v);
    y = apply_anti_deadzone_i16(y, anti_deadzone_v);
    x = apply_outer_deadzone_i16(x, outer_deadzone_v);
    y = apply_outer_deadzone_i16(y, outer_deadzone_v);
    if response_gamma != 1.0 {
        x = apply_response_curve_i16(x, response_gamma);
        y = apply_response_curve_i16(y, response_gamma);
    }
    (x, y)
}

/// Optionally apply anti-deadzone (minimum magnitude).
/// `anti` in [0..=32767].
pub fn apply_anti_deadzone_i16(v: i16, anti: i16) -> i16 {
    let anti = anti.clamp(0, 32767) as i32;
    let vi = v as i32;
    if vi == 0 || anti == 0 {
        return v;
    }
    let sign = vi.signum();
    let mag = vi.unsigned_abs() as i32;
    let boosted = mag.max(anti);
    (boosted * sign).clamp(-32768, 32767) as i16
}

/// Trigger thresholding: turn trigger value [0..255] into boolean press.
pub fn trigger_pressed(v: u8, thresh: u8) -> bool {
    v >= thresh
}

/// Trigger with hysteresis: returns new state given last state and two thresholds.
/// - When currently released: becomes pressed if v >= press_thresh.
/// - When currently pressed: stays pressed until v < release_thresh.
pub fn trigger_hysteresis(last_pressed: bool, v: u8, press_thresh: u8, release_thresh: u8) -> bool {
    if last_pressed { v >= release_thresh } else { v >= press_thresh }
}

/* ============================== Button Utilities ============================== */

/// Compute edge masks between previous and current buttons.
pub fn button_edges(prev: u16, curr: u16) -> (u16, u16) {
    let changed = prev ^ curr;
    let pressed = changed & curr; // bits that went 0->1
    let released = changed & !curr; // bits that went 1->0
    (pressed, released)
}

/// Debounce mask: require a stable `hold_count` frames before accepting changes.
/// - `prev_out`: previous debounced output bit
/// - `curr_in`: current raw input bit
/// - `counter`: internal frame counter (call-site keeps one per bit)
/// Returns: (new_out_bit, new_counter)
pub fn debounce_bit(prev_out: bool, curr_in: bool, counter: u8, hold_count: u8) -> (bool, u8) {
    if curr_in == prev_out {
        (prev_out, 0)
    } else {
        let c = counter.saturating_add(1);
        if c >= hold_count {
            (curr_in, 0)
        } else {
            (prev_out, c)
        }
    }
}

/// Autorepeat helper (legacy): when a bit is held, fires at
/// (first_delay_ms then repeat_rate_ms). Uses modulo and can miss if jittery polls.
pub fn autorepeat_fire(
    is_down: bool,
    elapsed_ms_since_change: u32,
    first_delay_ms: u32,
    repeat_rate_ms: u32
) -> bool {
    if !is_down {
        return false;
    }
    if elapsed_ms_since_change == 0 {
        return true;
    }
    if elapsed_ms_since_change < first_delay_ms {
        return false;
    }
    let after = elapsed_ms_since_change - first_delay_ms;
    repeat_rate_ms != 0 && after % repeat_rate_ms == 0
}

/// Autorepeat helper (jitter-tolerant): fire if the time since last fire
/// crosses the next repeat boundary within a small window.
/// - `is_down`: key/button held
/// - `elapsed_down_ms`: time since became down
/// - `elapsed_since_last_fire_ms`: time since the last generated fire (0 at initial down)
/// - `first_delay_ms`: initial delay before repeating
/// - `repeat_rate_ms`: cadence for subsequent fires
/// - `window_ms`: allowed jitter window (e.g., 5~16ms)
pub fn autorepeat_fire_window(
    is_down: bool,
    elapsed_down_ms: u32,
    elapsed_since_last_fire_ms: u32,
    first_delay_ms: u32,
    repeat_rate_ms: u32,
    window_ms: u32
) -> bool {
    if !is_down {
        return false;
    }
    if elapsed_down_ms == 0 {
        return true;
    } // initial press
    if elapsed_down_ms < first_delay_ms {
        return false;
    }
    if repeat_rate_ms == 0 {
        return false;
    }

    // Compute target interval since last fire.
    // If we recently fired, we expect next in `repeat_rate_ms`.
    // Otherwise, at the very first repeat, we accept when elapsed_down_ms - first_delay_ms hits near multiples.
    let target = repeat_rate_ms;
    let e = elapsed_since_last_fire_ms;
    // Fire once when we cross the boundary within [0..window_ms]
    e >= target && e.saturating_sub(target) <= window_ms
}

/// Build a new mask by applying a remap table (source->dest). Missing sources are ignored.
/// `remap`: list of (src_mask_bit, dst_mask_bit).
pub fn remap_buttons(mask: u16, remap: &[(u16, u16)]) -> u16 {
    let mut out = 0u16;
    for &(src, dst) in remap {
        if (mask & src) != 0 {
            out |= dst;
        }
    }
    out
}

/// Merge a list of masks (e.g., macro/extra layers) into one via OR.
pub fn merge_masks(masks: &[u16]) -> u16 {
    masks.iter().fold(0u16, |acc, &m| acc | m)
}

/// Set/clear/toggle helpers
pub fn set_bit(mask: u16, bit: u16, on: bool) -> u16 {
    if on { mask | bit } else { mask & !bit }
}
pub fn toggle_bit(mask: u16, bit: u16) -> u16 {
    mask ^ bit
}

/* ============================== Convenience =============================== */

/// Map u8 [0..255] through an anti-deadzone (minimum) and optional linear outer-deadzone.
/// `anti` and `outer` in [0..=255].
pub fn apply_u8_zones(v: u8, anti: u8, outer: u8) -> u8 {
    let mut out = v as i32;
    if out > 0 && anti > 0 {
        out = out.max(anti as i32);
    }
    if outer > 0 {
        let lim = 255 - (outer as i32);
        out = (out.min(lim) * 255) / lim.max(1);
    }
    out.clamp(0, 255) as u8
}