Documentation

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.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_LockJoysticks, defined at SDL3/SDL_joystick.h 189:34

Since: 3.2.0

Unlocking for atomic access to the joystick API.

Thread safety

This should be called from the same thread that called SDL_LockJoysticks().

C declaration

SDL_UnlockJoysticks, defined at SDL3/SDL_joystick.h 199:34

Since: 3.2.0

Return whether a joystick is currently connected.

Returns

true if a joystick is connected, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoysticks

C declaration

SDL_HasJoystick, defined at SDL3/SDL_joystick.h 212:34

Since: 3.2.0

Get a list of currently connected joysticks.

count

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

Thread safety

It is safe to call this function from any thread.

See also

sDL_HasJoystick, sDL_OpenJoystick

C declaration

SDL_GetJoysticks, defined at SDL3/SDL_joystick.h 230:46

Since: 3.2.0

Get the implementation dependent name of a joystick.

This can be called before any joysticks are opened.

instance_id

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

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickName, sDL_GetJoysticks

C declaration

SDL_GetJoystickNameForID, defined at SDL3/SDL_joystick.h 248:42

Since: 3.2.0

Get the implementation dependent path of a joystick.

This can be called before any joysticks are opened.

instance_id

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

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickPath, sDL_GetJoysticks

C declaration

SDL_GetJoystickPathForID, defined at SDL3/SDL_joystick.h 266:42

Since: 3.2.0

Get the player index of a joystick.

This can be called before any joysticks are opened.

instance_id

the joystick instance ID.

Returns

the player index of a joystick, or -1 if it's not available.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickPlayerIndex, sDL_GetJoysticks

C declaration

SDL_GetJoystickPlayerIndexForID, defined at SDL3/SDL_joystick.h 283:33

Since: 3.2.0

Get the implementation-dependent GUID of a joystick.

This can be called before any joysticks are opened.

instance_id

the joystick instance ID.

Returns

the GUID of the selected joystick. If called with an invalid instance_id, this function returns a zero GUID.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickGUID, SDL_GUIDToString

C declaration

SDL_GetJoystickGUIDForID, defined at SDL3/SDL_joystick.h 301:38

Since: 3.2.0

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.

instance_id

the joystick instance ID.

Returns

the USB vendor ID of the selected joystick. If called with an invalid instance_id, this function returns 0.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickVendor, sDL_GetJoysticks

C declaration

SDL_GetJoystickVendorForID, defined at SDL3/SDL_joystick.h 320:36

Since: 3.2.0

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.

instance_id

the joystick instance ID.

Returns

the USB product ID of the selected joystick. If called with an invalid instance_id, this function returns 0.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickProduct, sDL_GetJoysticks

C declaration

SDL_GetJoystickProductForID, defined at SDL3/SDL_joystick.h 339:36

Since: 3.2.0

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.

instance_id

the joystick instance ID.

Returns

the product version of the selected joystick. If called with an invalid instance_id, this function returns 0.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickProductVersion, sDL_GetJoysticks

C declaration

SDL_GetJoystickProductVersionForID, defined at SDL3/SDL_joystick.h 358:36

Since: 3.2.0

Get the type of a joystick, if available.

This can be called before any joysticks are opened.

instance_id

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

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickType, sDL_GetJoysticks

C declaration

SDL_GetJoystickTypeForID, defined at SDL3/SDL_joystick.h 377:46

Since: 3.2.0

Open a joystick for use.

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

instance_id

the joystick instance ID.

Returns

a joystick identifier or NULL on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_CloseJoystick

C declaration

SDL_OpenJoystick, defined at SDL3/SDL_joystick.h 395:44

Since: 3.2.0

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

instance_id

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

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetJoystickFromID, defined at SDL3/SDL_joystick.h 408:44

Since: 3.2.0

Get the SDL_Joystick associated with a player index.

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.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickPlayerIndex, sDL_SetJoystickPlayerIndex

C declaration

SDL_GetJoystickFromPlayerIndex, defined at SDL3/SDL_joystick.h 424:44

Since: 3.2.0

Attach a new virtual joystick.

Apps can create virtual joysticks, that exist without hardware directly backing them, and have program-supplied inputs. Once attached, a virtual joystick looks like any other joystick that SDL can access. These can be used to make other things look like joysticks, or provide pre-recorded input, etc.

