mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-09-29 14:38:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document that the joystick and gamepad functions are thread-safe

Browse Source
This commit is contained in:
Sam Lantinga
2025-09-22 08:32:39 -07:00
parent 8abbb98222
commit 86203d8312
2 changed files with 256 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
include/SDL3/SDL_gamepad.h
View File

@@ -424,6 +424,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file)
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_ReloadGamepadMappings(void); extern SDL_DECLSPEC bool SDLCALL SDL_ReloadGamepadMappings(void);
@@ -438,6 +440,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReloadGamepadMappings(void);
* single allocation that should be freed with SDL_free() when it is * single allocation that should be freed with SDL_free() when it is
* no longer needed. * no longer needed.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count); extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count);
@@ -450,6 +454,8 @@ extern SDL_DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count);
* information. This should be freed with SDL_free() when it is no * information. This should be freed with SDL_free() when it is no
* longer needed. * longer needed.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickGUIDForID * \sa SDL_GetJoystickGUIDForID
@@ -467,6 +473,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID guid);
* available; call SDL_GetError() for more information. This should * available; call SDL_GetError() for more information. This should
* be freed with SDL_free() when it is no longer needed. * be freed with SDL_free() when it is no longer needed.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_AddGamepadMapping * \sa SDL_AddGamepadMapping
@@ -487,6 +495,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad);
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_AddGamepadMapping * \sa SDL_AddGamepadMapping
@@ -499,6 +509,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadMapping(SDL_JoystickID instance_i
* *
* \returns true if a gamepad is connected, false otherwise. * \returns true if a gamepad is connected, false otherwise.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepads * \sa SDL_GetGamepads
@@ -514,6 +526,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasGamepad(void);
* call SDL_GetError() for more information. This should be freed * call SDL_GetError() for more information. This should be freed
* with SDL_free() when it is no longer needed. * with SDL_free() when it is no longer needed.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_HasGamepad * \sa SDL_HasGamepad
@@ -528,6 +542,8 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetGamepads(int *count);
* \returns true if the given joystick is supported by the gamepad interface, * \returns true if the given joystick is supported by the gamepad interface,
* false if it isn't or it's an invalid index. * false if it isn't or it's an invalid index.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoysticks * \sa SDL_GetJoysticks
@@ -544,6 +560,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id);
* \returns the name of the selected gamepad. If no name can be found, this * \returns the name of the selected gamepad. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information. * function returns NULL; call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadName * \sa SDL_GetGamepadName
@@ -560,6 +578,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID
* \returns the path of the selected gamepad. If no path can be found, this * \returns the path of the selected gamepad. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information. * function returns NULL; call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadPath * \sa SDL_GetGamepadPath
@@ -575,6 +595,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPathForID(SDL_JoystickID
* \param instance_id the joystick instance ID. * \param instance_id the joystick instance ID.
* \returns the player index of a gamepad, or -1 if it's not available. * \returns the player index of a gamepad, or -1 if it's not available.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadPlayerIndex * \sa SDL_GetGamepadPlayerIndex
@@ -591,6 +613,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndexForID(SDL_JoystickID in
* \returns the GUID of the selected gamepad. If called on an invalid index, * \returns the GUID of the selected gamepad. If called on an invalid index,
* this function returns a zero GUID. * this function returns a zero GUID.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GUIDToString * \sa SDL_GUIDToString
@@ -608,6 +632,8 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetGamepadGUIDForID(SDL_JoystickID inst
* \returns the USB vendor ID of the selected gamepad. If called on an invalid * \returns the USB vendor ID of the selected gamepad. If called on an invalid
* index, this function returns zero. * index, this function returns zero.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadVendor * \sa SDL_GetGamepadVendor
@@ -625,6 +651,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendorForID(SDL_JoystickID inst
* \returns the USB product ID of the selected gamepad. If called on an * \returns the USB product ID of the selected gamepad. If called on an
* invalid index, this function returns zero. * invalid index, this function returns zero.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadProduct * \sa SDL_GetGamepadProduct
@@ -642,6 +670,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductForID(SDL_JoystickID ins
* \returns the product version of the selected gamepad. If called on an * \returns the product version of the selected gamepad. If called on an
* invalid index, this function returns zero. * invalid index, this function returns zero.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadProductVersion * \sa SDL_GetGamepadProductVersion
@@ -657,6 +687,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersionForID(SDL_Joystic
* \param instance_id the joystick instance ID. * \param instance_id the joystick instance ID.
* \returns the gamepad type. * \returns the gamepad type.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadType * \sa SDL_GetGamepadType
@@ -673,6 +705,8 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeForID(SDL_Joystick
* \param instance_id the joystick instance ID. * \param instance_id the joystick instance ID.
* \returns the gamepad type. * \returns the gamepad type.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadTypeForID * \sa SDL_GetGamepadTypeForID
@@ -690,6 +724,8 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_Joys
* \returns the mapping string. Returns NULL if no mapping is available. This * \returns the mapping string. Returns NULL if no mapping is available. This
* should be freed with SDL_free() when it is no longer needed. * should be freed with SDL_free() when it is no longer needed.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepads * \sa SDL_GetGamepads
@@ -704,6 +740,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetGamepadMappingForID(SDL_JoystickID ins
* \returns a gamepad identifier or NULL if an error occurred; call * \returns a gamepad identifier or NULL if an error occurred; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_CloseGamepad * \sa SDL_CloseGamepad
@@ -719,6 +757,8 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_OpenGamepad(SDL_JoystickID instanc
* \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been
* opened yet; call SDL_GetError() for more information. * opened yet; call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID instance_id); extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID instance_id);
@@ -729,6 +769,8 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromID(SDL_JoystickID in
* \param player_index the player index, which different from the instance ID. * \param player_index the player index, which different from the instance ID.
* \returns the SDL_Gamepad associated with a player index. * \returns the SDL_Gamepad associated with a player index.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadPlayerIndex * \sa SDL_GetGamepadPlayerIndex
@@ -759,6 +801,8 @@ extern SDL_DECLSPEC SDL_Gamepad * SDLCALL SDL_GetGamepadFromPlayerIndex(int play
* \returns a valid property ID on success or 0 on failure; call * \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepad *gamepad); extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepad *gamepad);
@@ -777,6 +821,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepa
* \returns the instance ID of the specified gamepad on success or 0 on * \returns the instance ID of the specified gamepad on success or 0 on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad); extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad);
@@ -789,6 +835,8 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad
* \returns the implementation dependent name for the gamepad, or NULL if * \returns the implementation dependent name for the gamepad, or NULL if
* there is no name or the identifier passed is invalid. * there is no name or the identifier passed is invalid.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadNameForID * \sa SDL_GetGamepadNameForID
@@ -803,6 +851,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad
* \returns the implementation dependent path for the gamepad, or NULL if * \returns the implementation dependent path for the gamepad, or NULL if
* there is no path or the identifier passed is invalid. * there is no path or the identifier passed is invalid.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadPathForID * \sa SDL_GetGamepadPathForID
@@ -816,6 +866,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad
* \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not
* available. * available.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadTypeForID * \sa SDL_GetGamepadTypeForID
@@ -829,6 +881,8 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadType(SDL_Gamepad *game
* \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not
* available. * available.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetRealGamepadTypeForID * \sa SDL_GetRealGamepadTypeForID
@@ -843,6 +897,8 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadType(SDL_Gamepad *
* \param gamepad the gamepad object to query. * \param gamepad the gamepad object to query.
* \returns the player index for gamepad, or -1 if it's not available. * \returns the player index for gamepad, or -1 if it's not available.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_SetGamepadPlayerIndex * \sa SDL_SetGamepadPlayerIndex
@@ -858,6 +914,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad);
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadPlayerIndex * \sa SDL_GetGamepadPlayerIndex
@@ -872,6 +930,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad,
* \param gamepad the gamepad object to query. * \param gamepad the gamepad object to query.
* \returns the USB vendor ID, or zero if unavailable. * \returns the USB vendor ID, or zero if unavailable.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadVendorForID * \sa SDL_GetGamepadVendorForID
@@ -886,6 +946,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadVendor(SDL_Gamepad *gamepad);
* \param gamepad the gamepad object to query. * \param gamepad the gamepad object to query.
* \returns the USB product ID, or zero if unavailable. * \returns the USB product ID, or zero if unavailable.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadProductForID * \sa SDL_GetGamepadProductForID
@@ -900,6 +962,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProduct(SDL_Gamepad *gamepad);
* \param gamepad the gamepad object to query. * \param gamepad the gamepad object to query.
* \returns the USB product version, or zero if unavailable. * \returns the USB product version, or zero if unavailable.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadProductVersionForID * \sa SDL_GetGamepadProductVersionForID
@@ -914,6 +978,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadProductVersion(SDL_Gamepad *gam
* \param gamepad the gamepad object to query. * \param gamepad the gamepad object to query.
* \returns the gamepad firmware version, or zero if unavailable. * \returns the gamepad firmware version, or zero if unavailable.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepad); extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepad);
@@ -926,6 +992,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *ga
* \param gamepad the gamepad object to query. * \param gamepad the gamepad object to query.
* \returns the serial number, or NULL if unavailable. * \returns the serial number, or NULL if unavailable.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad); extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad);
@@ -939,6 +1007,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamep
* \param gamepad the gamepad object to query. * \param gamepad the gamepad object to query.
* \returns the gamepad handle, or 0 if unavailable. * \returns the gamepad handle, or 0 if unavailable.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepad); extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepad);
@@ -951,6 +1021,8 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepa
* `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError()
* for more information. * for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnectionState(SDL_Gamepad *gamepad); extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnectionState(SDL_Gamepad *gamepad);
@@ -971,6 +1043,8 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetGamepadConnection
* battery. * battery.
* \returns the current battery state. * \returns the current battery state.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *gamepad, int *percent); extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *gamepad, int *percent);
@@ -983,6 +1057,8 @@ extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *
* \returns true if the gamepad has been opened and is currently connected, or * \returns true if the gamepad has been opened and is currently connected, or
* false if not. * false if not.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); extern SDL_DECLSPEC bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);
@@ -1003,6 +1079,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);
* \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError() * \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError()
* for more information. * for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *gamepad); extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *gamepad);
@@ -1015,6 +1093,8 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *g
* *
* \param enabled whether to process gamepad events or not. * \param enabled whether to process gamepad events or not.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GamepadEventsEnabled * \sa SDL_GamepadEventsEnabled
@@ -1030,6 +1110,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(bool enabled);
* *
* \returns true if gamepad events are being processed, false otherwise. * \returns true if gamepad events are being processed, false otherwise.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_SetGamepadEventsEnabled * \sa SDL_SetGamepadEventsEnabled
@@ -1046,6 +1128,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GamepadEventsEnabled(void);
* single allocation that should be freed with SDL_free() when it is * single allocation that should be freed with SDL_free() when it is
* no longer needed. * no longer needed.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gamepad *gamepad, int *count); extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gamepad *gamepad, int *count);
@@ -1057,6 +1141,8 @@ extern SDL_DECLSPEC SDL_GamepadBinding ** SDLCALL SDL_GetGamepadBindings(SDL_Gam
* enabled. Under such circumstances, it will not be necessary to call this * enabled. Under such circumstances, it will not be necessary to call this
* function. * function.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void); extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void);
@@ -1073,6 +1159,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateGamepads(void);
* \returns the SDL_GamepadType enum corresponding to the input string, or * \returns the SDL_GamepadType enum corresponding to the input string, or
* `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found. * `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadStringForType * \sa SDL_GetGamepadStringForType
@@ -1087,6 +1175,8 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c
* specified. The string returned is of the format used by * specified. The string returned is of the format used by
* SDL_Gamepad mapping strings. * SDL_Gamepad mapping strings.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadTypeFromString * \sa SDL_GetGamepadTypeFromString
@@ -1109,6 +1199,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForType(SDL_Gamepad
* \returns the SDL_GamepadAxis enum corresponding to the input string, or * \returns the SDL_GamepadAxis enum corresponding to the input string, or
* `SDL_GAMEPAD_AXIS_INVALID` if no match was found. * `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadStringForAxis * \sa SDL_GetGamepadStringForAxis
@@ -1123,6 +1215,8 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c
* specified. The string returned is of the format used by * specified. The string returned is of the format used by
* SDL_Gamepad mapping strings. * SDL_Gamepad mapping strings.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadAxisFromString * \sa SDL_GetGamepadAxisFromString
@@ -1139,6 +1233,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_Gamepad
* \param axis an axis enum value (an SDL_GamepadAxis value). * \param axis an axis enum value (an SDL_GamepadAxis value).
* \returns true if the gamepad has this axis, false otherwise. * \returns true if the gamepad has this axis, false otherwise.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GamepadHasButton * \sa SDL_GamepadHasButton
@@ -1165,6 +1261,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_Ga
* \param axis an axis index (one of the SDL_GamepadAxis values). * \param axis an axis index (one of the SDL_GamepadAxis values).
* \returns axis state. * \returns axis state.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GamepadHasAxis * \sa SDL_GamepadHasAxis
@@ -1184,6 +1282,8 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_
* \returns the SDL_GamepadButton enum corresponding to the input string, or * \returns the SDL_GamepadButton enum corresponding to the input string, or
* `SDL_GAMEPAD_BUTTON_INVALID` if no match was found. * `SDL_GAMEPAD_BUTTON_INVALID` if no match was found.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadStringForButton * \sa SDL_GetGamepadStringForButton
@@ -1198,6 +1298,8 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con
* specified. The string returned is of the format used by * specified. The string returned is of the format used by
* SDL_Gamepad mapping strings. * SDL_Gamepad mapping strings.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadButtonFromString * \sa SDL_GetGamepadButtonFromString
@@ -1214,6 +1316,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForButton(SDL_Gamep
* \param button a button enum value (an SDL_GamepadButton value). * \param button a button enum value (an SDL_GamepadButton value).
* \returns true if the gamepad has this button, false otherwise. * \returns true if the gamepad has this button, false otherwise.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GamepadHasAxis * \sa SDL_GamepadHasAxis
@@ -1227,6 +1331,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_
* \param button a button index (one of the SDL_GamepadButton values). * \param button a button index (one of the SDL_GamepadButton values).
* \returns true if the button is pressed, false otherwise. * \returns true if the button is pressed, false otherwise.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GamepadHasButton * \sa SDL_GamepadHasButton
@@ -1241,6 +1347,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_
* \param button a button index (one of the SDL_GamepadButton values). * \param button a button index (one of the SDL_GamepadButton values).
* \returns the SDL_GamepadButtonLabel enum corresponding to the button label. * \returns the SDL_GamepadButtonLabel enum corresponding to the button label.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadButtonLabel * \sa SDL_GetGamepadButtonLabel
@@ -1254,6 +1362,8 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabelForT
* \param button a button index (one of the SDL_GamepadButton values). * \param button a button index (one of the SDL_GamepadButton values).
* \returns the SDL_GamepadButtonLabel enum corresponding to the button label. * \returns the SDL_GamepadButtonLabel enum corresponding to the button label.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadButtonLabelForType * \sa SDL_GetGamepadButtonLabelForType
@@ -1266,6 +1376,8 @@ extern SDL_DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabel(SDL
* \param gamepad a gamepad. * \param gamepad a gamepad.
* \returns number of touchpads. * \returns number of touchpads.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetNumGamepadTouchpadFingers * \sa SDL_GetNumGamepadTouchpadFingers
@@ -1280,6 +1392,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad)
* \param touchpad a touchpad. * \param touchpad a touchpad.
* \returns number of supported simultaneous fingers. * \returns number of supported simultaneous fingers.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadTouchpadFinger * \sa SDL_GetGamepadTouchpadFinger
@@ -1303,6 +1417,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *ga
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetNumGamepadTouchpadFingers * \sa SDL_GetNumGamepadTouchpadFingers
@@ -1316,6 +1432,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadTouchpadFinger(SDL_Gamepad *gamep
* \param type the type of sensor to query. * \param type the type of sensor to query.
* \returns true if the sensor exists, false otherwise. * \returns true if the sensor exists, false otherwise.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadSensorData * \sa SDL_GetGamepadSensorData
@@ -1333,6 +1451,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GamepadHasSensor * \sa SDL_GamepadHasSensor
@@ -1347,6 +1467,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepa
* \param type the type of sensor to query. * \param type the type of sensor to query.
* \returns true if the sensor is enabled, false otherwise. * \returns true if the sensor is enabled, false otherwise.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_SetGamepadSensorEnabled * \sa SDL_SetGamepadSensorEnabled
@@ -1360,6 +1482,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad,
* \param type the type of sensor to query. * \param type the type of sensor to query.
* \returns the data rate, or 0.0f if the data rate is not available. * \returns the data rate, or 0.0f if the data rate is not available.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *gamepad, SDL_SensorType type); extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *gamepad, SDL_SensorType type);
@@ -1377,6 +1501,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *game
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values); extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values);
@@ -1399,6 +1525,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad,
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
@@ -1425,6 +1553,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_RumbleGamepad * \sa SDL_RumbleGamepad
@@ -1447,6 +1577,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad,
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue);
@@ -1460,6 +1592,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 r
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size); extern SDL_DECLSPEC bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const void *data, int size);
@@ -1470,6 +1604,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, con
* \param gamepad a gamepad identifier previously returned by * \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad(). * SDL_OpenGamepad().
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_OpenGamepad * \sa SDL_OpenGamepad
@@ -1484,6 +1620,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad);
* \param button a button on the gamepad. * \param button a button on the gamepad.
* \returns the sfSymbolsName or NULL if the name can't be found. * \returns the sfSymbolsName or NULL if the name can't be found.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadAppleSFSymbolsNameForAxis * \sa SDL_GetGamepadAppleSFSymbolsNameForAxis
@@ -1497,6 +1635,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButt
* \param axis an axis on the gamepad. * \param axis an axis on the gamepad.
* \returns the sfSymbolsName or NULL if the name can't be found. * \returns the sfSymbolsName or NULL if the name can't be found.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetGamepadAppleSFSymbolsNameForButton * \sa SDL_GetGamepadAppleSFSymbolsNameForButton

