# CategoryGamepad 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](SDL_Init)() must have been called with the [SDL_INIT_GAMEPAD](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_Init)(): [SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS](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](SDL_GetGamepadProperties)() and checking the various capability properties. You can check for touchpad by calling [SDL_GetNumGamepadTouchpads](SDL_GetNumGamepadTouchpads)() and check for gyro and accelerometer by calling [SDL_GamepadHasSensor](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](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. <!-- END CATEGORY DOCUMENTATION --> ## Functions <!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. --> <!-- BEGIN CATEGORY LIST: CategoryGamepad, CategoryAPIFunction --> - [SDL_AddGamepadMapping](SDL_AddGamepadMapping) - [SDL_AddGamepadMappingsFromFile](SDL_AddGamepadMappingsFromFile) - [SDL_AddGamepadMappingsFromIO](SDL_AddGamepadMappingsFromIO) - [SDL_CloseGamepad](SDL_CloseGamepad) - [SDL_GamepadConnected](SDL_GamepadConnected) - [SDL_GamepadEventsEnabled](SDL_GamepadEventsEnabled) - [SDL_GamepadHasAxis](SDL_GamepadHasAxis) - [SDL_GamepadHasButton](SDL_GamepadHasButton) - [SDL_GamepadHasSensor](SDL_GamepadHasSensor) - [SDL_GamepadSensorEnabled](SDL_GamepadSensorEnabled) - [SDL_GetGamepadAppleSFSymbolsNameForAxis](SDL_GetGamepadAppleSFSymbolsNameForAxis) - [SDL_GetGamepadAppleSFSymbolsNameForButton](SDL_GetGamepadAppleSFSymbolsNameForButton) - [SDL_GetGamepadAxis](SDL_GetGamepadAxis) - [SDL_GetGamepadAxisFromString](SDL_GetGamepadAxisFromString) - [SDL_GetGamepadBindings](SDL_GetGamepadBindings) - [SDL_GetGamepadButton](SDL_GetGamepadButton) - [SDL_GetGamepadButtonFromString](SDL_GetGamepadButtonFromString) - [SDL_GetGamepadButtonLabel](SDL_GetGamepadButtonLabel) - [SDL_GetGamepadButtonLabelForType](SDL_GetGamepadButtonLabelForType) - [SDL_GetGamepadConnectionState](SDL_GetGamepadConnectionState) - [SDL_GetGamepadFirmwareVersion](SDL_GetGamepadFirmwareVersion) - [SDL_GetGamepadFromID](SDL_GetGamepadFromID) - [SDL_GetGamepadFromPlayerIndex](SDL_GetGamepadFromPlayerIndex) - [SDL_GetGamepadGUIDForID](SDL_GetGamepadGUIDForID) - [SDL_GetGamepadID](SDL_GetGamepadID) - [SDL_GetGamepadJoystick](SDL_GetGamepadJoystick) - [SDL_GetGamepadMapping](SDL_GetGamepadMapping) - [SDL_GetGamepadMappingForGUID](SDL_GetGamepadMappingForGUID) - [SDL_GetGamepadMappingForID](SDL_GetGamepadMappingForID) - [SDL_GetGamepadMappings](SDL_GetGamepadMappings) - [SDL_GetGamepadName](SDL_GetGamepadName) - [SDL_GetGamepadNameForID](SDL_GetGamepadNameForID) - [SDL_GetGamepadPath](SDL_GetGamepadPath) - [SDL_GetGamepadPathForID](SDL_GetGamepadPathForID) - [SDL_GetGamepadPlayerIndex](SDL_GetGamepadPlayerIndex) - [SDL_GetGamepadPlayerIndexForID](SDL_GetGamepadPlayerIndexForID) - [SDL_GetGamepadPowerInfo](SDL_GetGamepadPowerInfo) - [SDL_GetGamepadProduct](SDL_GetGamepadProduct) - [SDL_GetGamepadProductForID](SDL_GetGamepadProductForID) - [SDL_GetGamepadProductVersion](SDL_GetGamepadProductVersion) - [SDL_GetGamepadProductVersionForID](SDL_GetGamepadProductVersionForID) - [SDL_GetGamepadProperties](SDL_GetGamepadProperties) - [SDL_GetGamepads](SDL_GetGamepads) - [SDL_GetGamepadSensorData](SDL_GetGamepadSensorData) - [SDL_GetGamepadSensorDataRate](SDL_GetGamepadSensorDataRate) - [SDL_GetGamepadSerial](SDL_GetGamepadSerial) - [SDL_GetGamepadSteamHandle](SDL_GetGamepadSteamHandle) - [SDL_GetGamepadStringForAxis](SDL_GetGamepadStringForAxis) - [SDL_GetGamepadStringForButton](SDL_GetGamepadStringForButton) - [SDL_GetGamepadStringForType](SDL_GetGamepadStringForType) - [SDL_GetGamepadTouchpadFinger](SDL_GetGamepadTouchpadFinger) - [SDL_GetGamepadType](SDL_GetGamepadType) - [SDL_GetGamepadTypeForID](SDL_GetGamepadTypeForID) - [SDL_GetGamepadTypeFromString](SDL_GetGamepadTypeFromString) - [SDL_GetGamepadVendor](SDL_GetGamepadVendor) - [SDL_GetGamepadVendorForID](SDL_GetGamepadVendorForID) - [SDL_GetNumGamepadTouchpadFingers](SDL_GetNumGamepadTouchpadFingers) - [SDL_GetNumGamepadTouchpads](SDL_GetNumGamepadTouchpads) - [SDL_GetRealGamepadType](SDL_GetRealGamepadType) - [SDL_GetRealGamepadTypeForID](SDL_GetRealGamepadTypeForID) - [SDL_HasGamepad](SDL_HasGamepad) - [SDL_IsGamepad](SDL_IsGamepad) - [SDL_OpenGamepad](SDL_OpenGamepad) - [SDL_ReloadGamepadMappings](SDL_ReloadGamepadMappings) - [SDL_RumbleGamepad](SDL_RumbleGamepad) - [SDL_RumbleGamepadTriggers](SDL_RumbleGamepadTriggers) - [SDL_SendGamepadEffect](SDL_SendGamepadEffect) - [SDL_SetGamepadEventsEnabled](SDL_SetGamepadEventsEnabled) - [SDL_SetGamepadLED](SDL_SetGamepadLED) - [SDL_SetGamepadMapping](SDL_SetGamepadMapping) - [SDL_SetGamepadPlayerIndex](SDL_SetGamepadPlayerIndex) - [SDL_SetGamepadSensorEnabled](SDL_SetGamepadSensorEnabled) - [SDL_UpdateGamepads](SDL_UpdateGamepads) <!-- END CATEGORY LIST --> ## Datatypes <!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. --> <!-- BEGIN CATEGORY LIST: CategoryGamepad, CategoryAPIDatatype --> - [SDL_Gamepad](SDL_Gamepad) <!-- END CATEGORY LIST --> ## Structs <!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. --> <!-- BEGIN CATEGORY LIST: CategoryGamepad, CategoryAPIStruct --> - [SDL_GamepadBinding](SDL_GamepadBinding) <!-- END CATEGORY LIST --> ## Enums <!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. --> <!-- BEGIN CATEGORY LIST: CategoryGamepad, CategoryAPIEnum --> - [SDL_GamepadAxis](SDL_GamepadAxis) - [SDL_GamepadBindingType](SDL_GamepadBindingType) - [SDL_GamepadButton](SDL_GamepadButton) - [SDL_GamepadButtonLabel](SDL_GamepadButtonLabel) - [SDL_GamepadType](SDL_GamepadType) <!-- END CATEGORY LIST --> ## Macros <!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. --> <!-- BEGIN CATEGORY LIST: CategoryGamepad, CategoryAPIMacro --> - (none.) <!-- END CATEGORY LIST --> ---- [CategoryAPICategory](CategoryAPICategory)