From 312faf930525198ed502d4aeca89c27d9bb0a877 Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Fri, 10 Nov 2023 15:37:21 -0800
Subject: [PATCH] Updated documentation for the controller face buttons
---
include/SDL3/SDL_gamepad.h | 53 +++++++++++++++++++++++++-------------
1 file changed, 35 insertions(+), 18 deletions(-)
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index ccbd5d8baaf1..9d11b8efc5d2 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -77,14 +77,31 @@ typedef enum
/**
* The list of buttons available on a gamepad
+ *
+ * For controllers that use a diamond pattern for the face buttons,
+ * the south/east/west/north buttons below correspond to the locations
+ * in the diamond pattern. For Xbox controllers, this would be A/B/X/Y,
+ * for Nintendo Switch controllers, this would be B/A/Y/X, for
+ * PlayStation controllers this would be Cross/Circle/Square/Triangle.
+ *
+ * For controllers that don't use a diamond pattern for the face buttons,
+ * the south/east/west/north buttons indicate the buttons labeled A, B,
+ * C, D, or 1, 2, 3, 4, or for controllers that aren't labeled, they are
+ * the primary, secondary, etc. buttons.
+ *
+ * The activate action is often the south button and the cancel action
+ * is often the east button, but in some regions this is reversed, so
+ * your game should allow remapping actions based on user preferences.
+ *
+ * You can query the labels for the face buttons using SDL_GetGamepadButtonLabel()
*/
typedef enum
{
SDL_GAMEPAD_BUTTON_INVALID = -1,
- SDL_GAMEPAD_BUTTON_SOUTH,
- SDL_GAMEPAD_BUTTON_EAST,
- SDL_GAMEPAD_BUTTON_WEST,
- SDL_GAMEPAD_BUTTON_NORTH,
+ SDL_GAMEPAD_BUTTON_SOUTH, /* Bottom face button (e.g. Xbox A button) */
+ SDL_GAMEPAD_BUTTON_EAST, /* Right face button (e.g. Xbox B button) */
+ SDL_GAMEPAD_BUTTON_WEST, /* Left face button (e.g. Xbox X button) */
+ SDL_GAMEPAD_BUTTON_NORTH, /* Top face button (e.g. Xbox Y button) */
SDL_GAMEPAD_BUTTON_BACK,
SDL_GAMEPAD_BUTTON_GUIDE,
SDL_GAMEPAD_BUTTON_START,
@@ -96,12 +113,12 @@ typedef enum
SDL_GAMEPAD_BUTTON_DPAD_DOWN,
SDL_GAMEPAD_BUTTON_DPAD_LEFT,
SDL_GAMEPAD_BUTTON_DPAD_RIGHT,
- SDL_GAMEPAD_BUTTON_MISC1, /* Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button) */
- SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /* Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */
- SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /* Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */
- SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /* Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */
- SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /* Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */
- SDL_GAMEPAD_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */
+ SDL_GAMEPAD_BUTTON_MISC1, /* Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button) */
+ SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /* Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */
+ SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /* Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */
+ SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /* Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */
+ SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /* Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */
+ SDL_GAMEPAD_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */
SDL_GAMEPAD_BUTTON_MAX
} SDL_GamepadButton;
@@ -115,14 +132,14 @@ typedef enum
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_GAMEPAD_BUTTON_LABEL_A,
+ SDL_GAMEPAD_BUTTON_LABEL_B,
+ SDL_GAMEPAD_BUTTON_LABEL_X,
+ SDL_GAMEPAD_BUTTON_LABEL_Y,
+ SDL_GAMEPAD_BUTTON_LABEL_CROSS,
+ SDL_GAMEPAD_BUTTON_LABEL_CIRCLE,
+ SDL_GAMEPAD_BUTTON_LABEL_SQUARE,
+ SDL_GAMEPAD_BUTTON_LABEL_TRIANGLE
} SDL_GamepadButtonLabel;
/**