Update SDL2 to newest version to fix 7.1 playback

This fixes 7.1 playback. Before this commit, SDL used 7.1 front audio configuration with Center Left and Center Right speakers, but without Rear speakers. See https://github.com/libsdl-org/SDL/issues/11709 for more details.
2025-07-07 20:14:09 +08:00
parent 489e60d2b1
commit 616c7673a4
92 changed files with 5767 additions and 3694 deletions
@@ -1,6 +1,6 @@
 /*
  Simple DirectMedia Layer
-  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>

  This software is provided 'as-is', without any express or implied
  warranty.  In no event will the authors be held liable for any damages
@@ -19,10 +19,12 @@
  3. This notice may not be removed or altered from any source distribution.
 */

+/* WIKI CATEGORY: GameController */
+
 /**
- *  \file SDL_gamecontroller.h
+ * # CategoryGameController
 *
- *  Include file for SDL game controller event handling
+ * Include file for SDL game controller event handling
 */

 #ifndef SDL_gamecontroller_h_
@@ -44,7 +46,7 @@ extern "C" {
 *  \file SDL_gamecontroller.h
 *
 *  In order to use these functions, SDL_Init() must have been called
- *  with the ::SDL_INIT_GAMECONTROLLER flag.  This causes SDL to scan the system
+ *  with the SDL_INIT_GAMECONTROLLER flag.  This causes SDL to scan the system
 *  for game controllers, and load appropriate drivers.
 *
 *  If you would like to receive controller updates while the application
@@ -58,7 +60,7 @@ extern "C" {
 struct _SDL_GameController;
 typedef struct _SDL_GameController SDL_GameController;

-typedef enum
+typedef enum SDL_GameControllerType
 {
    SDL_CONTROLLER_TYPE_UNKNOWN = 0,
    SDL_CONTROLLER_TYPE_XBOX360,
@@ -73,10 +75,11 @@ typedef enum
    SDL_CONTROLLER_TYPE_NVIDIA_SHIELD,
    SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT,
    SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT,
-    SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR
+    SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR,
+    SDL_CONTROLLER_TYPE_MAX
 } SDL_GameControllerType;

-typedef enum
+typedef enum SDL_GameControllerBindType
 {
    SDL_CONTROLLER_BINDTYPE_NONE = 0,
    SDL_CONTROLLER_BINDTYPE_BUTTON,
@@ -85,7 +88,7 @@ typedef enum
 } SDL_GameControllerBindType;

 /**
- *  Get the SDL joystick layer binding for this controller button/axis mapping
+ * Get the SDL joystick layer binding for this controller button/axis mapping
 */
 typedef struct SDL_GameControllerButtonBind
 {
@@ -143,6 +146,10 @@ typedef struct SDL_GameControllerButtonBind
 * If a new mapping is loaded for an already known controller GUID, the later
 * version will overwrite the one currently loaded.
 *
+ * If this function is called before SDL_Init, SDL will generate an
+ * SDL_CONTROLLERDEVICEADDED event for matching controllers that are plugged
+ * in at the time that SDL_Init is called.
+ *
 * Mappings not belonging to the current platform or with no platform field
 * specified will be ignored (i.e. mappings for Linux will be ignored in
 * Windows, etc).
@@ -151,8 +158,8 @@ typedef struct SDL_GameControllerButtonBind
 * processing it, so take this into consideration if you are in a memory
 * constrained environment.
 *
- * \param rw the data stream for the mappings to be added
- * \param freerw non-zero to close the stream after being read
+ * \param rw the data stream for the mappings to be added.
+ * \param freerw non-zero to close the stream after being read.
 * \returns the number of mappings added or -1 on error; call SDL_GetError()
 *          for more information.
 *
@@ -161,13 +168,15 @@ typedef struct SDL_GameControllerButtonBind
 * \sa SDL_GameControllerAddMapping
 * \sa SDL_GameControllerAddMappingsFromFile
 * \sa SDL_GameControllerMappingForGUID
+ * \sa SDL_CONTROLLERDEVICEADDED
 */
 extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw);

 /**
- *  Load a set of mappings from a file, filtered by the current SDL_GetPlatform()
+ * Load a set of mappings from a file, filtered by the current
+ * SDL_GetPlatform()
 *
- *  Convenience macro.
+ * Convenience macro.
 */
 #define SDL_GameControllerAddMappingsFromFile(file)   SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)

@@ -189,7 +198,11 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
 * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
 * ```
 *
- * \param mappingString the mapping string
+ * If this function is called before SDL_Init, SDL will generate an
+ * SDL_CONTROLLERDEVICEADDED event for matching controllers that are plugged
+ * in at the time that SDL_Init is called.
+ *
+ * \param mappingString the mapping string.
 * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
 *          -1 on error; call SDL_GetError() for more information.
 *
@@ -197,6 +210,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
 *
 * \sa SDL_GameControllerMapping
 * \sa SDL_GameControllerMappingForGUID
+ * \sa SDL_CONTROLLERDEVICEADDED
 */
 extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString);

@@ -224,7 +238,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_ind
 *
 * The returned string must be freed with SDL_free().
 *
- * \param guid a structure containing the GUID for which a mapping is desired
+ * \param guid a structure containing the GUID for which a mapping is desired.
 * \returns a mapping string or NULL on error; call SDL_GetError() for more
 *          information.
 *
@@ -243,7 +257,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID
 * Details about mappings are discussed with SDL_GameControllerAddMapping().
 *
 * \param gamecontroller the game controller you want to get the current
- *                       mapping for
+ *                       mapping for.
 * \returns a string that has the controller's mapping or NULL if no mapping
 *          is available; call SDL_GetError() for more information.
 *
@@ -261,7 +275,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gam
 * SDL_JoystickOpen().
 *
 * \param joystick_index the device_index of a device, up to
- *                       SDL_NumJoysticks()
+ *                       SDL_NumJoysticks().
 * \returns SDL_TRUE if the given joystick is supported by the game controller
 *          interface, SDL_FALSE if it isn't or it's an invalid index.
 *
@@ -281,7 +295,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
 * SDL_JoystickOpen().
 *
 * \param joystick_index the device_index of a device, from zero to
- *                       SDL_NumJoysticks()-1
+ *                       SDL_NumJoysticks()-1.
 * \returns the implementation-dependent name for the game controller, or NULL
 *          if there is no name or the index is invalid.
 *
@@ -302,7 +316,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_
 * SDL_JoystickOpen().
 *
 * \param joystick_index the device_index of a device, from zero to
- *                       SDL_NumJoysticks()-1
+ *                       SDL_NumJoysticks()-1.
 * \returns the implementation-dependent path for the game controller, or NULL
 *          if there is no path or the index is invalid.
 *
@@ -318,7 +332,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerPathForIndex(int joystick_
 * This can be called before any controllers are opened.
 *
 * \param joystick_index the device_index of a device, from zero to
- *                       SDL_NumJoysticks()-1
+ *                       SDL_NumJoysticks()-1.
 * \returns the controller type.
 *
 * \since This function is available since SDL 2.0.12.
@@ -331,7 +345,7 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(in
 * This can be called before any controllers are opened.
 *
 * \param joystick_index the device_index of a device, from zero to
- *                       SDL_NumJoysticks()-1
+ *                       SDL_NumJoysticks()-1.
 * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
 *          no mapping is available.
 *
@@ -351,7 +365,7 @@ extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joysti
 * be used there instead.
 *
 * \param joystick_index the device_index of a device, up to
- *                       SDL_NumJoysticks()
+ *                       SDL_NumJoysticks().
 * \returns a gamecontroller identifier or NULL if an error occurred; call
 *          SDL_GetError() for more information.
 *
@@ -366,7 +380,7 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_
 /**
 * Get the SDL_GameController associated with an instance id.
 *
- * \param joyid the instance id to get the SDL_GameController for
+ * \param joyid the instance id to get the SDL_GameController for.
 * \returns an SDL_GameController on success or NULL on failure; call
 *          SDL_GetError() for more information.
 *
@@ -398,7 +412,7 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(in
 * it takes a controller identifier instead of the (unstable) device index.
 *
 * \param gamecontroller a game controller identifier previously returned by
- *                       SDL_GameControllerOpen()
+ *                       SDL_GameControllerOpen().
 * \returns the implementation dependent name for the game controller, or NULL
 *          if there is no name or the identifier passed is invalid.
 *
@@ -416,7 +430,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *g
 * it takes a controller identifier instead of the (unstable) device index.
 *
 * \param gamecontroller a game controller identifier previously returned by
- *                       SDL_GameControllerOpen()
+ *                       SDL_GameControllerOpen().
 * \returns the implementation dependent path for the game controller, or NULL
 *          if there is no path or the identifier passed is invalid.
 *
@@ -523,11 +537,25 @@ extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetFirmwareVersion(SDL_GameCont
 */
 extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller);

+/**
+ * Get the Steam Input handle of an opened controller, if available.
+ *
+ * Returns an InputHandle_t for the controller that can be used with Steam
+ * Input API: https://partner.steamgames.com/doc/api/ISteamInput
+ *
+ * \param gamecontroller the game controller object to query.
+ * \returns the gamepad handle, or 0 if unavailable.
+ *
+ * \since This function is available since SDL 2.30.0.
+ */
+extern DECLSPEC Uint64 SDLCALL SDL_GameControllerGetSteamHandle(SDL_GameController *gamecontroller);
+
+
 /**
 * Check if a controller has been opened and is currently connected.
 *
 * \param gamecontroller a game controller identifier previously returned by
- *                       SDL_GameControllerOpen()
+ *                       SDL_GameControllerOpen().
 * \returns SDL_TRUE if the controller has been opened and is currently
 *          connected, or SDL_FALSE if not.
 *
@@ -552,7 +580,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameControlle
 * cause SDL to crash.
 *
 * \param gamecontroller the game controller object that you want to get a
- *                       joystick from
+ *                       joystick from.
 * \returns a SDL_Joystick object; call SDL_GetError() for more information.
 *
 * \since This function is available since SDL 2.0.0.
@@ -569,7 +597,7 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameCont
 * Any number can be passed to SDL_GameControllerEventState(), but only -1, 0,
 * and 1 will have any effect. Other numbers will just be returned.
 *
- * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
+ * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`.
 * \returns the same value passed to the function, with exception to -1
 *          (SDL_QUERY), which will return the current state.
 *
@@ -592,15 +620,19 @@ extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void);


 /**
- *  The list of axes available from a controller
+ * The list of axes available from a controller
 *
- *  Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to SDL_JOYSTICK_AXIS_MAX,
- *  and are centered within ~8000 of zero, though advanced UI will allow users to set
- *  or autodetect the dead zone, which varies between controllers.
+ * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to
+ * SDL_JOYSTICK_AXIS_MAX, 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_GameControllerGetAxis(). Note that this is
+ * not the same range that will be reported by the lower-level
+ * SDL_GetJoystickAxis().
 */
-typedef enum
+typedef enum SDL_GameControllerAxis
 {
    SDL_CONTROLLER_AXIS_INVALID = -1,
    SDL_CONTROLLER_AXIS_LEFTX,
@@ -624,7 +656,7 @@ typedef enum
 * `SDL_CONTROLLER_AXIS_TRIGGERRIGHT` and `SDL_CONTROLLER_AXIS_TRIGGERLEFT`,
 * respectively.
 *
- * \param str string representing a SDL_GameController axis
+ * \param str string representing a SDL_GameController axis.
 * \returns the SDL_GameControllerAxis enum corresponding to the input string,
 *          or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
 *
@@ -639,7 +671,7 @@ extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromStri
 *
 * The caller should not SDL_free() the returned string.
 *
- * \param axis an enum value for a given SDL_GameControllerAxis
+ * \param axis an enum value for a given SDL_GameControllerAxis.
 * \returns a string for the given axis, or NULL if an invalid axis is
 *          specified. The string returned is of the format used by
 *          SDL_GameController mapping strings.
@@ -653,8 +685,8 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameC
 /**
 * Get the SDL joystick layer binding for a controller axis mapping.
 *
- * \param gamecontroller a game controller
- * \param axis an axis enum value (one of the SDL_GameControllerAxis values)
+ * \param gamecontroller a game controller.
+ * \param axis an axis enum value (one of the SDL_GameControllerAxis values).
 * \returns a SDL_GameControllerButtonBind describing the bind. On failure
 *          (like the given Controller axis doesn't exist on the device), its
 *          `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
@@ -673,8 +705,8 @@ SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller,
 * This merely reports whether the controller's mapping defined this axis, as
 * that is all the information SDL has about the physical device.
 *
- * \param gamecontroller a game controller
- * \param axis an axis enum value (an SDL_GameControllerAxis value)
+ * \param gamecontroller a game controller.
+ * \param axis an axis enum value (an SDL_GameControllerAxis value).
 * \returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise.
 *
 * \since This function is available since SDL 2.0.14.
@@ -687,11 +719,15 @@ 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).
 *
- * \param gamecontroller a game controller
- * \param axis an axis index (one of the SDL_GameControllerAxis values)
+ * 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_JoystickGetAxis(), which normally uses the full range.
+ *
+ * \param gamecontroller a game controller.
+ * \param axis an axis index (one of the SDL_GameControllerAxis values).
 * \returns axis state (including 0) on success or 0 (also) on failure; call
 *          SDL_GetError() for more information.
 *
@@ -703,9 +739,9 @@ extern DECLSPEC Sint16 SDLCALL
 SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);

 /**
- *  The list of buttons available from a controller
+ * The list of buttons available from a controller
 */
-typedef enum
+typedef enum SDL_GameControllerButton
 {
    SDL_CONTROLLER_BUTTON_INVALID = -1,
    SDL_CONTROLLER_BUTTON_A,
@@ -740,7 +776,7 @@ typedef enum
 * SDL_GameController mapping. You do not normally need to call this function
 * unless you are parsing SDL_GameController mappings in your own code.
 *
- * \param str string representing a SDL_GameController axis
+ * \param str string representing a SDL_GameController axis.
 * \returns the SDL_GameControllerButton enum corresponding to the input
 *          string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
 *
@@ -753,7 +789,7 @@ extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFrom
 *
 * The caller should not SDL_free() the returned string.
 *
- * \param button an enum value for a given SDL_GameControllerButton
+ * \param button an enum value for a given SDL_GameControllerButton.
 * \returns a string for the given button, or NULL if an invalid button is
 *          specified. The string returned is of the format used by
 *          SDL_GameController mapping strings.
@@ -767,8 +803,8 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_Gam
 /**
 * Get the SDL joystick layer binding for a controller button mapping.
 *
- * \param gamecontroller a game controller
- * \param button an button enum value (an SDL_GameControllerButton value)
+ * \param gamecontroller a game controller.
+ * \param button an button enum value (an SDL_GameControllerButton value).
 * \returns a SDL_GameControllerButtonBind describing the bind. On failure
 *          (like the given Controller button doesn't exist on the device),
 *          its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
@@ -787,8 +823,8 @@ SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller,
 * This merely reports whether the controller's mapping defined this button,
 * as that is all the information SDL has about the physical device.
 *
- * \param gamecontroller a game controller
- * \param button a button enum value (an SDL_GameControllerButton value)
+ * \param gamecontroller a game controller.
+ * \param button a button enum value (an SDL_GameControllerButton value).
 * \returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise.
 *
 * \since This function is available since SDL 2.0.14.
@@ -799,8 +835,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController
 /**
 * Get the current state of a button on a game controller.
 *
- * \param gamecontroller a game controller
- * \param button a button index (one of the SDL_GameControllerButton values)
+ * \param gamecontroller a game controller.
+ * \param button a button index (one of the SDL_GameControllerButton values).
 * \returns 1 for pressed state or 0 for not pressed state or error; call
 *          SDL_GetError() for more information.
 *
@@ -836,8 +872,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameControll
 /**
 * Return whether a game controller has a particular sensor.
 *
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
+ * \param gamecontroller The controller to query.
+ * \param type The type of sensor to query.
 * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
 *
 * \since This function is available since SDL 2.0.14.
@@ -847,9 +883,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController
 /**
 * Set whether data reporting for a game controller sensor is enabled.
 *
- * \param gamecontroller The controller to update
- * \param type The type of sensor to enable/disable
- * \param enabled Whether data reporting should be enabled
+ * \param gamecontroller The controller to update.
+ * \param type The type of sensor to enable/disable.
+ * \param enabled Whether data reporting should be enabled.
 * \returns 0 or -1 if an error occurred.
 *
 * \since This function is available since SDL 2.0.14.
@@ -859,8 +895,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameControlle
 /**
 * Query whether sensor data reporting is enabled for a game controller.
 *
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
+ * \param gamecontroller The controller to query.
+ * \param type The type of sensor to query.
 * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
 *
 * \since This function is available since SDL 2.0.14.
@@ -871,8 +907,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameContr
 * Get the data rate (number of events per second) of a game controller
 * sensor.
 *
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
+ * \param gamecontroller The controller to query.
+ * \param type The type of sensor to query.
 * \return the data rate, or 0.0f if the data rate is not available.
 *
 * \since This function is available since SDL 2.0.16.
@@ -885,10 +921,10 @@ extern DECLSPEC float SDLCALL SDL_GameControllerGetSensorDataRate(SDL_GameContro
 * The number of values and interpretation of the data is sensor dependent.
 * See SDL_sensor.h for the details for each type of sensor.
 *
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
- * \param data A pointer filled with the current sensor state
- * \param num_values The number of values to write to data
+ * \param gamecontroller The controller to query.
+ * \param type The type of sensor to query.
+ * \param data A pointer filled with the current sensor state.
+ * \param num_values The number of values to write to data.
 * \return 0 or -1 if an error occurred.
 *
 * \since This function is available since SDL 2.0.14.
@@ -902,12 +938,12 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController *
 * The number of values and interpretation of the data is sensor dependent.
 * See SDL_sensor.h for the details for each type of sensor.
 *
- * \param gamecontroller The controller to query
- * \param type The type of sensor to query
+ * \param gamecontroller The controller to query.
+ * \param type The type of sensor to query.
 * \param timestamp A pointer filled with the timestamp in microseconds of the
- *                  current sensor reading if available, or 0 if not
- * \param data A pointer filled with the current sensor state
- * \param num_values The number of values to write to data
+ *                  current sensor reading if available, or 0 if not.
+ * \param data A pointer filled with the current sensor state.
+ * \param num_values The number of values to write to data.
 * \return 0 or -1 if an error occurred.
 *
 * \since This function is available since SDL 2.26.0.
@@ -920,13 +956,13 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorDataWithTimestamp(SDL_Gam
 * Each call to this function cancels any previous rumble effect, and calling
 * it with 0 intensity stops any rumbling.
 *
- * \param gamecontroller The controller to vibrate
+ * \param gamecontroller The controller to vibrate.
 * \param low_frequency_rumble The intensity of the low frequency (left)
- *                             rumble motor, from 0 to 0xFFFF
+ *                             rumble motor, from 0 to 0xFFFF.
 * \param high_frequency_rumble The intensity of the high frequency (right)
- *                              rumble motor, from 0 to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
- * \returns 0, or -1 if rumble isn't supported on this controller
+ *                              rumble motor, from 0 to 0xFFFF.
+ * \param duration_ms The duration of the rumble effect, in milliseconds.
+ * \returns 0, or -1 if rumble isn't supported on this controller.
 *
 * \since This function is available since SDL 2.0.9.
 *
@@ -945,13 +981,13 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecon
 * want the (more common) whole-controller rumble, use
 * SDL_GameControllerRumble() instead.
 *
- * \param gamecontroller The controller to vibrate
+ * \param gamecontroller The controller to vibrate.
 * \param left_rumble The intensity of the left trigger rumble motor, from 0
- *                    to 0xFFFF
+ *                    to 0xFFFF.
 * \param right_rumble The intensity of the right trigger rumble motor, from 0
- *                     to 0xFFFF
- * \param duration_ms The duration of the rumble effect, in milliseconds
- * \returns 0, or -1 if trigger rumble isn't supported on this controller
+ *                     to 0xFFFF.
+ * \param duration_ms The duration of the rumble effect, in milliseconds.
+ * \returns 0, or -1 if trigger rumble isn't supported on this controller.
 *
 * \since This function is available since SDL 2.0.14.
 *
@@ -962,9 +998,9 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController
 /**
 * Query whether a game controller has an LED.
 *
- * \param gamecontroller The controller to query
+ * \param gamecontroller The controller to query.
 * \returns SDL_TRUE, or SDL_FALSE if this controller does not have a
- *          modifiable LED
+ *          modifiable LED.
 *
 * \since This function is available since SDL 2.0.14.
 */
@@ -973,9 +1009,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *ga
 /**
 * Query whether a game controller has rumble support.
 *
- * \param gamecontroller The controller to query
+ * \param gamecontroller The controller to query.
 * \returns SDL_TRUE, or SDL_FALSE if this controller does not have rumble
- *          support
+ *          support.
 *
 * \since This function is available since SDL 2.0.18.
 *
@@ -986,9 +1022,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumble(SDL_GameController
 /**
 * Query whether a game controller has rumble support on triggers.
 *
- * \param gamecontroller The controller to query
+ * \param gamecontroller The controller to query.
 * \returns SDL_TRUE, or SDL_FALSE if this controller does not have trigger
- *          rumble support
+ *          rumble support.
 *
 * \since This function is available since SDL 2.0.18.
 *
@@ -999,11 +1035,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumbleTriggers(SDL_GameCon
 /**
 * Update a game controller's LED color.
 *
- * \param gamecontroller The controller to update
- * \param red The intensity of the red LED
- * \param green The intensity of the green LED
- * \param blue The intensity of the blue LED
- * \returns 0, or -1 if this controller does not have a modifiable LED
+ * \param gamecontroller The controller to update.
+ * \param red The intensity of the red LED.
+ * \param green The intensity of the green LED.
+ * \param blue The intensity of the blue LED.
+ * \returns 0, or -1 if this controller does not have a modifiable LED.
 *
 * \since This function is available since SDL 2.0.14.
 */
@@ -1012,11 +1048,11 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecon
 /**
 * Send a controller specific effect packet
 *
- * \param gamecontroller The controller to affect
- * \param data The data to send to the controller
- * \param size The size of the data to send to the controller
+ * \param gamecontroller The controller to affect.
+ * \param data The data to send to the controller.
+ * \param size The size of the data to send to the controller.
 * \returns 0, or -1 if this controller or driver doesn't support effect
- *          packets
+ *          packets.
 *
 * \since This function is available since SDL 2.0.16.
 */
@@ -1026,7 +1062,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gam
 * Close a game controller previously opened with SDL_GameControllerOpen().
 *
 * \param gamecontroller a game controller identifier previously returned by
- *                       SDL_GameControllerOpen()
+ *                       SDL_GameControllerOpen().
 *
 * \since This function is available since SDL 2.0.0.
 *
@@ -1038,9 +1074,9 @@ extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecon
 * Return the sfSymbolsName for a given button on a game controller on Apple
 * platforms.
 *
- * \param gamecontroller the controller to query
- * \param button a button on the game controller
- * \returns the sfSymbolsName or NULL if the name can't be found
+ * \param gamecontroller the controller to query.
+ * \param button a button on the game controller.
+ * \returns the sfSymbolsName or NULL if the name can't be found.
 *
 * \since This function is available since SDL 2.0.18.
 *
@@ -1052,9 +1088,9 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForBu
 * Return the sfSymbolsName for a given axis on a game controller on Apple
 * platforms.
 *
- * \param gamecontroller the controller to query
- * \param axis an axis on the game controller
- * \returns the sfSymbolsName or NULL if the name can't be found
+ * \param gamecontroller the controller to query.
+ * \param axis an axis on the game controller.
+ * \returns the sfSymbolsName or NULL if the name can't be found.
 *
 * \since This function is available since SDL 2.0.18.
 *