Documentation

Add support for gamepads that SDL is unaware of or change the binding of an existing gamepad.

The mapping string has the format "GUID,name,mapping", where GUID is the string value from SDL_GUIDToString(), name is the human readable string for the device and mappings are gamepad mappings to joystick ones. Under Windows there is a reserved GUID of "xinput" that covers all XInput devices. The mapping format for joystick is:

• bX: a joystick button, index X
• hX.Y: hat X with value Y
• aX: axis X of the joystick

Buttons can be used as a gamepad axes and vice versa.

If a device with this GUID is already plugged in, SDL will generate an SDL_EVENT_GAMEPAD_ADDED event.

This string shows an example of a valid mapping for a gamepad:

    "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"
    

mapping

the mapping string.

Returns

1 if a new mapping is added, 0 if an existing mapping is updated, -1 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_AddGamepadMappingsFromFile, sDL_AddGamepadMappingsFromIO, sDL_GetGamepadMapping, sDL_GetGamepadMappingForGUID, SDL_HINT_GAMECONTROLLERCONFIG, SDL_HINT_GAMECONTROLLERCONFIG_FILE, SDL_EVENT_GAMEPAD_ADDED

C declaration

SDL_AddGamepadMapping, defined at SDL3/SDL_gamepad.h 347:33

Since: 3.2.0

Load a set of gamepad mappings from an SDL_IOStream.

You can call this function several times, if needed, to load different database files.

If a new mapping is loaded for an already known gamepad GUID, the later version will overwrite the one currently loaded.

Any new mappings for already plugged in controllers will generate SDL_EVENT_GAMEPAD_ADDED events.

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).

This function will load the text database entirely in memory before processing it, so take this into consideration if you are in a memory constrained environment.

src

the data stream for the mappings to be added.

closeio

if true, calls SDL_CloseIO() on src before returning, even in the case of an error.

Returns

the number of mappings added or -1 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_AddGamepadMapping, sDL_AddGamepadMappingsFromFile, sDL_GetGamepadMapping, sDL_GetGamepadMappingForGUID, SDL_HINT_GAMECONTROLLERCONFIG, SDL_HINT_GAMECONTROLLERCONFIG_FILE, SDL_EVENT_GAMEPAD_ADDED

C declaration

SDL_AddGamepadMappingsFromIO, defined at SDL3/SDL_gamepad.h 387:33

Since: 3.2.0

Load a set of gamepad mappings from a file.

You can call this function several times, if needed, to load different database files.

If a new mapping is loaded for an already known gamepad GUID, the later version will overwrite the one currently loaded.

Any new mappings for already plugged in controllers will generate SDL_EVENT_GAMEPAD_ADDED events.

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).

file

the mappings file to load.

Returns

the number of mappings added or -1 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_AddGamepadMapping, sDL_AddGamepadMappingsFromIO, sDL_GetGamepadMapping, sDL_GetGamepadMappingForGUID, SDL_HINT_GAMECONTROLLERCONFIG, SDL_HINT_GAMECONTROLLERCONFIG_FILE, SDL_EVENT_GAMEPAD_ADDED

C declaration

SDL_AddGamepadMappingsFromFile, defined at SDL3/SDL_gamepad.h 421:33

Since: 3.2.0

Reinitialize the SDL mapping database to its initial state.

This will generate gamepad events as needed if device mappings change.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_ReloadGamepadMappings, defined at SDL3/SDL_gamepad.h 435:34

Since: 3.2.0

Get the current gamepad mappings.

count

a pointer filled in with the number of mappings returned, can be NULL.

Returns

an array of the mapping strings, NULL-terminated, or NULL on failure; call SDL_GetError() for more information. This is a single allocation that should be freed with SDL_free() when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadMappings, defined at SDL3/SDL_gamepad.h 451:37

Since: 3.2.0

Get the gamepad mapping string for a given GUID.

guid

a structure containing the GUID for which a mapping is desired.

Returns