Once attached, the app can send joystick inputs to the new virtual joystick using SDL_SetJoystickVirtualAxis(), etc.

When no longer needed, the virtual joystick can be removed by calling SDL_DetachVirtualJoystick().

desc

joystick description, initialized using SDL_INIT_INTERFACE().

Returns

the joystick instance ID, or 0 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_DetachVirtualJoystick, sDL_SetJoystickVirtualAxis, sDL_SetJoystickVirtualButton, sDL_SetJoystickVirtualBall, sDL_SetJoystickVirtualHat, sDL_SetJoystickVirtualTouchpad, SDL_SetJoystickVirtualSensorData

C declaration

SDL_AttachVirtualJoystick, defined at SDL3/SDL_joystick.h 539:44

Since: 3.2.0

Detach a virtual joystick.

instance_id

the joystick instance ID, previously returned from SDL_AttachVirtualJoystick().

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_AttachVirtualJoystick

C declaration

SDL_DetachVirtualJoystick, defined at SDL3/SDL_joystick.h 555:34

Since: 3.2.0

Query whether or not a joystick is virtual.

instance_id

the joystick instance ID.

Returns

true if the joystick is virtual, false otherwise.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_IsJoystickVirtual, defined at SDL3/SDL_joystick.h 567:34

Since: 3.2.0

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.

joystick

the virtual joystick on which to set state.

axis

the index of the axis on the virtual joystick to update.

value

the new value for the specified axis.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetJoystickVirtualButton, sDL_SetJoystickVirtualBall, sDL_SetJoystickVirtualHat, sDL_SetJoystickVirtualTouchpad, SDL_SetJoystickVirtualSensorData

C declaration

SDL_SetJoystickVirtualAxis, defined at SDL3/SDL_joystick.h 598:34

Since: 3.2.0

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.

joystick

the virtual joystick on which to set state.

ball

the index of the ball on the virtual joystick to update.

xrel

the relative motion on the X axis.

yrel

the relative motion on the Y axis.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetJoystickVirtualAxis, sDL_SetJoystickVirtualButton, sDL_SetJoystickVirtualHat, sDL_SetJoystickVirtualTouchpad, SDL_SetJoystickVirtualSensorData

C declaration

SDL_SetJoystickVirtualBall, defined at SDL3/SDL_joystick.h 626:34

Since: 3.2.0

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.

joystick

the virtual joystick on which to set state.

button

the index of the button on the virtual joystick to update.

down

true if the button is pressed, false otherwise.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetJoystickVirtualAxis, sDL_SetJoystickVirtualBall, sDL_SetJoystickVirtualHat, sDL_SetJoystickVirtualTouchpad, SDL_SetJoystickVirtualSensorData

C declaration

SDL_SetJoystickVirtualButton, defined at SDL3/SDL_joystick.h 653:34

Since: 3.2.0

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.

joystick

the virtual joystick on which to set state.

hat

the index of the hat on the virtual joystick to update.

value

the new value for the specified hat.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetJoystickVirtualAxis, sDL_SetJoystickVirtualButton, sDL_SetJoystickVirtualBall, sDL_SetJoystickVirtualTouchpad, SDL_SetJoystickVirtualSensorData

C declaration

SDL_SetJoystickVirtualHat, defined at SDL3/SDL_joystick.h 680:34

Since: 3.2.0

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.

joystick

the virtual joystick on which to set state.

touchpad

the index of the touchpad on the virtual joystick to update.

finger

the index of the finger on the touchpad to set.

down

true if the finger is pressed, false if the finger is released.

x

the x coordinate of the finger on the touchpad, normalized 0 to 1, with the origin in the upper left.

y

the y coordinate of the finger on the touchpad, normalized 0 to 1, with the origin in the upper left.

pressure

the pressure of the finger.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetJoystickVirtualAxis, sDL_SetJoystickVirtualButton, sDL_SetJoystickVirtualBall, sDL_SetJoystickVirtualHat, SDL_SetJoystickVirtualSensorData

C declaration

SDL_SetJoystickVirtualTouchpad, defined at SDL3/SDL_joystick.h 714:34

Since: 3.2.0

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.

joystick

the virtual joystick on which to set state.

type

the type of the sensor on the virtual joystick to update.

sensor_timestamp

a 64-bit timestamp in nanoseconds associated with the sensor reading.

data

the data associated with the sensor reading.

