The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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:

device_index - the index of the joystick to query (the N'th joystick on the system)

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:

device_index - the index of the joystick to query (the N'th joystick on the system

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:

device_index - the index of the joystick to query (the N'th joystick on the system

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:

device_index - the index of the joystick to query (the N'th joystick on the system

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:

device_index - the index of the joystick to query (the N'th joystick on the system

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:

device_index - the index of the joystick to query (the N'th joystick on the system

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:

device_index - the index of the joystick to query (the N'th joystick on the system

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:

device_index - the index of the joystick to query

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:

instance_id - the instance id to get the SDL_Joystick for

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:

type - SDL_JoystickType
naxes - number of axes
nbuttons - number of buttons
nhats - number of hats

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 from SDL_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:

device_index - a joystick device index

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 state
axis - the specific axis on the virtual joystick to set
value - 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:

joystick - the virtual joystick on which to set state
button - the specific button on the virtual joystick to set
value - the new value for the specified button

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 state
hat - the specific hat on the virtual joystick to set
value - 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 from SDL_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 from SDL_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 from SDL_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 from SDL_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 from SDL_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 from SDL_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 from SDL_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 from SDL_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 from SDL_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 - the SDL_JoystickGUID you wish to convert to string
pszGUID - buffer in which to write the ASCII string
cbGUID - 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:

pchGUID - string containing an ASCII representation of a GUID

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:

state - can be one of SDL_QUERY, SDL_IGNORE, or SDL_ENABLE

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 information
axis - the axis to query; the axis indices start at index 0

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 information
axis - the axis to query; the axis indices start at index 0
state - 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_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

Expected parameters include:

joystick - an SDL2::Joystick structure containing joystick information
hat - the hat index to get the state from; indices start at index 0

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 query
ball - the ball index to query; ball indices start at index 0
dx - stores the difference in the x axis position since the last poll
dy - 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
button - the button index to get the state from; indices start at index 0

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 vibrate
low_frequency_rumble - the intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
high_frequency_rumble - the intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
duration_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 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, 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:

joystick - the joystick to query

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 update
red - the intensity of the red LED
green - the intensity of the green LED
blue - 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:

joystick - the joystick device to close

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_UNKNOWN
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

SDL_JoystickPowerLevel

These values by me imported with the :joystickPowerLevel tag.

SDL_JOYSTICK_POWER_UNKNOWN
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.

Axis limits

These may be imported with the :joystick tag.

SDL_JOYSTICK_AXIS_MAX
SDL_JOYSTICK_AXIS_MIN

Hat Positions

These may be imported by name or with the :joystick tag.

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

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>