SDL_joystick.h File Reference
`#include "SDL_stdinc.h"`
`#include "SDL_error.h"`
`#include "SDL_guid.h"`
`#include "SDL_mutex.h"`
`#include "begin_code.h"`
`#include "close_code.h"`
Include dependency graph for SDL_joystick.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures

struct | SDL_VirtualJoystickDesc

## Macros

#define | SDL_IPHONE_MAX_GFORCE 5.0
#define | SDL_VIRTUAL_JOYSTICK_DESC_VERSION 1
#define | SDL_JOYSTICK_AXIS_MAX 32767
#define | SDL_JOYSTICK_AXIS_MIN -32768

## Typedefs

typedef struct _SDL_Joystick | SDL_Joystick
typedef SDL_GUID | SDL_JoystickGUID
typedef Sint32 | SDL_JoystickID

## Enumerations

enum | SDL_JoystickType { 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 }
enum | SDL_JoystickPowerLevel { SDL_JOYSTICK_POWER_UNKNOWN = -1 , SDL_JOYSTICK_POWER_EMPTY , SDL_JOYSTICK_POWER_LOW , SDL_JOYSTICK_POWER_MEDIUM , SDL_JOYSTICK_POWER_FULL , SDL_JOYSTICK_POWER_WIRED , SDL_JOYSTICK_POWER_MAX }

## Functions

void | SDL_LockJoysticks (void) SDL_ACQUIRE(SDL_joystick_lock)
void | SDL_UnlockJoysticks (void) SDL_RELEASE(SDL_joystick_lock)
int | SDL_NumJoysticks (void)
const char * | SDL_JoystickNameForIndex (int device_index)
const char * | SDL_JoystickPathForIndex (int device_index)
int | SDL_JoystickGetDevicePlayerIndex (int device_index)
SDL_JoystickGUID | SDL_JoystickGetDeviceGUID (int device_index)
Uint16 | SDL_JoystickGetDeviceVendor (int device_index)
Uint16 | SDL_JoystickGetDeviceProduct (int device_index)
Uint16 | SDL_JoystickGetDeviceProductVersion (int device_index)
SDL_JoystickType | SDL_JoystickGetDeviceType (int device_index)
SDL_JoystickID | SDL_JoystickGetDeviceInstanceID (int device_index)
SDL_Joystick * | SDL_JoystickOpen (int device_index)
SDL_Joystick * | SDL_JoystickFromInstanceID (SDL_JoystickID instance_id)
SDL_Joystick * | SDL_JoystickFromPlayerIndex (int player_index)
int | SDL_JoystickAttachVirtual (SDL_JoystickType type, int naxes, int nbuttons, int nhats)
int | SDL_JoystickAttachVirtualEx (const SDL_VirtualJoystickDesc *desc)
int | SDL_JoystickDetachVirtual (int device_index)
SDL_bool | SDL_JoystickIsVirtual (int device_index)
int | SDL_JoystickSetVirtualAxis (SDL_Joystick *joystick, int axis, Sint16 value)
int | SDL_JoystickSetVirtualButton (SDL_Joystick *joystick, int button, Uint8 value)
int | SDL_JoystickSetVirtualHat (SDL_Joystick *joystick, int hat, Uint8 value)
const char * | SDL_JoystickName (SDL_Joystick *joystick)
const char * | SDL_JoystickPath (SDL_Joystick *joystick)
int | SDL_JoystickGetPlayerIndex (SDL_Joystick *joystick)
void | SDL_JoystickSetPlayerIndex (SDL_Joystick *joystick, int player_index)
SDL_JoystickGUID | SDL_JoystickGetGUID (SDL_Joystick *joystick)
Uint16 | SDL_JoystickGetVendor (SDL_Joystick *joystick)
Uint16 | SDL_JoystickGetProduct (SDL_Joystick *joystick)
Uint16 | SDL_JoystickGetProductVersion (SDL_Joystick *joystick)
Uint16 | SDL_JoystickGetFirmwareVersion (SDL_Joystick *joystick)
const char * | SDL_JoystickGetSerial (SDL_Joystick *joystick)
SDL_JoystickType | SDL_JoystickGetType (SDL_Joystick *joystick)
void | SDL_JoystickGetGUIDString (SDL_JoystickGUID guid, char *pszGUID, int cbGUID)
SDL_JoystickGUID | SDL_JoystickGetGUIDFromString (const char *pchGUID)
void | SDL_GetJoystickGUIDInfo (SDL_JoystickGUID guid, Uint16 *vendor, Uint16 *product, Uint16 *version, Uint16 *crc16)
SDL_bool | SDL_JoystickGetAttached (SDL_Joystick *joystick)
SDL_JoystickID | SDL_JoystickInstanceID (SDL_Joystick *joystick)
int | SDL_JoystickNumAxes (SDL_Joystick *joystick)
int | SDL_JoystickNumBalls (SDL_Joystick *joystick)
int | SDL_JoystickNumHats (SDL_Joystick *joystick)
int | SDL_JoystickNumButtons (SDL_Joystick *joystick)
void | SDL_JoystickUpdate (void)
int | SDL_JoystickEventState (int state)
Sint16 | SDL_JoystickGetAxis (SDL_Joystick *joystick, int axis)
SDL_bool | SDL_JoystickGetAxisInitialState (SDL_Joystick *joystick, int axis, Sint16 *state)