116
include/SDL3/SDL_joystick.h
View File

@@ -182,6 +182,8 @@ typedef enum SDL_JoystickConnectionState
* joysticks while processing to guarantee that the joystick list won't change * joysticks while processing to guarantee that the joystick list won't change
* and joystick and gamepad events will not be delivered. * and joystick and gamepad events will not be delivered.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock); extern SDL_DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock);
@@ -189,6 +191,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystic
/** /**
* Unlocking for atomic access to the joystick API. * Unlocking for atomic access to the joystick API.
* *
* \threadsafety This should be called from the same thread that called SDL_LockJoysticks().
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock); extern SDL_DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock);
@@ -198,6 +202,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joyst
* *
* \returns true if a joystick is connected, false otherwise. * \returns true if a joystick is connected, false otherwise.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoysticks * \sa SDL_GetJoysticks
@@ -213,6 +219,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasJoystick(void);
* call SDL_GetError() for more information. This should be freed * call SDL_GetError() for more information. This should be freed
* with SDL_free() when it is no longer needed. * with SDL_free() when it is no longer needed.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_HasJoystick * \sa SDL_HasJoystick
@@ -229,6 +237,8 @@ extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count);
* \returns the name of the selected joystick. If no name can be found, this * \returns the name of the selected joystick. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information. * function returns NULL; call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickName * \sa SDL_GetJoystickName
@@ -245,6 +255,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID
* \returns the path of the selected joystick. If no path can be found, this * \returns the path of the selected joystick. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information. * function returns NULL; call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickPath * \sa SDL_GetJoystickPath
@@ -260,6 +272,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPathForID(SDL_JoystickID
* \param instance_id the joystick instance ID. * \param instance_id the joystick instance ID.
* \returns the player index of a joystick, or -1 if it's not available. * \returns the player index of a joystick, or -1 if it's not available.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickPlayerIndex * \sa SDL_GetJoystickPlayerIndex
@@ -276,6 +290,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndexForID(SDL_JoystickID i
* \returns the GUID of the selected joystick. If called with an invalid * \returns the GUID of the selected joystick. If called with an invalid
* instance_id, this function returns a zero GUID. * instance_id, this function returns a zero GUID.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickGUID * \sa SDL_GetJoystickGUID
@@ -293,6 +309,8 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUIDForID(SDL_JoystickID ins
* \returns the USB vendor ID of the selected joystick. If called with an * \returns the USB vendor ID of the selected joystick. If called with an
* invalid instance_id, this function returns 0. * invalid instance_id, this function returns 0.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickVendor * \sa SDL_GetJoystickVendor
@@ -310,6 +328,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendorForID(SDL_JoystickID ins
* \returns the USB product ID of the selected joystick. If called with an * \returns the USB product ID of the selected joystick. If called with an
* invalid instance_id, this function returns 0. * invalid instance_id, this function returns 0.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickProduct * \sa SDL_GetJoystickProduct
@@ -327,6 +347,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductForID(SDL_JoystickID in
* \returns the product version of the selected joystick. If called with an * \returns the product version of the selected joystick. If called with an
* invalid instance_id, this function returns 0. * invalid instance_id, this function returns 0.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickProductVersion * \sa SDL_GetJoystickProductVersion
@@ -344,6 +366,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersionForID(SDL_Joysti
* invalid instance_id, this function returns * invalid instance_id, this function returns
* `SDL_JOYSTICK_TYPE_UNKNOWN`. * `SDL_JOYSTICK_TYPE_UNKNOWN`.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickType * \sa SDL_GetJoystickType
@@ -361,6 +385,8 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_Joysti
* \returns a joystick identifier or NULL on failure; call SDL_GetError() for * \returns a joystick identifier or NULL on failure; call SDL_GetError() for
* more information. * more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_CloseJoystick * \sa SDL_CloseJoystick
@@ -374,6 +400,8 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_OpenJoystick(SDL_JoystickID insta
* \returns an SDL_Joystick on success or NULL on failure or if it hasn't been * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been
* opened yet; call SDL_GetError() for more information. * opened yet; call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID instance_id); extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID instance_id);
@@ -385,6 +413,8 @@ extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID
* \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
* for more information. * for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickPlayerIndex * \sa SDL_GetJoystickPlayerIndex
@@ -493,6 +523,8 @@ SDL_COMPILE_TIME_ASSERT(SDL_VirtualJoystickDesc_SIZE,
* \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for * \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for
* more information. * more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_DetachVirtualJoystick * \sa SDL_DetachVirtualJoystick
@@ -513,6 +545,8 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_V
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_AttachVirtualJoystick * \sa SDL_AttachVirtualJoystick
@@ -525,6 +559,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instan
* \param instance_id the joystick instance ID. * \param instance_id the joystick instance ID.
* \returns true if the joystick is virtual, false otherwise. * \returns true if the joystick is virtual, false otherwise.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id);
@@ -548,6 +584,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_i
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_SetJoystickVirtualButton * \sa SDL_SetJoystickVirtualButton
@@ -574,6 +612,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joysti
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_SetJoystickVirtualAxis * \sa SDL_SetJoystickVirtualAxis
@@ -599,6 +639,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joysti
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_SetJoystickVirtualAxis * \sa SDL_SetJoystickVirtualAxis
@@ -624,6 +666,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joys
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_SetJoystickVirtualAxis * \sa SDL_SetJoystickVirtualAxis
@@ -656,6 +700,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystic
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_SetJoystickVirtualAxis * \sa SDL_SetJoystickVirtualAxis
@@ -684,6 +730,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *jo
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_SetJoystickVirtualAxis * \sa SDL_SetJoystickVirtualAxis
@@ -714,6 +762,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick
* \returns a valid property ID on success or 0 on failure; call * \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joystick *joystick); extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joystick *joystick);
@@ -731,6 +781,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst
* \returns the name of the selected joystick. If no name can be found, this * \returns the name of the selected joystick. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information. * function returns NULL; call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickNameForID * \sa SDL_GetJoystickNameForID
@@ -744,6 +796,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joyst
* \returns the path of the selected joystick. If no path can be found, this * \returns the path of the selected joystick. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information. * function returns NULL; call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickPathForID * \sa SDL_GetJoystickPathForID
@@ -759,6 +813,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPath(SDL_Joystick *joyst
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the player index, or -1 if it's not available. * \returns the player index, or -1 if it's not available.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_SetJoystickPlayerIndex * \sa SDL_SetJoystickPlayerIndex
@@ -774,6 +830,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndex(SDL_Joystick *joystic
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickPlayerIndex * \sa SDL_GetJoystickPlayerIndex
@@ -790,6 +848,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joysti
* this function returns a zero GUID; call SDL_GetError() for more * this function returns a zero GUID; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickGUIDForID * \sa SDL_GetJoystickGUIDForID
@@ -805,6 +865,8 @@ extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUID(SDL_Joystick *joystick)
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the USB vendor ID of the selected joystick, or 0 if unavailable. * \returns the USB vendor ID of the selected joystick, or 0 if unavailable.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickVendorForID * \sa SDL_GetJoystickVendorForID
@@ -819,6 +881,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendor(SDL_Joystick *joystick)
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the USB product ID of the selected joystick, or 0 if unavailable. * \returns the USB product ID of the selected joystick, or 0 if unavailable.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickProductForID * \sa SDL_GetJoystickProductForID
@@ -833,6 +897,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProduct(SDL_Joystick *joystick
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the product version of the selected joystick, or 0 if unavailable. * \returns the product version of the selected joystick, or 0 if unavailable.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickProductVersionForID * \sa SDL_GetJoystickProductVersionForID
@@ -848,6 +914,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersion(SDL_Joystick *j
* \returns the firmware version of the selected joystick, or 0 if * \returns the firmware version of the selected joystick, or 0 if
* unavailable. * unavailable.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *joystick); extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *joystick);
@@ -861,6 +929,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *
* \returns the serial number of the selected joystick, or NULL if * \returns the serial number of the selected joystick, or NULL if
* unavailable. * unavailable.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joystick); extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joystick);
@@ -871,6 +941,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joy
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the SDL_JoystickType of the selected joystick. * \returns the SDL_JoystickType of the selected joystick.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickTypeForID * \sa SDL_GetJoystickTypeForID
@@ -890,6 +962,8 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *j
* \param crc16 a pointer filled in with a CRC used to distinguish different * \param crc16 a pointer filled in with a CRC used to distinguish different
* products with the same VID/PID, or 0 if not available. * products with the same VID/PID, or 0 if not available.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickGUIDForID * \sa SDL_GetJoystickGUIDForID
@@ -903,6 +977,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_GUID guid, Uint16 *
* \returns true if the joystick has been opened, false if it has not; call * \returns true if the joystick has been opened, false if it has not; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); extern SDL_DECLSPEC bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick);
@@ -914,6 +990,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick);
* \returns the instance ID of the specified joystick on success or 0 on * \returns the instance ID of the specified joystick on success or 0 on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joystick); extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joystick);
@@ -929,6 +1007,8 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joyst
* \returns the number of axis controls/number of axes on success or -1 on * \returns the number of axis controls/number of axes on success or -1 on
* failure; call SDL_GetError() for more information. * failure; call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickAxis * \sa SDL_GetJoystickAxis
@@ -950,6 +1030,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick);
* \returns the number of trackballs on success or -1 on failure; call * \returns the number of trackballs on success or -1 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickBall * \sa SDL_GetJoystickBall
@@ -966,6 +1048,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickBalls(SDL_Joystick *joystick);
* \returns the number of POV hats on success or -1 on failure; call * \returns the number of POV hats on success or -1 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickHat * \sa SDL_GetJoystickHat
@@ -982,6 +1066,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickHats(SDL_Joystick *joystick);
* \returns the number of buttons on success or -1 on failure; call * \returns the number of buttons on success or -1 on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetJoystickButton * \sa SDL_GetJoystickButton
@@ -1000,6 +1086,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick
* *
* \param enabled whether to process joystick events or not. * \param enabled whether to process joystick events or not.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_JoystickEventsEnabled * \sa SDL_JoystickEventsEnabled
@@ -1016,6 +1104,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(bool enabled);
* *
* \returns true if joystick events are being processed, false otherwise. * \returns true if joystick events are being processed, false otherwise.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_SetJoystickEventsEnabled * \sa SDL_SetJoystickEventsEnabled
@@ -1028,6 +1118,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_JoystickEventsEnabled(void);
* This is called automatically by the event loop if any joystick events are * This is called automatically by the event loop if any joystick events are
* enabled. * enabled.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void);
@@ -1050,6 +1142,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void);
* \returns a 16-bit signed integer representing the current position of the * \returns a 16-bit signed integer representing the current position of the
* axis or 0 on failure; call SDL_GetError() for more information. * axis or 0 on failure; call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetNumJoystickAxes * \sa SDL_GetNumJoystickAxes
@@ -1068,6 +1162,8 @@ extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, i
* \param state upon return, the initial value is supplied here. * \param state upon return, the initial value is supplied here.
* \returns true if this axis has any initial value, or false if not. * \returns true if this axis has any initial value, or false if not.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state);
@@ -1087,6 +1183,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *j
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetNumJoystickBalls * \sa SDL_GetNumJoystickBalls
@@ -1102,6 +1200,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int
* \param hat the hat index to get the state from; indices start at index 0. * \param hat the hat index to get the state from; indices start at index 0.
* \returns the current hat position. * \returns the current hat position.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetNumJoystickHats * \sa SDL_GetNumJoystickHats
@@ -1126,6 +1226,8 @@ extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int
* index 0. * index 0.
* \returns true if the button is pressed, false otherwise. * \returns true if the button is pressed, false otherwise.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_GetNumJoystickButtons * \sa SDL_GetNumJoystickButtons
@@ -1149,6 +1251,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, i
* \param duration_ms the duration of the rumble effect, in milliseconds. * \param duration_ms the duration of the rumble effect, in milliseconds.
* \returns true, or false if rumble isn't supported on this joystick. * \returns true, or false if rumble isn't supported on this joystick.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
@@ -1176,6 +1280,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_RumbleJoystick * \sa SDL_RumbleJoystick
@@ -1198,6 +1304,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joysti
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue);
@@ -1211,6 +1319,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint
* \returns true on success or false on failure; call SDL_GetError() for more * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size);
@@ -1220,6 +1330,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick,
* *
* \param joystick the joystick device to close. * \param joystick the joystick device to close.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
* *
* \sa SDL_OpenJoystick * \sa SDL_OpenJoystick
@@ -1234,6 +1346,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseJoystick(SDL_Joystick *joystick);
* `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError()
* for more information. * for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectionState(SDL_Joystick *joystick); extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectionState(SDL_Joystick *joystick);
@@ -1255,6 +1369,8 @@ extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectio
* \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure;
* call SDL_GetError() for more information. * call SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.2.0. * \since This function is available since SDL 3.2.0.
*/ */
extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetJoystickPowerInfo(SDL_Joystick *joystick, int *percent); extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetJoystickPowerInfo(SDL_Joystick *joystick, int *percent);