eden-emu/SDL
18
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

gamepad: Clarify range and direction of axes

Browse source 
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>

(cherry picked from commit 059fb560ba)
This commit is contained in:
Sam Lantinga 2024-01-08 09:48:04 -08:00
parent 5e12e4b813
commit d3c21666de
1 changed files with 10 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

13
include/SDL_gamecontroller.h
View file

@ -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)