num_values

the number of values pointed to by data.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetJoystickVirtualAxis, sDL_SetJoystickVirtualButton, sDL_SetJoystickVirtualBall, sDL_SetJoystickVirtualHat, sDL_SetJoystickVirtualTouchpad

C declaration

SDL_SendJoystickVirtualSensorData, defined at SDL3/SDL_joystick.h 744:34

Since: 3.2.0

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

joystick

the SDL_Joystick obtained from SDL_OpenJoystick().

Returns

a valid property ID on success or 0 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetJoystickProperties, defined at SDL3/SDL_joystick.h 770:46

Since: 3.2.0

Get the implementation dependent name of a joystick.

joystick

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

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickNameForID

C declaration

SDL_GetJoystickName, defined at SDL3/SDL_joystick.h 791:42

Since: 3.2.0

Get the implementation dependent path of a joystick.

joystick

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

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickPathForID

C declaration

SDL_GetJoystickPath, defined at SDL3/SDL_joystick.h 806:42

Since: 3.2.0

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.

joystick

the SDL_Joystick obtained from SDL_OpenJoystick().

Returns

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

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetJoystickPlayerIndex

C declaration

SDL_GetJoystickPlayerIndex, defined at SDL3/SDL_joystick.h 823:33

Since: 3.2.0

Set the player index of an opened joystick.

joystick

the SDL_Joystick obtained from SDL_OpenJoystick().

player_index

player index to assign to this joystick, or -1 to clear the player index and turn off player LEDs.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickPlayerIndex

C declaration

SDL_SetJoystickPlayerIndex, defined at SDL3/SDL_joystick.h 840:34

Since: 3.2.0

Get the implementation-dependent GUID for the joystick.

This function requires an open joystick.

joystick

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

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickGUIDForID, SDL_GUIDToString

C declaration

SDL_GetJoystickGUID, defined at SDL3/SDL_joystick.h 859:38

Since: 3.2.0

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

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

joystick

the SDL_Joystick obtained from SDL_OpenJoystick().

Returns

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

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickVendorForID

C declaration

SDL_GetJoystickVendor, defined at SDL3/SDL_joystick.h 875:36

Since: 3.2.0

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

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

joystick

the SDL_Joystick obtained from SDL_OpenJoystick().

Returns

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

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickProductForID

C declaration

SDL_GetJoystickProduct, defined at SDL3/SDL_joystick.h 891:36

Since: 3.2.0

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

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

joystick

the SDL_Joystick obtained from SDL_OpenJoystick().

Returns

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

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickProductVersionForID

C declaration

SDL_GetJoystickProductVersion, defined at SDL3/SDL_joystick.h 907:36

Since: 3.2.0

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

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

joystick

the SDL_Joystick obtained from SDL_OpenJoystick().

Returns

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

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetJoystickFirmwareVersion, defined at SDL3/SDL_joystick.h 922:36

Since: 3.2.0

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

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

joystick

the SDL_Joystick obtained from SDL_OpenJoystick().

Returns

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

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetJoystickSerial, defined at SDL3/SDL_joystick.h 937:42

Since: 3.2.0

Get the type of an opened joystick.

joystick

the SDL_Joystick obtained from SDL_OpenJoystick().

Returns

the SDL_JoystickType of the selected joystick.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickTypeForID

C declaration

SDL_GetJoystickType, defined at SDL3/SDL_joystick.h 951:46

Since: 3.2.0

Get the device information encoded in a SDL_GUID structure.

guid

the SDL_GUID 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.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickGUIDForID

C declaration

SDL_GetJoystickGUIDInfo, defined at SDL3/SDL_joystick.h 972:34

Since: 3.2.0

Get the status of a specified joystick.

joystick

the joystick to query.

Returns

true if the joystick has been opened, false if it has not; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_JoystickConnected, defined at SDL3/SDL_joystick.h 985:34

Since: 3.2.0

Get the instance ID of an opened joystick.

joystick

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

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetJoystickID, defined at SDL3/SDL_joystick.h 998:44

Since: 3.2.0

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.

joystick

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

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickAxis, sDL_GetNumJoystickBalls, sDL_GetNumJoystickButtons, sDL_GetNumJoystickHats

C declaration

SDL_GetNumJoystickAxes, defined at SDL3/SDL_joystick.h 1020:33

Since: 3.2.0

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.

