|
int | SDL_AddGamepadMapping (const char *mapping) |
|
int | SDL_AddGamepadMappingsFromIO (SDL_IOStream *src, SDL_bool closeio) |
|
int | SDL_AddGamepadMappingsFromFile (const char *file) |
|
int | SDL_ReloadGamepadMappings (void) |
|
char ** | SDL_GetGamepadMappings (int *count) |
|
char * | SDL_GetGamepadMappingForGUID (SDL_JoystickGUID guid) |
|
char * | SDL_GetGamepadMapping (SDL_Gamepad *gamepad) |
|
int | SDL_SetGamepadMapping (SDL_JoystickID instance_id, const char *mapping) |
|
SDL_bool | SDL_HasGamepad (void) |
|
SDL_JoystickID * | SDL_GetGamepads (int *count) |
|
SDL_bool | SDL_IsGamepad (SDL_JoystickID instance_id) |
|
const char * | SDL_GetGamepadInstanceName (SDL_JoystickID instance_id) |
|
const char * | SDL_GetGamepadInstancePath (SDL_JoystickID instance_id) |
|
int | SDL_GetGamepadInstancePlayerIndex (SDL_JoystickID instance_id) |
|
SDL_JoystickGUID | SDL_GetGamepadInstanceGUID (SDL_JoystickID instance_id) |
|
Uint16 | SDL_GetGamepadInstanceVendor (SDL_JoystickID instance_id) |
|
Uint16 | SDL_GetGamepadInstanceProduct (SDL_JoystickID instance_id) |
|
Uint16 | SDL_GetGamepadInstanceProductVersion (SDL_JoystickID instance_id) |
|
SDL_GamepadType | SDL_GetGamepadInstanceType (SDL_JoystickID instance_id) |
|
SDL_GamepadType | SDL_GetRealGamepadInstanceType (SDL_JoystickID instance_id) |
|
char * | SDL_GetGamepadInstanceMapping (SDL_JoystickID instance_id) |
|
SDL_Gamepad * | SDL_OpenGamepad (SDL_JoystickID instance_id) |
|
SDL_Gamepad * | SDL_GetGamepadFromInstanceID (SDL_JoystickID instance_id) |
|
SDL_Gamepad * | SDL_GetGamepadFromPlayerIndex (int player_index) |
|
SDL_PropertiesID | SDL_GetGamepadProperties (SDL_Gamepad *gamepad) |
|
SDL_JoystickID | SDL_GetGamepadInstanceID (SDL_Gamepad *gamepad) |
|
const char * | SDL_GetGamepadName (SDL_Gamepad *gamepad) |
|
const char * | SDL_GetGamepadPath (SDL_Gamepad *gamepad) |
|
SDL_GamepadType | SDL_GetGamepadType (SDL_Gamepad *gamepad) |
|
SDL_GamepadType | SDL_GetRealGamepadType (SDL_Gamepad *gamepad) |
|
int | SDL_GetGamepadPlayerIndex (SDL_Gamepad *gamepad) |
|
int | SDL_SetGamepadPlayerIndex (SDL_Gamepad *gamepad, int player_index) |
|
Uint16 | SDL_GetGamepadVendor (SDL_Gamepad *gamepad) |
|
Uint16 | SDL_GetGamepadProduct (SDL_Gamepad *gamepad) |
|
Uint16 | SDL_GetGamepadProductVersion (SDL_Gamepad *gamepad) |
|
Uint16 | SDL_GetGamepadFirmwareVersion (SDL_Gamepad *gamepad) |
|
const char * | SDL_GetGamepadSerial (SDL_Gamepad *gamepad) |
|
Uint64 | SDL_GetGamepadSteamHandle (SDL_Gamepad *gamepad) |
|
SDL_JoystickPowerLevel | SDL_GetGamepadPowerLevel (SDL_Gamepad *gamepad) |
|
SDL_bool | SDL_GamepadConnected (SDL_Gamepad *gamepad) |
|
SDL_Joystick * | SDL_GetGamepadJoystick (SDL_Gamepad *gamepad) |
|
void | SDL_SetGamepadEventsEnabled (SDL_bool enabled) |
|
SDL_bool | SDL_GamepadEventsEnabled (void) |
|
SDL_GamepadBinding ** | SDL_GetGamepadBindings (SDL_Gamepad *gamepad, int *count) |
|
void | SDL_UpdateGamepads (void) |
|
SDL_GamepadType | SDL_GetGamepadTypeFromString (const char *str) |
|
const char * | SDL_GetGamepadStringForType (SDL_GamepadType type) |
|
SDL_GamepadAxis | SDL_GetGamepadAxisFromString (const char *str) |
|
const char * | SDL_GetGamepadStringForAxis (SDL_GamepadAxis axis) |
|
SDL_bool | SDL_GamepadHasAxis (SDL_Gamepad *gamepad, SDL_GamepadAxis axis) |
|
Sint16 | SDL_GetGamepadAxis (SDL_Gamepad *gamepad, SDL_GamepadAxis axis) |
|
SDL_GamepadButton | SDL_GetGamepadButtonFromString (const char *str) |
|
const char * | SDL_GetGamepadStringForButton (SDL_GamepadButton button) |
|
SDL_bool | SDL_GamepadHasButton (SDL_Gamepad *gamepad, SDL_GamepadButton button) |
|
Uint8 | SDL_GetGamepadButton (SDL_Gamepad *gamepad, SDL_GamepadButton button) |
|
SDL_GamepadButtonLabel | SDL_GetGamepadButtonLabelForType (SDL_GamepadType type, SDL_GamepadButton button) |
|
SDL_GamepadButtonLabel | SDL_GetGamepadButtonLabel (SDL_Gamepad *gamepad, SDL_GamepadButton button) |
|
int | SDL_GetNumGamepadTouchpads (SDL_Gamepad *gamepad) |
|
int | SDL_GetNumGamepadTouchpadFingers (SDL_Gamepad *gamepad, int touchpad) |
|
int | SDL_GetGamepadTouchpadFinger (SDL_Gamepad *gamepad, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure) |
|
SDL_bool | SDL_GamepadHasSensor (SDL_Gamepad *gamepad, SDL_SensorType type) |
|
int | SDL_SetGamepadSensorEnabled (SDL_Gamepad *gamepad, SDL_SensorType type, SDL_bool enabled) |
|
SDL_bool | SDL_GamepadSensorEnabled (SDL_Gamepad *gamepad, SDL_SensorType type) |
|
float | SDL_GetGamepadSensorDataRate (SDL_Gamepad *gamepad, SDL_SensorType type) |
|
int | SDL_GetGamepadSensorData (SDL_Gamepad *gamepad, SDL_SensorType type, float *data, int num_values) |
|
int | SDL_RumbleGamepad (SDL_Gamepad *gamepad, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms) |
|
int | SDL_RumbleGamepadTriggers (SDL_Gamepad *gamepad, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms) |
|
int | SDL_SetGamepadLED (SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue) |
|
int | SDL_SendGamepadEffect (SDL_Gamepad *gamepad, const void *data, int size) |
|
void | SDL_CloseGamepad (SDL_Gamepad *gamepad) |
|
const char * | SDL_GetGamepadAppleSFSymbolsNameForButton (SDL_Gamepad *gamepad, SDL_GamepadButton button) |
|
const char * | SDL_GetGamepadAppleSFSymbolsNameForAxis (SDL_Gamepad *gamepad, SDL_GamepadAxis axis) |
|
Include file for SDL gamepad event handling
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
Definition in file SDL_gamepad.h.
The list of buttons available on a gamepad
For controllers that use a diamond pattern for the face buttons, the south/east/west/north buttons below correspond to the locations in the diamond pattern. For Xbox controllers, this would be A/B/X/Y, for Nintendo Switch controllers, this would be B/A/Y/X, for PlayStation controllers this would be Cross/Circle/Square/Triangle.
For controllers that don't use a diamond pattern for the face buttons, the south/east/west/north buttons indicate the buttons labeled A, B, C, D, or 1, 2, 3, 4, or for controllers that aren't labeled, they are the primary, secondary, etc. buttons.
The activate action is often the south button and the cancel action is often the east button, but in some regions this is reversed, so your game should allow remapping actions based on user preferences.
You can query the labels for the face buttons using SDL_GetGamepadButtonLabel()
Enumerator |
---|
SDL_GAMEPAD_BUTTON_INVALID | |
SDL_GAMEPAD_BUTTON_SOUTH | |
SDL_GAMEPAD_BUTTON_EAST | |
SDL_GAMEPAD_BUTTON_WEST | |
SDL_GAMEPAD_BUTTON_NORTH | |
SDL_GAMEPAD_BUTTON_BACK | |
SDL_GAMEPAD_BUTTON_GUIDE | |
SDL_GAMEPAD_BUTTON_START | |
SDL_GAMEPAD_BUTTON_LEFT_STICK | |
SDL_GAMEPAD_BUTTON_RIGHT_STICK | |
SDL_GAMEPAD_BUTTON_LEFT_SHOULDER | |
SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER | |
SDL_GAMEPAD_BUTTON_DPAD_UP | |
SDL_GAMEPAD_BUTTON_DPAD_DOWN | |
SDL_GAMEPAD_BUTTON_DPAD_LEFT | |
SDL_GAMEPAD_BUTTON_DPAD_RIGHT | |
SDL_GAMEPAD_BUTTON_MISC1 | |
SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 | |
SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 | |
SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2 | |
SDL_GAMEPAD_BUTTON_LEFT_PADDLE2 | |
SDL_GAMEPAD_BUTTON_TOUCHPAD | |
SDL_GAMEPAD_BUTTON_MISC2 | |
SDL_GAMEPAD_BUTTON_MISC3 | |
SDL_GAMEPAD_BUTTON_MISC4 | |
SDL_GAMEPAD_BUTTON_MISC5 | |
SDL_GAMEPAD_BUTTON_MISC6 | |
SDL_GAMEPAD_BUTTON_MAX | |
Definition at line 98 of file SDL_gamepad.h.
99{
@ SDL_GAMEPAD_BUTTON_LEFT_PADDLE2
@ SDL_GAMEPAD_BUTTON_WEST
@ SDL_GAMEPAD_BUTTON_EAST
@ SDL_GAMEPAD_BUTTON_MISC2
@ SDL_GAMEPAD_BUTTON_GUIDE
@ SDL_GAMEPAD_BUTTON_LEFT_STICK
@ SDL_GAMEPAD_BUTTON_TOUCHPAD
@ SDL_GAMEPAD_BUTTON_MISC4
@ SDL_GAMEPAD_BUTTON_MISC5
@ SDL_GAMEPAD_BUTTON_LEFT_SHOULDER
@ SDL_GAMEPAD_BUTTON_DPAD_DOWN
@ SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1
@ SDL_GAMEPAD_BUTTON_INVALID
@ SDL_GAMEPAD_BUTTON_MISC6
@ SDL_GAMEPAD_BUTTON_MISC1
@ SDL_GAMEPAD_BUTTON_BACK
@ SDL_GAMEPAD_BUTTON_DPAD_UP
@ SDL_GAMEPAD_BUTTON_LEFT_PADDLE1
@ SDL_GAMEPAD_BUTTON_RIGHT_STICK
@ SDL_GAMEPAD_BUTTON_START
@ SDL_GAMEPAD_BUTTON_DPAD_RIGHT
@ SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER
@ SDL_GAMEPAD_BUTTON_MISC3
@ SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2
@ SDL_GAMEPAD_BUTTON_SOUTH
@ SDL_GAMEPAD_BUTTON_DPAD_LEFT
@ SDL_GAMEPAD_BUTTON_NORTH
int SDL_AddGamepadMapping |
( |
const char * |
mapping | ) |
|
|
extern |
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_GetJoystickGUIDString(), 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.
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"
- Parameters
-
mapping | the mapping string |
- Returns
- 1 if a new mapping is added, 0 if an existing mapping is updated, -1 on error; call SDL_GetError() for more information.
- Since
- This function is available since SDL 3.0.0.
- See also
- SDL_GetGamepadMapping
-
SDL_GetGamepadMappingForGUID
int SDL_AddGamepadMappingsFromFile |
( |
const char * |
file | ) |
|
|
extern |
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.
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).
- Parameters
-
file | the mappings file to load |
- Returns
- the number of mappings added or -1 on error; call SDL_GetError() for more information.
- Since
- This function is available since SDL 3.0.0.
- See also
- SDL_AddGamepadMapping
-
SDL_AddGamepadMappingsFromIO
-
SDL_GetGamepadMapping
-
SDL_GetGamepadMappingForGUID
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.
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.
- Parameters
-
src | the data stream for the mappings to be added |
closeio | if SDL_TRUE, calls SDL_CloseIO() on src before returning, even in the case of an error |
- Returns
- the number of mappings added or -1 on error; call SDL_GetError() for more information.
- Since
- This function is available since SDL 3.0.0.
- See also
- SDL_AddGamepadMapping
-
SDL_AddGamepadMappingsFromFile
-
SDL_GetGamepadMapping
-
SDL_GetGamepadMappingForGUID
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.
- Parameters
-
gamepad | a gamepad |
axis | an axis index (one of the SDL_GamepadAxis values) |
- Returns
- axis state (including 0) on success or 0 (also) on failure; call SDL_GetError() for more information.
- Since
- This function is available since SDL 3.0.0.
- See also
- SDL_GamepadHasAxis
-
SDL_GetGamepadButton
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.
- Parameters
-
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.
- Since
- This function is available since SDL 3.0.0.
- See also
- SDL_GetGamepadStringForAxis
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.
- Parameters
-
gamepad | the gamepad object that you want to get a joystick from |
- Returns
- an SDL_Joystick object; call SDL_GetError() for more information.
- Since
- This function is available since SDL 3.0.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.
- Parameters
-
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
- 0 on success or a negative error code on failure; call SDL_GetError() for more information.
- Since
- This function is available since SDL 3.0.0.
- See also
- SDL_RumbleGamepad