a mapping string or NULL on failure; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

See also

SDL_GetJoystickGUIDForID, SDL_GetJoystickGUID

C declaration

SDL_GetGamepadMappingForGUID, defined at SDL3/SDL_gamepad.h 468:36

Since: 3.2.0

Get the current mapping of a gamepad.

Details about mappings are discussed with SDL_AddGamepadMapping().

gamepad

the gamepad you want to get the current mapping for.

Returns

a string that has the gamepad's mapping or NULL if no mapping is available; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

See also

sDL_AddGamepadMapping, sDL_GetGamepadMappingForID, sDL_GetGamepadMappingForGUID, sDL_SetGamepadMapping

C declaration

SDL_GetGamepadMapping, defined at SDL3/SDL_gamepad.h 489:36

Since: 3.2.0

Set the current mapping of a joystick or gamepad.

Details about mappings are discussed with SDL_AddGamepadMapping().

instance_id

the joystick instance ID.

mapping

the mapping to use for this device, or NULL to clear the mapping.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_AddGamepadMapping, sDL_GetGamepadMapping

C declaration

SDL_SetGamepadMapping, defined at SDL3/SDL_gamepad.h 509:34

Since: 3.2.0

Return whether a gamepad is currently connected.

Returns

true if a gamepad is connected, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepads

C declaration

SDL_HasGamepad, defined at SDL3/SDL_gamepad.h 522:34

Since: 3.2.0

Get a list of currently connected gamepads.

count

a pointer filled in with the number of gamepads returned, may be NULL.

Returns

a 0 terminated array of joystick instance IDs or NULL on failure; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

See also

sDL_HasGamepad, sDL_OpenGamepad

C declaration

SDL_GetGamepads, defined at SDL3/SDL_gamepad.h 540:46

Since: 3.2.0

Check if the given joystick is supported by the gamepad interface.

instance_id

the joystick instance ID.

Returns

true if the given joystick is supported by the gamepad interface, false if it isn't or it's an invalid index.

Thread safety

It is safe to call this function from any thread.

See also

SDL_GetJoysticks, sDL_OpenGamepad

C declaration

SDL_IsGamepad, defined at SDL3/SDL_gamepad.h 556:34

Since: 3.2.0

Get the implementation dependent name of a gamepad.

This can be called before any gamepads are opened.

instance_id

the joystick instance ID.

Returns

the name of the selected gamepad. If no name can be found, this function returns NULL; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadName, sDL_GetGamepads

C declaration

SDL_GetGamepadNameForID, defined at SDL3/SDL_gamepad.h 574:42

Since: 3.2.0

Get the implementation dependent path of a gamepad.

This can be called before any gamepads are opened.

instance_id

the joystick instance ID.

Returns

the path of the selected gamepad. If no path can be found, this function returns NULL; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadPath, sDL_GetGamepads

C declaration

SDL_GetGamepadPathForID, defined at SDL3/SDL_gamepad.h 592:42

Since: 3.2.0

Get the player index of a gamepad.

This can be called before any gamepads are opened.

instance_id

the joystick instance ID.

Returns

the player index of a gamepad, or -1 if it's not available.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadPlayerIndex, sDL_GetGamepads

C declaration

SDL_GetGamepadPlayerIndexForID, defined at SDL3/SDL_gamepad.h 609:33

Since: 3.2.0

Get the implementation-dependent GUID of a gamepad.

This can be called before any gamepads are opened.

instance_id

the joystick instance ID.

Returns

the GUID of the selected gamepad. If called on an invalid index, this function returns a zero GUID.

Thread safety

It is safe to call this function from any thread.

See also

SDL_GUIDToString, sDL_GetGamepads

C declaration

SDL_GetGamepadGUIDForID, defined at SDL3/SDL_gamepad.h 627:38

Since: 3.2.0

Get the USB vendor ID of a gamepad, if available.

This can be called before any gamepads are opened. If the vendor ID isn't available this function returns 0.

instance_id

the joystick instance ID.

