Added SDL_GetJoystickCaps() and SDL_GetGamepadCaps() to get the capabilities of controllers

Also added SDL_GAMEPAD_CAP_PLAYER_LED to let the application know if the controller has a visible player LED
2026-04-04 14:49:40 +00:00 · 2024-01-22 19:07:33 -08:00
parent c88c12148d
commit cd231a65f6
36 changed files with 133 additions and 226 deletions
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -75,6 +75,15 @@ typedef enum
    SDL_GAMEPAD_TYPE_MAX
 } SDL_GamepadType;

+typedef enum
+{
+    SDL_GAMEPAD_CAP_MONO_LED       = 0x00000001,   /**< This gamepad has an LED that has adjustable brightness */
+    SDL_GAMEPAD_CAP_RGB_LED        = 0x00000002,   /**< This gamepad has an LED that has adjustable color */
+    SDL_GAMEPAD_CAP_PLAYER_LED     = 0x00000004,   /**< This gamepad has a player LED */
+    SDL_GAMEPAD_CAP_RUMBLE         = 0x00000010,   /**< This gamepad has left/right rumble */
+    SDL_GAMEPAD_CAP_TRIGGER_RUMBLE = 0x00000020,   /**< This gamepad has simple trigger rumble */
+} SDL_GamepadCaps;
+
 /**
 *  The list of buttons available on a gamepad
 *
@@ -1169,6 +1178,16 @@ extern DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *gamepad,
 */
 extern DECLSPEC int SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values);

+/**
+ * Query gamepad capabilities
+ *
+ * \param gamepad The gamepad to query
+ * \returns a mask of SDL_GamepadCaps values indicating the gamepad capabilities.
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern DECLSPEC Uint32 SDLCALL SDL_GetGamepadCaps(SDL_Gamepad *gamepad);
+
 /**
 * Start a rumble effect on a gamepad.
 *
@@ -1185,7 +1204,7 @@ extern DECLSPEC int SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_S
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_GamepadHasRumble
+ * \sa SDL_GetGamepadCaps
 */
 extern DECLSPEC int SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);

@@ -1210,50 +1229,18 @@ extern DECLSPEC int SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_f
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_GamepadHasRumbleTriggers
+ * \sa SDL_GetGamepadCaps
 */
 extern DECLSPEC int SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);

-/**
- * Query whether a gamepad has an LED.
- *
- * \param gamepad The gamepad to query
- * \returns SDL_TRUE, or SDL_FALSE if this gamepad does not have a modifiable
- *          LED
- *
- * \since This function is available since SDL 3.0.0.
- */
-extern DECLSPEC SDL_bool SDLCALL SDL_GamepadHasLED(SDL_Gamepad *gamepad);
-
-/**
- * Query whether a gamepad has rumble support.
- *
- * \param gamepad The gamepad to query
- * \returns SDL_TRUE, or SDL_FALSE if this gamepad does not have rumble
- *          support
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_RumbleGamepad
- */
-extern DECLSPEC SDL_bool SDLCALL SDL_GamepadHasRumble(SDL_Gamepad *gamepad);
-
-/**
- * Query whether a gamepad has rumble support on triggers.
- *
- * \param gamepad The gamepad to query
- * \returns SDL_TRUE, or SDL_FALSE if this gamepad does not have trigger
- *          rumble support
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_RumbleGamepadTriggers
- */
-extern DECLSPEC SDL_bool SDLCALL SDL_GamepadHasRumbleTriggers(SDL_Gamepad *gamepad);
-
 /**
 * Update a gamepad's LED color.
 *
+ * An example of a joystick LED is the light on the back of a PlayStation 4's
+ * DualShock 4 controller.
+ *
+ * For gamepads with a single color LED, the maximum of the RGB values will be used as the LED brightness.
+ *
 * \param gamepad The gamepad to update
 * \param red The intensity of the red LED
 * \param green The intensity of the green LED
@@ -1262,6 +1249,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadHasRumbleTriggers(SDL_Gamepad *gamep
 *          SDL_GetError() for more information.
 *
 * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetGamepadCaps
 */
 extern DECLSPEC int SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue);

--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -97,6 +97,15 @@ typedef enum
    SDL_JOYSTICK_TYPE_THROTTLE
 } SDL_JoystickType;

+typedef enum
+{
+    SDL_JOYSTICK_CAP_MONO_LED       = 0x00000001,   /**< This joystick has an LED that has adjustable brightness */
+    SDL_JOYSTICK_CAP_RGB_LED        = 0x00000002,   /**< This joystick has an LED that has adjustable color */
+    SDL_JOYSTICK_CAP_PLAYER_LED     = 0x00000004,   /**< This joystick has a player LED */
+    SDL_JOYSTICK_CAP_RUMBLE         = 0x00000010,   /**< This joystick has left/right rumble */
+    SDL_JOYSTICK_CAP_TRIGGER_RUMBLE = 0x00000020,   /**< This joystick has simple trigger rumble */
+} SDL_JoystickCaps;
+
 typedef enum
 {
    SDL_JOYSTICK_POWER_UNKNOWN = -1,
@@ -880,6 +889,16 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick,
 extern DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick,
                                                    int button);

