SDL 3.0
SDL_joystick.h File Reference

Include file for SDL joystick event handling. More...

#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_guid.h>
#include <SDL3/SDL_mutex.h>
#include <SDL3/SDL_begin_code.h>
#include <SDL3/SDL_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_JOYSTICK_AXIS_MAX   32767
 
#define SDL_JOYSTICK_AXIS_MIN   -32768
 
#define SDL_IPHONE_MAX_GFORCE   5.0
 
#define SDL_VIRTUAL_JOYSTICK_DESC_VERSION   1
 The current version of the SDL_VirtualJoystickDesc structure.
 

Typedefs

typedef struct SDL_Joystick SDL_Joystick
 
typedef SDL_GUID SDL_JoystickGUID
 
typedef Uint32 SDL_JoystickID
 

Enumerations

enum  SDL_JoystickType {
  SDL_JOYSTICK_TYPE_UNKNOWN ,
  SDL_JOYSTICK_TYPE_GAMEPAD ,
  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)
 
SDL_JoystickIDSDL_GetJoysticks (int *count)
 
const char * SDL_GetJoystickInstanceName (SDL_JoystickID instance_id)
 
const char * SDL_GetJoystickInstancePath (SDL_JoystickID instance_id)
 
int SDL_GetJoystickInstancePlayerIndex (SDL_JoystickID instance_id)
 
SDL_JoystickGUID SDL_GetJoystickInstanceGUID (SDL_JoystickID instance_id)
 
Uint16 SDL_GetJoystickInstanceVendor (SDL_JoystickID instance_id)
 
Uint16 SDL_GetJoystickInstanceProduct (SDL_JoystickID instance_id)
 
Uint16 SDL_GetJoystickInstanceProductVersion (SDL_JoystickID instance_id)
 
SDL_JoystickType SDL_GetJoystickInstanceType (SDL_JoystickID instance_id)
 
SDL_JoystickSDL_OpenJoystick (SDL_JoystickID instance_id)
 
SDL_JoystickSDL_GetJoystickFromInstanceID (SDL_JoystickID instance_id)
 
SDL_JoystickSDL_GetJoystickFromPlayerIndex (int player_index)
 
SDL_JoystickID SDL_AttachVirtualJoystick (SDL_JoystickType type, int naxes, int nbuttons, int nhats)
 
SDL_JoystickID SDL_AttachVirtualJoystickEx (const SDL_VirtualJoystickDesc *desc)
 
int SDL_DetachVirtualJoystick (SDL_JoystickID instance_id)
 
SDL_bool SDL_IsJoystickVirtual (SDL_JoystickID instance_id)
 
int SDL_SetJoystickVirtualAxis (SDL_Joystick *joystick, int axis, Sint16 value)
 
int SDL_SetJoystickVirtualButton (SDL_Joystick *joystick, int button, Uint8 value)
 
int SDL_SetJoystickVirtualHat (SDL_Joystick *joystick, int hat, Uint8 value)
 
const char * SDL_GetJoystickName (SDL_Joystick *joystick)
 
const char * SDL_GetJoystickPath (SDL_Joystick *joystick)
 
int SDL_GetJoystickPlayerIndex (SDL_Joystick *joystick)
 
int SDL_SetJoystickPlayerIndex (SDL_Joystick *joystick, int player_index)
 
SDL_JoystickGUID SDL_GetJoystickGUID (SDL_Joystick *joystick)
 
Uint16 SDL_GetJoystickVendor (SDL_Joystick *joystick)
 
Uint16 SDL_GetJoystickProduct (SDL_Joystick *joystick)
 
Uint16 SDL_GetJoystickProductVersion (SDL_Joystick *joystick)
 
Uint16 SDL_GetJoystickFirmwareVersion (SDL_Joystick *joystick)
 
const char * SDL_GetJoystickSerial (SDL_Joystick *joystick)
 
SDL_JoystickType SDL_GetJoystickType (SDL_Joystick *joystick)
 
int SDL_GetJoystickGUIDString (SDL_JoystickGUID guid, char *pszGUID, int cbGUID)
 
SDL_JoystickGUID SDL_GetJoystickGUIDFromString (const char *pchGUID)
 
void SDL_GetJoystickGUIDInfo (SDL_JoystickGUID guid, Uint16 *vendor, Uint16 *product, Uint16 *version, Uint16 *crc16)
 
