SDL 3.0
SDL_joystick.h File Reference
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_guid.h>
#include <SDL3/SDL_mutex.h>
#include <SDL3/SDL_power.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_sensor.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_VirtualJoystickTouchpadDesc
 
struct  SDL_VirtualJoystickSensorDesc
 
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_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN   "SDL.joystick.cap.mono_led"
 
#define SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN   "SDL.joystick.cap.rgb_led"
 
#define SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN   "SDL.joystick.cap.player_led"
 
#define SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN   "SDL.joystick.cap.rumble"
 
#define SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN   "SDL.joystick.cap.trigger_rumble"
 
#define SDL_HAT_CENTERED   0x00u
 
#define SDL_HAT_UP   0x01u
 
#define SDL_HAT_RIGHT   0x02u
 
#define SDL_HAT_DOWN   0x04u
 
#define SDL_HAT_LEFT   0x08u
 
#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)
 

Typedefs

typedef struct SDL_Joystick SDL_Joystick
 
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_JoystickConnectionState {
  SDL_JOYSTICK_CONNECTION_INVALID = -1 ,
  SDL_JOYSTICK_CONNECTION_UNKNOWN ,
  SDL_JOYSTICK_CONNECTION_WIRED ,
  SDL_JOYSTICK_CONNECTION_WIRELESS
}
 

Functions

void SDL_LockJoysticks (void) SDL_ACQUIRE(SDL_joystick_lock)
 
void SDL_UnlockJoysticks (void) SDL_RELEASE(SDL_joystick_lock)
 
SDL_bool SDL_HasJoystick (void)
 
SDL_JoystickIDSDL_GetJoysticks (int *count)
 
const char * SDL_GetJoystickNameForID (SDL_JoystickID instance_id)
 
const char * SDL_GetJoystickPathForID (SDL_JoystickID instance_id)
 
int SDL_GetJoystickPlayerIndexForID (SDL_JoystickID instance_id)
 
SDL_GUID SDL_GetJoystickGUIDForID (SDL_JoystickID instance_id)
 
Uint16 SDL_GetJoystickVendorForID (SDL_JoystickID instance_id)
 
Uint16 SDL_GetJoystickProductForID (SDL_JoystickID instance_id)
 
Uint16 SDL_GetJoystickProductVersionForID (SDL_JoystickID instance_id)
 
SDL_JoystickType SDL_GetJoystickTypeForID (SDL_JoystickID instance_id)
 
SDL_JoystickSDL_OpenJoystick (SDL_JoystickID instance_id)
 
SDL_JoystickSDL_GetJoystickFromID (SDL_JoystickID instance_id)
 
SDL_JoystickSDL_GetJoystickFromPlayerIndex (int player_index)
 
SDL_JoystickID SDL_AttachVirtualJoystick (const SDL_VirtualJoystickDesc *desc)
 
SDL_bool SDL_DetachVirtualJoystick (SDL_JoystickID instance_id)
 
SDL_bool SDL_IsJoystickVirtual (SDL_JoystickID instance_id)
 
SDL_bool SDL_SetJoystickVirtualAxis (SDL_Joystick *joystick, int axis, Sint16 value)
 
SDL_bool SDL_SetJoystickVirtualBall (SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel)
 
SDL_bool SDL_SetJoystickVirtualButton (SDL_Joystick *joystick, int button, Uint8 value)
 
SDL_bool SDL_SetJoystickVirtualHat (SDL_Joystick *joystick, int hat, Uint8 value)
 
SDL_bool SDL_SetJoystickVirtualTouchpad (SDL_Joystick *joystick, int touchpad, int finger, Uint8 state, float x, float y, float pressure)
 
SDL_bool SDL_SendJoystickVirtualSensorData (SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values)
 
SDL_PropertiesID SDL_GetJoystickProperties (SDL_Joystick *joystick)
 
const char * SDL_GetJoystickName (SDL_Joystick *joystick)
 
const char * SDL_GetJoystickPath (SDL_Joystick *joystick)
 
int SDL_GetJoystickPlayerIndex (SDL_Joystick *joystick)
 
SDL_bool SDL_SetJoystickPlayerIndex (SDL_Joystick *joystick, int player_index)
 