## Hat positions

#define | SDL_HAT_CENTERED 0x00
#define | SDL_HAT_UP 0x01
#define | SDL_HAT_RIGHT 0x02
#define | SDL_HAT_DOWN 0x04
#define | SDL_HAT_LEFT 0x08
#define | SDL_HAT_RIGHTUP (SDL_HAT_RIGHT|SDL_HAT_UP)
#define | SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN)
#define | SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP)
#define | SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN)
Uint8 | SDL_JoystickGetHat (SDL_Joystick *joystick, int hat)
int | SDL_JoystickGetBall (SDL_Joystick *joystick, int ball, int *dx, int *dy)
Uint8 | SDL_JoystickGetButton (SDL_Joystick *joystick, int button)
int | SDL_JoystickRumble (SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms)
int | SDL_JoystickRumbleTriggers (SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms)
SDL_bool | SDL_JoystickHasLED (SDL_Joystick *joystick)
SDL_bool | SDL_JoystickHasRumble (SDL_Joystick *joystick)
SDL_bool | SDL_JoystickHasRumbleTriggers (SDL_Joystick *joystick)
int | SDL_JoystickSetLED (SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue)
int | SDL_JoystickSendEffect (SDL_Joystick *joystick, const void *data, int size)
void | SDL_JoystickClose (SDL_Joystick *joystick)
SDL_JoystickPowerLevel | SDL_JoystickCurrentPowerLevel (SDL_Joystick *joystick)

## Detailed Description

# CategoryJoystick

Include file for SDL joystick event handling

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.

In order to use these functions, SDL_Init() must have been called with the SDL_INIT_JOYSTICK flag. This causes SDL to scan the system for joysticks, and load appropriate drivers.

If you would like to receive joystick 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_joystick.h.

## Macro Definition Documentation

## SDL_HAT_CENTERED

#define SDL_HAT_CENTERED 0x00

Definition at line 873 of file SDL_joystick.h.

## SDL_HAT_DOWN

#define SDL_HAT_DOWN 0x04

Definition at line 876 of file SDL_joystick.h.

## SDL_HAT_LEFT

#define SDL_HAT_LEFT 0x08

Definition at line 877 of file SDL_joystick.h.

## SDL_HAT_LEFTDOWN

#define SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN)

Definition at line 881 of file SDL_joystick.h.

## SDL_HAT_LEFTUP

#define SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP)

Definition at line 880 of file SDL_joystick.h.

## SDL_HAT_RIGHT

#define SDL_HAT_RIGHT 0x02

Definition at line 875 of file SDL_joystick.h.

## SDL_HAT_RIGHTDOWN

#define SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN)

Definition at line 879 of file SDL_joystick.h.

## SDL_HAT_RIGHTUP

#define SDL_HAT_RIGHTUP (SDL_HAT_RIGHT|SDL_HAT_UP)

Definition at line 878 of file SDL_joystick.h.

## SDL_HAT_UP

#define SDL_HAT_UP 0x01

Definition at line 874 of file SDL_joystick.h.

## SDL_IPHONE_MAX_GFORCE

#define SDL_IPHONE_MAX_GFORCE 5.0

Definition at line 126 of file SDL_joystick.h.

## SDL_JOYSTICK_AXIS_MAX

#define SDL_JOYSTICK_AXIS_MAX 32767

Definition at line 824 of file SDL_joystick.h.

## SDL_JOYSTICK_AXIS_MIN

