Module gamepad

Available on crate feature dep_sdl3 only.

SDL provides a low-level joystick API, which just treats joysticks as an arbitrary pile of buttons, axes, and hat switches. If you’re planning to write your own control configuration screen, this can give you a lot of flexibility, but that’s a lot of work, and most things that we consider “joysticks” now are actually console-style gamepads. So SDL provides the gamepad API on top of the lower-level joystick functionality.

The difference between a joystick and a gamepad is that a gamepad tells you where a button or axis is on the device. You don’t speak to gamepads in terms of arbitrary numbers like “button 3” or “axis 2” but in standard locations: the d-pad, the shoulder buttons, triggers, A/B/X/Y (or X/O/Square/Triangle, if you will).

One turns a joystick into a gamepad by providing a magic configuration string, which tells SDL the details of a specific device: when you see this specific hardware, if button 2 gets pressed, this is actually D-Pad Up, etc.

SDL has many popular controllers configured out of the box, and users can add their own controller details through an environment variable if it’s otherwise unknown to SDL.

In order to use these functions, [SDL_Init()] must have been called with the [SDL_INIT_GAMEPAD] flag. This causes SDL to scan the system for gamepads, and load appropriate drivers.

If you would like to receive gamepad updates while the application is in the background, you should set the following hint before calling [SDL_Init()]: [SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS]

Gamepads support various optional features such as rumble, color LEDs, touchpad, gyro, etc. The support for these features varies depending on the controller and OS support available. You can check for LED and rumble capabilities at runtime by calling SDL_GetGamepadProperties() and checking the various capability properties. You can check for touchpad by calling SDL_GetNumGamepadTouchpads() and check for gyro and accelerometer by calling SDL_GamepadHasSensor().

By default SDL will try to use the most capable driver available, but you can tune which OS drivers to use with the various joystick hints in SDL_hints.h.

Your application should always support gamepad hotplugging. On some platforms like Xbox, Steam Deck, etc., this is a requirement for certification. On other platforms, like macOS and Windows when using Windows.Gaming.Input, controllers may not be available at startup and will come in at some point after you’ve started processing events.

Structs

SDL_Gamepad

The structure used to identify an SDL gamepad

SDL_GamepadAxis

The list of axes available on a gamepad

SDL_GamepadBinding

A mapping between one joystick input to a gamepad control.

SDL_GamepadBindingType

Types of gamepad control bindings.

SDL_GamepadBinding__AnonUnion1__AnonStruct1

SDL_GamepadBinding__AnonUnion1__AnonStruct2

SDL_GamepadBinding__AnonUnion2__AnonStruct1

SDL_GamepadButton

The list of buttons available on a gamepad

SDL_GamepadButtonLabel

The set of gamepad button labels

SDL_GamepadType

Standard gamepad types.

Constants

SDL_GAMEPAD_AXIS_COUNT

SDL_GAMEPAD_AXIS_INVALID

SDL_GAMEPAD_AXIS_LEFTX

SDL_GAMEPAD_AXIS_LEFTY

SDL_GAMEPAD_AXIS_LEFT_TRIGGER

SDL_GAMEPAD_AXIS_RIGHTX

SDL_GAMEPAD_AXIS_RIGHTY

SDL_GAMEPAD_AXIS_RIGHT_TRIGGER

SDL_GAMEPAD_BINDTYPE_AXIS

SDL_GAMEPAD_BINDTYPE_BUTTON

SDL_GAMEPAD_BINDTYPE_HAT

SDL_GAMEPAD_BINDTYPE_NONE

SDL_GAMEPAD_BUTTON_BACK

SDL_GAMEPAD_BUTTON_COUNT

SDL_GAMEPAD_BUTTON_DPAD_DOWN

SDL_GAMEPAD_BUTTON_DPAD_LEFT

SDL_GAMEPAD_BUTTON_DPAD_RIGHT

SDL_GAMEPAD_BUTTON_DPAD_UP

SDL_GAMEPAD_BUTTON_EAST

Right face button (e.g. Xbox B button)

SDL_GAMEPAD_BUTTON_GUIDE

SDL_GAMEPAD_BUTTON_INVALID

SDL_GAMEPAD_BUTTON_LABEL_A

SDL_GAMEPAD_BUTTON_LABEL_B

SDL_GAMEPAD_BUTTON_LABEL_CIRCLE

SDL_GAMEPAD_BUTTON_LABEL_CROSS