SDL_bool SDL_JoystickConnected (SDL_Joystick *joystick)
 
SDL_JoystickID SDL_GetJoystickInstanceID (SDL_Joystick *joystick)
 
int SDL_GetNumJoystickAxes (SDL_Joystick *joystick)
 
int SDL_GetNumJoystickHats (SDL_Joystick *joystick)
 
int SDL_GetNumJoystickButtons (SDL_Joystick *joystick)
 
void SDL_SetJoystickEventsEnabled (SDL_bool enabled)
 
SDL_bool SDL_JoystickEventsEnabled (void)
 
void SDL_UpdateJoysticks (void)
 
Sint16 SDL_GetJoystickAxis (SDL_Joystick *joystick, int axis)
 
SDL_bool SDL_GetJoystickAxisInitialState (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_GetJoystickHat (SDL_Joystick *joystick, int hat)
 
Uint8 SDL_GetJoystickButton (SDL_Joystick *joystick, int button)
 
int SDL_RumbleJoystick (SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms)
 
int SDL_RumbleJoystickTriggers (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_SetJoystickLED (SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue)
 
int SDL_SendJoystickEffect (SDL_Joystick *joystick, const void *data, int size)
 
void SDL_CloseJoystick (SDL_Joystick *joystick)
 
SDL_JoystickPowerLevel SDL_GetJoystickPowerLevel (SDL_Joystick *joystick)
 

Detailed Description

Include file for SDL joystick event handling.

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 816 of file SDL_joystick.h.

◆ SDL_HAT_DOWN

#define SDL_HAT_DOWN   0x04

Definition at line 819 of file SDL_joystick.h.

◆ SDL_HAT_LEFT

#define SDL_HAT_LEFT   0x08

Definition at line 820 of file SDL_joystick.h.

◆ SDL_HAT_LEFTDOWN

#define SDL_HAT_LEFTDOWN   (SDL_HAT_LEFT|SDL_HAT_DOWN)

Definition at line 824 of file SDL_joystick.h.

◆ SDL_HAT_LEFTUP

#define SDL_HAT_LEFTUP   (SDL_HAT_LEFT|SDL_HAT_UP)

Definition at line 823 of file SDL_joystick.h.

◆ SDL_HAT_RIGHT

#define SDL_HAT_RIGHT   0x02

Definition at line 818 of file SDL_joystick.h.

◆ SDL_HAT_RIGHTDOWN

#define SDL_HAT_RIGHTDOWN   (SDL_HAT_RIGHT|SDL_HAT_DOWN)

Definition at line 822 of file SDL_joystick.h.

◆ SDL_HAT_RIGHTUP

#define SDL_HAT_RIGHTUP   (SDL_HAT_RIGHT|SDL_HAT_UP)

Definition at line 821 of file SDL_joystick.h.

◆ SDL_HAT_UP

#define SDL_HAT_UP   0x01

Definition at line 817 of file SDL_joystick.h.

◆ SDL_IPHONE_MAX_GFORCE

#define SDL_IPHONE_MAX_GFORCE   5.0

Definition at line 116 of file SDL_joystick.h.

◆ SDL_JOYSTICK_AXIS_MAX

#define SDL_JOYSTICK_AXIS_MAX   32767

Definition at line 110 of file SDL_joystick.h.

◆ SDL_JOYSTICK_AXIS_MIN

#define SDL_JOYSTICK_AXIS_MIN   -32768

Definition at line 111 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 363 of file SDL_joystick.h.

Typedef Documentation

◆ SDL_Joystick

typedef struct SDL_Joystick SDL_Joystick

Definition at line 71 of file SDL_joystick.h.

◆ SDL_JoystickGUID

Definition at line 74 of file SDL_joystick.h.

◆ 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 1 and increments from there. The value 0 is an invalid ID.

Definition at line 83 of file SDL_joystick.h.

Enumeration Type Documentation

◆ 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 99 of file SDL_joystick.h.

100{
102 SDL_JOYSTICK_POWER_EMPTY, /* <= 5% */
103 SDL_JOYSTICK_POWER_LOW, /* <= 20% */
104 SDL_JOYSTICK_POWER_MEDIUM, /* <= 70% */
105 SDL_JOYSTICK_POWER_FULL, /* <= 100% */
SDL_JoystickPowerLevel
@ SDL_JOYSTICK_POWER_MAX
@ SDL_JOYSTICK_POWER_FULL
@ SDL_JOYSTICK_POWER_MEDIUM
@ SDL_JOYSTICK_POWER_EMPTY
@ SDL_JOYSTICK_POWER_UNKNOWN
@ SDL_JOYSTICK_POWER_WIRED
@ SDL_JOYSTICK_POWER_LOW

◆ SDL_JoystickType

Enumerator
SDL_JOYSTICK_TYPE_UNKNOWN 
SDL_JOYSTICK_TYPE_GAMEPAD 
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 85 of file SDL_joystick.h.

Function Documentation

◆ SDL_AttachVirtualJoystick()

SDL_JoystickID SDL_AttachVirtualJoystick ( SDL_JoystickType  type,
int  naxes,
int  nbuttons,
int  nhats 
)
extern

Attach a new virtual joystick.

Parameters
typetype of joystick
naxesnumber of axes
nbuttonsnumber of buttons
nhatsnumber of hats
Returns
the joystick instance ID, or 0 if an error occurred; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_AttachVirtualJoystickEx()

SDL_JoystickID SDL_AttachVirtualJoystickEx ( const SDL_VirtualJoystickDesc desc)
extern

Attach a new virtual joystick with extended properties.

Parameters
descJoystick description
Returns
the joystick instance ID, or 0 if an error occurred; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_CloseJoystick()

void SDL_CloseJoystick ( SDL_Joystick joystick)
extern

Close a joystick previously opened with SDL_OpenJoystick().

Parameters
joystickThe joystick device to close
Since
This function is available since SDL 3.0.0.
See also
SDL_OpenJoystick

◆ SDL_DetachVirtualJoystick()

int SDL_DetachVirtualJoystick ( SDL_JoystickID  instance_id)
extern

Detach a virtual joystick.

Parameters
instance_idthe joystick instance ID, previously returned from SDL_AttachVirtualJoystick()
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetJoystickAxis()

Sint16 SDL_GetJoystickAxis ( 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_GetJoystickAxis() 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
joystickan SDL_Joystick structure containing joystick information
axisthe 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 3.0.0.
See also
SDL_GetNumJoystickAxes

◆ SDL_GetJoystickAxisInitialState()

SDL_bool SDL_GetJoystickAxisInitialState ( 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
joystickan SDL_Joystick structure containing joystick information
axisthe axis to query; the axis indices start at index 0
stateUpon 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 3.0.0.

◆ SDL_GetJoystickButton()

Uint8 SDL_GetJoystickButton ( SDL_Joystick joystick,
int  button 
)
extern

Get the current state of a button on a joystick.

Parameters
joystickan SDL_Joystick structure containing joystick information
buttonthe 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 3.0.0.
See also
SDL_GetNumJoystickButtons

◆ SDL_GetJoystickFirmwareVersion()

Uint16 SDL_GetJoystickFirmwareVersion ( 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
joystickthe SDL_Joystick obtained from SDL_OpenJoystick()
Returns
the firmware version of the selected joystick, or 0 if unavailable.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetJoystickFromInstanceID()

SDL_Joystick * SDL_GetJoystickFromInstanceID ( SDL_JoystickID  instance_id)
extern

Get the SDL_Joystick associated with an instance ID, if it has been opened.

Parameters
instance_idthe instance ID to get the SDL_Joystick for
Returns
an SDL_Joystick on success or NULL on failure or if it hasn't been opened yet; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetJoystickFromPlayerIndex()

SDL_Joystick * SDL_GetJoystickFromPlayerIndex ( int  player_index)
extern

Get the SDL_Joystick associated with a player index.

Parameters
player_indexthe 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 3.0.0.

◆ SDL_GetJoystickGUID()

SDL_JoystickGUID SDL_GetJoystickGUID ( SDL_Joystick joystick)
extern

Get the implementation-dependent GUID for the joystick.

This function requires an open joystick.

Parameters
joystickthe SDL_Joystick obtained from SDL_OpenJoystick()
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 3.0.0.
See also
SDL_GetJoystickInstanceGUID
SDL_GetJoystickGUIDString

◆ SDL_GetJoystickGUIDFromString()

SDL_JoystickGUID SDL_GetJoystickGUIDFromString ( 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
pchGUIDstring containing an ASCII representation of a GUID
Returns
a SDL_JoystickGUID structure.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickGUIDString

◆ 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
guidthe SDL_JoystickGUID you wish to get info about
vendorA pointer filled in with the device VID, or 0 if not available
productA pointer filled in with the device PID, or 0 if not available
versionA pointer filled in with the device version, or 0 if not available
crc16A 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 3.0.0.
See also
SDL_GetJoystickInstanceGUID

◆ SDL_GetJoystickGUIDString()

int SDL_GetJoystickGUIDString ( 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
guidthe SDL_JoystickGUID you wish to convert to string
pszGUIDbuffer in which to write the ASCII string
cbGUIDthe size of pszGUID
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickInstanceGUID
SDL_GetJoystickGUID
SDL_GetJoystickGUIDFromString

◆ SDL_GetJoystickHat()

Uint8 SDL_GetJoystickHat ( 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
joystickan SDL_Joystick structure containing joystick information
hatthe hat index to get the state from; indices start at index 0
Returns
the current hat position.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetNumJoystickHats

◆ SDL_GetJoystickInstanceGUID()

SDL_JoystickGUID SDL_GetJoystickInstanceGUID ( SDL_JoystickID  instance_id)
extern

Get the implementation-dependent GUID of a joystick.

This can be called before any joysticks are opened.

Parameters
instance_idthe joystick instance ID
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 3.0.0.
See also
SDL_GetJoystickGUID
SDL_GetJoystickGUIDString

◆ SDL_GetJoystickInstanceID()

SDL_JoystickID SDL_GetJoystickInstanceID ( SDL_Joystick joystick)
extern

Get the instance ID of an opened joystick.

Parameters
joystickan SDL_Joystick structure containing joystick information
Returns
the instance ID of the specified joystick on success or 0 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_OpenJoystick

◆ SDL_GetJoystickInstanceName()

const char * SDL_GetJoystickInstanceName ( SDL_JoystickID  instance_id)
extern

Get the implementation dependent name of a joystick.

This can be called before any joysticks are opened.

Parameters
instance_idthe joystick instance ID
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 3.0.0.
See also
SDL_GetJoystickName
SDL_OpenJoystick

◆ SDL_GetJoystickInstancePath()

const char * SDL_GetJoystickInstancePath ( SDL_JoystickID  instance_id)
extern

Get the implementation dependent path of a joystick.

This can be called before any joysticks are opened.

Parameters
instance_idthe joystick instance ID
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 3.0.0.
See also
SDL_GetJoystickPath
SDL_OpenJoystick

◆ SDL_GetJoystickInstancePlayerIndex()

int SDL_GetJoystickInstancePlayerIndex ( SDL_JoystickID  instance_id)
extern

Get the player index of a joystick.

This can be called before any joysticks are opened.

Parameters
instance_idthe joystick instance ID
Returns
the player index of a joystick, or -1 if it's not available
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickPlayerIndex
SDL_OpenJoystick

◆ SDL_GetJoystickInstanceProduct()

Uint16 SDL_GetJoystickInstanceProduct ( SDL_JoystickID  instance_id)
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
instance_idthe joystick instance ID
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 3.0.0.

◆ SDL_GetJoystickInstanceProductVersion()

Uint16 SDL_GetJoystickInstanceProductVersion ( SDL_JoystickID  instance_id)
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
instance_idthe joystick instance ID
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 3.0.0.

◆ SDL_GetJoystickInstanceType()

SDL_JoystickType SDL_GetJoystickInstanceType ( SDL_JoystickID  instance_id)
extern

Get the type of a joystick, if available.

This can be called before any joysticks are opened.

Parameters
instance_idthe joystick instance ID
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 3.0.0.

◆ SDL_GetJoystickInstanceVendor()

Uint16 SDL_GetJoystickInstanceVendor ( SDL_JoystickID  instance_id)
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
instance_idthe joystick instance ID
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 3.0.0.

◆ SDL_GetJoystickName()

const char * SDL_GetJoystickName ( SDL_Joystick joystick)
extern

Get the implementation dependent name of a joystick.

Parameters
joystickthe SDL_Joystick obtained from SDL_OpenJoystick()
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 3.0.0.
See also
SDL_GetJoystickInstanceName
SDL_OpenJoystick

◆ SDL_GetJoystickPath()

const char * SDL_GetJoystickPath ( SDL_Joystick joystick)
extern

Get the implementation dependent path of a joystick.

Parameters
joystickthe SDL_Joystick obtained from SDL_OpenJoystick()
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 3.0.0.
See also
SDL_GetJoystickInstancePath

◆ SDL_GetJoystickPlayerIndex()

int SDL_GetJoystickPlayerIndex ( 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
joystickthe SDL_Joystick obtained from SDL_OpenJoystick()
Returns
the player index, or -1 if it's not available.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetJoystickPowerLevel()

SDL_JoystickPowerLevel SDL_GetJoystickPowerLevel ( SDL_Joystick joystick)
extern

Get the battery level of a joystick as SDL_JoystickPowerLevel.

Parameters
joystickthe 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 3.0.0.

◆ SDL_GetJoystickProduct()

Uint16 SDL_GetJoystickProduct ( 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
joystickthe SDL_Joystick obtained from SDL_OpenJoystick()
Returns
the USB product ID of the selected joystick, or 0 if unavailable.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetJoystickProductVersion()

Uint16 SDL_GetJoystickProductVersion ( 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
joystickthe SDL_Joystick obtained from SDL_OpenJoystick()
Returns
the product version of the selected joystick, or 0 if unavailable.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetJoysticks()

SDL_JoystickID * SDL_GetJoysticks ( int *  count)
extern

Get a list of currently connected joysticks.

Parameters
counta pointer filled in with the number of joysticks returned
Returns
a 0 terminated array of joystick instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details.
Since
This function is available since SDL 3.0.0.
See also
SDL_OpenJoystick

◆ SDL_GetJoystickSerial()

const char * SDL_GetJoystickSerial ( 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
joystickthe SDL_Joystick obtained from SDL_OpenJoystick()
Returns
the serial number of the selected joystick, or NULL if unavailable.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetJoystickType()

SDL_JoystickType SDL_GetJoystickType ( SDL_Joystick joystick)
extern

Get the type of an opened joystick.

Parameters
joystickthe SDL_Joystick obtained from SDL_OpenJoystick()
Returns
the SDL_JoystickType of the selected joystick.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetJoystickVendor()

Uint16 SDL_GetJoystickVendor ( 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
joystickthe SDL_Joystick obtained from SDL_OpenJoystick()
Returns
the USB vendor ID of the selected joystick, or 0 if unavailable.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetNumJoystickAxes()

int SDL_GetNumJoystickAxes ( 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
joystickan 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 3.0.0.
See also
SDL_GetJoystickAxis
SDL_OpenJoystick

◆ SDL_GetNumJoystickButtons()

int SDL_GetNumJoystickButtons ( SDL_Joystick joystick)
extern

Get the number of buttons on a joystick.

Parameters
joystickan 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 3.0.0.
See also
SDL_GetJoystickButton
SDL_OpenJoystick

◆ SDL_GetNumJoystickHats()

int SDL_GetNumJoystickHats ( SDL_Joystick joystick)
extern

Get the number of POV hats on a joystick.

Parameters
joystickan 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 3.0.0.
See also
SDL_GetJoystickHat
SDL_OpenJoystick

◆ SDL_IsJoystickVirtual()

SDL_bool SDL_IsJoystickVirtual ( SDL_JoystickID  instance_id)
extern

Query whether or not a joystick is virtual.

Parameters
instance_idthe joystick instance ID
Returns
SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.

◆ SDL_JoystickConnected()

SDL_bool SDL_JoystickConnected ( SDL_Joystick joystick)
extern

Get the status of a specified joystick.

Parameters
joystickthe 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 3.0.0.
See also
SDL_CloseJoystick
SDL_OpenJoystick

◆ SDL_JoystickEventsEnabled()

SDL_bool SDL_JoystickEventsEnabled ( void  )
extern

Query the state of joystick event processing.

If joystick events are disabled, you must call SDL_UpdateJoysticks() yourself and check the state of the joystick when you want joystick information.

Returns
SDL_TRUE if joystick events are being processed, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.
See also
SDL_SetJoystickEventsEnabled

◆ 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
joystickThe joystick to query
Returns
SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.

◆ SDL_JoystickHasRumble()

SDL_bool SDL_JoystickHasRumble ( SDL_Joystick joystick)
extern

Query whether a joystick has rumble support.

Parameters
joystickThe joystick to query
Returns
SDL_TRUE if the joystick has rumble, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.
See also
SDL_RumbleJoystick

◆ SDL_JoystickHasRumbleTriggers()

SDL_bool SDL_JoystickHasRumbleTriggers ( SDL_Joystick joystick)
extern

Query whether a joystick has rumble support on triggers.

Parameters
joystickThe joystick to query
Returns
SDL_TRUE if the joystick has trigger rumble, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.
See also
SDL_RumbleJoystickTriggers

◆ SDL_LockJoysticks()

void SDL_LockJoysticks ( void  )
extern

Locking for atomic access to the joystick API

The SDL joystick functions are thread-safe, however you can lock the joysticks while processing to guarantee that the joystick list won't change and joystick and gamepad events will not be delivered.

Since
This function is available since SDL 3.0.0.

◆ SDL_OpenJoystick()

SDL_Joystick * SDL_OpenJoystick ( SDL_JoystickID  instance_id)
extern

Open a joystick for use.

The joystick subsystem must be initialized before a joystick can be opened for use.

Parameters
instance_idthe joystick instance ID
Returns
a joystick identifier or NULL if an error occurred; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_CloseJoystick

◆ SDL_RumbleJoystick()

int SDL_RumbleJoystick ( 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
joystickThe joystick to vibrate
low_frequency_rumbleThe intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
high_frequency_rumbleThe intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
duration_msThe 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 3.0.0.
See also
SDL_JoystickHasRumble

◆ SDL_RumbleJoystickTriggers()

int SDL_RumbleJoystickTriggers ( 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_RumbleJoystick() instead.

Parameters
joystickThe joystick to vibrate
left_rumbleThe intensity of the left trigger rumble motor, from 0 to 0xFFFF
right_rumbleThe intensity of the right trigger rumble motor, from 0 to 0xFFFF
duration_msThe duration of the rumble effect, in milliseconds
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_JoystickHasRumbleTriggers

◆ SDL_SendJoystickEffect()

int SDL_SendJoystickEffect ( SDL_Joystick joystick,
const void *  data,
int  size 
)
extern

Send a joystick specific effect packet

Parameters
joystickThe joystick to affect
dataThe data to send to the joystick
sizeThe size of the data to send to the joystick
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_SetJoystickEventsEnabled()

void SDL_SetJoystickEventsEnabled ( SDL_bool  enabled)
extern

Set the state of joystick event processing.

If joystick events are disabled, you must call SDL_UpdateJoysticks() yourself and check the state of the joystick when you want joystick information.

Parameters
enabledwhether to process joystick events or not
Since
This function is available since SDL 3.0.0.
See also
SDL_JoystickEventsEnabled

◆ SDL_SetJoystickLED()

int SDL_SetJoystickLED ( 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
joystickThe joystick to update
redThe intensity of the red LED
greenThe intensity of the green LED
blueThe intensity of the blue LED
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_SetJoystickPlayerIndex()

int SDL_SetJoystickPlayerIndex ( SDL_Joystick joystick,
int  player_index 
)
extern

Set the player index of an opened joystick.

Parameters
joystickthe SDL_Joystick obtained from SDL_OpenJoystick()
player_indexPlayer index to assign to this joystick, or -1 to clear the player index and turn off player LEDs.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_SetJoystickVirtualAxis()

int SDL_SetJoystickVirtualAxis ( 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_UpdateJoysticks, 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
joystickthe virtual joystick on which to set state.
axisthe specific axis on the virtual joystick to set.
valuethe new value for the specified axis.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_SetJoystickVirtualButton()

int SDL_SetJoystickVirtualButton ( 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_UpdateJoysticks, 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
joystickthe virtual joystick on which to set state.
buttonthe specific button on the virtual joystick to set.
valuethe new value for the specified button.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_SetJoystickVirtualHat()

int SDL_SetJoystickVirtualHat ( 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_UpdateJoysticks, 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
joystickthe virtual joystick on which to set state.
hatthe specific hat on the virtual joystick to set.
valuethe new value for the specified hat.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_UnlockJoysticks()

void SDL_UnlockJoysticks ( void  )
extern

Unlocking for atomic access to the joystick API

Since
This function is available since SDL 3.0.0.

◆ SDL_UpdateJoysticks()

void SDL_UpdateJoysticks ( 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 3.0.0.