NAME
SDL2::joystick - SDL Joystick Event Handling
SYNOPSIS
use SDL2 qw[:joystick];DESCRIPTION
The term "device_index" identifies currently plugged in joystick devices between 0 and SDL_NumJoysticks( ), with the exact joystick behind a device_index changing as joysticks are plugged and unplugged.
The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
The term "player_index" is the number assigned to a player on a specific controller. For XInput controllers this returns the XInput user index. Many joysticks will not be able to supply this information.
The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of the device (a X360 wired controller for example). This identifier is platform dependent.
Functions
These functions may be imported with the :joystick tag or by name.
SDL_LockJoysticks( )
Locking for multi-threaded access to the joystick API.
If you are using the joystick API or handling events from multiple threads you should use these locking functions to protect access to the joysticks.
In particular, you are guaranteed that the joystick list won't change, so the API functions that take a joystick index will be valid, and joystick and game controller events will not be delivered.
SDL_UnlockJoysticks( )
Unlocking for multi-threaded access to the joystick API
If you are using the joystick API or handling events from multiple threads you should use these locking functions to protect access to the joysticks.
In particular, you are guaranteed that the joystick list won't change, so the API functions that take a joystick index will be valid, and joystick and game controller events will not be delivered.
SDL_NumJoysticks( )
Count the number of joysticks attached to the system.
my $count = SDL_NumJoysticks( );Returns the number of attached joysticks on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_JoystickNameForIndex( ... )
Get the implementation dependent name of a joystick.
This can be called before any joysticks are opened.
Expected parameters include:
Returns the name of the selected joystick. If no name can be found, this function returns undef; call SDL_GetError( ) for more information.
SDL_JoystickGetDevicePlayerIndex( ... )
Get the player index of a joystick, or -1 if it's not available This can be called before any joysticks are opened.
my $p_id = SDL_JoystickGetDevicePlayerIndex( 1 );Expected parameters include:
device_index
Returns the player index or -1 on error; call SDL_GetError( ) for more information.
SDL_JoystickGetDeviceGUID( ... )
Get the implementation-dependent GUID for the joystick at a given device index.
This function can be called before any joysticks are opened.
Expected parameters include:
Returns the GUID of the selected joystick. If called on an invalid index, this function returns a zero GUID.
SDL_JoystickGetDeviceVendor( ... )
Get the USB vendor ID of a joystick, if available.
This can be called before any joysticks are opened. If the vendor ID isn't available this function returns 0.
Expected parameters include:
Returns the USB vendor ID of the selected joystick. If called on an invalid index, this function returns zero.
SDL_JoystickGetDeviceProduct( ... )
Get the USB product ID of a joystick, if available.
This can be called before any joysticks are opened. If the product ID isn't available this function returns 0.
Expected parameters include:
Returns the USB product ID of the selected joystick. If called on an invalid index, this function returns zero.
SDL_JoystickGetDeviceProductVersion( ... )
Get the product version of a joystick, if available.
This can be called before any joysticks are opened. If the product version isn't available this function returns 0.
Expected parameters include:
Returns the product version of the selected joystick. If called on an invalid index, this function returns zero.
SDL_JoystickGetDeviceType( ... )
Get the type of a joystick, if available.
This can be called before any joysticks are opened.
Expected parameters include:
Returns the SDL_JoystickType of the selected joystick. If called on an invalid index, this function returns SDL_JOYSTICK_TYPE_UNKNOWN.
SDL_JoystickGetDeviceInstanceID( ... )
Get the instance ID of a joystick.
This can be called before any joysticks are opened. If the index is out of range, this function will return -1.
Expected parameters include:
Returns the instance id of the selected joystick. If called on an invalid index, this function returns zero.
SDL_JoystickOpen( ... )
Open a joystick for use.
# Initialize the joystick subsystem
SDL_InitSubSystem( SDL_INIT_JOYSTICK );
# Check for joystick
if (SDL_NumJoysticks( ) > 0) {
# Open joystick
my $joy = SDL_JoystickOpen( 0 );
if (joy) {
printf( "Opened Joystick 0\n" );
printf( "Name: %s\n", SDL_JoystickNameForIndex( 0 ) );
printf( "Number of Axes: %d\n", SDL_JoystickNumAxes($joy) );
printf( "Number of Buttons: %d\n", SDL_JoystickNumButtons( $joy ) );
printf( "Number of Balls: %d\n", SDL_JoystickNumBalls( $joy ) );
}
else {
printf( "Couldn't open Joystick 0\n" );
}
# Close if opened
if ( SDL_JoystickGetAttached( $joy ) ) {
SDL_JoystickClose( $joy );
}
}The device_index argument refers to the N'th joystick presently recognized by SDL on the system. It is NOT the same as the instance ID used to identify the joystick in future events. See SDL_JoystickInstanceID( ... ) for more details about instance IDs.
The joystick subsystem must be initialized before a joystick can be opened for use.
Expected parameters include:
Returns a joystick identifier or undef if an error occurred; call SDL_GetError( ) for more information.
SDL_JoystickFromInstanceID( ... )
Get the SDL2::Joystick associated with an instance id.
Expected parameters include:
Returns an SDL2::Joystick on success or undef on failure; call SDL_GetError( ) for more information.
SDL_JoystickFromPlayerIndex( ... )
Get the SDL2::Joystick associated with a player index.
Expected parameters include:
player_index- the player index to get the SDL2::Joystick for
Returns an SDL2::Joystick on success or undef on failure; call SDL_GetError( ) for more information.
SDL_JoystickAttachVirtual( ... )
Attach a new virtual joystick.
Expected parameters include:
Returns the joystick's device index, or -1 if an error occurred.
SDL_JoystickDetachVirtual( ... )
Detach a virtual joystick.
Expected parameters include:
device_index- a value previously returned fromSDL_JoystickAttachVirtual( ... )
Returns 0 on success, or -1 if an error occurred.
SDL_JoystickIsVirtual( ... )
Query whether or not the joystick at a given device index is virtual.
Expected parameters include:
Returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.
SDL_JoystickSetVirtualAxis( ... )
Set values on an opened, virtual-joystick's axis.
Please note that values set here will not be applied until the next call to SDL_JoystickUpdate, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
Expected parameters include:
joystick- the virtual joystick on which to set stateaxis- the specific axis on the virtual joystick to setvalue- the new value for the specified axis
Returns 0 on success, -1 on error.
SDL_JoystickSetVirtualButton( ... )
Set values on an opened, virtual-joystick's button.
Please note that values set here will not be applied until the next call to SDL_JoystickUpdate, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
Expected parameters include:
Returns 0 on success, -1 on error.
SDL_JoystickSetVirtualHat( ... )
Set values on an opened, virtual-joystick's hat.
Please note that values set here will not be applied until the next call to SDL_JoystickUpdate, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, SDL_WaitEvent.
Expected parameters include:
joystick- the virtual joystick on which to set statehat- the specific hat on the virtual joystick to setvalue- the new value for the specified hat
Returns 0 on success, -1 on error.
SDL_JoystickName( ... )
Get the implementation dependent name of a joystick.
Expected parameters include:
joystick- the SDL2::Joystick obtained fromSDL_JoystickOpen( ... )
Returns the name of the selected joystick. If no name can be found, this function returns undef; call SDL_GetError( ) for more information.
SDL_JoystickGetPlayerIndex( ... )
Get the player index of an opened joystick.
For XInput controllers this returns the XInput user index. Many joysticks will not be able to supply this information.
Expected parameters include:
joystick- the SDL2::Joystick obtained fromSDL_JoystickOpen( ... )
Returns the player index, or -1 if it's not available.
SDL_JoystickSetPlayerIndex( ... )
Set the player index of an opened joystick.
Expected parameters include:
joystick- the SDL2::Joystick obtained fromSDL_JoystickOpen( ... )player_index- the player index to set
SDL_JoystickGetGUID( ... )
Get the implementation-dependent GUID for the joystick.
This function requires an open joystick.
Expected parameters include:
joystick- the SDL2::Joystick obtained fromSDL_JoystickOpen( ... )
Returns the GUID of the given joystick. If called on an invalid index, this function returns a zero GUID; call SDL_GetError( ) for more information.
SDL_JoystickGetVendor( ... )
Get the USB vendor ID of an opened joystick, if available.
If the vendor ID isn't available this function returns 0.
Expected parameters include:
joystick- the SDL2::Joystick obtained fromSDL_JoystickOpen( ... )
Returns the USB vendor ID of the selected joystick, or 0 if unavailable.
SDL_JoystickGetProduct( ... )
Get the USB product ID of an opened joystick, if available.
If the product ID isn't available this function returns 0.
Expected parameters include:
joystick- the SDL2::Joystick obtained fromSDL_JoystickOpen( ... )
Returns the USB product ID of the selected joystick, or 0 if unavailable.
SDL_JoystickGetProductVersion( ... )
Get the product version of an opened joystick, if available. If the product version isn't available this function returns 0.
Expected parameters include:
joystick- the SDL2::Joystick obtained fromSDL_JoystickOpen( ... )
Returns the product version of the selected joystick, or 0 if unavailable.
SDL_JoystickGetSerial( ... )
Get the serial number of an opened joystick, if available.
joystick- the SDL2::Joystick obtained fromSDL_JoystickOpen( ... )
Returns the serial number of the joystick, or undef if it is not available.
SDL_JoystickGetType( ... )
Get the type of an opened joystick.
Expected parameters include:
joystick- the SDL2::Joystick obtained fromSDL_JoystickOpen( ... )
Returns the SDL_JoystickType of the selected joystick.
SDL_JoystickGetGUIDString( ... )
Get an ASCII string representation for a given SDL_JoystickGUID.
You should supply at least 33 bytes for pszGUID.
Expected parameters include:
guid- theSDL_JoystickGUIDyou wish to convert to stringpszGUID- buffer in which to write the ASCII stringcbGUID- the size of pszGUID
SDL_JoystickGetGUIDFromString( ... )
Convert a GUID string into a SDL_JoystickGUID structure.
Performs no error checking. If this function is given a string containing an invalid GUID, the function will silently succeed, but the GUID generated will not be useful.
Expected parameters include:
Returns a SDL_JoystickGUID structure.
SDL_JoystickGetAttached( ... )
Get the status of a specified joystick.
Expected parameters include:
joystick- the joystick to query
Returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not; call SDL_GetError( ) for more information.
SDL_JoystickInstanceID( ... )
Get the instance ID of an opened joystick.
Expected parameters include:
joystick- an SDL2::Joystick structure containing joystick information
Returns the instance ID of the specified joystick on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_JoystickNumAxes( ... )
Get the number of general axis controls on a joystick.
Often, the directional pad on a game controller will either look like 4 separate buttons or a POV hat, and not axes, but all of this is up to the device and platform.
Expected parameters include:
joystick- an SDL2::Joystick structure containing joystick information
Returns the number of axis controls/number of axes on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_JoystickNumBalls( ... )
Get the number of trackballs on a joystick.
Joystick trackballs have only relative motion events associated with them and their state cannot be polled.
Most joysticks do not have trackballs.
Expected parameters include:
joystick- an SDL2::Joystick structure containing joystick information
Returns the number of trackballs on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_JoystickNumHats( ... )
Get the number of POV hats on a joystick.
Expected parameters include:
joystick- an SDL2::Joystick structure containing joystick information
Returns the number of POV hats on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_JoystickNumButtons( ... )
Get the number of buttons on a joystick.
Expected parameters include:
joystick- an SDL2::Joystick structure containing joystick information
Returns the number of buttons on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_JoystickUpdate( )
Update the current state of the open joysticks.
This is called automatically by the event loop if any joystick events are enabled.
SDL_JoystickEventState( ... )
Enable/disable joystick event polling.
If joystick events are disabled, you must call SDL_JoystickUpdate( ) yourself and manually check the state of the joystick when you want joystick information.
It is recommended that you leave joystick event handling enabled.
WARNING: Calling this function may delete all events currently in SDL's event queue.
Expected parameters include:
Returns 1 if enabled, 0 if disabled, or a negative error code on failure; call SDL_GetError( ) for more information.
If state is SDL_QUERY then the current state is returned, otherwise the new processing state is returned.
SDL_JoystickGetAxis( ... )
Get the current state of an axis control on a joystick.
SDL makes no promises about what part of the joystick any given axis refers to. Your game should have some sort of configuration UI to let users specify what each axis should be bound to. Alternately, SDL's higher-level Game Controller API makes a great effort to apply order to this lower-level interface, so you know that a specific axis is the "left thumb stick," etc.
The value returned by SDL_JoystickGetAxis( ... ) is a signed integer (-32768 to 32767) representing the current position of the axis. It may be necessary to impose certain tolerances on these values to account for jitter.
Expected parameters include:
joystick- an SDL2::Joystick structure containing joystick informationaxis- the axis to query; the axis indices start at index0
Returns a 16-bit signed integer representing the current position of the axis or 0 on failure; call SDL_GetError( ) for more information.
SDL_JoystickGetAxisInitialState( ... )
Get the initial state of an axis control on a joystick.
The state is a value ranging from -32768 to 32767.
The axis indices start at index 0.
Expected parameters include:
joystick- an SDL2::Joystick structure containing joystick informationaxis- the axis to query; the axis indices start at index0state- upon return, the initial value is supplied here
Return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
SDL_JoystickGetHat
Get the current state of a POV hat on a joystick.
The returned value will be one of the following positions:
SDL_HAT_CENTEREDSDL_HAT_UPSDL_HAT_RIGHTSDL_HAT_DOWNSDL_HAT_LEFTSDL_HAT_RIGHTUPSDL_HAT_RIGHTDOWNSDL_HAT_LEFTUPSDL_HAT_LEFTDOWN
Expected parameters include:
joystick- an SDL2::Joystick structure containing joystick informationhat- the hat index to get the state from; indices start at index0
Returns the current hat position.
SDL_JoystickGetBall( ... )
Get the ball axis change since the last poll.
Trackballs can only return relative motion since the last call to SDL_JoystickGetBall( ... ), these motion deltas are placed into dx and dy.
Most joysticks do not have trackballs.
Expected parameters include:
joystick- the SDL2::Joystick to queryball- the ball index to query; ball indices start at index0dx- stores the difference in the x axis position since the last polldy- stores the difference in the y axis position since the last poll
Returns 0 on success or a negative error code on failure; call SDL_GetError( ) for more information.
SDL_JoystickGetButton( ... )
Get the current state of a button on a joystick.
Expected parameters include:
joystick- an SDL2::Joystick structure containing joystick information
Returns 1 if the specified button is pressed, 0 otherwise.
SDL_JoystickRumble( ... )
Start a rumble effect.
Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
Expected parameters include:
joystick- the joystick 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 joystick.
SDL_JoystickRumbleTriggers( ... )
Start a rumble effect in the joystick'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 function is for _trigger_ rumble; the first joystick to support this was the PlayStation 5's DualShock 5 controller. If you want the (more common) whole-controller rumble, use SDL_JoystickRumble() instead.
Expected parameters include:
joystick- the joystick 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 joystick.
SDL_JoystickHasLED( ... )
Query whether a joystick has an LED.
An example of a joystick LED is the light on the back of a PlayStation 4's DualShock 4 controller.
Expected parameters include:
Return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
SDL_JoystickSetLED( ... )
Update a joystick's LED color.
An example of a joystick LED is the light on the back of a PlayStation 4's DualShock 4 controller.
Expected parameters include:
joystick- the joystick to updatered- the intensity of the red LEDgreen- the intensity of the green LEDblue- the intensity of the blue LED
Returns 0 on success, -1 if this joystick does not have a modifiable LED.
SDL_JoystickClose( ... )
Close a joystick previously opened with CSDL_JoystickOpen( ... ).
Expected parameters include:
SDL_JoystickCurrentPowerLevel( ... )
Get the battery level of a joystick as SDL_JoystickPowerLevel.
Expected parameters include:
joystick- the SDL2::Joystick to query
Returns the current battery level as SDL_JoystickPowerLevel on success or SDL_JOYSTICK_POWER_UNKNOWN if it is unknown
Defined Values and Enumerations
You may import these values by name or, unless another tag is given, with the :joystick tag.
SDL_JoystickType
These values may be imported with the :joystickType tag.
SDL_JOYSTICK_TYPE_UNKNOWNSDL_JOYSTICK_TYPE_GAMECONTROLLERSDL_JOYSTICK_TYPE_WHEELSDL_JOYSTICK_TYPE_ARCADE_STICKSDL_JOYSTICK_TYPE_FLIGHT_STICKSDL_JOYSTICK_TYPE_DANCE_PADSDL_JOYSTICK_TYPE_GUITARSDL_JOYSTICK_TYPE_DRUM_KITSDL_JOYSTICK_TYPE_ARCADE_PADSDL_JOYSTICK_TYPE_THROTTLE
SDL_JoystickPowerLevel
These values by me imported with the :joystickPowerLevel tag.
SDL_JOYSTICK_POWER_UNKNOWNSDL_JOYSTICK_POWER_EMPTY-<= 5%SDL_JOYSTICK_POWER_LOW-<= 20%SDL_JOYSTICK_POWER_MEDIUM-<= 70%SDL_JOYSTICK_POWER_FULL-<= 100%SDL_JOYSTICK_POWER_WIREDSDL_JOYSTICK_POWER_MAX
SDL_IPHONE_MAX_GFORCE
Set max recognized G-force from accelerometer. See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed.
Axis limits
These may be imported with the :joystick tag.
SDL_JOYSTICK_AXIS_MAXSDL_JOYSTICK_AXIS_MIN
Hat Positions
These may be imported by name or with the :joystick tag.
SDL_HAT_CENTEREDSDL_HAT_UPSDL_HAT_RIGHTSDL_HAT_DOWNSDL_HAT_LEFTSDL_HAT_RIGHTUPSDL_HAT_RIGHTDOWNSDL_HAT_LEFTUPSDL_HAT_LEFTDOWN
LICENSE
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>