Files
totk-pc-recomp/runtime/input.h
T
palxex dc13b194ce Add gyro bias calibration for the six-axis sensor
The yaw axis has no gravity reference, so it drifts with the gyro's
manufacturing bias. Two controllers of the same model can drift in
opposite directions, and the sensor fusion had no way to estimate or
remove the offset: aiming with motion turned slowly on its own and
needed constant correction.

A Calibrate gyro row on the Controls tab collects 250 gyro samples
(about a second) while the controller is held still, averages them per
axis into a bias, subtracts that bias from every sample before the
fusion integrates it, and restarts the angle so the estimate starts
clean. Collection has no motion threshold: a controller whose bias
exceeds any absolute threshold would otherwise never finish, which is
how the first version of this stalled with no way out. Five seconds
without the expected samples ends the attempt, from the sample path and
from the menu alike, so a sensor thread that stops feeding it is
reported instead of leaving the row on "calibrating". The first raw
sample and the final bias are logged, so a report carries the numbers
that were measured.

The row's value says where the controller stands: calibrating,
"<controller>, calibrated" once it is done or when the bias was loaded
from totk.ini at start, and "calibration failed" when an attempt timed
out with no bias in effect. A controller change cancels a calibration
that is in progress and clears the bias and the label, so neither is
carried over to the new controller.

