SDL: gamepad: Clarify range and direction of axes

https://github.com/libsdl-org/SDL/commit/059fb560ba98df5668e1cf1c88560b3156e0fb66

From 059fb560ba98df5668e1cf1c88560b3156e0fb66 Mon Sep 17 00:00:00 2001
From: Simon McVittie <[EMAIL REDACTED]>
Date: Mon, 8 Jan 2024 15:53:51 +0000
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 <smcv@collabora.com>
---
 include/SDL3/SDL_gamepad.h | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index be970e640b8f..0e66b3b891c7 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -149,7 +149,9 @@ typedef enum
  *  and are centered within ~8000 of zero, though advanced UI will allow users to set
  *  or autodetect the dead zone, which varies between gamepads.
  *
- *  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
 {
@@ -961,8 +963,13 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_Ga
  *
  * 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 gamepad a gamepad
  * \param axis an axis index (one of the SDL_GamepadAxis values)