joystick

an SDL_Joystick structure containing joystick information.

Returns

the number of trackballs on success or -1 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickBall, sDL_GetNumJoystickAxes, sDL_GetNumJoystickButtons, sDL_GetNumJoystickHats

C declaration

SDL_GetNumJoystickBalls, defined at SDL3/SDL_joystick.h 1043:33

Since: 3.2.0

Get the number of POV hats on a joystick.

joystick

an SDL_Joystick structure containing joystick information.

Returns

the number of POV hats on success or -1 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickHat, sDL_GetNumJoystickAxes, sDL_GetNumJoystickBalls, sDL_GetNumJoystickButtons

C declaration

SDL_GetNumJoystickHats, defined at SDL3/SDL_joystick.h 1061:33

Since: 3.2.0

Get the number of buttons on a joystick.

joystick

an SDL_Joystick structure containing joystick information.

Returns

the number of buttons on success or -1 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetJoystickButton, sDL_GetNumJoystickAxes, sDL_GetNumJoystickBalls, sDL_GetNumJoystickHats

C declaration

SDL_GetNumJoystickButtons, defined at SDL3/SDL_joystick.h 1079:33

Since: 3.2.0

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.

enabled

whether to process joystick events or not.

Thread safety

It is safe to call this function from any thread.

See also

sDL_JoystickEventsEnabled, sDL_UpdateJoysticks

C declaration

SDL_SetJoystickEventsEnabled, defined at SDL3/SDL_joystick.h 1097:34

Since: 3.2.0

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

true if joystick events are being processed, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetJoystickEventsEnabled

C declaration

SDL_JoystickEventsEnabled, defined at SDL3/SDL_joystick.h 1114:34

Since: 3.2.0

Update the current state of the open joysticks.

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

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_UpdateJoysticks, defined at SDL3/SDL_joystick.h 1126:34

Since: 3.2.0

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.

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.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetNumJoystickAxes

C declaration

SDL_GetJoystickAxis, defined at SDL3/SDL_joystick.h 1152:36

Since: 3.2.0

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.

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

true if this axis has any initial value, or false if not.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetJoystickAxisInitialState, defined at SDL3/SDL_joystick.h 1170:34

Since: 3.2.0

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.

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

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetNumJoystickBalls

C declaration

SDL_GetJoystickBall, defined at SDL3/SDL_joystick.h 1193:34

Since: 3.2.0

Get the current state of a POV hat on a joystick.

The returned value will be one of the SDL_HAT_* values.

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.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetNumJoystickHats

C declaration

SDL_GetJoystickHat, defined at SDL3/SDL_joystick.h 1210:35

Since: 3.2.0

Get the current state of a button on a joystick.

joystick

an SDL_Joystick structure containing joystick information.

button

the button index to get the state from; indices start at index 0.

Returns

true if the button is pressed, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetNumJoystickButtons

C declaration

SDL_GetJoystickButton, defined at SDL3/SDL_joystick.h 1236:34

Since: 3.2.0

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.

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

true, or false if rumble isn't supported on this joystick.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_RumbleJoystick, defined at SDL3/SDL_joystick.h 1259:34

Since: 3.2.0

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.

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

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_RumbleJoystick

C declaration

SDL_RumbleJoystickTriggers, defined at SDL3/SDL_joystick.h 1290:34

Since: 3.2.0

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.

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

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_SetJoystickLED, defined at SDL3/SDL_joystick.h 1312:34

Since: 3.2.0

Send a joystick specific effect packet.

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

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_SendJoystickEffect, defined at SDL3/SDL_joystick.h 1327:34

Since: 3.2.0

Close a joystick previously opened with SDL_OpenJoystick().

joystick

the joystick device to close.

Thread safety

It is safe to call this function from any thread.

See also

sDL_OpenJoystick

C declaration

SDL_CloseJoystick, defined at SDL3/SDL_joystick.h 1340:34

Since: 3.2.0

Get the connection state of a joystick.

joystick

the joystick to query.

Returns

the connection state on success or SDL_JOYSTICK_CONNECTION_INVALID on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetJoystickConnectionState, defined at SDL3/SDL_joystick.h 1354:57

Since: 3.2.0

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.

joystick

the joystick to query.

percent

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

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetJoystickPowerInfo, defined at SDL3/SDL_joystick.h 1377:44

Since: 3.2.0