The behaviour sits behind gyro_calibration (the Controls tab's "Gyro
bias calibration", default on, live): off, the fusion takes the raw
gyro, an attempt in progress is dropped, and nothing is loaded at
start, while the saved keys stay in totk.ini so turning it back on
restores the last calibration.

The bias and the controller's name go to totk.ini when calibration
completes, outside the fusion's lock, and are loaded at the next start
only when the connected controller has the same name.

Tested with a Switch Pro Controller on the 1.4.3 build: the log shows a
z-axis bias of 0.139 rad/s (8 degrees per second), calibration finishes
in about a second, the yaw drift is gone, and the row reports each state.
2026-11-15 02:26:30 +08:00

148 lines
11 KiB
C

// Host input sampling (runtime/input.c, with input_win.c or input_sdl.c): SDL3 gamepad and the keyboard as one Switch npad.
#pragma once
#include <stdint.h>
// Bits of libnx HidNpadButton (A=0 B=1 X=2 Y=3 StickL=4 StickR=5 L=6 R=7 ZL=8 ZR=9 Plus=10 Minus=11 Left=12 Up=13 Right=14
// Down=15) and the stick directions (StickLLeft..Down 16-19, StickRLeft..Down 20-23, derived from the sticks).
// Sticks are -32767..32767, up is +y. TOTK_INPUT=none reports no input. Callable from any thread.
void input_poll(uint64_t *buttons, int32_t *lx, int32_t *ly, int32_t *rx, int32_t *ry);
// 1 when keyboard and mouse are the device the player used last, 0 when the gamepad is: what is shown for pointing
// (menu_cursor.c shows the pointer in the game's menus only for the keyboard and mouse)
int input_kbm_last(void);
// Direct mouse input is consumed by the game's camera-input update, after its stick response. While that update
// accepts camera input, the HID right stick contains only the controller and keyboard. Selectors route mouse input
// separately: a persistent radial cursor for the ability wheel, discrete steps for horizontal quick lists.
int input_direct_mouse_active(void);
int input_direct_mouse_enabled(void);
// A radial selector uses a persistent virtual cursor while its opening button is held.
void input_direct_mouse_radial(int32_t dx, int32_t dy, float sensitivity, float cursor[2], int32_t out[2]);
// Horizontal quick selectors receive short, separated steps instead of a latched radial-cursor direction.
typedef struct { float distance; uint64_t pulse_until, neutral_until; int direction; } InputMouseRow;
void input_direct_mouse_row(int32_t dx, float sensitivity, uint64_t now, InputMouseRow *row, int32_t out[2]);
int input_direct_mouse_selector_active(void);
// Consume direct mouse counts, including one-shot MOUSE events from an input script. enabled=0 discards scripted
// counts while leaving the real mouse for menu input. Live counts require cursor capture and foreground focus.
void input_direct_mouse_sample(int enabled, int32_t *dx, int32_t *dy);
// The buttons (B_* bits) of the last poll, keys and gamepad merged; any thread (mouse_direct.c: ZR for the bow's scale)
uint64_t input_buttons_last(void);
// mouse_direct.c: the right stick's side a mouse shake gives while Ultrahand holds an object (-1 / +1), 0 while the
// mouse does not shake; input.c puts it on the stick
int input_direct_mouse_shake(void);
enum {
INPUT_CAM_UNCLASSIFIED = 0,
INPUT_CAM_FREE_ROAM,
INPUT_CAM_AIM,
INPUT_CAM_SCOPE,
INPUT_CAM_LOCK_ON,
INPUT_CAM_MENU_WHEEL,
INPUT_CAM_ABILITY,
INPUT_CAM_ULTRAHAND_OBJECT,
INPUT_CAM_VEHICLE,
INPUT_CAM_DISABLED,
};
int input_camera_context(void);
int input_gameplay_active(void);
// menu_cursor.c: the L ability wheel or a D-pad strip has the focus: 1 / 0, -1 with the menu cursor off (not read)
int menu_cursor_shortcut(void);
// menu_cursor.c: the pointer in the game's menus (1.4.3). poll: once per pad read, adds a click's A or B; pointer: a
// menu has the pointer, so the mouse camera's capture is released
void menu_cursor_poll(uint64_t *buttons);
int menu_cursor_pointer(void);
int menu_cursor_map(void); // the Purah Pad's map is open: the mouse's stick is the left one (its cursor)
// a dialogue box is on screen and TOTK_DIALOGUE_CLICK is on: left click is B, right click A (input.c poll_merged)
int menu_cursor_dialogue(void);
// A menu screen (not the ability wheel, a D-pad strip or the map) has the game's focus box, whichever device was used
// last: input.c turns the scroll wheel into steps of its focus. 0 with the menu cursor off.
int menu_cursor_menu(void);
// A D-pad strip's screen (ShortCut_00) is open; it has no focus box while held. 0 with the menu cursor off.
int menu_cursor_strip(void);
// The Purah Pad's camera is open: its frame and pointer without the map the Scope has. 0 with the menu cursor off.
int menu_cursor_camera(void);
// The same for host UI (the text entry): never blocked. input_block(1) while a text entry is open: input_poll then
// reports nothing; input_block(0) when it closes: nothing until all buttons and stick directions are released.
void input_poll_ui(uint64_t *buttons, int32_t *lx, int32_t *ly, int32_t *rx, int32_t *ry);
void input_block(int on);
// The in-game menu (ui/menu.h): input_menu(1) when it opens (input_poll reports nothing, the cursor is released), (0) when
// it closes (nothing until every button and stick direction is released). Independent of input_block.
void input_menu(int open);
// The gamepad alone, for the menu: Switch button bits and the left stick (up +y). 0 without a connected gamepad.
// Minus+Plus combo and the neutral pad while the menu is open (input_map.c, window-system free): *held is the caller's memory
// of the combo, sticks are lx, ly, rx, ry. Returns 1 in the poll where the combo goes down (toggle the menu once).
int input_menu_gate(int *held, int menu_open, uint64_t *buttons, int32_t sticks[4]);
int input_overlay_gate(int *held, uint64_t *buttons); // L3+R3: 1 in the poll both go down
int input_pad_read(uint64_t *buttons, int32_t *lx, int32_t *ly);
// The gamepad layout in effect (PAD_LAYOUT_*, input_map.h; TOTK_PAD_LAYOUT, live); -1 without a gamepad. Any thread.
int input_pad_layout(void);
// How far the open gamepad's left (pct[0]) and right (pct[1]) sticks are from the centre now, in percent of full
// deflection, before the dead zone: the menu shows it on the dead zone rows, so a drifting stick's resting value can be
// read off. 0 (and both 0) without a connected gamepad. Any thread.
int input_pad_stick_percent(double pct[2]);
// The label on a face button of the open gamepad (input_map.h PAD_SOUTH..PAD_NORTH, as SDL reports it); PAD_LABEL_NONE for another
// button, an unknown label or no gamepad. Any thread.
enum { PAD_LABEL_NONE, PAD_LABEL_A, PAD_LABEL_B, PAD_LABEL_X, PAD_LABEL_Y, PAD_LABEL_CROSS, PAD_LABEL_CIRCLE,
PAD_LABEL_SQUARE, PAD_LABEL_TRIANGLE };
int input_pad_label(int pad);
// The menu's remapping rows (Controls tab). input_map_snapshot copies the tables in effect (after any changed TOTK_BIND_* line).
// input_capture polls the keys, the mouse buttons and the gamepad for a press: reset 1 takes what is held now as the
// start (a held key counts once released and pressed again) and returns NONE; then it returns KEY or PAD with *id the
// key or pad id (input_map.h) pressed since the last call, or CANCEL for Esc. Keys count only while the game window is in front.
enum { INPUT_CAPTURE_NONE, INPUT_CAPTURE_KEY, INPUT_CAPTURE_PAD, INPUT_CAPTURE_CANCEL };
struct InputMap; // input_map.h (not included here: swkbd_win.c has button names of its own)
void input_map_snapshot(struct InputMap *m);
int input_capture(int reset, int *id);
// The character on a punctuation key (KEY_MINUS..KEY_GRAVE) in the keyboard layout in use, 0 for another key.
uint32_t input_key_char(int key);
// F8, the flight recorder's key (no KEY_ id), held while the game window is in front.
int input_flight_key(void);
// Mouse camera and cursor (input_win.c, Win32 window thread). The window procedure calls input_window_msg first for raw
// mouse input, cursor hiding and confinement; it returns 1 with *res set when the message is handled. input_cursor_suspend(1)
// releases the cursor around an F11 window change, (0) captures it again once the client area has its new size.
void input_cursor_suspend(int on);
int input_cursor_released(void); // Esc or a non-client activation released the cursor (probe)
// Rumble: SDL_RumbleGamepad on the open gamepad, low (heavy, left) and high (light, right) motor 0..65535 for ms
// milliseconds. 1 if a gamepad with rumble took it. Callable from any thread.
int input_rumble(uint16_t low, uint16_t high, uint32_t ms);
// Motor value for a normalised amplitude: pow(a, curve) * strength, saturated to 0..65535. Pure.
uint16_t rumble_motor(float a, float curve, float strength);
// TOTK_RUMBLE_TRIGGERS=1: input_rumble also drives the impulse triggers (Xbox) with the high motor's value.
int input_rumble_triggers_enabled(void);
// Motion (TOTK_MOTION=0 turns it off, live). input_motion_start starts the sensor thread once: every 4 ms it reads the
// gamepad's gyro and accelerometer (when it has them) and feeds motion_global(). Callable from any thread.
void input_motion_start(void);
// TOTK_MOTION is not "0" (a live setting: read again when cfg_version changes). Off: the sensor reads at rest.
int input_motion_enabled(void);
void input_motion_calibrate(void); // start collecting resting gyro samples for a bias estimate
// What the Controls tab's Calibrate gyro row shows: 0 no bias for this controller, 1 collecting, 2 calibrated
// (by this run or loaded from totk.ini), 3 the last attempt timed out. pad receives the controller the bias belongs
// to (empty when none), copied so the caller does not read a buffer another thread may be rewriting.
int input_motion_calib_state(char *pad, size_t cap);
// The bias's own switch (gyro_calibration, live). Off: no collection, the fusion takes the raw gyro, and the row's
// state reads as before any calibration while the saved keys stay in totk.ini.
int input_gyro_calibration_enabled(void);
// The fusion's own read of the same switch (motion_fusion.c); input.c reaches it for the load and the row's state.
int motion_calibration_enabled(void);
// SDL sensor values (accelerometer m/s^2, gyro rad/s, SDL gamepad axes) to the Switch controller frame motion_feed
// takes (acceleration in G as gravity reads, rotation rad/s). The mapping is documented in input_win.c.
void input_motion_axes(const float sdl_acc[3], const float sdl_gyro[3], double acc_g[3], double gyro[3]);
// motion_fusion.c: nn::hid::SixAxisSensorState and the sensor fusion that produces it.
typedef struct {
int64_t delta_ns, sampling;
float acc[3], gyro[3], angle[3], dir[9]; // G, revolutions/s, revolutions, controller axes in the reference frame
uint32_t attributes, reserved; // bit 0 connected
} MotionState;
_Static_assert(sizeof(MotionState) == 0x60, "SixAxisSensorState ABI");
typedef struct MotionFusion MotionFusion;
MotionFusion *motion_new(void);
MotionFusion *motion_global(void); // the gamepad's, fed by input_win.c
void motion_feed(MotionFusion *m, const double acc_g[3], const double gyro_rad_s[3], uint64_t now_ns);
int motion_read(MotionFusion *m, MotionState *out, int max, uint64_t now_ns); // newest first; 0 = none in 200 ms
void motion_restart(MotionFusion *m); // angle and direction start over at the next sample
void motion_calibrate_start(MotionFusion *m, const char *pad_name); // start collecting; pad_name saved with the bias
int motion_calib_poll(MotionFusion *m, uint64_t now_ns); // the timeout, for when motion_feed is not called
void motion_bias_load(MotionFusion *m); // load the bias from totk.ini (TOTK_GYRO_BIAS_*)
void motion_bias_reset(MotionFusion *m); // zero the bias (new controller)