Added functions to get the face button labels and primary and seconda…

…ry actions for a gamepad

docs/README-migration.md

@@ -390,7 +390,7 @@ The SDL_EVENT_GAMEPAD_ADDED event now provides the joystick instance ID in the w
 
 The functions SDL_GetGamepads(), SDL_GetGamepadInstanceName(), SDL_GetGamepadInstancePath(), SDL_GetGamepadInstancePlayerIndex(), SDL_GetGamepadInstanceGUID(), SDL_GetGamepadInstanceVendor(), SDL_GetGamepadInstanceProduct(), SDL_GetGamepadInstanceProductVersion(), and SDL_GetGamepadInstanceType() have been added to directly query the list of available gamepads.
 
-The gamepad face buttons have been renamed to indicate that they are positional rather than Xbox-centric.
+The gamepad face buttons have been renamed from A/B/X/Y to North/South/East/West to indicate that they are positional rather than Xbox-centric. You can use SDL_GetGamepadButtonLabel() to get the labels for the face buttons and SDL_GetGamepadPrimaryAction() and SDL_GetGamepadSecondaryAction() to get the buttons used for primary and secondary actions (A and B on an Xbox controller).
 
 SDL_GameControllerGetSensorDataWithTimestamp() has been removed. If you want timestamps for the sensor data, you should use the sensor_timestamp member of SDL_EVENT_GAMEPAD_SENSOR_UPDATE events.
 

include/SDL3/SDL_gamepad.h

@@ -105,6 +105,26 @@ typedef enum
     SDL_GAMEPAD_BUTTON_MAX
 } SDL_GamepadButton;
 
+/**
+ *  The set of gamepad button labels
+ *
+ *  This isn't a complete set, just the face buttons to make it easy to show button prompts.
+ *
+ *  For a complete set, you should look at the button and gamepad type and have a set of symbols that work well with your art style.
+ */
+typedef enum
+{
+    SDL_GAMEPAD_BUTTON_LABEL_UNKNOWN,
+    SDL_GAMEPAD_BUTTON_LABEL_A,         /**< The south button for Xbox controllers, the east button for Nintendo controllers */
+    SDL_GAMEPAD_BUTTON_LABEL_B,         /**< The east button for Xbox controllers, the south button for Nintendo controllers */
+    SDL_GAMEPAD_BUTTON_LABEL_X,         /**< The west button for Xbox controllers, the north button for Nintendo controllers */
+    SDL_GAMEPAD_BUTTON_LABEL_Y,         /**< The north button for Xbox controllers, the west button for Nintendo controllers */
+    SDL_GAMEPAD_BUTTON_LABEL_CROSS,     /**< The south button for Playstation controllers */
+    SDL_GAMEPAD_BUTTON_LABEL_CIRCLE,    /**< The east button for Playstation controllers */
+    SDL_GAMEPAD_BUTTON_LABEL_SQUARE,    /**< The west button for Playstation controllers */
+    SDL_GAMEPAD_BUTTON_LABEL_TRIANGLE   /**< The north button for Playstation controllers */
+} SDL_GamepadButtonLabel;
+
 /**
  *  The list of axes available on a gamepad
  *
@@ -990,6 +1010,80 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_
  */
 extern DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button);
 