SDL_GUID 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)
 
void SDL_GetJoystickGUIDInfo (SDL_GUID guid, Uint16 *vendor, Uint16 *product, Uint16 *version, Uint16 *crc16)
 
SDL_bool SDL_JoystickConnected (SDL_Joystick *joystick)
 
SDL_JoystickID SDL_GetJoystickID (SDL_Joystick *joystick)
 
int SDL_GetNumJoystickAxes (SDL_Joystick *joystick)
 
int SDL_GetNumJoystickBalls (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)
 
SDL_bool SDL_GetJoystickBall (SDL_Joystick *joystick, int ball, int *dx, int *dy)
 
Uint8 SDL_GetJoystickHat (SDL_Joystick *joystick, int hat)
 
Uint8 SDL_GetJoystickButton (SDL_Joystick *joystick, int button)
 
SDL_bool SDL_RumbleJoystick (SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms)
 
SDL_bool SDL_RumbleJoystickTriggers (SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms)
 
SDL_bool SDL_SetJoystickLED (SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue)
 
SDL_bool SDL_SendJoystickEffect (SDL_Joystick *joystick, const void *data, int size)
 
void SDL_CloseJoystick (SDL_Joystick *joystick)
 
SDL_JoystickConnectionState SDL_GetJoystickConnectionState (SDL_Joystick *joystick)
 
SDL_PowerState SDL_GetJoystickPowerInfo (SDL_Joystick *joystick, int *percent)
 

Macro Definition Documentation

◆ SDL_HAT_CENTERED

#define SDL_HAT_CENTERED   0x00u

Definition at line 1039 of file SDL_joystick.h.

◆ SDL_HAT_DOWN

#define SDL_HAT_DOWN   0x04u

Definition at line 1042 of file SDL_joystick.h.

◆ SDL_HAT_LEFT

#define SDL_HAT_LEFT   0x08u

Definition at line 1043 of file SDL_joystick.h.

◆ SDL_HAT_LEFTDOWN

#define SDL_HAT_LEFTDOWN   (SDL_HAT_LEFT|SDL_HAT_DOWN)

Definition at line 1047 of file SDL_joystick.h.

◆ SDL_HAT_LEFTUP

#define SDL_HAT_LEFTUP   (SDL_HAT_LEFT|SDL_HAT_UP)

Definition at line 1046 of file SDL_joystick.h.

◆ SDL_HAT_RIGHT

#define SDL_HAT_RIGHT   0x02u

Definition at line 1041 of file SDL_joystick.h.

◆ SDL_HAT_RIGHTDOWN

#define SDL_HAT_RIGHTDOWN   (SDL_HAT_RIGHT|SDL_HAT_DOWN)

Definition at line 1045 of file SDL_joystick.h.

◆ SDL_HAT_RIGHTUP

#define SDL_HAT_RIGHTUP   (SDL_HAT_RIGHT|SDL_HAT_UP)

Definition at line 1044 of file SDL_joystick.h.

◆ SDL_HAT_UP

#define SDL_HAT_UP   0x01u

Definition at line 1040 of file SDL_joystick.h.

◆ SDL_IPHONE_MAX_GFORCE

#define SDL_IPHONE_MAX_GFORCE   5.0

Definition at line 166 of file SDL_joystick.h.

◆ SDL_JOYSTICK_AXIS_MAX

#define SDL_JOYSTICK_AXIS_MAX   32767

The largest value an SDL_Joystick's axis can report.

Since
This macro is available since SDL 3.0.0.
See also
SDL_JOYSTICK_AXIS_MIN

Definition at line 149 of file SDL_joystick.h.

◆ SDL_JOYSTICK_AXIS_MIN

#define SDL_JOYSTICK_AXIS_MIN   -32768

The smallest value an SDL_Joystick's axis can report.

This is a negative number!

Since
This macro is available since SDL 3.0.0.
See also
SDL_JOYSTICK_AXIS_MAX

Definition at line 160 of file SDL_joystick.h.

◆ SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN

#define SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN   "SDL.joystick.cap.mono_led"

Definition at line 648 of file SDL_joystick.h.

◆ SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN

#define SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN   "SDL.joystick.cap.player_led"

Definition at line 650 of file SDL_joystick.h.