Returns

the USB vendor ID of the selected gamepad. If called on an invalid index, this function returns zero.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadVendor, sDL_GetGamepads

C declaration

SDL_GetGamepadVendorForID, defined at SDL3/SDL_gamepad.h 646:36

Since: 3.2.0

Get the USB product ID of a gamepad, if available.

This can be called before any gamepads are opened. If the product ID isn't available this function returns 0.

instance_id

the joystick instance ID.

Returns

the USB product ID of the selected gamepad. If called on an invalid index, this function returns zero.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadProduct, sDL_GetGamepads

C declaration

SDL_GetGamepadProductForID, defined at SDL3/SDL_gamepad.h 665:36

Since: 3.2.0

Get the product version of a gamepad, if available.

This can be called before any gamepads are opened. If the product version isn't available this function returns 0.

instance_id

the joystick instance ID.

Returns

the product version of the selected gamepad. If called on an invalid index, this function returns zero.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadProductVersion, sDL_GetGamepads

C declaration

SDL_GetGamepadProductVersionForID, defined at SDL3/SDL_gamepad.h 684:36

Since: 3.2.0

Get the type of a gamepad.

This can be called before any gamepads are opened.

instance_id

the joystick instance ID.

Returns

the gamepad type.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadType, sDL_GetGamepads, sDL_GetRealGamepadTypeForID

C declaration

SDL_GetGamepadTypeForID, defined at SDL3/SDL_gamepad.h 702:45

Since: 3.2.0

Get the type of a gamepad, ignoring any mapping override.

This can be called before any gamepads are opened.

instance_id

the joystick instance ID.

Returns

the gamepad type.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadTypeForID, sDL_GetGamepads, sDL_GetRealGamepadType

C declaration

SDL_GetRealGamepadTypeForID, defined at SDL3/SDL_gamepad.h 720:45

Since: 3.2.0

Get the mapping of a gamepad.

This can be called before any gamepads are opened.

instance_id

the joystick instance ID.

Returns

the mapping string. Returns NULL if no mapping is available. This should be freed with SDL_free() when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepads, sDL_GetGamepadMapping

C declaration

SDL_GetGamepadMappingForID, defined at SDL3/SDL_gamepad.h 738:36

Since: 3.2.0

Open a gamepad for use.

instance_id

the joystick instance ID.

Returns

a gamepad identifier or NULL if an error occurred; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_CloseGamepad, sDL_IsGamepad

C declaration

SDL_OpenGamepad, defined at SDL3/SDL_gamepad.h 754:43

Since: 3.2.0

Get the SDL_Gamepad associated with a joystick instance ID, if it has been opened.

instance_id

the joystick instance ID of the gamepad.

Returns

an SDL_Gamepad on success or NULL on failure or if it hasn't been opened yet; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadFromID, defined at SDL3/SDL_gamepad.h 768:43

Since: 3.2.0

Get the SDL_Gamepad associated with a player index.

player_index

the player index, which different from the instance ID.

Returns

the SDL_Gamepad associated with a player index.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadPlayerIndex, sDL_SetGamepadPlayerIndex

C declaration

SDL_GetGamepadFromPlayerIndex, defined at SDL3/SDL_gamepad.h 783:43

Since: 3.2.0

Get the properties associated with an opened gamepad.

These properties are shared with the underlying joystick object.

The following read-only properties are provided by SDL:

• sDL_PROP_GAMEPAD_CAP_MONO_LED_BOOLEAN: true if this gamepad has an LED that has adjustable brightness
• sDL_PROP_GAMEPAD_CAP_RGB_LED_BOOLEAN: true if this gamepad has an LED that has adjustable color
• sDL_PROP_GAMEPAD_CAP_PLAYER_LED_BOOLEAN: true if this gamepad has a player LED
• sDL_PROP_GAMEPAD_CAP_RUMBLE_BOOLEAN: true if this gamepad has left/right rumble
• sDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN: true if this gamepad has simple trigger rumble

