SDL2::joystick - SDL Joystick Event Handling
use SDL2 qw[:joystick];
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.
SDL_NumJoysticks( )
device_index
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.
instance_id
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.
player_index
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.
These functions may be imported with the :joystick tag or by name.
:joystick
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
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_GetError( )
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.
undef
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.
-1
my $p_id = SDL_JoystickGetDevicePlayerIndex( 1 );
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.
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.
0
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.
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.
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.
Returns the SDL_JoystickType of the selected joystick. If called on an invalid index, this function returns SDL_JOYSTICK_TYPE_UNKNOWN.
SDL_JoystickType
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.
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.
SDL_JoystickInstanceID( ... )
The joystick subsystem must be initialized before a joystick can be opened for use.
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.
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.
SDL_JoystickAttachVirtual( ... )
Attach a new virtual joystick.
type
naxes
nbuttons
nhats
Returns the joystick's device index, or -1 if an error occurred.
SDL_JoystickDetachVirtual( ... )
Detach a virtual joystick.
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.
Returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.
SDL_TRUE
SDL_FALSE
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.
SDL_PollEvent
SDL_PumpEvents
SDL_WaitEventTimeout
SDL_WaitEvent
joystick
axis
value
Returns 0 on success, -1 on error.
SDL_JoystickSetVirtualButton( ... )
Set values on an opened, virtual-joystick's button.
button
SDL_JoystickSetVirtualHat( ... )
Set values on an opened, virtual-joystick's hat.
SDL_JoystickUpdate
hat
SDL_JoystickName( ... )
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.
Returns the player index, or -1 if it's not available.
SDL_JoystickSetPlayerIndex( ... )
Set the player index of an opened joystick.
SDL_JoystickGetGUID( ... )
Get the implementation-dependent GUID for the joystick.
This function requires an open joystick.
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.
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.
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.
Returns the product version of the selected joystick, or 0 if unavailable.
SDL_JoystickGetSerial( ... )
Get the serial number of an opened joystick, if available.
Returns the serial number of the joystick, or undef if it is not available.
SDL_JoystickGetType( ... )
Get the type of an opened joystick.
Returns the SDL_JoystickType of the selected joystick.
SDL_JoystickGetGUIDString( ... )
Get an ASCII string representation for a given SDL_JoystickGUID.
SDL_JoystickGUID
You should supply at least 33 bytes for pszGUID.
guid
pszGUID
cbGUID
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.
pchGUID
Returns a SDL_JoystickGUID structure.
SDL_JoystickGetAttached( ... )
Get the status of a specified joystick.
Returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not; call SDL_GetError( ) for more information.
Get the instance ID of an opened joystick.
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.
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.
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.
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.
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.
state
SDL_QUERY
SDL_IGNORE
SDL_ENABLE
Returns 1 if enabled, 0 if disabled, or a negative error code on failure; call SDL_GetError( ) for more information.
1
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.
-32768
32767
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.
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_CENTERED
SDL_HAT_UP
SDL_HAT_RIGHT
SDL_HAT_DOWN
SDL_HAT_LEFT
SDL_HAT_RIGHTUP
SDL_HAT_RIGHTDOWN
SDL_HAT_LEFTUP
SDL_HAT_LEFTDOWN
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.
dx
dy
ball
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.
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.
low_frequency_rumble
0xFFFF
high_frequency_rumble
duration_ms
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.
left_rumble
right_rumble
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.
Return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
SDL_JoystickSetLED( ... )
Update a joystick's LED color.
red
green
blue
Returns 0 on success, -1 if this joystick does not have a modifiable LED.
SDL_JoystickClose( ... )
Close a joystick previously opened with CSDL_JoystickOpen( ... ).
SDL_JoystickCurrentPowerLevel( ... )
Get the battery level of a joystick as SDL_JoystickPowerLevel.
SDL_JoystickPowerLevel
Returns the current battery level as SDL_JoystickPowerLevel on success or SDL_JOYSTICK_POWER_UNKNOWN if it is unknown
SDL_JOYSTICK_POWER_UNKNOWN
You may import these values by name or, unless another tag is given, with the :joystick tag.
These values may be imported with the :joystickType tag.
:joystickType
SDL_JOYSTICK_TYPE_GAMECONTROLLER
SDL_JOYSTICK_TYPE_WHEEL
SDL_JOYSTICK_TYPE_ARCADE_STICK
SDL_JOYSTICK_TYPE_FLIGHT_STICK
SDL_JOYSTICK_TYPE_DANCE_PAD
SDL_JOYSTICK_TYPE_GUITAR
SDL_JOYSTICK_TYPE_DRUM_KIT
SDL_JOYSTICK_TYPE_ARCADE_PAD
SDL_JOYSTICK_TYPE_THROTTLE
These values by me imported with the :joystickPowerLevel tag.
:joystickPowerLevel
SDL_JOYSTICK_POWER_EMPTY
<= 5%
SDL_JOYSTICK_POWER_LOW
<= 20%
SDL_JOYSTICK_POWER_MEDIUM
<= 70%
SDL_JOYSTICK_POWER_FULL
<= 100%
SDL_JOYSTICK_POWER_WIRED
SDL_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.
src/joystick/uikit/SDL_sysjoystick.m
These may be imported with the :joystick tag.
SDL_JOYSTICK_AXIS_MAX
SDL_JOYSTICK_AXIS_MIN
These may be imported by name or with the :joystick tag.
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.
Sanko Robinson <sanko@cpan.org>
To install SDL2::FFI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SDL2::FFI
CPAN shell
perl -MCPAN -e shell install SDL2::FFI
For more information on module installation, please visit the detailed CPAN module installation guide.