◆ SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN

#define SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN   "SDL.joystick.cap.rgb_led"

Definition at line 649 of file SDL_joystick.h.

◆ SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN

#define SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN   "SDL.joystick.cap.rumble"

Definition at line 651 of file SDL_joystick.h.

◆ SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN

#define SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN   "SDL.joystick.cap.trigger_rumble"

Definition at line 652 of file SDL_joystick.h.

Typedef Documentation

◆ SDL_Joystick

typedef struct SDL_Joystick SDL_Joystick

CategoryJoystick

SDL joystick support.

This is the lower-level joystick handling. If you want the simpler option, where what buttons does what is well-defined, you should use the gamepad API instead.

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.

SDL_GUID is used as 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 The joystick structure used to identify an SDL joystick.

This is opaque data.

Since
This struct is available since SDL 3.0.0.

Definition at line 86 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 value 0 is an invalid ID.

Since
This datatype is available since SDL 3.0.0.

Definition at line 98 of file SDL_joystick.h.

Enumeration Type Documentation

◆ SDL_JoystickConnectionState

Possible connection states for a joystick device.

This is used by SDL_GetJoystickConnectionState to report how a device is connected to the system.

Since
This enum is available since SDL 3.0.0.
Enumerator
SDL_JOYSTICK_CONNECTION_INVALID 
SDL_JOYSTICK_CONNECTION_UNKNOWN 
SDL_JOYSTICK_CONNECTION_WIRED 
SDL_JOYSTICK_CONNECTION_WIRELESS 

Definition at line 134 of file SDL_joystick.h.

◆ SDL_JoystickType

An enum of some common joystick types.

In some cases, SDL can identify a low-level joystick as being a certain type of device, and will report it through SDL_GetJoystickType (or SDL_GetJoystickTypeForID).

This is by no means a complete list of everything that can be plugged into a computer.

Since
This enum is available since SDL 3.0.0.
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 112 of file SDL_joystick.h.

Function Documentation

◆ SDL_AttachVirtualJoystick()

SDL_JoystickID SDL_AttachVirtualJoystick ( const SDL_VirtualJoystickDesc desc)
extern

Attach a new virtual joystick.

Parameters
descjoystick description.
Returns
the joystick instance ID, or 0 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_DetachVirtualJoystick

◆ 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()

SDL_bool SDL_DetachVirtualJoystick ( SDL_JoystickID  instance_id)
extern

Detach a virtual joystick.

Parameters
instance_idthe joystick instance ID, previously returned from SDL_AttachVirtualJoystick().
Returns
SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_AttachVirtualJoystick

◆ 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_GetJoystickBall()