gamepad

a gamepad identifier previously returned by SDL_OpenGamepad().

Returns

a valid property ID on success or 0 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadProperties, defined at SDL3/SDL_gamepad.h 812:46

Since: 3.2.0

Get the instance ID of an opened gamepad.

gamepad

a gamepad identifier previously returned by SDL_OpenGamepad().

Returns

the instance ID of the specified gamepad on success or 0 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadID, defined at SDL3/SDL_gamepad.h 832:44

Since: 3.2.0

Get the implementation-dependent name for an opened gamepad.

gamepad

a gamepad identifier previously returned by SDL_OpenGamepad().

Returns

the implementation dependent name for the gamepad, or NULL if there is no name or the identifier passed is invalid.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadNameForID

C declaration

SDL_GetGamepadName, defined at SDL3/SDL_gamepad.h 848:42

Since: 3.2.0

Get the implementation-dependent path for an opened gamepad.

gamepad

a gamepad identifier previously returned by SDL_OpenGamepad().

Returns

the implementation dependent path for the gamepad, or NULL if there is no path or the identifier passed is invalid.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadPathForID

C declaration

SDL_GetGamepadPath, defined at SDL3/SDL_gamepad.h 864:42

Since: 3.2.0

Get the type of an opened gamepad.

gamepad

the gamepad object to query.

Returns

the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not available.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadTypeForID

C declaration

SDL_GetGamepadType, defined at SDL3/SDL_gamepad.h 879:45

Since: 3.2.0

Get the type of an opened gamepad, ignoring any mapping override.

gamepad

the gamepad object to query.

Returns

the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not available.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetRealGamepadTypeForID

C declaration

SDL_GetRealGamepadType, defined at SDL3/SDL_gamepad.h 894:45

Since: 3.2.0

Get the player index of an opened gamepad.

For XInput gamepads this returns the XInput user index.

gamepad

the gamepad object to query.

Returns

the player index for gamepad, or -1 if it's not available.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetGamepadPlayerIndex

C declaration

SDL_GetGamepadPlayerIndex, defined at SDL3/SDL_gamepad.h 910:33

Since: 3.2.0

Set the player index of an opened gamepad.

gamepad

the gamepad object to adjust.

player_index

player index to assign to this gamepad, or -1 to clear the player index and turn off player LEDs.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadPlayerIndex

C declaration

SDL_SetGamepadPlayerIndex, defined at SDL3/SDL_gamepad.h 927:34

Since: 3.2.0

Get the USB vendor ID of an opened gamepad, if available.

If the vendor ID isn't available this function returns 0.

gamepad

the gamepad object to query.

Returns

the USB vendor ID, or zero if unavailable.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadVendorForID

C declaration

SDL_GetGamepadVendor, defined at SDL3/SDL_gamepad.h 943:36

Since: 3.2.0

Get the USB product ID of an opened gamepad, if available.

If the product ID isn't available this function returns 0.

gamepad

the gamepad object to query.

Returns

the USB product ID, or zero if unavailable.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadProductForID

C declaration

SDL_GetGamepadProduct, defined at SDL3/SDL_gamepad.h 959:36

Since: 3.2.0

Get the product version of an opened gamepad, if available.

If the product version isn't available this function returns 0.

gamepad

the gamepad object to query.

Returns

the USB product version, or zero if unavailable.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadProductVersionForID

C declaration

SDL_GetGamepadProductVersion, defined at SDL3/SDL_gamepad.h 975:36

Since: 3.2.0

Get the firmware version of an opened gamepad, if available.

If the firmware version isn't available this function returns 0.

gamepad

the gamepad object to query.

Returns

the gamepad firmware version, or zero if unavailable.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadFirmwareVersion, defined at SDL3/SDL_gamepad.h 989:36

Since: 3.2.0

Get the serial number of an opened gamepad, if available.

Returns the serial number of the gamepad, or NULL if it is not available.

gamepad

the gamepad object to query.