#define SDL_JOYSTICK_AXIS_MIN -32768

Definition at line 825 of file SDL_joystick.h.

## SDL_VIRTUAL_JOYSTICK_DESC_VERSION

#define SDL_VIRTUAL_JOYSTICK_DESC_VERSION 1

The current version of the SDL_VirtualJoystickDesc structure

Definition at line 407 of file SDL_joystick.h.

## Typedef Documentation

## SDL_Joystick

typedef struct _SDL_Joystick SDL_Joystick

Definition at line 78 of file SDL_joystick.h.

## SDL_JoystickGUID

typedef SDL_GUID SDL_JoystickGUID

A structure that encodes the stable unique id for a joystick device.

This is just a standard SDL_GUID by a different name.

Definition at line 85 of file SDL_joystick.h.

## SDL_JoystickID

typedef Sint32 SDL_JoystickID

This is a unique ID for a joystick for the time it is connected to the system, and is never reused for the lifetime of the application.

If the joystick is disconnected and reconnected, it will get a new ID.

The ID value starts at 0 and increments from there. The value -1 is an invalid ID.

Definition at line 96 of file SDL_joystick.h.

## Enumeration Type Documentation

## SDL_JoystickPowerLevel

enum SDL_JoystickPowerLevel

Enumerator
SDL_JOYSTICK_POWER_UNKNOWN |
SDL_JOYSTICK_POWER_EMPTY |
SDL_JOYSTICK_POWER_LOW |
SDL_JOYSTICK_POWER_MEDIUM |
SDL_JOYSTICK_POWER_FULL |
SDL_JOYSTICK_POWER_WIRED |
SDL_JOYSTICK_POWER_MAX |

Definition at line 112 of file SDL_joystick.h.

