From d3c21666dea2efbd64aec923ab230da37f91b3da Mon Sep 17 00:00:00 2001 From: Sam Lantinga Date: Mon, 8 Jan 2024 09:48:04 -0800 Subject: [PATCH] gamepad: Clarify range and direction of axes It would be easy to assume that all APIs that reference SDL_JOYSTICK_AXIS_MAX work the same way, but they do not: triggers generally use the full signed 16-bit range in the lower-level joystick API, but are normalized to be non-negative by the higher-level gamepad API. We also never said explicitly which direction is positive here. Experimentally, it's right (X), down (Y), and pressed (triggers). Resolves: https://github.com/libsdl-org/SDL/issues/8793 Signed-off-by: Simon McVittie (cherry picked from commit 059fb560ba98df5668e1cf1c88560b3156e0fb66) --- include/SDL_gamecontroller.h | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h index c27e453d2..a1b436685 100644 --- a/include/SDL_gamecontroller.h +++ b/include/SDL_gamecontroller.h @@ -613,7 +613,9 @@ extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void); * and are centered within ~8000 of zero, though advanced UI will allow users to set * or autodetect the dead zone, which varies between controllers. * - * Trigger axis values range from 0 to SDL_JOYSTICK_AXIS_MAX. + * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX + * (fully pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the + * same range that will be reported by the lower-level SDL_GetJoystickAxis(). */ typedef enum { @@ -702,8 +704,13 @@ SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameController * * The axis indices start at index 0. * - * The state is a value ranging from -32768 to 32767. Triggers, however, range - * from 0 to 32767 (they never return a negative value). + * For thumbsticks, the state is a value ranging from -32768 (up/left) + * to 32767 (down/right). + * + * Triggers range from 0 when released to 32767 when fully pressed, and + * never return a negative value. Note that this differs from the value + * reported by the lower-level SDL_GetJoystickAxis(), which normally uses + * the full range. * * \param gamecontroller a game controller * \param axis an axis index (one of the SDL_GameControllerAxis values)