+/**
+ * Query joystick capabilities
+ *
+ * \param joystick The joystick to query
+ * \returns a mask of SDL_JoystickCaps values indicating the joystick capabilities.
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern DECLSPEC Uint32 SDLCALL SDL_GetJoystickCaps(SDL_Joystick *joystick);
+
 /**
 * Start a rumble effect.
 *
@@ -896,7 +915,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick,
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_JoystickHasRumble
+ * \sa SDL_GetJoystickCaps
 */
 extern DECLSPEC int SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);

@@ -922,54 +941,18 @@ extern DECLSPEC int SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 lo
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_JoystickHasRumbleTriggers
+ * \sa SDL_GetJoystickCaps
 */
 extern DECLSPEC int SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);

-/**
- * Query whether a joystick has an LED.
- *
- * An example of a joystick LED is the light on the back of a PlayStation 4's
- * DualShock 4 controller.
- *
- * \param joystick The joystick to query
- * \returns SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE
- *          otherwise.
- *
- * \since This function is available since SDL 3.0.0.
- */
-extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick);
-
-/**
- * Query whether a joystick has rumble support.
- *
- * \param joystick The joystick to query
- * \returns SDL_TRUE if the joystick has rumble, SDL_FALSE otherwise.
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_RumbleJoystick
- */
-extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumble(SDL_Joystick *joystick);
-
-/**
- * Query whether a joystick has rumble support on triggers.
- *
- * \param joystick The joystick to query
- * \returns SDL_TRUE if the joystick has trigger rumble, SDL_FALSE otherwise.
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_RumbleJoystickTriggers
- */
-extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumbleTriggers(SDL_Joystick *joystick);
-
 /**
 * Update a joystick's LED color.
 *
 * An example of a joystick LED is the light on the back of a PlayStation 4's
 * DualShock 4 controller.
 *
+ * For joysticks with a single color LED, the maximum of the RGB values will be used as the LED brightness.
+ *
 * \param joystick The joystick to update
 * \param red The intensity of the red LED
 * \param green The intensity of the green LED
@@ -978,6 +961,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumbleTriggers(SDL_Joystick *joy
 *          SDL_GetError() for more information.
 *
 * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetJoystickCaps
 */
 extern DECLSPEC int SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue);

--- a/include/SDL3/SDL_oldnames.h
+++ b/include/SDL3/SDL_oldnames.h
@@ -235,9 +235,6 @@
 #define SDL_GameControllerGetVendor SDL_GetGamepadVendor
 #define SDL_GameControllerHasAxis SDL_GamepadHasAxis
 #define SDL_GameControllerHasButton SDL_GamepadHasButton
-#define SDL_GameControllerHasLED SDL_GamepadHasLED
-#define SDL_GameControllerHasRumble SDL_GamepadHasRumble
-#define SDL_GameControllerHasRumbleTriggers SDL_GamepadHasRumbleTriggers
 #define SDL_GameControllerHasSensor SDL_GamepadHasSensor
 #define SDL_GameControllerIsSensorEnabled SDL_GamepadSensorEnabled
 #define SDL_GameControllerMapping SDL_GetGamepadMapping
@@ -713,9 +710,6 @@
 #define SDL_GameControllerGetVendor SDL_GameControllerGetVendor_renamed_SDL_GetGamepadVendor
 #define SDL_GameControllerHasAxis SDL_GameControllerHasAxis_renamed_SDL_GamepadHasAxis
 #define SDL_GameControllerHasButton SDL_GameControllerHasButton_renamed_SDL_GamepadHasButton
-#define SDL_GameControllerHasLED SDL_GameControllerHasLED_renamed_SDL_GamepadHasLED
-#define SDL_GameControllerHasRumble SDL_GameControllerHasRumble_renamed_SDL_GamepadHasRumble
-#define SDL_GameControllerHasRumbleTriggers SDL_GameControllerHasRumbleTriggers_renamed_SDL_GamepadHasRumbleTriggers
 #define SDL_GameControllerHasSensor SDL_GameControllerHasSensor_renamed_SDL_GamepadHasSensor
 #define SDL_GameControllerIsSensorEnabled SDL_GameControllerIsSensorEnabled_renamed_SDL_GamepadSensorEnabled
 #define SDL_GameControllerMapping SDL_GameControllerMapping_renamed_SDL_GetGamepadMapping