SDL_bool SDL_GetJoystickBall ( 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_GetJoystickBall(), these motion deltas are placed into dx and dy.

Most joysticks do not have trackballs.

Parameters
joystickthe SDL_Joystick to query.
ballthe ball index to query; ball indices start at index 0.
dxstores the difference in the x axis position since the last poll.
dystores the difference in the y axis position since the last poll.
Returns
SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetNumJoystickBalls

◆ 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_GetJoystickConnectionState()

SDL_JoystickConnectionState SDL_GetJoystickConnectionState ( SDL_Joystick joystick)
extern

Get the connection state of a joystick.

Parameters
joystickthe joystick to query.
Returns
the connection state on success or SDL_JOYSTICK_CONNECTION_INVALID on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ 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_GetJoystickFromID()

SDL_Joystick * SDL_GetJoystickFromID ( 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.
See also
SDL_GetJoystickPlayerIndex
SDL_SetJoystickPlayerIndex

◆ SDL_GetJoystickGUID()

SDL_GUID 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_GetJoystickGUIDForID
SDL_GUIDToString

◆ SDL_GetJoystickGUIDForID()

SDL_GUID SDL_GetJoystickGUIDForID ( 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 with an invalid instance_id, this function returns a zero GUID.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickGUID
SDL_GUIDToString

◆ SDL_GetJoystickGUIDInfo()

void SDL_GetJoystickGUIDInfo ( SDL_GUID  guid,
Uint16 vendor,
Uint16 product,
Uint16 version,
Uint16 crc16 
)
extern

Get the device information encoded in a SDL_GUID structure.

Parameters
guidthe SDL_GUID 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_GetJoystickGUIDForID

◆ 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 SDL_HAT_* values.

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_GetJoystickID()

SDL_JoystickID SDL_GetJoystickID ( 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.

◆ 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_GetJoystickNameForID

◆ SDL_GetJoystickNameForID()

const char * SDL_GetJoystickNameForID ( 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_GetJoysticks

◆ 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_GetJoystickPathForID

◆ SDL_GetJoystickPathForID()

const char * SDL_GetJoystickPathForID ( 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_GetJoysticks

◆ 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.
See also
SDL_SetJoystickPlayerIndex

◆ SDL_GetJoystickPlayerIndexForID()

int SDL_GetJoystickPlayerIndexForID ( 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_GetJoysticks

◆ SDL_GetJoystickPowerInfo()

SDL_PowerState SDL_GetJoystickPowerInfo ( SDL_Joystick joystick,
int *  percent 
)
extern

Get the battery state of a joystick.

You should never take a battery status as absolute truth. Batteries (especially failing batteries) are delicate hardware, and the values reported here are best estimates based on what that hardware reports. It's not uncommon for older batteries to lose stored power much faster than it reports, or completely drain when reporting it has 20 percent left, etc.

Parameters
joystickthe joystick to query.
percenta pointer filled in with the percentage of battery life left, between 0 and 100, or NULL to ignore. This will be filled in with -1 we can't determine a value or there is no battery.
Returns
the current battery state or SDL_POWERSTATE_ERROR on failure; call SDL_GetError() for more information.
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.
See also
SDL_GetJoystickProductForID

◆ SDL_GetJoystickProductForID()

Uint16 SDL_GetJoystickProductForID ( 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 with an invalid instance_id, this function returns 0.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickProduct
SDL_GetJoysticks

◆ 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.
See also
SDL_GetJoystickProductVersionForID

◆ SDL_GetJoystickProductVersionForID()

Uint16 SDL_GetJoystickProductVersionForID ( 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 with an invalid instance_id, this function returns 0.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickProductVersion
SDL_GetJoysticks

◆ SDL_GetJoystickProperties()

SDL_PropertiesID SDL_GetJoystickProperties ( SDL_Joystick joystick)
extern

Get the properties associated with a joystick.

The following read-only properties are provided by SDL:

  • SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN: true if this joystick has an LED that has adjustable brightness
  • SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN: true if this joystick has an LED that has adjustable color
  • SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN: true if this joystick has a player LED
  • SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN: true if this joystick has left/right rumble
  • SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN: true if this joystick has simple trigger rumble
Parameters
joystickthe SDL_Joystick obtained from SDL_OpenJoystick().
Returns
a valid property ID on success or 0 on failure; call SDL_GetError() for more information.
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, may be NULL.
Returns
a 0 terminated array of joystick instance IDs or NULL on failure; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
Since
This function is available since SDL 3.0.0.
See also
SDL_HasJoystick
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.
See also
SDL_GetJoystickTypeForID

◆ SDL_GetJoystickTypeForID()

SDL_JoystickType SDL_GetJoystickTypeForID ( 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 with an invalid instance_id, this function returns SDL_JOYSTICK_TYPE_UNKNOWN.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickType
SDL_GetJoysticks

◆ 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.
See also
SDL_GetJoystickVendorForID

◆ SDL_GetJoystickVendorForID()

Uint16 SDL_GetJoystickVendorForID ( 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 with an invalid instance_id, this function returns 0.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickVendor
SDL_GetJoysticks

◆ 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 -1 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickAxis
SDL_GetNumJoystickBalls
SDL_GetNumJoystickButtons
SDL_GetNumJoystickHats

◆ SDL_GetNumJoystickBalls()

int SDL_GetNumJoystickBalls ( 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
joystickan SDL_Joystick structure containing joystick information.
Returns
the number of trackballs on success or -1 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickBall
SDL_GetNumJoystickAxes
SDL_GetNumJoystickButtons
SDL_GetNumJoystickHats

◆ 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 -1 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickButton
SDL_GetNumJoystickAxes
SDL_GetNumJoystickBalls
SDL_GetNumJoystickHats

◆ 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 -1 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickHat
SDL_GetNumJoystickAxes
SDL_GetNumJoystickBalls
SDL_GetNumJoystickButtons

◆ SDL_HasJoystick()

SDL_bool SDL_HasJoystick ( void  )
extern

Return whether a joystick is currently connected.

Returns
SDL_TRUE if a joystick is connected, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoysticks

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

◆ 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_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 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_CloseJoystick

◆ SDL_RumbleJoystick()

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

This function requires you to process SDL events or call SDL_UpdateJoysticks() to update rumble state.

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
SDL_TRUE, or SDL_FALSE if rumble isn't supported on this joystick.
Since
This function is available since SDL 3.0.0.

◆ SDL_RumbleJoystickTriggers()

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

This function requires you to process SDL events or call SDL_UpdateJoysticks() to update rumble state.

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
SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_RumbleJoystick

◆ SDL_SendJoystickEffect()

SDL_bool 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
SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_SendJoystickVirtualSensorData()

SDL_bool SDL_SendJoystickVirtualSensorData ( SDL_Joystick joystick,
SDL_SensorType  type,
Uint64  sensor_timestamp,
const float *  data,
int  num_values 
)
extern

Send a sensor update for an opened virtual joystick.

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.
typethe type of the sensor on the virtual joystick to update.
sensor_timestampa 64-bit timestamp in nanoseconds associated with the sensor reading.
datathe data associated with the sensor reading.
num_valuesthe number of values pointed to by data.
Returns
SDL_TRUE on success or SDL_FALSE 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_UpdateJoysticks

◆ SDL_SetJoystickLED()

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

For joysticks with a single color LED, the maximum of the RGB values will be used as the LED brightness.

Parameters
joystickthe joystick to update.
redthe intensity of the red LED.
greenthe intensity of the green LED.
bluethe intensity of the blue LED.
Returns
SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_SetJoystickPlayerIndex()

SDL_bool 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
SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetJoystickPlayerIndex

◆ SDL_SetJoystickVirtualAxis()

SDL_bool SDL_SetJoystickVirtualAxis ( SDL_Joystick joystick,
int  axis,
Sint16  value 
)
extern

Set the state of an axis on an opened virtual joystick.

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 index of the axis on the virtual joystick to update.
valuethe new value for the specified axis.
Returns
SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_SetJoystickVirtualBall()

SDL_bool SDL_SetJoystickVirtualBall ( SDL_Joystick joystick,
int  ball,
Sint16  xrel,
Sint16  yrel 
)
extern

Generate ball motion on an opened virtual joystick.

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.
ballthe index of the ball on the virtual joystick to update.
xrelthe relative motion on the X axis.
yrelthe relative motion on the Y axis.
Returns
SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_SetJoystickVirtualButton()

SDL_bool SDL_SetJoystickVirtualButton ( SDL_Joystick joystick,
int  button,
Uint8  value 
)
extern

Set the state of a button on an opened virtual joystick.

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 index of the button on the virtual joystick to update.
valuethe new value for the specified button.
Returns
SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_SetJoystickVirtualHat()

SDL_bool SDL_SetJoystickVirtualHat ( SDL_Joystick joystick,
int  hat,
Uint8  value 
)
extern

Set the state of a hat on an opened virtual joystick.

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 index of the hat on the virtual joystick to update.
valuethe new value for the specified hat.
Returns
SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_SetJoystickVirtualTouchpad()

SDL_bool SDL_SetJoystickVirtualTouchpad ( SDL_Joystick joystick,
int  touchpad,
int  finger,
Uint8  state,
float  x,
float  y,
float  pressure 
)
extern

Set touchpad finger state on an opened virtual joystick.

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.
touchpadthe index of the touchpad on the virtual joystick to update.
fingerthe index of the finger on the touchpad to set.
stateSDL_PRESSED if the finger is pressed, SDL_RELEASED if the finger is released.
xthe x coordinate of the finger on the touchpad, normalized 0 to 1, with the origin in the upper left.
ythe y coordinate of the finger on the touchpad, normalized 0 to 1, with the origin in the upper left.
pressurethe pressure of the finger.
Returns
SDL_TRUE on success or SDL_FALSE 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.