gamepad topic

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

Functions

sdlAddGamepadMapping(String? mapping) → int gamepad
Add support for gamepads that SDL is unaware of or change the binding of an existing gamepad.
sdlAddGamepadMappingsFromFile(String? file) → int gamepad
Load a set of gamepad mappings from a file.
sdlAddGamepadMappingsFromIo(Pointer<SdlIoStream> src, bool closeio) → int gamepad
Load a set of gamepad mappings from an SDL_IOStream.
sdlCloseGamepad(Pointer<SdlGamepad> gamepad) → void gamepad
Close a gamepad previously opened with SDL_OpenGamepad().
sdlGamepadConnected(Pointer<SdlGamepad> gamepad) → bool gamepad
Check if a gamepad has been opened and is currently connected.
sdlGamepadEventsEnabled() → bool gamepad
Query the state of gamepad event processing.
sdlGamepadHasAxis(Pointer<SdlGamepad> gamepad, int axis) → bool gamepad
Query whether a gamepad has a given axis.
sdlGamepadHasButton(Pointer<SdlGamepad> gamepad, int button) → bool gamepad
Query whether a gamepad has a given button.
sdlGamepadHasSensor(Pointer<SdlGamepad> gamepad, int type) → bool gamepad
Return whether a gamepad has a particular sensor.
sdlGamepadSensorEnabled(Pointer<SdlGamepad> gamepad, int type) → bool gamepad
Query whether sensor data reporting is enabled for a gamepad.
sdlGetGamepadAppleSfSymbolsNameForAxis(Pointer<SdlGamepad> gamepad, int axis) → String? gamepad
Return the sfSymbolsName for a given axis on a gamepad on Apple platforms.
sdlGetGamepadAppleSfSymbolsNameForButton(Pointer<SdlGamepad> gamepad, int button) → String? gamepad
Return the sfSymbolsName for a given button on a gamepad on Apple platforms.
sdlGetGamepadAxis(Pointer<SdlGamepad> gamepad, int axis) → int gamepad
Get the current state of an axis control on a gamepad.
sdlGetGamepadAxisFromString(String? str) → int gamepad
Convert a string into SDL_GamepadAxis enum.
sdlGetGamepadBindings(Pointer<SdlGamepad> gamepad, Pointer<Int32> count) → Pointer<Pointer<SdlGamepadBinding>> gamepad
Get the SDL joystick layer bindings for a gamepad.
sdlGetGamepadButton(Pointer<SdlGamepad> gamepad, int button) → bool gamepad
Get the current state of a button on a gamepad.
sdlGetGamepadButtonFromString(String? str) → int gamepad
Convert a string into an SDL_GamepadButton enum.
sdlGetGamepadButtonLabel(Pointer<SdlGamepad> gamepad, int button) → int gamepad
Get the label of a button on a gamepad.
sdlGetGamepadButtonLabelForType(int type, int button) → int gamepad
Get the label of a button on a gamepad.
sdlGetGamepadConnectionState(Pointer<SdlGamepad> gamepad) → int gamepad
Get the connection state of a gamepad.
sdlGetGamepadFirmwareVersion(Pointer<SdlGamepad> gamepad) → int gamepad
Get the firmware version of an opened gamepad, if available.
sdlGetGamepadFromId(int instanceId) → Pointer<SdlGamepad> gamepad
Get the SDL_Gamepad associated with a joystick instance ID, if it has been opened.
sdlGetGamepadFromPlayerIndex(int playerIndex) → Pointer<SdlGamepad> gamepad
Get the SDL_Gamepad associated with a player index.
sdlGetGamepadGuidForId(int instanceId) → SdlGuid gamepad
Get the implementation-dependent GUID of a gamepad.
sdlGetGamepadId(Pointer<SdlGamepad> gamepad) → int gamepad
Get the instance ID of an opened gamepad.
sdlGetGamepadJoystick(Pointer<SdlGamepad> gamepad) → Pointer<SdlJoystick> gamepad
Get the underlying joystick from a gamepad.
sdlGetGamepadMapping(Pointer<SdlGamepad> gamepad) → Pointer<Int8> gamepad
Get the current mapping of a gamepad.
sdlGetGamepadMappingForGuid(SdlGuid guid) → Pointer<Int8> gamepad
Get the gamepad mapping string for a given GUID.
sdlGetGamepadMappingForId(int instanceId) → Pointer<Int8> gamepad
Get the mapping of a gamepad.
sdlGetGamepadMappings(Pointer<Int32> count) → Pointer<Pointer<Int8>> gamepad
Get the current gamepad mappings.
sdlGetGamepadName(Pointer<SdlGamepad> gamepad) → String? gamepad
Get the implementation-dependent name for an opened gamepad.
sdlGetGamepadNameForId(int instanceId) → String? gamepad
Get the implementation dependent name of a gamepad.
sdlGetGamepadPath(Pointer<SdlGamepad> gamepad) → String? gamepad
Get the implementation-dependent path for an opened gamepad.
sdlGetGamepadPathForId(int instanceId) → String? gamepad
Get the implementation dependent path of a gamepad.
sdlGetGamepadPlayerIndex(Pointer<SdlGamepad> gamepad) → int gamepad
Get the player index of an opened gamepad.
sdlGetGamepadPlayerIndexForId(int instanceId) → int gamepad
Get the player index of a gamepad.
sdlGetGamepadPowerInfo(Pointer<SdlGamepad> gamepad, Pointer<Int32> percent) → int gamepad
Get the battery state of a gamepad.
sdlGetGamepadProduct(Pointer<SdlGamepad> gamepad) → int gamepad
Get the USB product ID of an opened gamepad, if available.
sdlGetGamepadProductForId(int instanceId) → int gamepad
Get the USB product ID of a gamepad, if available.
sdlGetGamepadProductVersion(Pointer<SdlGamepad> gamepad) → int gamepad
Get the product version of an opened gamepad, if available.
sdlGetGamepadProductVersionForId(int instanceId) → int gamepad
Get the product version of a gamepad, if available.
sdlGetGamepadProperties(Pointer<SdlGamepad> gamepad) → int gamepad
Get the properties associated with an opened gamepad.
sdlGetGamepads(Pointer<Int32> count) → Pointer<Uint32> gamepad
Get a list of currently connected gamepads.
sdlGetGamepadSensorData(Pointer<SdlGamepad> gamepad, int type, Pointer<Float> data, int numValues) → bool gamepad
Get the current state of a gamepad sensor.
sdlGetGamepadSensorDataRate(Pointer<SdlGamepad> gamepad, int type) → double gamepad
Get the data rate (number of events per second) of a gamepad sensor.
sdlGetGamepadSerial(Pointer<SdlGamepad> gamepad) → String? gamepad
Get the serial number of an opened gamepad, if available.
sdlGetGamepadSteamHandle(Pointer<SdlGamepad> gamepad) → int gamepad
Get the Steam Input handle of an opened gamepad, if available.
sdlGetGamepadStringForAxis(int axis) → String? gamepad
Convert from an SDL_GamepadAxis enum to a string.
sdlGetGamepadStringForButton(int button) → String? gamepad
Convert from an SDL_GamepadButton enum to a string.
sdlGetGamepadStringForType(int type) → String? gamepad
Convert from an SDL_GamepadType enum to a string.
sdlGetGamepadTouchpadFinger(Pointer<SdlGamepad> gamepad, int touchpad, int finger, Pointer<Uint8> down, Pointer<Float> x, Pointer<Float> y, Pointer<Float> pressure) → bool gamepad
Get the current state of a finger on a touchpad on a gamepad.
sdlGetGamepadType(Pointer<SdlGamepad> gamepad) → int gamepad
Get the type of an opened gamepad.
sdlGetGamepadTypeForId(int instanceId) → int gamepad
Get the type of a gamepad.
sdlGetGamepadTypeFromString(String? str) → int gamepad
Convert a string into SDL_GamepadType enum.
sdlGetGamepadVendor(Pointer<SdlGamepad> gamepad) → int gamepad
Get the USB vendor ID of an opened gamepad, if available.
sdlGetGamepadVendorForId(int instanceId) → int gamepad
Get the USB vendor ID of a gamepad, if available.
sdlGetNumGamepadTouchpadFingers(Pointer<SdlGamepad> gamepad, int touchpad) → int gamepad
Get the number of supported simultaneous fingers on a touchpad on a game gamepad.
sdlGetNumGamepadTouchpads(Pointer<SdlGamepad> gamepad) → int gamepad
Get the number of touchpads on a gamepad.
sdlGetRealGamepadType(Pointer<SdlGamepad> gamepad) → int gamepad
Get the type of an opened gamepad, ignoring any mapping override.
sdlGetRealGamepadTypeForId(int instanceId) → int gamepad
Get the type of a gamepad, ignoring any mapping override.
sdlHasGamepad() → bool gamepad
Return whether a gamepad is currently connected.
sdlIsGamepad(int instanceId) → bool gamepad
Check if the given joystick is supported by the gamepad interface.
sdlOpenGamepad(int instanceId) → Pointer<SdlGamepad> gamepad
Open a gamepad for use.
sdlReloadGamepadMappings() → bool gamepad
Reinitialize the SDL mapping database to its initial state.
sdlRumbleGamepad(Pointer<SdlGamepad> gamepad, int lowFrequencyRumble, int highFrequencyRumble, int durationMs) → bool gamepad
Start a rumble effect on a gamepad.
sdlRumbleGamepadTriggers(Pointer<SdlGamepad> gamepad, int leftRumble, int rightRumble, int durationMs) → bool gamepad
Start a rumble effect in the gamepad's triggers.
sdlSendGamepadEffect(Pointer<SdlGamepad> gamepad, Pointer<NativeType> data, int size) → bool gamepad
Send a gamepad specific effect packet.
sdlSetGamepadEventsEnabled(bool enabled) → void gamepad
Set the state of gamepad event processing.
sdlSetGamepadLed(Pointer<SdlGamepad> gamepad, int red, int green, int blue) → bool gamepad
Update a gamepad's LED color.
sdlSetGamepadMapping(int instanceId, String? mapping) → bool gamepad
Set the current mapping of a joystick or gamepad.
sdlSetGamepadPlayerIndex(Pointer<SdlGamepad> gamepad, int playerIndex) → bool gamepad
Set the player index of an opened gamepad.
sdlSetGamepadSensorEnabled(Pointer<SdlGamepad> gamepad, int type, bool enabled) → bool gamepad
Set whether data reporting for a gamepad sensor is enabled.
sdlUpdateGamepads() → void gamepad
Manually pump gamepad updates if not using the loop.