Returns

the serial number, or NULL if unavailable.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadSerial, defined at SDL3/SDL_gamepad.h 1003:42

Since: 3.2.0

Get the Steam Input handle of an opened gamepad, if available.

Returns an InputHandle_t for the gamepad that can be used with Steam Input API: https://partner.steamgames.com/doc/api/ISteamInput

gamepad

the gamepad object to query.

Returns

the gamepad handle, or 0 if unavailable.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadSteamHandle, defined at SDL3/SDL_gamepad.h 1018:36

Since: 3.2.0

Get the connection state of a gamepad.

gamepad

the gamepad object to query.

Returns

the connection state on success or SDL_JOYSTICK_CONNECTION_INVALID on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadConnectionState, defined at SDL3/SDL_gamepad.h 1032:57

Since: 3.2.0

Get the battery state of a gamepad.

You should never take a battery status as absolute truth. Batteries (especially failing batteries) are delicate hardware, and the values reported here are best estimates based on what that hardware reports. It's not uncommon for older batteries to lose stored power much faster than it reports, or completely drain when reporting it has 20 percent left, etc.

gamepad

the gamepad object to query.

percent

a pointer filled in with the percentage of battery life left, between 0 and 100, or NULL to ignore. This will be filled in with -1 we can't determine a value or there is no battery.

Returns

the current battery state.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadPowerInfo, defined at SDL3/SDL_gamepad.h 1054:44

Since: 3.2.0

Check if a gamepad has been opened and is currently connected.

gamepad

a gamepad identifier previously returned by SDL_OpenGamepad().

Returns

true if the gamepad has been opened and is currently connected, or false if not.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GamepadConnected, defined at SDL3/SDL_gamepad.h 1068:34

Since: 3.2.0

Get the underlying joystick from a gamepad.