SDL_GAMEPAD_BUTTON_LABEL_SQUARE

SDL_GAMEPAD_BUTTON_LABEL_TRIANGLE

SDL_GAMEPAD_BUTTON_LABEL_UNKNOWN

SDL_GAMEPAD_BUTTON_LABEL_X

SDL_GAMEPAD_BUTTON_LABEL_Y

SDL_GAMEPAD_BUTTON_LEFT_PADDLE1

Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3)

SDL_GAMEPAD_BUTTON_LEFT_PADDLE2

Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4)

SDL_GAMEPAD_BUTTON_LEFT_SHOULDER

SDL_GAMEPAD_BUTTON_LEFT_STICK

SDL_GAMEPAD_BUTTON_MISC1

Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button)

SDL_GAMEPAD_BUTTON_MISC2

Additional button

SDL_GAMEPAD_BUTTON_MISC3

Additional button

SDL_GAMEPAD_BUTTON_MISC4

Additional button

SDL_GAMEPAD_BUTTON_MISC5

Additional button

SDL_GAMEPAD_BUTTON_MISC6

Additional button

SDL_GAMEPAD_BUTTON_NORTH

Top face button (e.g. Xbox Y button)

SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1

Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1)

SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2

Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2)

SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER

SDL_GAMEPAD_BUTTON_RIGHT_STICK

SDL_GAMEPAD_BUTTON_SOUTH

Bottom face button (e.g. Xbox A button)

SDL_GAMEPAD_BUTTON_START

SDL_GAMEPAD_BUTTON_TOUCHPAD

PS4/PS5 touchpad button

SDL_GAMEPAD_BUTTON_WEST

Left face button (e.g. Xbox X button)

SDL_GAMEPAD_TYPE_COUNT

SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT

SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR

SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT

SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_PRO

SDL_GAMEPAD_TYPE_PS3

SDL_GAMEPAD_TYPE_PS4

SDL_GAMEPAD_TYPE_PS5

SDL_GAMEPAD_TYPE_STANDARD

SDL_GAMEPAD_TYPE_UNKNOWN

SDL_GAMEPAD_TYPE_XBOX360

SDL_GAMEPAD_TYPE_XBOXONE

SDL_PROP_GAMEPAD_CAP_MONO_LED_BOOLEAN

SDL_PROP_GAMEPAD_CAP_PLAYER_LED_BOOLEAN

SDL_PROP_GAMEPAD_CAP_RGB_LED_BOOLEAN

SDL_PROP_GAMEPAD_CAP_RUMBLE_BOOLEAN

SDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN

Functions

SDL_AddGamepadMapping^⚠

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

SDL_AddGamepadMappingsFromFile^⚠

Load a set of gamepad mappings from a file.

SDL_AddGamepadMappingsFromIO^⚠

Load a set of gamepad mappings from an SDL_IOStream.

SDL_CloseGamepad^⚠

Close a gamepad previously opened with SDL_OpenGamepad().

SDL_GamepadConnected^⚠

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

SDL_GamepadEventsEnabled^⚠

Query the state of gamepad event processing.

SDL_GamepadHasAxis^⚠

Query whether a gamepad has a given axis.

SDL_GamepadHasButton^⚠

Query whether a gamepad has a given button.

SDL_GamepadHasSensor^⚠

Return whether a gamepad has a particular sensor.

SDL_GamepadSensorEnabled^⚠

Query whether sensor data reporting is enabled for a gamepad.

SDL_GetGamepadAppleSFSymbolsNameForAxis^⚠

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

SDL_GetGamepadAppleSFSymbolsNameForButton^⚠

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

SDL_GetGamepadAxis^⚠

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

SDL_GetGamepadAxisFromString^⚠

Convert a string into SDL_GamepadAxis enum.

SDL_GetGamepadBindings^⚠

Get the SDL joystick layer bindings for a gamepad.

SDL_GetGamepadButton^⚠

Get the current state of a button on a gamepad.

SDL_GetGamepadButtonFromString^⚠

Convert a string into an SDL_GamepadButton enum.

SDL_GetGamepadButtonLabel^⚠

Get the label of a button on a gamepad.

SDL_GetGamepadButtonLabelForType^⚠

Get the label of a button on a gamepad.

SDL_GetGamepadConnectionState^⚠

Get the connection state of a gamepad.

SDL_GetGamepadFirmwareVersion^⚠

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