{
SDL_JOYSTICK_POWER_UNKNOWN = -1,
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_JoystickPowerLevel;
SDL_JoystickPowerLevel
SDL_JoystickPowerLevel
Definition SDL_joystick.h:113
SDL_JOYSTICK_POWER_MAX
@ SDL_JOYSTICK_POWER_MAX
Definition SDL_joystick.h:120
SDL_JOYSTICK_POWER_FULL
@ SDL_JOYSTICK_POWER_FULL
Definition SDL_joystick.h:118
SDL_JOYSTICK_POWER_MEDIUM
@ SDL_JOYSTICK_POWER_MEDIUM
Definition SDL_joystick.h:117
SDL_JOYSTICK_POWER_EMPTY
@ SDL_JOYSTICK_POWER_EMPTY
Definition SDL_joystick.h:115
SDL_JOYSTICK_POWER_UNKNOWN
@ SDL_JOYSTICK_POWER_UNKNOWN
Definition SDL_joystick.h:114
SDL_JOYSTICK_POWER_WIRED
@ SDL_JOYSTICK_POWER_WIRED
Definition SDL_joystick.h:119
SDL_JOYSTICK_POWER_LOW
@ SDL_JOYSTICK_POWER_LOW
Definition SDL_joystick.h:116

## SDL_JoystickType

enum SDL_JoystickType

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

Definition at line 98 of file SDL_joystick.h.

{
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_JoystickType;
SDL_JoystickType
SDL_JoystickType
Definition SDL_joystick.h:99
SDL_JOYSTICK_TYPE_DANCE_PAD
@ SDL_JOYSTICK_TYPE_DANCE_PAD
Definition SDL_joystick.h:105
SDL_JOYSTICK_TYPE_ARCADE_PAD
@ SDL_JOYSTICK_TYPE_ARCADE_PAD
Definition SDL_joystick.h:108
SDL_JOYSTICK_TYPE_UNKNOWN
@ SDL_JOYSTICK_TYPE_UNKNOWN
Definition SDL_joystick.h:100
SDL_JOYSTICK_TYPE_ARCADE_STICK
@ SDL_JOYSTICK_TYPE_ARCADE_STICK
Definition SDL_joystick.h:103
SDL_JOYSTICK_TYPE_WHEEL
@ SDL_JOYSTICK_TYPE_WHEEL
Definition SDL_joystick.h:102
SDL_JOYSTICK_TYPE_THROTTLE
@ SDL_JOYSTICK_TYPE_THROTTLE
Definition SDL_joystick.h:109
SDL_JOYSTICK_TYPE_GUITAR
@ SDL_JOYSTICK_TYPE_GUITAR
Definition SDL_joystick.h:106
SDL_JOYSTICK_TYPE_FLIGHT_STICK
@ SDL_JOYSTICK_TYPE_FLIGHT_STICK
Definition SDL_joystick.h:104
SDL_JOYSTICK_TYPE_GAMECONTROLLER
@ SDL_JOYSTICK_TYPE_GAMECONTROLLER
Definition SDL_joystick.h:101
SDL_JOYSTICK_TYPE_DRUM_KIT
@ SDL_JOYSTICK_TYPE_DRUM_KIT
Definition SDL_joystick.h:107

## Function Documentation

## SDL_GetJoystickGUIDInfo()

void SDL_GetJoystickGUIDInfo | ( | SDL_JoystickGUID | guid,
|  | Uint16 * | vendor,
|  | Uint16 * | product,
|  | Uint16 * | version,
|  | Uint16 * | crc16 )

extern

Get the device information encoded in a SDL_JoystickGUID structure

Parameters

  guid | the SDL_JoystickGUID you wish to get info about.
  vendor | A pointer filled in with the device VID, or 0 if not available.
  product | A pointer filled in with the device PID, or 0 if not available.
  version | A pointer filled in with the device version, or 0 if not available.
  crc16 | A pointer filled in with a CRC used to distinguish different products with the same VID/PID, or 0 if not available.

Since
  This function is available since SDL 2.26.0.

See also
  SDL_JoystickGetDeviceGUID

## SDL_JoystickAttachVirtual()

int SDL_JoystickAttachVirtual | ( | SDL_JoystickType | type,
|  | int | naxes,
|  | int | nbuttons,
|  | int | nhats )

extern

Attach a new virtual joystick.

Returns
  the joystick's device index, or -1 if an error occurred.

Since
  This function is available since SDL 2.0.14.

## SDL_JoystickAttachVirtualEx()

int SDL_JoystickAttachVirtualEx | ( | const SDL_VirtualJoystickDesc * | desc | ) |

extern

Attach a new virtual joystick with extended properties.

Returns
  the joystick's device index, or -1 if an error occurred.

Since
  This function is available since SDL 2.24.0.

## SDL_JoystickClose()

void SDL_JoystickClose | ( | SDL_Joystick * | joystick | ) |

extern

Close a joystick previously opened with SDL_JoystickOpen().

Parameters

  joystick | The joystick device to close.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickOpen

## SDL_JoystickCurrentPowerLevel()

SDL_JoystickPowerLevel SDL_JoystickCurrentPowerLevel | ( | SDL_Joystick * | joystick | ) |

extern

Get the battery level of a joystick as SDL_JoystickPowerLevel.

Parameters

  joystick | the SDL_Joystick to query.

Returns
  the current battery level as SDL_JoystickPowerLevel on success or SDL_JOYSTICK_POWER_UNKNOWN if it is unknown.

Since
  This function is available since SDL 2.0.4.

## SDL_JoystickDetachVirtual()

int SDL_JoystickDetachVirtual | ( | int | device_index | ) |

extern

Detach a virtual joystick.

Parameters

  device_index | a value previously returned from SDL_JoystickAttachVirtual().

Returns
  0 on success, or -1 if an error occurred.

Since
  This function is available since SDL 2.0.14.

## SDL_JoystickEventState()

int SDL_JoystickEventState | ( | int | state | ) |

extern

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.

While param is meant to be one of SDL_QUERY, SDL_IGNORE, or SDL_ENABLE, this function accepts any value, with any non-zero value that isn't SDL_QUERY being treated as SDL_ENABLE.

If SDL was built with events disabled (extremely uncommon!), this will do nothing and always return SDL_IGNORE.

Parameters

  state | can be one of SDL_QUERY, SDL_IGNORE, or SDL_ENABLE.

Returns
  If state is SDL_QUERY then the current state is returned, otherwise state is returned (even if it was not one of the allowed values).

Since
  This function is available since SDL 2.0.0.

See also
  SDL_GameControllerEventState

## SDL_JoystickFromInstanceID()

SDL_Joystick * SDL_JoystickFromInstanceID | ( | SDL_JoystickID | instance_id | ) |

extern

Get the SDL_Joystick associated with an instance id.

Parameters

  instance_id | the instance id to get the SDL_Joystick for.

Returns
  an SDL_Joystick on success or NULL on failure; call SDL_GetError() for more information.

Since
  This function is available since SDL 2.0.4.

## SDL_JoystickFromPlayerIndex()

SDL_Joystick * SDL_JoystickFromPlayerIndex | ( | int | player_index | ) |

extern

Get the SDL_Joystick associated with a player index.

Parameters

  player_index | the player index to get the SDL_Joystick for.

Returns
  an SDL_Joystick on success or NULL on failure; call SDL_GetError() for more information.

Since
  This function is available since SDL 2.0.12.

## SDL_JoystickGetAttached()

SDL_bool SDL_JoystickGetAttached | ( | SDL_Joystick * | joystick | ) |

extern

Get the status of a specified joystick.

Parameters

  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.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickClose
  SDL_JoystickOpen

## SDL_JoystickGetAxis()

Sint16 SDL_JoystickGetAxis | ( | SDL_Joystick * | joystick,
|  | int | axis )

extern

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.

Parameters

  joystick | an SDL_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.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickNumAxes

## SDL_JoystickGetAxisInitialState()

SDL_bool SDL_JoystickGetAxisInitialState | ( | SDL_Joystick * | joystick,
|  | int | axis,
|  | Sint16 * | state )

extern

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.

Parameters

  joystick | an SDL_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.

Returns
  SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.

Since
  This function is available since SDL 2.0.6.

## SDL_JoystickGetBall()

int SDL_JoystickGetBall | ( | SDL_Joystick * | joystick,
|  | int | ball,
|  | int * | dx,
|  | int * | dy )

extern

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.

Parameters

  joystick | the SDL_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.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickNumBalls

## SDL_JoystickGetButton()

Uint8 SDL_JoystickGetButton | ( | SDL_Joystick * | joystick,
|  | int | button )

extern

Get the current state of a button on a joystick.

Parameters

  joystick | an SDL_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.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickNumButtons

## SDL_JoystickGetDeviceGUID()

SDL_JoystickGUID SDL_JoystickGetDeviceGUID | ( | int | device_index | ) |

extern

Get the implementation-dependent GUID for the joystick at a given device index.

This function can be called before any joysticks are opened.

Parameters

  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.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickGetGUID
  SDL_JoystickGetGUIDString

## SDL_JoystickGetDeviceInstanceID()

SDL_JoystickID SDL_JoystickGetDeviceInstanceID | ( | int | device_index | ) |

extern

Get the instance ID of a joystick.

This can be called before any joysticks are opened.

Parameters

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

Since
  This function is available since SDL 2.0.6.

## SDL_JoystickGetDevicePlayerIndex()

int SDL_JoystickGetDevicePlayerIndex | ( | int | device_index | ) |

extern

Get the player index of a joystick, or -1 if it's not available This can be called before any joysticks are opened.

Since
  This function is available since SDL 2.0.9.

## SDL_JoystickGetDeviceProduct()

Uint16 SDL_JoystickGetDeviceProduct | ( | int | device_index | ) |

extern

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.

Parameters

  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.

Since
  This function is available since SDL 2.0.6.

## SDL_JoystickGetDeviceProductVersion()

Uint16 SDL_JoystickGetDeviceProductVersion | ( | int | device_index | ) |

extern

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.

Parameters

  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.

Since
  This function is available since SDL 2.0.6.

## SDL_JoystickGetDeviceType()

SDL_JoystickType SDL_JoystickGetDeviceType | ( | int | device_index | ) |

extern

Get the type of a joystick, if available.

This can be called before any joysticks are opened.

Parameters

  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.

Since
  This function is available since SDL 2.0.6.

## SDL_JoystickGetDeviceVendor()

Uint16 SDL_JoystickGetDeviceVendor | ( | int | device_index | ) |

extern

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.

Parameters

  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.

Since
  This function is available since SDL 2.0.6.

## SDL_JoystickGetFirmwareVersion()

Uint16 SDL_JoystickGetFirmwareVersion | ( | SDL_Joystick * | joystick | ) |

extern

Get the firmware version of an opened joystick, if available.

If the firmware version isn't available this function returns 0.

Parameters

  joystick | the SDL_Joystick obtained from SDL_JoystickOpen().

Returns
  the firmware version of the selected joystick, or 0 if unavailable.

Since
  This function is available since SDL 2.24.0.

## SDL_JoystickGetGUID()

SDL_JoystickGUID SDL_JoystickGetGUID | ( | SDL_Joystick * | joystick | ) |

extern

Get the implementation-dependent GUID for the joystick.

This function requires an open joystick.

Parameters

  joystick | the SDL_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.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickGetDeviceGUID
  SDL_JoystickGetGUIDString

## SDL_JoystickGetGUIDFromString()

SDL_JoystickGUID SDL_JoystickGetGUIDFromString | ( | const char * | pchGUID | ) |

extern

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.

Parameters

  pchGUID | string containing an ASCII representation of a GUID.

Returns
  a SDL_JoystickGUID structure.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickGetGUIDString

## SDL_JoystickGetGUIDString()

void SDL_JoystickGetGUIDString | ( | SDL_JoystickGUID | guid,
|  | char * | pszGUID,
|  | int | cbGUID )

extern

Get an ASCII string representation for a given SDL_JoystickGUID.

You should supply at least 33 bytes for pszGUID.

Parameters

  guid | the SDL_JoystickGUID you wish to convert to string.
  pszGUID | buffer in which to write the ASCII string.
  cbGUID | the size of pszGUID.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickGetDeviceGUID
  SDL_JoystickGetGUID
  SDL_JoystickGetGUIDFromString

## SDL_JoystickGetHat()

Uint8 SDL_JoystickGetHat | ( | SDL_Joystick * | joystick,
|  | int | hat )

extern

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

Parameters

  joystick | an SDL_Joystick structure containing joystick information.
  hat | the hat index to get the state from; indices start at index 0.

Returns
  the current hat position.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickNumHats

## SDL_JoystickGetPlayerIndex()

int SDL_JoystickGetPlayerIndex | ( | SDL_Joystick * | joystick | ) |

extern

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.

Parameters

  joystick | the SDL_Joystick obtained from SDL_JoystickOpen().

Returns
  the player index, or -1 if it's not available.

Since
  This function is available since SDL 2.0.9.

## SDL_JoystickGetProduct()

Uint16 SDL_JoystickGetProduct | ( | SDL_Joystick * | joystick | ) |

extern

Get the USB product ID of an opened joystick, if available.

If the product ID isn't available this function returns 0.

Parameters

  joystick | the SDL_Joystick obtained from SDL_JoystickOpen().

Returns
  the USB product ID of the selected joystick, or 0 if unavailable.

Since
  This function is available since SDL 2.0.6.

## SDL_JoystickGetProductVersion()

Uint16 SDL_JoystickGetProductVersion | ( | SDL_Joystick * | joystick | ) |

extern

Get the product version of an opened joystick, if available.

If the product version isn't available this function returns 0.

Parameters

  joystick | the SDL_Joystick obtained from SDL_JoystickOpen().

Returns
  the product version of the selected joystick, or 0 if unavailable.

Since
  This function is available since SDL 2.0.6.

## SDL_JoystickGetSerial()

const char * SDL_JoystickGetSerial | ( | SDL_Joystick * | joystick | ) |

extern

Get the serial number of an opened joystick, if available.

Returns the serial number of the joystick, or NULL if it is not available.

Parameters

  joystick | the SDL_Joystick obtained from SDL_JoystickOpen().

Returns
  the serial number of the selected joystick, or NULL if unavailable.

Since
  This function is available since SDL 2.0.14.

## SDL_JoystickGetType()

SDL_JoystickType SDL_JoystickGetType | ( | SDL_Joystick * | joystick | ) |

extern

Get the type of an opened joystick.

Parameters

  joystick | the SDL_Joystick obtained from SDL_JoystickOpen().

Returns
  the SDL_JoystickType of the selected joystick.

Since
  This function is available since SDL 2.0.6.

## SDL_JoystickGetVendor()

Uint16 SDL_JoystickGetVendor | ( | SDL_Joystick * | joystick | ) |

extern

Get the USB vendor ID of an opened joystick, if available.

If the vendor ID isn't available this function returns 0.

Parameters

  joystick | the SDL_Joystick obtained from SDL_JoystickOpen().

Returns
  the USB vendor ID of the selected joystick, or 0 if unavailable.

Since
  This function is available since SDL 2.0.6.

## SDL_JoystickHasLED()

SDL_bool SDL_JoystickHasLED | ( | SDL_Joystick * | joystick | ) |

extern

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.

Parameters

  joystick | The joystick to query.

Returns
  SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.

Since
  This function is available since SDL 2.0.14.

## SDL_JoystickHasRumble()

SDL_bool SDL_JoystickHasRumble | ( | SDL_Joystick * | joystick | ) |

extern

Query whether a joystick has rumble support.

Parameters

  joystick | The joystick to query.

Returns
  SDL_TRUE if the joystick has rumble, SDL_FALSE otherwise.

Since
  This function is available since SDL 2.0.18.

See also
  SDL_JoystickRumble

## SDL_JoystickHasRumbleTriggers()

SDL_bool SDL_JoystickHasRumbleTriggers | ( | SDL_Joystick * | joystick | ) |

extern

Query whether a joystick has rumble support on triggers.

Parameters

  joystick | The joystick to query.

Returns
  SDL_TRUE if the joystick has trigger rumble, SDL_FALSE otherwise.

Since
  This function is available since SDL 2.0.18.

See also
  SDL_JoystickRumbleTriggers

## SDL_JoystickInstanceID()

SDL_JoystickID SDL_JoystickInstanceID | ( | SDL_Joystick * | joystick | ) |

extern

Get the instance ID of an opened joystick.

Parameters

  joystick | an SDL_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.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickOpen

## SDL_JoystickIsVirtual()

SDL_bool SDL_JoystickIsVirtual | ( | int | device_index | ) |

extern

Query whether or not the joystick at a given device index is virtual.

Parameters

  device_index | a joystick device index.

Returns
  SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.

Since
  This function is available since SDL 2.0.14.

## SDL_JoystickName()

const char * SDL_JoystickName | ( | SDL_Joystick * | joystick | ) |

extern

Get the implementation dependent name of a joystick.

Parameters

  joystick | the SDL_Joystick obtained from SDL_JoystickOpen().

Returns
  the name of the selected joystick. If no name can be found, this function returns NULL; call SDL_GetError() for more information.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickNameForIndex
  SDL_JoystickOpen

## SDL_JoystickNameForIndex()

const char * SDL_JoystickNameForIndex | ( | int | device_index | ) |

extern

Get the implementation dependent name of a joystick.

This can be called before any joysticks are opened.

Parameters

  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 NULL; call SDL_GetError() for more information.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickName
  SDL_JoystickOpen

## SDL_JoystickNumAxes()

int SDL_JoystickNumAxes | ( | SDL_Joystick * | joystick | ) |

extern

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.

Parameters

  joystick | an SDL_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.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickGetAxis
  SDL_JoystickOpen

## SDL_JoystickNumBalls()

int SDL_JoystickNumBalls | ( | SDL_Joystick * | joystick | ) |

extern

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.

Parameters

  joystick | an SDL_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.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickGetBall

## SDL_JoystickNumButtons()

int SDL_JoystickNumButtons | ( | SDL_Joystick * | joystick | ) |

extern

Get the number of buttons on a joystick.

Parameters

  joystick | an SDL_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.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickGetButton
  SDL_JoystickOpen

## SDL_JoystickNumHats()

int SDL_JoystickNumHats | ( | SDL_Joystick * | joystick | ) |

extern

Get the number of POV hats on a joystick.

Parameters

  joystick | an SDL_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.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickGetHat
  SDL_JoystickOpen

## SDL_JoystickOpen()

SDL_Joystick * SDL_JoystickOpen | ( | int | device_index | ) |

extern

Open a joystick for use.

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.

Parameters

  device_index | the index of the joystick to query.

Returns
  a joystick identifier or NULL if an error occurred; call SDL_GetError() for more information.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickClose
  SDL_JoystickInstanceID

## SDL_JoystickPath()

const char * SDL_JoystickPath | ( | SDL_Joystick * | joystick | ) |

extern

Get the implementation dependent path of a joystick.

Parameters

  joystick | the SDL_Joystick obtained from SDL_JoystickOpen().

Returns
  the path of the selected joystick. If no path can be found, this function returns NULL; call SDL_GetError() for more information.

Since
  This function is available since SDL 2.24.0.

See also
  SDL_JoystickPathForIndex

## SDL_JoystickPathForIndex()

const char * SDL_JoystickPathForIndex | ( | int | device_index | ) |

extern

Get the implementation dependent path of a joystick.

This can be called before any joysticks are opened.

Parameters

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

Returns
  the path of the selected joystick. If no path can be found, this function returns NULL; call SDL_GetError() for more information.

Since
  This function is available since SDL 2.24.0.

See also
  SDL_JoystickPath
  SDL_JoystickOpen

## SDL_JoystickRumble()

int SDL_JoystickRumble | ( | SDL_Joystick * | joystick,
|  | Uint16 | low_frequency_rumble,
|  | Uint16 | high_frequency_rumble,
|  | Uint32 | duration_ms )

extern

Start a rumble effect.

Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.

Parameters

  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.

Since
  This function is available since SDL 2.0.9.

See also
  SDL_JoystickHasRumble

## SDL_JoystickRumbleTriggers()

int SDL_JoystickRumbleTriggers | ( | SDL_Joystick * | joystick,
|  | Uint16 | left_rumble,
|  | Uint16 | right_rumble,
|  | Uint32 | duration_ms )

extern

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 is rumbling of the triggers and not the game controller as a whole. This is currently only supported on Xbox One controllers. If you want the (more common) whole-controller rumble, use SDL_JoystickRumble() instead.

Parameters

  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.

Since
  This function is available since SDL 2.0.14.

See also
  SDL_JoystickHasRumbleTriggers

## SDL_JoystickSendEffect()

int SDL_JoystickSendEffect | ( | SDL_Joystick * | joystick,
|  | const void * | data,
|  | int | size )

extern

Send a joystick specific effect packet

Parameters

  joystick | The joystick to affect.
  data | The data to send to the joystick.
  size | The size of the data to send to the joystick.

Returns
  0, or -1 if this joystick or driver doesn't support effect packets.

Since
  This function is available since SDL 2.0.16.

## SDL_JoystickSetLED()

int SDL_JoystickSetLED | ( | SDL_Joystick * | joystick,
|  | Uint8 | red,
|  | Uint8 | green,
|  | Uint8 | blue )

extern

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.

Parameters

  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.

Since
  This function is available since SDL 2.0.14.

## SDL_JoystickSetPlayerIndex()

void SDL_JoystickSetPlayerIndex | ( | SDL_Joystick * | joystick,
|  | int | player_index )

extern

Set the player index of an opened joystick.

Parameters

  joystick | the SDL_Joystick obtained from SDL_JoystickOpen().
  player_index | Player index to assign to this joystick, or -1 to clear the player index and turn off player LEDs.

Since
  This function is available since SDL 2.0.12.

## SDL_JoystickSetVirtualAxis()

int SDL_JoystickSetVirtualAxis | ( | SDL_Joystick * | joystick,
|  | int | axis,
|  | Sint16 | value )

extern

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.

Note that when sending trigger axes, you should scale the value to the full range of Sint16. For example, a trigger at rest would have the value of SDL_JOYSTICK_AXIS_MIN.

Parameters

  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.

Since
  This function is available since SDL 2.0.14.

## SDL_JoystickSetVirtualButton()

int SDL_JoystickSetVirtualButton | ( | SDL_Joystick * | joystick,
|  | int | button,
|  | Uint8 | value )

extern

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.

Parameters

  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.

Since
  This function is available since SDL 2.0.14.

## SDL_JoystickSetVirtualHat()

int SDL_JoystickSetVirtualHat | ( | SDL_Joystick * | joystick,
|  | int | hat,
|  | Uint8 | value )

extern

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.

Parameters

  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.

Since
  This function is available since SDL 2.0.14.

## SDL_JoystickUpdate()

void SDL_JoystickUpdate | ( | void |  | ) |

extern

Update the current state of the open joysticks.

This is called automatically by the event loop if any joystick events are enabled.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickEventState

## SDL_LockJoysticks()

void SDL_LockJoysticks | ( | void |  | ) |

extern

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.

As of SDL 2.26.0, you can take the joystick lock around reinitializing the joystick subsystem, to prevent other threads from seeing joysticks in an uninitialized state. However, all open joysticks will be closed and SDL functions called with them will fail.

Since
  This function is available since SDL 2.0.7.

## SDL_NumJoysticks()

int SDL_NumJoysticks | ( | void |  | ) |

extern

Count the number of joysticks attached to the system.

Returns
  the number of attached joysticks on success or a negative error code on failure; call SDL_GetError() for more information.

Since
  This function is available since SDL 2.0.0.

See also
  SDL_JoystickName
  SDL_JoystickPath
  SDL_JoystickOpen

## SDL_UnlockJoysticks()

void SDL_UnlockJoysticks | ( | void |  | ) |

extern

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.

Since
  This function is available since SDL 2.0.7.