NAME
SDL2::gamecontroller - SDL Game Controller Event Handling
SYNOPSIS
use SDL2 qw[:gamecontroller];DESCRIPTION
In order to use these functions, SDL_Init( ... ) must have been called with the SDL_INIT_GAMECONTROLLER flag. This causes SDL to scan the system for game controllers, and load appropriate drivers.
If you would like to receive controller updates while the application is in the background, you should set the following hint before calling SDL_Init( ... ): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS.
Functions
These may be imported by name or with the :gamecontroller tag.
SDL_GameControllerAddMappingsFromRW( ... )
Load a set of Game Controller mappings from a seekable SDL data stream.
You can call this function several times, if needed, to load different database files.
If a new mapping is loaded for an already known controller 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.
Expected parameters include:
rw- the data stream for the mappings to be addedfreerw- non-zero to close the stream after being read
Returns the number of mappings added or -1 on error; call SDL_GetError( ) for more information.
SDL_GameControllerAddMappingsFromRW( ... )
Load a set of mappings from a file, filtered by the current SDL_GetPlatform( ).
SDL_GameControllerAddMappingsFromFile( 'gamecontrollerdb.txt' );Expected parameters include:
Returns the number of mappings added or -1 on error; call SDL_GetError( ) for more information.
SDL_GameControllerAddMapping( ... )
Add support for controllers that SDL is unaware of or to cause an existing controller to have a different binding.
The mapping string has the format "GUID,name,mapping", where GUID is the string value from SDL_JoystickGetGUIDString( ... ), name is the human readable string for the device and mappings are controller 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 joystickbutton, index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick|}Buttons can be used as a controller axes and vice versa.
This string shows an example of a valid mapping for a controller:
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:b7Expected parameters include:
Returns 1 if a new mapping is added, 0 if an existing mapping is updated, -1 on error; call SDL_GetError( ) for more information.
SDL_GameControllerNumMappings( )
Get the number of mappings installed.
Returns the number of mappings.
SDL_GameControllerMappingForIndex( ... )
Get the mapping at a particular index.
Returns the mapping string. Must be freed with SDL_free( ... ). Returns undef if the index is out of range.
SDL_GameControllerMappingForGUID( ... )
Get the game controller mapping string for a given GUID.
The returned string must be freed with SDL_free( ... ).
Expected parameters include:
Returns a mapping string or NULL on error; call SDL_GetError( ) for more information.
SDL_GameControllerMapping( ... )
Get the current mapping of a Game Controller.
The returned string must be freed with SDL_free( ... ).
Details about mappings are discussed with SDL_GameControllerAddMapping( ... ).
Expected parameters include:
Returns a string that has the controller's mapping or undef if no mapping is available; call SDL_GetError( ) for more information.
SDL_IsGameController( ... )
Check if the given joystick is supported by the game controller interface.
joystick_index is the same as the device_index passed to SDL_JoystickOpen( ... ).
Expected parameters include:
joystick_index- thedevice_indexof a device, up toSDL_NumJoysticks( )
Returns SDL_TRUE if the given joystick is supported by the game controller interface, SDL_FALSE if it isn't or it's an invalid index.
SDL_GameControllerNameForIndex( ... )
Get the implementation dependent name for the game controller.
This function can be called before any controllers are opened.
joystick_index is the same as the device_index passed to SDL_JoystickOpen( ... ).
Expected parameters include:
Returns the implementation-dependent name for the game controller, or undef if there is no name or the index is invalid.
SDL_GameControllerTypeForIndex( ... )
Get the type of a game controller.
This can be called before any controllers are opened.
Expected parameters include:
Returns the controller type.
SDL_GameControllerMappingForDeviceIndex( ... )
Get the mapping of a game controller.
This can be called before any controllers are opened.
Expected parameters include:
Returns the mapping string. Must be freed with SDL_free( ... ). Returns undef if no mapping is available.
SDL_GameControllerOpen( ... )
Open a game controller for use.
joystick_index is the same as the device_index passed to SDL_JoystickOpen( ... ).
The index passed as an argument refers to the N'th game controller on the system. This index is not the value which will identify this controller in future controller events. The joystick's instance id (SDL_JoystickID) will be used there instead.
Expected parameters include;
joystick_index- the device_index of a device, up toSDL_NumJoysticks( )
Returns a gamecontroller identifier or undef if an error occurred; call SDL_GetError( ) for more information.
SDL_GameControllerFromInstanceID( ... )
Get the SDL_GameController associated with an instance id.
Expected parameters include:
Returns an SDL2::GameController on success or undef on failure; call SDL_GetError( ) for more information.
SDL_GameControllerFromPlayerIndex( ... )
Get the SDL2::GameController associated with a player index.
Please note that the player index is _not_ the device index, nor is it the instance id!
Expected parameters include:
Returns the SDL2::GameController associated with a player index.
SDL_GameControllerName( ... )
Get the implementation-dependent name for an opened game controller.
This is the same name as returned by SDL_GameControllerNameForIndex(), but it takes a controller identifier instead of the (unstable) device index.
Expected parameters include:
gamecontrollera game controller identifier previously returned bySDL_GameControllerOpen( ... )
Returns the implementation dependent name for the game controller, or undef if there is no name or the identifier passed is invalid.
SDL_GameControllerGetType( ... )
Get the type of this currently opened controller
This is the same name as returned by SDL_GameControllerTypeForIndex( ... ), but it takes a controller identifier instead of the (unstable) device index.
Expected parameters include:
Returns the controller type.
SDL_GameControllerGetPlayerIndex( ... )
Get the player index of an opened game controller.
For XInput controllers this returns the XInput user index.
Expected parameters include:
Returns player index for controller, or -1 if it's not available.
SDL_GameControllerSetPlayerIndex( ... )
Set the player index of an opened game controller.
Expected parameters include:
gamecontroller- the game controller object to adjustplayer_index- player index to assign to this controller
SDL_GameControllerGetVendor( ... )
Get the USB vendor ID of an opened controller, if available.
If the vendor ID isn't available this function returns 0.
Expected parameters include:
Return USB vendor ID, or zero if unavailable.
SDL_GameControllerGetProduct( ... )
Get the USB product ID of an opened controller, if available.
If the product ID isn't available this function returns 0.
Expected parameters include:
Return USB product ID, or zero if unavailable.
SDL_GameControllerGetProductVersion( ... )
Get the product version of an opened controller, if available.
If the product version isn't available this function returns 0.
Expected parameters include:
Return USB product version, or zero if unavailable.
SDL_GameControllerGetSerial( ... )
Get the serial number of an opened controller, if available.
Returns the serial number of the controller, or undef if it is not available.
Expected parameters include:
Returns a serial number, or undef if unavailable.
SDL_GameControllerGetAttached( ... )
Check if a controller has been opened and is currently connected.
Expected parameters include:
gamecontroller- a game controller identifier previously returned bySDL_GameControllerOpen( ... )
Returns SDL_TRUE if the controller has been opened and is currently connected, or SDL_FALSE if not.
SDL_GameControllerGetJoystick( ... )
Get the Joystick ID from a Game Controller.
This function will give you a SDL2::Joystick object, which allows you to use the SDL2::Joystick functions with a SDL2::GameController 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 SDL2::GameController. You should not call SDL_JoystickClose( ... ) on it, for example, since doing so will likely cause SDL to crash.
Expected parameters include:
Returns a SDL2::Joystick object; call SDL_GetError( ) for more information.
SDL_GameControllerEventState( ... )
Query or change current state of Game Controller events.
If controller events are disabled, you must call SDL_GameControllerUpdate( ) yourself and check the state of the controller when you want controller information.
Any number can be passed to SDL_GameControllerEventState( ... ), but only -1, 0, and 1 will have any effect. Other numbers will just be returned.
Returns the same value passed to the function, with exception to -1 (SDL_QUERY), which will return the current state.
SDL_GameControllerUpdate( )
Manually pump game controller 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.
SDL_GameControllerGetAxisFromString( ... )
Convert a string into SDL_GameControllerAxis enum.
This function is called internally to translate SDL2::GameController mapping strings for the underlying joystick device into the consistent SDL2::GameController mapping. You do not normally need to call this function unless you are parsing SDL2::GameController mappings in your own code.
Expected parameters include:
str- string representing a SDL2::GameController axis
Returns the SDL_GameControllerAxis enum corresponding to the input string, or SDL_CONTROLLER_AXIS_INVALID if no match was found.
SDL_GameControllerGetStringForAxis( ... )
Convert from an SDL_GameControllerAxis enum to a string.
The caller should not SDL_free( ... ) the returned string.
Expected parameters include:
axis- an enum value for a givenSDL_GameControllerAxis
Returns a string for the given axis, or undef if an invalid axis is specified. The string returned is of the format used by SDL2::GameController mapping strings.
SDL_GameControllerGetBindForAxis( ... )
Get the SDL joystick layer binding for a controller axis mapping.
Expected parameters include:
gamecontroller- a game controlleraxis- an axis enum value (one of theSDL_GameControllerAxisvalues)
Returns a SDL2::GameControllerButtonBind describing the bind. On failure (like the given Controller axis doesn't exist on the device), its bindType will be SDL_CONTROLLER_BINDTYPE_NONE.
SDL_GameControllerHasAxis( ... )
Query whether a game controller has a given axis.
This merely reports whether the controller's mapping defined this axis, as that is all the information SDL has about the physical device.
Expected parameters include:
gamecontroller- a game controlleraxis- an axis enum value (anSDL_GameControllerAxisvalue)
Returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise.
SDL_GameControllerGetAxis( ... )
Get the current state of an axis control on a game controller.
The axis indices start at index 0.
The state is a value ranging from -32768 to 32767. Triggers, however, range from 0 to 32767 (they never return a negative value).
Expected parameters include:
gamecontroller- a game controlleraxis- an axis index (one of theSDL_GameControllerAxisvalues)
Returns axis state (including 0) on success or 0 (also) on failure; call SDL_GetError( ) for more information.
SDL_GameControllerGetButtonFromString( ... )
Convert a string into an SDL_GameControllerButton enum.
This function is called internally to translate SDL2::GameController mapping strings for the underlying joystick device into the consistent SDL2::GameController mapping. You do not normally need to call this function unless you are parsing SDL2::GameController mappings in your own code.
Expected parameters include:
str- string representing a SDL2::GameController axis
Returns the SDL_GameControllerButton enum corresponding to the input string, or SDL_CONTROLLER_AXIS_INVALID if no match was found.
SDL_GameControllerGetStringForButton( ... )
Convert from an SDL_GameControllerButton enum to a string.
The caller should not SDL_free( ) the returned string.
Expected parameters include:
Returns a string for the given button, or undef if an invalid axis is specified. The string returned is of the format used by SDL2::GameController mapping strings.
SDL_GameControllerGetBindForButton( ... )
Get the SDL joystick layer binding for a controller button mapping.
Expected parameters includes:
Returns a SDL_GameControllerButtonBind describing the bind. On failure (like the given Controller button doesn't exist on the device), its bindType will be SDL_CONTROLLER_BINDTYPE_NONE.
SDL_GameControllerHasButton( ... )
Query whether a game controller has a given button.
This merely reports whether the controller's mapping defined this button, as that is all the information SDL has about the physical device.
Expected parameters include:
Returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise.
SDL_GameControllerGetButton( ... )
Get the current state of a button on a game controller.
Expected parameters include:
Returns 1 for pressed state or 0 for not pressed state or error; call SDL_GetError( ) for more information.
SDL_GameControllerGetNumTouchpads( ... )
Get the number of touchpads on a game controller.
Expected parameters include:
Returns the number of touchpads.
SDL_GameControllerGetNumTouchpadFingers( ... )
Get the number of supported simultaneous fingers on a touchpad on a game controller.
Expected parameters include:
Returns the number of supported simultaneous fingers.
SDL_GameControllerGetTouchpadFinger( ... )
Get the current state of a finger on a touchpad on a game controller.
Expected parameters include:
gamecontroller- a game controllertouchpad- touchpad index to queryfinger- finger index to querystate- pointerx- pointery- pointerpressure- pointer
Returns 0 if the given finger is defined on the given touchpad on the given controller, -1 otherwise.
SDL_GameControllerHasSensor( ... )
Return whether a game controller has a particular sensor.
Expected parameters include:
Returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
SDL_GameControllerSetSensorEnabled( ... )
Set whether data reporting for a game controller sensor is enabled.
Expected parameters include:
gamecontroller- the controller to updatetype- the type of sensor to enable/disableenabled- whether data reporting should be enabled
Returns 0 or -1 if an error occurred.
SDL_GameControllerIsSensorEnabled( ... )
Query whether sensor data reporting is enabled for a game controller.
Expected parameters include:
Returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
SDL_GameControllerGetSensorData( ... )
Get the current state of a game controller sensor.
The number of values and interpretation of the data is sensor dependent. See SDL_sensor.h for the details for each type of sensor.
Expected parameters include;
gamecontroller- the controller to querytype- the type of sensor to querydata- a pointer filled with the current sensor statenum_values- the number of values to write to data
Return 0 or -1 if an error occurred.
SDL_GameControllerRumble( ... )
Start a rumble effect on a game controller.
Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
Expected parameters include:
gamecontroller- the controller to vibratelow_frequency_rumble- the intensity of the low frequency (left) rumble motor, from0to0xFFFFhigh_frequency_rumble- the intensity of the high frequency (right) rumble motor, from0to0xFFFFduration_ms- the duration of the rumble effect, in milliseconds
Returns 0, or -1 if rumble isn't supported on this controller
SDL_GameControllerRumbleTriggers( ... )
Start a rumble effect in the game controller'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 game controller as a whole. The first controller to offer this feature was the PlayStation 5's DualShock 5.
Expected parameters include:
gamecontroller- the controller to vibrateleft_rumble- the intensity of the left trigger rumble motor, from0to0xFFFFright_rumble- the intensity of the right trigger rumble motor, from0to0xFFFFduration_ms- the duration of the rumble effect, in milliseconds
Returns 0, or -1 if trigger rumble isn't supported on this controller.
SDL_GameControllerHasLED( ... )
Query whether a game controller has an LED.
Expected parameters include:
Returns SDL_TRUE, or SDL_FALSE if this controller does not have a modifiable LED.
SDL_GameControllerSetLED( ... )
Update a game controller's LED color.
Expected parameters include:
gamecontroller- the controller to updatered- the intensity of the red LEDgreen- the intensity of the green LEDblue- the intensity of the blue LED
Returns 0, or -1 if this controller does not have a modifiable LED
SDL_GameControllerClose( ... )
Close a game controller previously opened with SDL_GameControllerOpen( ... ).
Expected parameters include:
gamecontroller- a game controller identifier previously returned bySDL_GameControllerOpen( ... )
Defined Values and Enumerations
These may be imported by name or with the given tag.
SDL_GameControllerType
SDL_CONTROLLER_TYPE_UNKNOWNSDL_CONTROLLER_TYPE_XBOX360SDL_CONTROLLER_TYPE_XBOXONESDL_CONTROLLER_TYPE_PS3SDL_CONTROLLER_TYPE_PS4SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_PROSDL_CONTROLLER_TYPE_VIRTUALSDL_CONTROLLER_TYPE_PS5
SDL_GameControllerBindType
SDL_CONTROLLER_BINDTYPE_NONESDL_CONTROLLER_BINDTYPE_BUTTONSDL_CONTROLLER_BINDTYPE_AXISSDL_CONTROLLER_BINDTYPE_HAT
SDL_GameControllerAxis
The list of axes available from a controller
Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though advanced UI will allow users to set or autodetect the dead zone, which varies between controllers.
Trigger axis values range from 0 to SDL_JOYSTICK_AXIS_MAX.
SDL_CONTROLLER_AXIS_INVALIDSDL_CONTROLLER_AXIS_LEFTXSDL_CONTROLLER_AXIS_LEFTYSDL_CONTROLLER_AXIS_RIGHTXSDL_CONTROLLER_AXIS_RIGHTYSDL_CONTROLLER_AXIS_TRIGGERLEFTSDL_CONTROLLER_AXIS_TRIGGERRIGHTSDL_CONTROLLER_AXIS_MAX
SDL_GameControllerButton
The list of buttons available from a controller.
SDL_CONTROLLER_BUTTON_INVALIDSDL_CONTROLLER_BUTTON_ASDL_CONTROLLER_BUTTON_BSDL_CONTROLLER_BUTTON_XSDL_CONTROLLER_BUTTON_YSDL_CONTROLLER_BUTTON_BACKSDL_CONTROLLER_BUTTON_GUIDESDL_CONTROLLER_BUTTON_STARTSDL_CONTROLLER_BUTTON_LEFTSTICKSDL_CONTROLLER_BUTTON_RIGHTSTICKSDL_CONTROLLER_BUTTON_LEFTSHOULDERSDL_CONTROLLER_BUTTON_RIGHTSHOULDERSDL_CONTROLLER_BUTTON_DPAD_UPSDL_CONTROLLER_BUTTON_DPAD_DOWNSDL_CONTROLLER_BUTTON_DPAD_LEFTSDL_CONTROLLER_BUTTON_DPAD_RIGHTSDL_CONTROLLER_BUTTON_PADDLE1- Xbox Elite paddle P1SDL_CONTROLLER_BUTTON_PADDLE2- Xbox Elite paddle P3SDL_CONTROLLER_BUTTON_PADDLE3- Xbox Elite paddle P2SDL_CONTROLLER_BUTTON_PADDLE4- Xbox Elite paddle P4SDL_CONTROLLER_BUTTON_MAX
Notes
To count the number of game controllers in the system for the following:
my $nJoysticks = SDL_NumJoysticks();
my $nGameControllers = 0;
for my $i (0 .. $nJoysticks) {
$nGameControllers++ if SDL_IsGameController($i);
}Using the SDL_HINT_GAMECONTROLLERCONFIG hint or the SDL_GameControllerAddMapping( ... ) you can add support for controllers SDL is unaware of or cause an existing controller to have a different binding. The format is: guid,name,mappings,
Where GUID is the string value from SDL_JoystickGetGUIDString( ... ), name is the human readable string for the device and mappings are controller mappings to joystick ones. Under Windows there is a reserved GUID of "xinput" that covers any XInput devices. The mapping format for joystick is:
Buttons can be used as a controller axis and vice versa.
This string shows an example of a valid mapping for a controller
03000000341a00003608000000000000,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:b7LICENSE
Copyright (C) Sanko Robinson.
This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.
AUTHOR
Sanko Robinson <sanko@cpan.org>