SDL_GetGamepadFromID^⚠

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

SDL_GetGamepadFromPlayerIndex^⚠

Get the SDL_Gamepad associated with a player index.

SDL_GetGamepadGUIDForID^⚠

Get the implementation-dependent GUID of a gamepad.

SDL_GetGamepadID^⚠

Get the instance ID of an opened gamepad.

SDL_GetGamepadJoystick^⚠

Get the underlying joystick from a gamepad.

SDL_GetGamepadMapping^⚠

Get the current mapping of a gamepad.

SDL_GetGamepadMappingForGUID^⚠

Get the gamepad mapping string for a given GUID.

SDL_GetGamepadMappingForID^⚠

Get the mapping of a gamepad.

SDL_GetGamepadMappings^⚠

Get the current gamepad mappings.

SDL_GetGamepadName^⚠

Get the implementation-dependent name for an opened gamepad.

SDL_GetGamepadNameForID^⚠

Get the implementation dependent name of a gamepad.

SDL_GetGamepadPath^⚠

Get the implementation-dependent path for an opened gamepad.

SDL_GetGamepadPathForID^⚠

Get the implementation dependent path of a gamepad.

SDL_GetGamepadPlayerIndex^⚠

Get the player index of an opened gamepad.

SDL_GetGamepadPlayerIndexForID^⚠

Get the player index of a gamepad.

SDL_GetGamepadPowerInfo^⚠

Get the battery state of a gamepad.

SDL_GetGamepadProduct^⚠

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

SDL_GetGamepadProductForID^⚠

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

SDL_GetGamepadProductVersion^⚠

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

SDL_GetGamepadProductVersionForID^⚠

Get the product version of a gamepad, if available.

SDL_GetGamepadProperties^⚠

Get the properties associated with an opened gamepad.

SDL_GetGamepadSensorData^⚠

Get the current state of a gamepad sensor.

SDL_GetGamepadSensorDataRate^⚠

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

SDL_GetGamepadSerial^⚠

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

SDL_GetGamepadSteamHandle^⚠

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

SDL_GetGamepadStringForAxis^⚠

Convert from an SDL_GamepadAxis enum to a string.

SDL_GetGamepadStringForButton^⚠

Convert from an SDL_GamepadButton enum to a string.

SDL_GetGamepadStringForType^⚠

Convert from an SDL_GamepadType enum to a string.

SDL_GetGamepadTouchpadFinger^⚠

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

SDL_GetGamepadType^⚠

Get the type of an opened gamepad.

SDL_GetGamepadTypeForID^⚠

Get the type of a gamepad.

SDL_GetGamepadTypeFromString^⚠

Convert a string into SDL_GamepadType enum.

SDL_GetGamepadVendor^⚠

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

SDL_GetGamepadVendorForID^⚠

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

SDL_GetGamepads^⚠

Get a list of currently connected gamepads.

SDL_GetNumGamepadTouchpadFingers^⚠

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

SDL_GetNumGamepadTouchpads^⚠

Get the number of touchpads on a gamepad.

SDL_GetRealGamepadType^⚠

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

SDL_GetRealGamepadTypeForID^⚠

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

SDL_HasGamepad^⚠

Return whether a gamepad is currently connected.

SDL_IsGamepad^⚠

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

SDL_OpenGamepad^⚠

Open a gamepad for use.

SDL_ReloadGamepadMappings^⚠

Reinitialize the SDL mapping database to its initial state.

SDL_RumbleGamepad^⚠

Start a rumble effect on a gamepad.

SDL_RumbleGamepadTriggers^⚠

Start a rumble effect in the gamepad’s triggers.

SDL_SendGamepadEffect^⚠

Send a gamepad specific effect packet.

SDL_SetGamepadEventsEnabled^⚠

Set the state of gamepad event processing.

SDL_SetGamepadLED^⚠

Update a gamepad’s LED color.

SDL_SetGamepadMapping^⚠

Set the current mapping of a joystick or gamepad.

SDL_SetGamepadPlayerIndex^⚠

Set the player index of an opened gamepad.

SDL_SetGamepadSensorEnabled^⚠

Set whether data reporting for a gamepad sensor is enabled.

SDL_UpdateGamepads^⚠

Manually pump gamepad updates if not using the loop.

Unions

SDL_GamepadBinding__AnonUnion1

SDL_GamepadBinding__AnonUnion2