+/**
+ * Get the label of a button on a gamepad.
+ *
+ * \param type the type of gamepad to check
+ * \param button a button index (one of the SDL_GamepadButton values)
+ * \returns the SDL_GamepadButtonLabel enum corresponding to the button label
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetGamepadButtonLabel
+ */
+extern DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabelForType(SDL_GamepadType type, SDL_GamepadButton button);
+
+/**
+ * Get the label of a button on a gamepad.
+ *
+ * \param gamepad a gamepad
+ * \param button a button index (one of the SDL_GamepadButton values)
+ * \returns the SDL_GamepadButtonLabel enum corresponding to the button label
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetGamepadButtonLabelForType
+ */
+extern DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabel(SDL_Gamepad *gamepad, SDL_GamepadButton button);
+
+/**
+ * Get the primary action button of a gamepad.
+ *
+ * \param type the type of the gamepad to check
+ * \returns the SDL_GamepadButton corresponding to the primary action (e.g. A on an Xbox controller)
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetGamepadPrimaryAction
+ */
+extern DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadPrimaryActionForType(SDL_GamepadType type);
+
+/**
+ * Get the primary action button of a gamepad.
+ *
+ * \param gamepad a gamepad
+ * \returns the SDL_GamepadButton corresponding to the primary action (e.g. A on an Xbox controller)
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetGamepadPrimaryActionForType
+ */
+extern DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadPrimaryAction(SDL_Gamepad *gamepad);
+
+/**
+ * Get the secondary action button of a gamepad.
+ *
+ * \param type the type of the gamepad to check
+ * \returns the SDL_GamepadButton corresponding to the secondary action (e.g. B on an Xbox controller)
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetGamepadSecondaryAction
+ */
+extern DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadSecondaryActionForType(SDL_GamepadType type);
+
+/**
+ * Get the secondary action button of a gamepad.
+ *
+ * \param gamepad a gamepad
+ * \returns the SDL_GamepadButton corresponding to the secondary action (e.g. B on an Xbox controller)
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetGamepadSecondaryActionForType
+ */
+extern DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadSecondaryAction(SDL_Gamepad *gamepad);
+
 /**
  * Get the number of touchpads on a gamepad.
  *

src/dynapi/SDL_dynapi.sym

@@ -923,6 +923,12 @@ SDL3_0.0.0 {
     SDL_RWprintf;
     SDL_RWvprintf;
     SDL_AllocateEventMemory;
+    SDL_GetGamepadButtonLabelForType;
+    SDL_GetGamepadButtonLabel;
+    SDL_GetGamepadPrimaryActionForType;
+    SDL_GetGamepadPrimaryAction;
+    SDL_GetGamepadSecondaryActionForType;
+    SDL_GetGamepadSecondaryAction;
     # extra symbols go here (don't modify this line)
   local: *;
 };

src/dynapi/SDL_dynapi_overrides.h

@@ -948,3 +948,9 @@
 #define SDL_RWprintf SDL_RWprintf_REAL
 #define SDL_RWvprintf SDL_RWvprintf_REAL
 #define SDL_AllocateEventMemory SDL_AllocateEventMemory_REAL
+#define SDL_GetGamepadButtonLabelForType SDL_GetGamepadButtonLabelForType_REAL
+#define SDL_GetGamepadButtonLabel SDL_GetGamepadButtonLabel_REAL
+#define SDL_GetGamepadPrimaryActionForType SDL_GetGamepadPrimaryActionForType_REAL
+#define SDL_GetGamepadPrimaryAction SDL_GetGamepadPrimaryAction_REAL
+#define SDL_GetGamepadSecondaryActionForType SDL_GetGamepadSecondaryActionForType_REAL
+#define SDL_GetGamepadSecondaryAction SDL_GetGamepadSecondaryAction_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -981,3 +981,9 @@ SDL_DYNAPI_PROC(int,SDL_ClearProperty,(SDL_PropertiesID a, const char *b),(a,b),
 SDL_DYNAPI_PROC(int,SDL_EnterAppMainCallbacks,(int a, char *b[], SDL_AppInit_func c, SDL_AppIterate_func d, SDL_AppEvent_func e, SDL_AppQuit_func f),(a,b,c,d,e,f),return)
 SDL_DYNAPI_PROC(size_t,SDL_RWvprintf,(SDL_RWops *a, const char *b, va_list c),(a,b,c),return)
 SDL_DYNAPI_PROC(void*,SDL_AllocateEventMemory,(size_t a),(a),return)
+SDL_DYNAPI_PROC(SDL_GamepadButtonLabel,SDL_GetGamepadButtonLabelForType,(SDL_GamepadType a, SDL_GamepadButton b),(a,b),return)
+SDL_DYNAPI_PROC(SDL_GamepadButtonLabel,SDL_GetGamepadButtonLabel,(SDL_Gamepad *a, SDL_GamepadButton b),(a,b),return)
+SDL_DYNAPI_PROC(SDL_GamepadButton,SDL_GetGamepadPrimaryActionForType,(SDL_GamepadType a),(a),return)
+SDL_DYNAPI_PROC(SDL_GamepadButton,SDL_GetGamepadPrimaryAction,(SDL_Gamepad *a),(a),return)
+SDL_DYNAPI_PROC(SDL_GamepadButton,SDL_GetGamepadSecondaryActionForType,(SDL_GamepadType a),(a),return)
+SDL_DYNAPI_PROC(SDL_GamepadButton,SDL_GetGamepadSecondaryAction,(SDL_Gamepad *a),(a),return)