This function will give you a SDL_Joystick object, which allows you to use the SDL_Joystick functions with a SDL_Gamepad object. This would be useful for getting a joystick's position at any given time, even if it hasn't moved (moving it would produce an event, which would have the axis' value).

The pointer returned is owned by the SDL_Gamepad. You should not call SDL_CloseJoystick() on it, for example, since doing so will likely cause SDL to crash.

gamepad

the gamepad object that you want to get a joystick from.

Returns

an SDL_Joystick object, or NULL on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadJoystick, defined at SDL3/SDL_gamepad.h 1090:44

Since: 3.2.0

Set the state of gamepad event processing.

If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself and check the state of the gamepad when you want gamepad information.

enabled

whether to process gamepad events or not.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GamepadEventsEnabled, sDL_UpdateGamepads

C declaration

SDL_SetGamepadEventsEnabled, defined at SDL3/SDL_gamepad.h 1107:34

Since: 3.2.0

Query the state of gamepad event processing.

If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself and check the state of the gamepad when you want gamepad information.

Returns

true if gamepad events are being processed, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetGamepadEventsEnabled

C declaration

SDL_GamepadEventsEnabled, defined at SDL3/SDL_gamepad.h 1123:34

Since: 3.2.0

Get the SDL joystick layer bindings for a gamepad.

gamepad

a gamepad.

count

a pointer filled in with the number of bindings returned.

Returns

a NULL terminated array of pointers to bindings or NULL on failure; call SDL_GetError() for more information. This is a single allocation that should be freed with SDL_free() when it is no longer needed.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadBindings, defined at SDL3/SDL_gamepad.h 1139:51

Since: 3.2.0

Manually pump gamepad updates if not using the loop.

This function is called automatically by the event loop if events are enabled. Under such circumstances, it will not be necessary to call this function.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_UpdateGamepads, defined at SDL3/SDL_gamepad.h 1152:34

Since: 3.2.0

Convert a string into SDL_GamepadType enum.

This function is called internally to translate SDL_Gamepad mapping strings for the underlying joystick device into the consistent SDL_Gamepad mapping. You do not normally need to call this function unless you are parsing SDL_Gamepad mappings in your own code.

str

string representing a SDL_GamepadType type.

Returns

the SDL_GamepadType enum corresponding to the input string, or SDL_GAMEPAD_TYPE_UNKNOWN if no match was found.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadStringForType

C declaration

SDL_GetGamepadTypeFromString, defined at SDL3/SDL_gamepad.h 1172:45

Since: 3.2.0

Convert from an SDL_GamepadType enum to a string.

type

an enum value for a given SDL_GamepadType.

Returns

a string for the given type, or NULL if an invalid type is specified. The string returned is of the format used by SDL_Gamepad mapping strings.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadTypeFromString

C declaration

SDL_GetGamepadStringForType, defined at SDL3/SDL_gamepad.h 1188:42

Since: 3.2.0

Convert a string into SDL_GamepadAxis enum.

This function is called internally to translate SDL_Gamepad mapping strings for the underlying joystick device into the consistent SDL_Gamepad mapping. You do not normally need to call this function unless you are parsing SDL_Gamepad mappings in your own code.

Note specially that "righttrigger" and "lefttrigger" map to SDL_GAMEPAD_AXIS_RIGHT_TRIGGER and SDL_GAMEPAD_AXIS_LEFT_TRIGGER, respectively.

str

string representing a SDL_Gamepad axis.

Returns

the SDL_GamepadAxis enum corresponding to the input string, or SDL_GAMEPAD_AXIS_INVALID if no match was found.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadStringForAxis

C declaration

SDL_GetGamepadAxisFromString, defined at SDL3/SDL_gamepad.h 1212:45

Since: 3.2.0

Convert from an SDL_GamepadAxis enum to a string.

axis

an enum value for a given SDL_GamepadAxis.

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_Gamepad mapping strings.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadAxisFromString

C declaration

SDL_GetGamepadStringForAxis, defined at SDL3/SDL_gamepad.h 1228:42

Since: 3.2.0

Query whether a gamepad has a given axis.

This merely reports whether the gamepad's mapping defined this axis, as that is all the information SDL has about the physical device.

gamepad

a gamepad.

axis

an axis enum value (an SDL_GamepadAxis value).

Returns

true if the gamepad has this axis, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GamepadHasButton, sDL_GetGamepadAxis

C declaration

SDL_GamepadHasAxis, defined at SDL3/SDL_gamepad.h 1247:34

Since: 3.2.0

Get the current state of an axis control on a gamepad.

The axis indices start at index 0.

For thumbsticks, the state is a value ranging from -32768 (up/left) to 32767 (down/right).

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_GetJoystickAxis(), which normally uses the full range.

Note that for invalid gamepads or axes, this will return 0. Zero is also a valid value in normal operation; usually it means a centered axis.

gamepad

a gamepad.

axis

an axis index (one of the SDL_GamepadAxis values).

Returns

axis state.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GamepadHasAxis, sDL_GetGamepadButton

C declaration

SDL_GetGamepadAxis, defined at SDL3/SDL_gamepad.h 1275:36

Since: 3.2.0

Convert a string into an SDL_GamepadButton enum.

This function is called internally to translate SDL_Gamepad mapping strings for the underlying joystick device into the consistent SDL_Gamepad mapping. You do not normally need to call this function unless you are parsing SDL_Gamepad mappings in your own code.

str

string representing a SDL_Gamepad button.

Returns

the SDL_GamepadButton enum corresponding to the input string, or SDL_GAMEPAD_BUTTON_INVALID if no match was found.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadStringForButton

C declaration

SDL_GetGamepadButtonFromString, defined at SDL3/SDL_gamepad.h 1295:47

Since: 3.2.0

Convert from an SDL_GamepadButton enum to a string.

button

an enum value for a given SDL_GamepadButton.

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_Gamepad mapping strings.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadButtonFromString

C declaration

SDL_GetGamepadStringForButton, defined at SDL3/SDL_gamepad.h 1311:42

Since: 3.2.0

Query whether a gamepad has a given button.

This merely reports whether the gamepad's mapping defined this button, as that is all the information SDL has about the physical device.

gamepad

a gamepad.

button

a button enum value (an SDL_GamepadButton value).

Returns

true if the gamepad has this button, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GamepadHasAxis

C declaration

SDL_GamepadHasButton, defined at SDL3/SDL_gamepad.h 1329:34

Since: 3.2.0

Get the current state of a button on a gamepad.

gamepad

a gamepad.

button

a button index (one of the SDL_GamepadButton values).

Returns

true if the button is pressed, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GamepadHasButton, sDL_GetGamepadAxis

C declaration

SDL_GetGamepadButton, defined at SDL3/SDL_gamepad.h 1345:34

Since: 3.2.0

Get the label of a button on a gamepad.

type

the type of gamepad to check.

button

a button index (one of the SDL_GamepadButton values).

Returns

the SDL_GamepadButtonLabel enum corresponding to the button label.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadButtonLabel

C declaration

SDL_GetGamepadButtonLabelForType, defined at SDL3/SDL_gamepad.h 1360:52

Since: 3.2.0

Get the label of a button on a gamepad.

gamepad

a gamepad.

button

a button index (one of the SDL_GamepadButton values).

Returns

the SDL_GamepadButtonLabel enum corresponding to the button label.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadButtonLabelForType

C declaration

SDL_GetGamepadButtonLabel, defined at SDL3/SDL_gamepad.h 1375:52

Since: 3.2.0

Get the number of touchpads on a gamepad.

gamepad

a gamepad.

Returns

number of touchpads.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetNumGamepadTouchpadFingers

C declaration

SDL_GetNumGamepadTouchpads, defined at SDL3/SDL_gamepad.h 1389:33

Since: 3.2.0

Get the number of supported simultaneous fingers on a touchpad on a game gamepad.

gamepad

a gamepad.

touchpad

a touchpad.

Returns

number of supported simultaneous fingers.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadTouchpadFinger, sDL_GetNumGamepadTouchpads

C declaration

SDL_GetNumGamepadTouchpadFingers, defined at SDL3/SDL_gamepad.h 1406:33

Since: 3.2.0

Get the current state of a finger on a touchpad on a gamepad.

gamepad

a gamepad.

touchpad

a touchpad.

finger

a finger.

down

a pointer filled with true if the finger is down, false otherwise, may be NULL.

x

a pointer filled with the x position, normalized 0 to 1, with the origin in the upper left, may be NULL.

y

a pointer filled with the y position, normalized 0 to 1, with the origin in the upper left, may be NULL.

pressure

a pointer filled with pressure value, may be NULL.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetNumGamepadTouchpadFingers

C declaration

SDL_GetGamepadTouchpadFinger, defined at SDL3/SDL_gamepad.h 1430:34

Since: 3.2.0

Return whether a gamepad has a particular sensor.

gamepad

the gamepad to query.

type

the type of sensor to query.

Returns

true if the sensor exists, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadSensorData, sDL_GetGamepadSensorDataRate, sDL_SetGamepadSensorEnabled

C declaration

SDL_GamepadHasSensor, defined at SDL3/SDL_gamepad.h 1447:34

Since: 3.2.0

Set whether data reporting for a gamepad sensor is enabled.

gamepad

the gamepad to update.

type

the type of sensor to enable/disable.

enabled

whether data reporting should be enabled.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GamepadHasSensor, sDL_GamepadSensorEnabled

C declaration

SDL_SetGamepadSensorEnabled, defined at SDL3/SDL_gamepad.h 1465:34

Since: 3.2.0

Query whether sensor data reporting is enabled for a gamepad.

gamepad

the gamepad to query.

type

the type of sensor to query.

Returns

true if the sensor is enabled, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetGamepadSensorEnabled

C declaration

SDL_GamepadSensorEnabled, defined at SDL3/SDL_gamepad.h 1480:34

Since: 3.2.0

Get the data rate (number of events per second) of a gamepad sensor.

gamepad

the gamepad to query.

type

the type of sensor to query.

Returns

the data rate, or 0.0f if the data rate is not available.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadSensorDataRate, defined at SDL3/SDL_gamepad.h 1493:35

Since: 3.2.0

Get the current state of a gamepad sensor.

The number of values and interpretation of the data is sensor dependent. See the remarks in SDL_SensorType for details for each type of sensor.

gamepad

the gamepad to query.

type

the type of sensor to query.

data

a pointer filled with the current sensor state.

num_values

the number of values to write to data.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGamepadSensorData, defined at SDL3/SDL_gamepad.h 1512:34

Since: 3.2.0

Start a rumble effect on a gamepad.

Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.

This function requires you to process SDL events or call SDL_UpdateJoysticks() to update rumble state.

gamepad

the gamepad to vibrate.

low_frequency_rumble

the intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF.

high_frequency_rumble

the intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF.

duration_ms

the duration of the rumble effect, in milliseconds.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_RumbleGamepad, defined at SDL3/SDL_gamepad.h 1536:34

Since: 3.2.0

Start a rumble effect in the gamepad's triggers.

Each call to this function cancels any previous trigger rumble effect, and calling it with 0 intensity stops any rumbling.

Note that this is rumbling of the triggers and not the gamepad as a whole. This is currently only supported on Xbox One gamepads. If you want the (more common) whole-gamepad rumble, use SDL_RumbleGamepad() instead.

This function requires you to process SDL events or call SDL_UpdateJoysticks() to update rumble state.

gamepad

the gamepad to vibrate.

left_rumble

the intensity of the left trigger rumble motor, from 0 to 0xFFFF.

right_rumble

the intensity of the right trigger rumble motor, from 0 to 0xFFFF.

duration_ms

the duration of the rumble effect, in milliseconds.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_RumbleGamepad

C declaration

SDL_RumbleGamepadTriggers, defined at SDL3/SDL_gamepad.h 1566:34

Since: 3.2.0

Update a gamepad's LED color.

An example of a joystick LED is the light on the back of a PlayStation 4's DualShock 4 controller.

For gamepads with a single color LED, the maximum of the RGB values will be used as the LED brightness.

gamepad

the gamepad to update.

red

the intensity of the red LED.

green

the intensity of the green LED.

blue

the intensity of the blue LED.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_SetGamepadLED, defined at SDL3/SDL_gamepad.h 1588:34

Since: 3.2.0

Send a gamepad specific effect packet.

gamepad

the gamepad to affect.

data

the data to send to the gamepad.

size

the size of the data to send to the gamepad.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_SendGamepadEffect, defined at SDL3/SDL_gamepad.h 1603:34

Since: 3.2.0

Close a gamepad previously opened with SDL_OpenGamepad().

gamepad

a gamepad identifier previously returned by SDL_OpenGamepad().

Thread safety

It is safe to call this function from any thread.

See also

sDL_OpenGamepad

C declaration

SDL_CloseGamepad, defined at SDL3/SDL_gamepad.h 1617:34

Since: 3.2.0

Return the sfSymbolsName for a given button on a gamepad on Apple platforms.

gamepad

the gamepad to query.

button

a button on the gamepad.

Returns

the sfSymbolsName or NULL if the name can't be found.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadAppleSFSymbolsNameForAxis

C declaration

SDL_GetGamepadAppleSFSymbolsNameForButton, defined at SDL3/SDL_gamepad.h 1633:42

Since: 3.2.0

Return the sfSymbolsName for a given axis on a gamepad on Apple platforms.

gamepad

the gamepad to query.

axis

an axis on the gamepad.

Returns

the sfSymbolsName or NULL if the name can't be found.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetGamepadAppleSFSymbolsNameForButton

C declaration

SDL_GetGamepadAppleSFSymbolsNameForAxis, defined at SDL3/SDL_gamepad.h 1648:42

Since: 3.2.0