SDL joystick support. More...

Namespaces
namespace	SDL::prop
	Constants for Properties keys.
namespace	SDL::prop::JoystickCap
	Joystick capability properties.

Classes
class	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. More...
struct	SDL::Joystick
	The joystick structure used to identify an SDL joystick. More...
class	SDL::JoystickApiLock
	Locking for atomic access to the joystick API. More...

Typedefs
using	SDL::JoystickRaw = SDL_Joystick*
	Alias to raw representation for Joystick.
using	SDL::JoystickRef = ResourceRef<Joystick>
	Reference for Joystick.
using	SDL::JoystickIDRaw = SDL_JoystickID
	Alias to raw representation for JoystickID.
using	SDL::JoystickType = SDL_JoystickType
	An enum of some common joystick types.
using	SDL::JoystickConnectionState = SDL_JoystickConnectionState
	Possible connection states for a joystick device.
using	SDL::HatState = Uint8
	Represents tbe HatState for a Joystick.
using	SDL::VirtualJoystickTouchpadDesc = SDL_VirtualJoystickTouchpadDesc
	The structure that describes a virtual joystick touchpad.
using	SDL::VirtualJoystickSensorDesc = SDL_VirtualJoystickSensorDesc
	The structure that describes a virtual joystick sensor.
using	SDL::VirtualJoystickDesc = SDL_VirtualJoystickDesc
	The structure that describes a virtual joystick.

Functions
void	SDL::LockJoysticks ()
	Locking for atomic access to the joystick API.
void	SDL::UnlockJoysticks ()
	Unlocking for atomic access to the joystick API.
bool	SDL::HasJoystick ()
	Return whether a joystick is currently connected.
OwnArray< JoystickID >	SDL::GetJoysticks ()
	Get a list of currently connected joysticks.
const char *	SDL::GetJoystickNameForID (JoystickID instance_id)
	Get the implementation dependent name of a joystick.
const char *	SDL::GetJoystickPathForID (JoystickID instance_id)
	Get the implementation dependent path of a joystick.
int	SDL::GetJoystickPlayerIndexForID (JoystickID instance_id)
	Get the player index of a joystick.
GUID	SDL::GetJoystickGUIDForID (JoystickID instance_id)
	Get the implementation-dependent GUID of a joystick.
Uint16	SDL::GetJoystickVendorForID (JoystickID instance_id)
	Get the USB vendor ID of a joystick, if available.
Uint16	SDL::GetJoystickProductForID (JoystickID instance_id)
	Get the USB product ID of a joystick, if available.
Uint16	SDL::GetJoystickProductVersionForID (JoystickID instance_id)
	Get the product version of a joystick, if available.
JoystickType	SDL::GetJoystickTypeForID (JoystickID instance_id)
	Get the type of a joystick, if available.
Joystick	SDL::OpenJoystick (JoystickID instance_id)
	Open a joystick for use.
JoystickRef	SDL::GetJoystickFromID (JoystickID instance_id)
	Get the Joystick associated with an instance ID, if it has been opened.
JoystickRef	SDL::GetJoystickFromPlayerIndex (int player_index)
	Get the Joystick associated with a player index.
JoystickID	SDL::AttachVirtualJoystick (const VirtualJoystickDesc &desc)
	Attach a new virtual joystick.
void	SDL::DetachVirtualJoystick (JoystickID instance_id)
	Detach a virtual joystick.
bool	SDL::IsJoystickVirtual (JoystickID instance_id)
	Query whether or not a joystick is virtual.
void	SDL::SetJoystickVirtualAxis (JoystickRef joystick, int axis, Sint16 value)
	Set the state of an axis on an opened virtual joystick.
void	SDL::SetJoystickVirtualBall (JoystickRef joystick, int ball, Sint16 xrel, Sint16 yrel)
	Generate ball motion on an opened virtual joystick.
void	SDL::SetJoystickVirtualButton (JoystickRef joystick, int button, bool down)
	Set the state of a button on an opened virtual joystick.
void	SDL::SetJoystickVirtualHat (JoystickRef joystick, int hat, Uint8 value)
	Set the state of a hat on an opened virtual joystick.
void	SDL::SetJoystickVirtualTouchpad (JoystickRef joystick, int touchpad, int finger, bool down, const FPointRaw &p, float pressure)
	Set touchpad finger state on an opened virtual joystick.
void	SDL::SendJoystickVirtualSensorData (JoystickRef joystick, SensorType type, Uint64 sensor_timestamp, const float *data, int num_values)
	Send a sensor update for an opened virtual joystick.
PropertiesRef	SDL::GetJoystickProperties (JoystickRef joystick)
	Get the properties associated with a joystick.
const char *	SDL::GetJoystickName (JoystickRef joystick)
	Get the implementation dependent name of a joystick.
const char *	SDL::GetJoystickPath (JoystickRef joystick)
	Get the implementation dependent path of a joystick.
int	SDL::GetJoystickPlayerIndex (JoystickRef joystick)
	Get the player index of an opened joystick.
void	SDL::SetJoystickPlayerIndex (JoystickRef joystick, int player_index)
	Set the player index of an opened joystick.
GUID	SDL::GetJoystickGUID (JoystickRef joystick)
	Get the implementation-dependent GUID for the joystick.
Uint16	SDL::GetJoystickVendor (JoystickRef joystick)
	Get the USB vendor ID of an opened joystick, if available.
Uint16	SDL::GetJoystickProduct (JoystickRef joystick)
	Get the USB product ID of an opened joystick, if available.
Uint16	SDL::GetJoystickProductVersion (JoystickRef joystick)
	Get the product version of an opened joystick, if available.
Uint16	SDL::GetJoystickFirmwareVersion (JoystickRef joystick)
	Get the firmware version of an opened joystick, if available.
const char *	SDL::GetJoystickSerial (JoystickRef joystick)
	Get the serial number of an opened joystick, if available.
JoystickType	SDL::GetJoystickType (JoystickRef joystick)
	Get the type of an opened joystick.
void	SDL::GetJoystickGUIDInfo (GUID guid, Uint16 vendor, Uint16 product, Uint16 version, Uint16 crc16)
	Get the device information encoded in a GUID structure.
bool	SDL::JoystickConnected (JoystickRef joystick)
	Get the status of a specified joystick.
JoystickID	SDL::GetJoystickID (JoystickRef joystick)
	Get the instance ID of an opened joystick.
int	SDL::GetNumJoystickAxes (JoystickRef joystick)
	Get the number of general axis controls on a joystick.
int	SDL::GetNumJoystickBalls (JoystickRef joystick)
	Get the number of trackballs on a joystick.
int	SDL::GetNumJoystickHats (JoystickRef joystick)
	Get the number of POV hats on a joystick.
int	SDL::GetNumJoystickButtons (JoystickRef joystick)
	Get the number of buttons on a joystick.
void	SDL::SetJoystickEventsEnabled (bool enabled)
	Set the state of joystick event processing.
bool	SDL::JoystickEventsEnabled ()
	Query the state of joystick event processing.
void	SDL::UpdateJoysticks ()
	Update the current state of the open joysticks.
Sint16	SDL::GetJoystickAxis (JoystickRef joystick, int axis)
	Get the current state of an axis control on a joystick.
bool	SDL::GetJoystickAxisInitialState (JoystickRef joystick, int axis, Sint16 *state)
	Get the initial state of an axis control on a joystick.
void	SDL::GetJoystickBall (JoystickRef joystick, int ball, int dx, int dy)
	Get the ball axis change since the last poll.
Uint8	SDL::GetJoystickHat (JoystickRef joystick, int hat)
	Get the current state of a POV hat on a joystick.
bool	SDL::GetJoystickButton (JoystickRef joystick, int button)
	Get the current state of a button on a joystick.
bool	SDL::RumbleJoystick (JoystickRef joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms)
	Start a rumble effect.
void	SDL::RumbleJoystickTriggers (JoystickRef joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms)
	Start a rumble effect in the joystick's triggers.
void	SDL::SetJoystickLED (JoystickRef joystick, Uint8 red, Uint8 green, Uint8 blue)
	Update a joystick's LED color.
void	SDL::SendJoystickEffect (JoystickRef joystick, const void *data, int size)
	Send a joystick specific effect packet.
void	SDL::CloseJoystick (JoystickRaw joystick)
	Close a joystick previously opened with JoystickID.OpenJoystick().
JoystickConnectionState	SDL::GetJoystickConnectionState (JoystickRef joystick)
	Get the connection state of a joystick.
PowerState	SDL::GetJoystickPowerInfo (JoystickRef joystick, int *percent)
	Get the battery state of a joystick.
	SDL::JoystickApiLock::JoystickApiLock ()
	Locking for atomic access to the joystick API.
void	SDL::JoystickApiLock::reset ()
	Unlocking for atomic access to the joystick API.
const char *	SDL::JoystickID::GetJoystickNameForID ()
	Get the implementation dependent name of a joystick.
const char *	SDL::JoystickID::GetJoystickPathForID ()
	Get the implementation dependent path of a joystick.
int	SDL::JoystickID::GetJoystickPlayerIndexForID ()
	Get the player index of a joystick.
GUID	SDL::JoystickID::GetJoystickGUIDForID ()
	Get the implementation-dependent GUID of a joystick.
Uint16	SDL::JoystickID::GetJoystickVendorForID ()
	Get the USB vendor ID of a joystick, if available.
Uint16	SDL::JoystickID::GetJoystickProductForID ()
	Get the USB product ID of a joystick, if available.
Uint16	SDL::JoystickID::GetJoystickProductVersionForID ()
	Get the product version of a joystick, if available.
JoystickType	SDL::JoystickID::GetJoystickTypeForID ()
	Get the type of a joystick, if available.
	SDL::Joystick::Joystick (JoystickID instance_id)
	Open a joystick for use.
Joystick	SDL::JoystickID::OpenJoystick ()
	Open a joystick for use.
JoystickRef	SDL::JoystickID::GetJoystickFromID ()
	Get the Joystick associated with an instance ID, if it has been opened.
void	SDL::JoystickID::DetachVirtualJoystick ()
	Detach a virtual joystick.
bool	SDL::JoystickID::IsJoystickVirtual ()
	Query whether or not a joystick is virtual.
void	SDL::Joystick::SetVirtualAxis (int axis, Sint16 value)
	Set the state of an axis on an opened virtual joystick.
void	SDL::Joystick::SetVirtualBall (int ball, Sint16 xrel, Sint16 yrel)
	Generate ball motion on an opened virtual joystick.
void	SDL::Joystick::SetVirtualButton (int button, bool down)
	Set the state of a button on an opened virtual joystick.
void	SDL::Joystick::SetVirtualHat (int hat, Uint8 value)
	Set the state of a hat on an opened virtual joystick.
void	SDL::Joystick::SetVirtualTouchpad (int touchpad, int finger, bool down, const FPointRaw &p, float pressure)
	Set touchpad finger state on an opened virtual joystick.
void	SDL::Joystick::SendVirtualSensorData (SensorType type, Uint64 sensor_timestamp, const float *data, int num_values)
	Send a sensor update for an opened virtual joystick.
PropertiesRef	SDL::Joystick::GetProperties ()
	Get the properties associated with a joystick.
const char *	SDL::Joystick::GetName ()
	Get the implementation dependent name of a joystick.
const char *	SDL::Joystick::GetPath ()
	Get the implementation dependent path of a joystick.
int	SDL::Joystick::GetPlayerIndex ()
	Get the player index of an opened joystick.
void	SDL::Joystick::SetPlayerIndex (int player_index)
	Set the player index of an opened joystick.
GUID	SDL::Joystick::GetGUID ()
	Get the implementation-dependent GUID for the joystick.
Uint16	SDL::Joystick::GetVendor ()
	Get the USB vendor ID of an opened joystick, if available.
Uint16	SDL::Joystick::GetProduct ()
	Get the USB product ID of an opened joystick, if available.
Uint16	SDL::Joystick::GetProductVersion ()
	Get the product version of an opened joystick, if available.
Uint16	SDL::Joystick::GetFirmwareVersion ()
	Get the firmware version of an opened joystick, if available.
const char *	SDL::Joystick::GetSerial ()
	Get the serial number of an opened joystick, if available.
JoystickType	SDL::Joystick::GetType ()
	Get the type of an opened joystick.
bool	SDL::Joystick::Connected ()
	Get the status of a specified joystick.
JoystickID	SDL::Joystick::GetID ()
	Get the instance ID of an opened joystick.
int	SDL::Joystick::GetNumAxes ()
	Get the number of general axis controls on a joystick.
int	SDL::Joystick::GetNumBalls ()
	Get the number of trackballs on a joystick.
int	SDL::Joystick::GetNumHats ()
	Get the number of POV hats on a joystick.
int	SDL::Joystick::GetNumButtons ()
	Get the number of buttons on a joystick.
Sint16	SDL::Joystick::GetAxis (int axis)
	Get the current state of an axis control on a joystick.
bool	SDL::Joystick::GetAxisInitialState (int axis, Sint16 *state)
	Get the initial state of an axis control on a joystick.
void	SDL::Joystick::GetBall (int ball, int dx, int dy)
	Get the ball axis change since the last poll.
Uint8	SDL::Joystick::GetHat (int hat)
	Get the current state of a POV hat on a joystick.
bool	SDL::Joystick::GetButton (int button)
	Get the current state of a button on a joystick.
bool	SDL::Joystick::Rumble (Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms)
	Start a rumble effect.
void	SDL::Joystick::RumbleTriggers (Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms)
	Start a rumble effect in the joystick's triggers.
void	SDL::Joystick::SetLED (Uint8 red, Uint8 green, Uint8 blue)
	Update a joystick's LED color.
void	SDL::Joystick::SendEffect (const void *data, int size)
	Send a joystick specific effect packet.
void	SDL::Joystick::Close ()
	Close a joystick previously opened with JoystickID.OpenJoystick().
JoystickConnectionState	SDL::Joystick::GetConnectionState ()
	Get the connection state of a joystick.
PowerState	SDL::Joystick::GetPowerInfo (int *percent)
	Get the battery state of a joystick.

Variables
constexpr JoystickType	SDL::JOYSTICK_TYPE_UNKNOWN
	JOYSTICK_TYPE_UNKNOWN.
constexpr JoystickType	SDL::JOYSTICK_TYPE_GAMEPAD
	JOYSTICK_TYPE_GAMEPAD.
constexpr JoystickType	SDL::JOYSTICK_TYPE_WHEEL
	JOYSTICK_TYPE_WHEEL.
constexpr JoystickType	SDL::JOYSTICK_TYPE_ARCADE_STICK
	JOYSTICK_TYPE_ARCADE_STICK.
constexpr JoystickType	SDL::JOYSTICK_TYPE_FLIGHT_STICK
	JOYSTICK_TYPE_FLIGHT_STICK.
constexpr JoystickType	SDL::JOYSTICK_TYPE_DANCE_PAD
	JOYSTICK_TYPE_DANCE_PAD.
constexpr JoystickType	SDL::JOYSTICK_TYPE_GUITAR
	JOYSTICK_TYPE_GUITAR.
constexpr JoystickType	SDL::JOYSTICK_TYPE_DRUM_KIT
	JOYSTICK_TYPE_DRUM_KIT.
constexpr JoystickType	SDL::JOYSTICK_TYPE_ARCADE_PAD
	JOYSTICK_TYPE_ARCADE_PAD.
constexpr JoystickType	SDL::JOYSTICK_TYPE_THROTTLE
	JOYSTICK_TYPE_THROTTLE.
constexpr JoystickType	SDL::JOYSTICK_TYPE_COUNT
	JOYSTICK_TYPE_COUNT.
constexpr JoystickConnectionState	SDL::JOYSTICK_CONNECTION_INVALID
	JOYSTICK_CONNECTION_INVALID.
constexpr JoystickConnectionState	SDL::JOYSTICK_CONNECTION_UNKNOWN
	JOYSTICK_CONNECTION_UNKNOWN.
constexpr JoystickConnectionState	SDL::JOYSTICK_CONNECTION_WIRED
	JOYSTICK_CONNECTION_WIRED.
constexpr JoystickConnectionState	SDL::JOYSTICK_CONNECTION_WIRELESS
	JOYSTICK_CONNECTION_WIRELESS.
constexpr Uint8	SDL::HAT_CENTERED = SDL_HAT_CENTERED
	CENTERED.
constexpr Uint8	SDL::HAT_UP = SDL_HAT_UP
	UP.
constexpr Uint8	SDL::HAT_RIGHT = SDL_HAT_RIGHT
	RIGHT.
constexpr Uint8	SDL::HAT_DOWN = SDL_HAT_DOWN
	DOWN.
constexpr Uint8	SDL::HAT_LEFT = SDL_HAT_LEFT
	LEFT.
constexpr Uint8	SDL::HAT_RIGHTUP = SDL_HAT_RIGHTUP
	RIGHTUP.
constexpr Uint8	SDL::HAT_RIGHTDOWN = SDL_HAT_RIGHTDOWN
	RIGHTDOWN.
constexpr Uint8	SDL::HAT_LEFTUP = SDL_HAT_LEFTUP
	LEFTUP.
constexpr Uint8	SDL::HAT_LEFTDOWN = SDL_HAT_LEFTDOWN
	LEFTDOWN.
constexpr int	SDL::JOYSTICK_AXIS_MAX = SDL_JOYSTICK_AXIS_MAX
	The largest value an Joystick's axis can report.
constexpr int	SDL::JOYSTICK_AXIS_MIN = SDL_JOYSTICK_AXIS_MIN
	The smallest value an Joystick's axis can report.

Detailed Description

SDL joystick support.

This is the lower-level joystick handling. If you want the simpler option, where what each button does 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.

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, Init() must have been called with the 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 Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS

SDL can provide virtual joysticks as well: the app defines an imaginary controller with AttachVirtualJoystick(), and then can provide inputs for it via Joystick.SetVirtualAxis(), Joystick.SetVirtualButton(), etc. As this data is supplied, it will look like a normal joystick to SDL, just not backed by a hardware driver. This has been used to make unusual devices, like VR headset controllers, look like normal joysticks, or provide recording/playback of game inputs, etc.

Typedef Documentation

◆ JoystickConnectionState

using SDL::JoystickConnectionState = SDL_JoystickConnectionState

Possible connection states for a joystick device.

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

Since: This enum is available since SDL 3.2.0.

◆ JoystickRef

using SDL::JoystickRef = ResourceRef<Joystick>

Reference for Joystick.

This does not take ownership!

◆ JoystickType

using SDL::JoystickType = 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 Joystick.GetType (or JoystickID.GetJoystickTypeForID).

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

You may refer to XInput Controller Types table for a general understanding of each joystick type.

Since: This enum is available since SDL 3.2.0.

◆ VirtualJoystickDesc

using SDL::VirtualJoystickDesc = SDL_VirtualJoystickDesc

The structure that describes a virtual joystick.

This structure should be initialized using InitInterface(). All elements of this structure are optional.

Since: This struct is available since SDL 3.2.0.

See also: AttachVirtualJoystick; InitInterface; VirtualJoystickSensorDesc; VirtualJoystickTouchpadDesc

◆ VirtualJoystickSensorDesc

using SDL::VirtualJoystickSensorDesc = SDL_VirtualJoystickSensorDesc

The structure that describes a virtual joystick sensor.

Since: This struct is available since SDL 3.2.0.

See also: VirtualJoystickDesc

◆ VirtualJoystickTouchpadDesc

using SDL::VirtualJoystickTouchpadDesc = SDL_VirtualJoystickTouchpadDesc

The structure that describes a virtual joystick touchpad.

Since: This struct is available since SDL 3.2.0.

See also: VirtualJoystickDesc

Function Documentation

◆ AttachVirtualJoystick()

JoystickID SDL::AttachVirtualJoystick ( const VirtualJoystickDesc & desc )

inline

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 Joystick.SetVirtualAxis(), etc.

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

Parameters

desc	joystick description, initialized using InitInterface().

Returns: the joystick instance ID on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: DetachVirtualJoystick; Joystick.SetVirtualAxis; Joystick.SetVirtualButton; Joystick.SetVirtualBall; Joystick.SetVirtualHat; Joystick.SetVirtualTouchpad; SDL_SetJoystickVirtualSensorData

◆ Close()

void SDL::Joystick::Close ( )

inline

Close a joystick previously opened with JoystickID.OpenJoystick().

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.OpenJoystick

◆ CloseJoystick()

void SDL::CloseJoystick ( JoystickRaw joystick )

inline

Close a joystick previously opened with JoystickID.OpenJoystick().

Parameters

joystick the joystick device to close.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.OpenJoystick

◆ Connected()

bool SDL::Joystick::Connected ( )

inline

Get the status of a specified joystick.

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ DetachVirtualJoystick() [1/2]

void SDL::DetachVirtualJoystick ( JoystickID instance_id )

inline

Detach a virtual joystick.

Parameters

instance_id the joystick instance ID, previously returned from AttachVirtualJoystick().

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AttachVirtualJoystick

◆ DetachVirtualJoystick() [2/2]

void SDL::JoystickID::DetachVirtualJoystick ( )

inline

Detach a virtual joystick.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: AttachVirtualJoystick

◆ GetAxis()

Sint16 SDL::Joystick::GetAxis ( int axis )

inline

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 Joystick.GetAxis() 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

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 GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumAxes

◆ GetAxisInitialState()

bool SDL::Joystick::GetAxisInitialState	(	int	axis,
		Sint16 *	state )

inline

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

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.

Since: This function is available since SDL 3.2.0.

◆ GetBall()

void SDL::Joystick::GetBall	(	int	ball,
		int *	dx,
		int *	dy )

inline

Get the ball axis change since the last poll.

Trackballs can only return relative motion since the last call to Joystick.GetBall(), these motion deltas are placed into dx and dy.

Most joysticks do not have trackballs.

Parameters

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.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumBalls

◆ GetButton()

bool SDL::Joystick::GetButton ( int button )

inline

Get the current state of a button on a joystick.

Parameters

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumButtons

◆ GetConnectionState()

JoystickConnectionState SDL::Joystick::GetConnectionState ( )

inline

Get the connection state of a joystick.

Returns: the connection state on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetFirmwareVersion()

Uint16 SDL::Joystick::GetFirmwareVersion ( )

inline

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

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

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetGUID()

GUID SDL::Joystick::GetGUID ( )

inline

Get the implementation-dependent GUID for the joystick.

This function requires an open joystick.

Returns: the GUID of the given joystick. If called on an invalid index, this function returns a zero GUID; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickGUIDForID; GUID.ToString

◆ GetHat()

Uint8 SDL::Joystick::GetHat ( int hat )

inline

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

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

Parameters

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumHats

◆ GetID()

JoystickID SDL::Joystick::GetID ( )

inline

Get the instance ID of an opened joystick.

Returns: the instance ID of the specified joystick on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickAxis()

Sint16 SDL::GetJoystickAxis	(	JoystickRef	joystick,
		int	axis )

inline

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 Joystick.GetAxis() is a signed integer (-32768 to 32767) representing the current position of the axis. It may be necessary to impose certain tolerances on these values to account for jitter.

Parameters

joystick	an 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 GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumAxes

◆ GetJoystickAxisInitialState()

bool SDL::GetJoystickAxisInitialState	(	JoystickRef	joystick,
		int	axis,
		Sint16 *	state )

inline

Get the initial state of an axis control on a joystick.

The state is a value ranging from -32768 to 32767.

The axis indices start at index 0.

Parameters

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

Since: This function is available since SDL 3.2.0.

◆ GetJoystickBall()

void SDL::GetJoystickBall	(	JoystickRef	joystick,
		int	ball,
		int *	dx,
		int *	dy )

inline

Get the ball axis change since the last poll.

Trackballs can only return relative motion since the last call to Joystick.GetBall(), these motion deltas are placed into dx and dy.

Most joysticks do not have trackballs.

Parameters

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

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumBalls

◆ GetJoystickButton()

bool SDL::GetJoystickButton	(	JoystickRef	joystick,
		int	button )

inline

Get the current state of a button on a joystick.

Parameters

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

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumButtons

◆ GetJoystickConnectionState()

JoystickConnectionState SDL::GetJoystickConnectionState ( JoystickRef joystick )

inline

Get the connection state of a joystick.

Parameters

joystick the joystick to query.

Returns: the connection state on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickFirmwareVersion()

Uint16 SDL::GetJoystickFirmwareVersion ( JoystickRef joystick )

inline

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

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

Parameters

joystick the Joystick obtained from JoystickID.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.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickFromID() [1/2]

JoystickRef SDL::GetJoystickFromID ( JoystickID instance_id )

inline

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

Parameters

instance_id the instance ID to get the Joystick for.

Returns: an Joystick on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickFromID() [2/2]

JoystickRef SDL::JoystickID::GetJoystickFromID ( )

inline

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

Returns: an Joystick on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickFromPlayerIndex()

JoystickRef SDL::GetJoystickFromPlayerIndex ( int player_index )

inline

Get the Joystick associated with a player index.

Parameters

player_index the player index to get the Joystick for.

Returns: an Joystick on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPlayerIndex; Joystick.SetPlayerIndex

◆ GetJoystickGUID()

GUID SDL::GetJoystickGUID ( JoystickRef joystick )

inline

Get the implementation-dependent GUID for the joystick.

This function requires an open joystick.

Parameters

joystick the Joystick obtained from JoystickID.OpenJoystick().

Returns: the GUID of the given joystick. If called on an invalid index, this function returns a zero GUID; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickGUIDForID; GUID.ToString

◆ GetJoystickGUIDForID() [1/2]

GUID SDL::GetJoystickGUIDForID ( JoystickID instance_id )

inline

Get the implementation-dependent GUID of a joystick.

This can be called before any joysticks are opened.

Parameters

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetGUID; GUID.ToString

◆ GetJoystickGUIDForID() [2/2]

GUID SDL::JoystickID::GetJoystickGUIDForID ( )

inline

Get the implementation-dependent GUID of a joystick.

This can be called before any joysticks are opened.

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetGUID; GUID.ToString

◆ GetJoystickGUIDInfo()

void SDL::GetJoystickGUIDInfo	(	GUID	guid,
		Uint16 *	vendor,
		Uint16 *	product,
		Uint16 *	version,
		Uint16 *	crc16 )

inline

Get the device information encoded in a GUID structure.

Parameters

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

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickGUIDForID

◆ GetJoystickHat()

Uint8 SDL::GetJoystickHat	(	JoystickRef	joystick,
		int	hat )

inline

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

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

Parameters

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

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumHats

◆ GetJoystickID()

JoystickID SDL::GetJoystickID ( JoystickRef joystick )

inline

Get the instance ID of an opened joystick.

Parameters

joystick an Joystick structure containing joystick information.

Returns: the instance ID of the specified joystick on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickName()

const char * SDL::GetJoystickName ( JoystickRef joystick )

inline

Get the implementation dependent name of a joystick.

Parameters

joystick the Joystick obtained from JoystickID.OpenJoystick().

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickNameForID

◆ GetJoystickNameForID() [1/2]

const char * SDL::GetJoystickNameForID ( JoystickID instance_id )

inline

Get the implementation dependent name of a joystick.

This can be called before any joysticks are opened.

Parameters

instance_id the joystick instance ID.

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetName; GetJoysticks

◆ GetJoystickNameForID() [2/2]

const char * SDL::JoystickID::GetJoystickNameForID ( )

inline

Get the implementation dependent name of a joystick.

This can be called before any joysticks are opened.

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetName; GetJoysticks

◆ GetJoystickPath()

const char * SDL::GetJoystickPath ( JoystickRef joystick )

inline

Get the implementation dependent path of a joystick.

Parameters

joystick the Joystick obtained from JoystickID.OpenJoystick().

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickPathForID

◆ GetJoystickPathForID() [1/2]

const char * SDL::GetJoystickPathForID ( JoystickID instance_id )

inline

Get the implementation dependent path of a joystick.

This can be called before any joysticks are opened.

Parameters

instance_id the joystick instance ID.

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPath; GetJoysticks

◆ GetJoystickPathForID() [2/2]

const char * SDL::JoystickID::GetJoystickPathForID ( )

inline

Get the implementation dependent path of a joystick.

This can be called before any joysticks are opened.

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPath; GetJoysticks

◆ GetJoystickPlayerIndex()

int SDL::GetJoystickPlayerIndex ( JoystickRef joystick )

inline

Get the player index of an opened joystick.

For XInput controllers this returns the XInput user index. Many joysticks will not be able to supply this information.

Parameters

joystick the Joystick obtained from JoystickID.OpenJoystick().

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetPlayerIndex

◆ GetJoystickPlayerIndexForID() [1/2]

int SDL::GetJoystickPlayerIndexForID ( JoystickID instance_id )

inline

Get the player index of a joystick.

This can be called before any joysticks are opened.

Parameters

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPlayerIndex; GetJoysticks

◆ GetJoystickPlayerIndexForID() [2/2]

int SDL::JoystickID::GetJoystickPlayerIndexForID ( )

inline

Get the player index of a joystick.

This can be called before any joysticks are opened.

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPlayerIndex; GetJoysticks

◆ GetJoystickPowerInfo()

PowerState SDL::GetJoystickPowerInfo	(	JoystickRef	joystick,
		int *	percent )

inline

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

joystick	the joystick to query.
percent	a pointer filled in with the percentage of battery life left, between 0 and 100, or nullptr 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 POWERSTATE_ERROR on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickProduct()

Uint16 SDL::GetJoystickProduct ( JoystickRef joystick )

inline

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

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

Parameters

joystick the Joystick obtained from JoystickID.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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickProductForID

◆ GetJoystickProductForID() [1/2]

Uint16 SDL::GetJoystickProductForID ( JoystickID instance_id )

inline

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

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetProduct; GetJoysticks

◆ GetJoystickProductForID() [2/2]

Uint16 SDL::JoystickID::GetJoystickProductForID ( )

inline

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.

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetProduct; GetJoysticks

◆ GetJoystickProductVersion()

Uint16 SDL::GetJoystickProductVersion ( JoystickRef joystick )

inline

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

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

Parameters

joystick the Joystick obtained from JoystickID.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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickProductVersionForID

◆ GetJoystickProductVersionForID() [1/2]

Uint16 SDL::GetJoystickProductVersionForID ( JoystickID instance_id )

inline

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

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetProductVersion; GetJoysticks

◆ GetJoystickProductVersionForID() [2/2]

Uint16 SDL::JoystickID::GetJoystickProductVersionForID ( )

inline

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.

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetProductVersion; GetJoysticks

◆ GetJoystickProperties()

PropertiesRef SDL::GetJoystickProperties ( JoystickRef joystick )

inline

Get the properties associated with a joystick.

The following read-only properties are provided by SDL:

prop.JoystickCap.MONO_LED_BOOLEAN: true if this joystick has an LED that has adjustable brightness
prop.JoystickCap.RGB_LED_BOOLEAN: true if this joystick has an LED that has adjustable color
prop.JoystickCap.PLAYER_LED_BOOLEAN: true if this joystick has a player LED
prop.JoystickCap.RUMBLE_BOOLEAN: true if this joystick has left/right rumble
prop.JoystickCap.TRIGGER_RUMBLE_BOOLEAN: true if this joystick has simple trigger rumble

Parameters

joystick the Joystick obtained from JoystickID.OpenJoystick().

Returns: a valid property ID on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetJoysticks()

OwnArray< JoystickID > SDL::GetJoysticks ( )

inline

Get a list of currently connected joysticks.

Returns: a 0 terminated array of joystick instance IDs or nullptr on failure; call GetError() for more information. This should be freed with free() when it is no longer needed.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: HasJoystick; JoystickID.OpenJoystick

◆ GetJoystickSerial()

const char * SDL::GetJoystickSerial ( JoystickRef joystick )

inline

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

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

Parameters

joystick the Joystick obtained from JoystickID.OpenJoystick().

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickType()

JoystickType SDL::GetJoystickType ( JoystickRef joystick )

inline

Get the type of an opened joystick.

Parameters

joystick the Joystick obtained from JoystickID.OpenJoystick().

Returns: the JoystickType of the selected joystick.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickTypeForID

◆ GetJoystickTypeForID() [1/2]

JoystickType SDL::GetJoystickTypeForID ( JoystickID instance_id )

inline

Get the type of a joystick, if available.

This can be called before any joysticks are opened.

Parameters

instance_id the joystick instance ID.

Returns: the JoystickType of the selected joystick. If called with an invalid instance_id, this function returns JOYSTICK_TYPE_UNKNOWN.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetType; GetJoysticks

◆ GetJoystickTypeForID() [2/2]

JoystickType SDL::JoystickID::GetJoystickTypeForID ( )

inline

Get the type of a joystick, if available.

This can be called before any joysticks are opened.

Returns: the JoystickType of the selected joystick. If called with an invalid instance_id, this function returns JOYSTICK_TYPE_UNKNOWN.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetType; GetJoysticks

◆ GetJoystickVendor()

Uint16 SDL::GetJoystickVendor ( JoystickRef joystick )

inline

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

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

Parameters

joystick the Joystick obtained from JoystickID.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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickVendorForID

◆ GetJoystickVendorForID() [1/2]

Uint16 SDL::GetJoystickVendorForID ( JoystickID instance_id )

inline

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

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetVendor; GetJoysticks

◆ GetJoystickVendorForID() [2/2]

Uint16 SDL::JoystickID::GetJoystickVendorForID ( )

inline

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.

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetVendor; GetJoysticks

◆ GetName()

const char * SDL::Joystick::GetName ( )

inline

Get the implementation dependent name of a joystick.

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickNameForID

◆ GetNumAxes()

int SDL::Joystick::GetNumAxes ( )

inline

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.

Returns: the number of axis controls/number of axes on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetAxis; Joystick.GetNumBalls; Joystick.GetNumButtons; Joystick.GetNumHats

◆ GetNumBalls()

int SDL::Joystick::GetNumBalls ( )

inline

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.

Returns: the number of trackballs on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetBall; Joystick.GetNumAxes; Joystick.GetNumButtons; Joystick.GetNumHats

◆ GetNumButtons()

int SDL::Joystick::GetNumButtons ( )

inline

Get the number of buttons on a joystick.

Returns: the number of buttons on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetButton; Joystick.GetNumAxes; Joystick.GetNumBalls; Joystick.GetNumHats

◆ GetNumHats()

int SDL::Joystick::GetNumHats ( )

inline

Get the number of POV hats on a joystick.

Returns: the number of POV hats on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetHat; Joystick.GetNumAxes; Joystick.GetNumBalls; Joystick.GetNumButtons

◆ GetNumJoystickAxes()

int SDL::GetNumJoystickAxes ( JoystickRef joystick )

inline

Get the number of general axis controls on a joystick.

Often, the directional pad on a game controller will either look like 4 separate buttons or a POV hat, and not axes, but all of this is up to the device and platform.

Parameters

joystick an Joystick structure containing joystick information.

Returns: the number of axis controls/number of axes on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetAxis; Joystick.GetNumBalls; Joystick.GetNumButtons; Joystick.GetNumHats

◆ GetNumJoystickBalls()

int SDL::GetNumJoystickBalls ( JoystickRef joystick )

inline

Get the number of trackballs on a joystick.

Joystick trackballs have only relative motion events associated with them and their state cannot be polled.

Most joysticks do not have trackballs.

Parameters

joystick an Joystick structure containing joystick information.

Returns: the number of trackballs on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetBall; Joystick.GetNumAxes; Joystick.GetNumButtons; Joystick.GetNumHats

◆ GetNumJoystickButtons()

int SDL::GetNumJoystickButtons ( JoystickRef joystick )

inline

Get the number of buttons on a joystick.

Parameters

joystick an Joystick structure containing joystick information.

Returns: the number of buttons on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetButton; Joystick.GetNumAxes; Joystick.GetNumBalls; Joystick.GetNumHats

◆ GetNumJoystickHats()

int SDL::GetNumJoystickHats ( JoystickRef joystick )

inline

Get the number of POV hats on a joystick.

Parameters

joystick an Joystick structure containing joystick information.

Returns: the number of POV hats on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetHat; Joystick.GetNumAxes; Joystick.GetNumBalls; Joystick.GetNumButtons

◆ GetPath()

const char * SDL::Joystick::GetPath ( )

inline

Get the implementation dependent path of a joystick.

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickPathForID

◆ GetPlayerIndex()

int SDL::Joystick::GetPlayerIndex ( )

inline

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.

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetPlayerIndex

◆ GetPowerInfo()

PowerState SDL::Joystick::GetPowerInfo ( int * percent )

inline

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

percent a pointer filled in with the percentage of battery life left, between 0 and 100, or nullptr 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 POWERSTATE_ERROR on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetProduct()

Uint16 SDL::Joystick::GetProduct ( )

inline

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

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

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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickProductForID

◆ GetProductVersion()

Uint16 SDL::Joystick::GetProductVersion ( )

inline

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

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

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickProductVersionForID

◆ GetProperties()

PropertiesRef SDL::Joystick::GetProperties ( )

inline

Get the properties associated with a joystick.

The following read-only properties are provided by SDL:

prop.JoystickCap.MONO_LED_BOOLEAN: true if this joystick has an LED that has adjustable brightness
prop.JoystickCap.RGB_LED_BOOLEAN: true if this joystick has an LED that has adjustable color
prop.JoystickCap.PLAYER_LED_BOOLEAN: true if this joystick has a player LED
prop.JoystickCap.RUMBLE_BOOLEAN: true if this joystick has left/right rumble
prop.JoystickCap.TRIGGER_RUMBLE_BOOLEAN: true if this joystick has simple trigger rumble

Returns: a valid property ID on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetSerial()

const char * SDL::Joystick::GetSerial ( )

inline

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

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

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetType()

JoystickType SDL::Joystick::GetType ( )

inline

Get the type of an opened joystick.

Returns: the JoystickType of the selected joystick.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickTypeForID

◆ GetVendor()

Uint16 SDL::Joystick::GetVendor ( )

inline

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

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

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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickVendorForID

◆ HasJoystick()

bool SDL::HasJoystick ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: GetJoysticks

◆ IsJoystickVirtual() [1/2]

bool SDL::IsJoystickVirtual ( JoystickID instance_id )

inline

Query whether or not a joystick is virtual.

Parameters

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.

Since: This function is available since SDL 3.2.0.

◆ IsJoystickVirtual() [2/2]

bool SDL::JoystickID::IsJoystickVirtual ( )

inline

Query whether or not a joystick is virtual.

Returns: true if the joystick is virtual, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ Joystick()

SDL::Joystick::Joystick ( JoystickID instance_id )

inline

Open a joystick for use.

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

Parameters

instance_id the joystick instance ID.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.Close

◆ JoystickApiLock()

SDL::JoystickApiLock::JoystickApiLock ( )

inline

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.

Since: This function is available since SDL 3.2.0.

◆ JoystickConnected()

bool SDL::JoystickConnected ( JoystickRef joystick )

inline

Get the status of a specified joystick.

Parameters

joystick the joystick to query.

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ JoystickEventsEnabled()

bool SDL::JoystickEventsEnabled ( )

inline

Query the state of joystick event processing.

If joystick events are disabled, you must call 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.

Since: This function is available since SDL 3.2.0.

See also: SetJoystickEventsEnabled

◆ LockJoysticks()

void SDL::LockJoysticks ( )

inline

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.

Since: This function is available since SDL 3.2.0.

◆ OpenJoystick() [1/2]

Joystick SDL::JoystickID::OpenJoystick ( )

inline

Open a joystick for use.

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

Returns: an Joystick on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.Close

◆ OpenJoystick() [2/2]

Joystick SDL::OpenJoystick ( JoystickID instance_id )

inline

Open a joystick for use.

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

Parameters

instance_id the joystick instance ID.

Returns: an Joystick on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.Close

◆ reset()

void SDL::JoystickApiLock::reset ( )

inline

Unlocking for atomic access to the joystick API.

Thread safety:: This should be called from the same thread that called LockJoysticks().

Since: This function is available since SDL 3.2.0.

◆ Rumble()

bool SDL::Joystick::Rumble	(	Uint16	low_frequency_rumble,
		Uint16	high_frequency_rumble,
		Uint32	duration_ms )

inline

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 UpdateJoysticks() to update rumble state.

Parameters

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.

Since: This function is available since SDL 3.2.0.

◆ RumbleJoystick()

bool SDL::RumbleJoystick	(	JoystickRef	joystick,
		Uint16	low_frequency_rumble,
		Uint16	high_frequency_rumble,
		Uint32	duration_ms )

inline

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 UpdateJoysticks() to update rumble state.

Parameters

joystick	the joystick to vibrate.
low_frequency_rumble	the intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF.
high_frequency_rumble	the intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF.
duration_ms	the duration of the rumble effect, in milliseconds.

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

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ RumbleJoystickTriggers()

void SDL::RumbleJoystickTriggers	(	JoystickRef	joystick,
		Uint16	left_rumble,
		Uint16	right_rumble,
		Uint32	duration_ms )

inline

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 Joystick.Rumble() instead.

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

Parameters

joystick	the joystick to vibrate.
left_rumble	the intensity of the left trigger rumble motor, from 0 to 0xFFFF.
right_rumble	the intensity of the right trigger rumble motor, from 0 to 0xFFFF.
duration_ms	the duration of the rumble effect, in milliseconds.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.Rumble

◆ RumbleTriggers()

void SDL::Joystick::RumbleTriggers	(	Uint16	left_rumble,
		Uint16	right_rumble,
		Uint32	duration_ms )

inline

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 Joystick.Rumble() instead.

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

Parameters

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.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.Rumble

◆ SendEffect()

void SDL::Joystick::SendEffect	(	const void *	data,
		int	size )

inline

Send a joystick specific effect packet.

Parameters

data	the data to send to the joystick.
size	the size of the data to send to the joystick.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ SendJoystickEffect()

void SDL::SendJoystickEffect	(	JoystickRef	joystick,
		const void *	data,
		int	size )

inline

Send a joystick specific effect packet.

Parameters

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

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ SendJoystickVirtualSensorData()

void SDL::SendJoystickVirtualSensorData	(	JoystickRef	joystick,
		SensorType	type,
		Uint64	sensor_timestamp,
		const float *	data,
		int	num_values )

inline

Send a sensor update for an opened virtual joystick.

Please note that values set here will not be applied until the next call to UpdateJoysticks, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: PollEvent, PumpEvents, WaitEventTimeout, WaitEvent.

Parameters

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.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetVirtualAxis; Joystick.SetVirtualButton; Joystick.SetVirtualBall; Joystick.SetVirtualHat; Joystick.SetVirtualTouchpad

◆ SendVirtualSensorData()

void SDL::Joystick::SendVirtualSensorData	(	SensorType	type,
		Uint64	sensor_timestamp,
		const float *	data,
		int	num_values )

inline

Send a sensor update for an opened virtual joystick.

Please note that values set here will not be applied until the next call to UpdateJoysticks, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: PollEvent, PumpEvents, WaitEventTimeout, WaitEvent.

Parameters

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.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetVirtualAxis; Joystick.SetVirtualButton; Joystick.SetVirtualBall; Joystick.SetVirtualHat; Joystick.SetVirtualTouchpad

◆ SetJoystickEventsEnabled()

void SDL::SetJoystickEventsEnabled ( bool enabled )

inline

Set the state of joystick event processing.

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

Parameters

enabled whether to process joystick events or not.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: JoystickEventsEnabled; UpdateJoysticks

◆ SetJoystickLED()

void SDL::SetJoystickLED	(	JoystickRef	joystick,
		Uint8	red,
		Uint8	green,
		Uint8	blue )

inline

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

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.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ SetJoystickPlayerIndex()

void SDL::SetJoystickPlayerIndex	(	JoystickRef	joystick,
		int	player_index )

inline

Set the player index of an opened joystick.

Parameters

joystick	the Joystick obtained from JoystickID.OpenJoystick().
player_index	player index to assign to this joystick, or -1 to clear the player index and turn off player LEDs.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPlayerIndex

◆ SetJoystickVirtualAxis()

void SDL::SetJoystickVirtualAxis	(	JoystickRef	joystick,
		int	axis,
		Sint16	value )

inline

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 UpdateJoysticks, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: PollEvent, PumpEvents, WaitEventTimeout, 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 JOYSTICK_AXIS_MIN.

Parameters

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.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetVirtualButton; Joystick.SetVirtualBall; Joystick.SetVirtualHat; Joystick.SetVirtualTouchpad; SDL_SetJoystickVirtualSensorData

◆ SetJoystickVirtualBall()

void SDL::SetJoystickVirtualBall	(	JoystickRef	joystick,
		int	ball,
		Sint16	xrel,
		Sint16	yrel )

inline

Generate ball motion on an opened virtual joystick.

Please note that values set here will not be applied until the next call to UpdateJoysticks, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: PollEvent, PumpEvents, WaitEventTimeout, WaitEvent.

Parameters

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.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetVirtualAxis; Joystick.SetVirtualButton; Joystick.SetVirtualHat; Joystick.SetVirtualTouchpad; SDL_SetJoystickVirtualSensorData

◆ SetJoystickVirtualButton()

void SDL::SetJoystickVirtualButton	(	JoystickRef	joystick,
		int	button,
		bool	down )

inline

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 UpdateJoysticks, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: PollEvent, PumpEvents, WaitEventTimeout, WaitEvent.

Parameters

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.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetVirtualAxis; Joystick.SetVirtualBall; Joystick.SetVirtualHat; Joystick.SetVirtualTouchpad; SDL_SetJoystickVirtualSensorData

◆ SetJoystickVirtualHat()

void SDL::SetJoystickVirtualHat	(	JoystickRef	joystick,
		int	hat,
		Uint8	value )

inline

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 UpdateJoysticks, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: PollEvent, PumpEvents, WaitEventTimeout, WaitEvent.

Parameters

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.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetVirtualAxis; Joystick.SetVirtualButton; Joystick.SetVirtualBall; Joystick.SetVirtualTouchpad; SDL_SetJoystickVirtualSensorData

◆ SetJoystickVirtualTouchpad()

void SDL::SetJoystickVirtualTouchpad	(	JoystickRef	joystick,
		int	touchpad,
		int	finger,
		bool	down,
		const FPointRaw &	p,
		float	pressure )

inline

Set touchpad finger state on an opened virtual joystick.

Please note that values set here will not be applied until the next call to UpdateJoysticks, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: PollEvent, PumpEvents, WaitEventTimeout, WaitEvent.

Parameters

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.
p	the x, y coordinates of the finger on the touchpad, normalized 0 to 1, with the origin in the upper left.
pressure	the pressure of the finger.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetVirtualAxis; Joystick.SetVirtualButton; Joystick.SetVirtualBall; Joystick.SetVirtualHat; SDL_SetJoystickVirtualSensorData

◆ SetLED()

void SDL::Joystick::SetLED	(	Uint8	red,
		Uint8	green,
		Uint8	blue )

inline

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

red	the intensity of the red LED.
green	the intensity of the green LED.
blue	the intensity of the blue LED.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ SetPlayerIndex()

void SDL::Joystick::SetPlayerIndex ( int player_index )

inline

Set the player index of an opened joystick.

Parameters

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

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPlayerIndex

◆ SetVirtualAxis()

void SDL::Joystick::SetVirtualAxis	(	int	axis,
		Sint16	value )

inline

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 UpdateJoysticks, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: PollEvent, PumpEvents, WaitEventTimeout, 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 JOYSTICK_AXIS_MIN.

Parameters

axis	the index of the axis on the virtual joystick to update.
value	the new value for the specified axis.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetVirtualButton; Joystick.SetVirtualBall; Joystick.SetVirtualHat; Joystick.SetVirtualTouchpad; SDL_SetJoystickVirtualSensorData

◆ SetVirtualBall()

void SDL::Joystick::SetVirtualBall	(	int	ball,
		Sint16	xrel,
		Sint16	yrel )

inline

Generate ball motion on an opened virtual joystick.

Please note that values set here will not be applied until the next call to UpdateJoysticks, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: PollEvent, PumpEvents, WaitEventTimeout, WaitEvent.

Parameters

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.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetVirtualAxis; Joystick.SetVirtualButton; Joystick.SetVirtualHat; Joystick.SetVirtualTouchpad; SDL_SetJoystickVirtualSensorData

◆ SetVirtualButton()

void SDL::Joystick::SetVirtualButton	(	int	button,
		bool	down )

inline

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 UpdateJoysticks, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: PollEvent, PumpEvents, WaitEventTimeout, WaitEvent.

Parameters

button	the index of the button on the virtual joystick to update.
down	true if the button is pressed, false otherwise.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetVirtualAxis; Joystick.SetVirtualBall; Joystick.SetVirtualHat; Joystick.SetVirtualTouchpad; SDL_SetJoystickVirtualSensorData

◆ SetVirtualHat()

void SDL::Joystick::SetVirtualHat	(	int	hat,
		Uint8	value )

inline

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 UpdateJoysticks, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: PollEvent, PumpEvents, WaitEventTimeout, WaitEvent.

Parameters

hat	the index of the hat on the virtual joystick to update.
value	the new value for the specified hat.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetVirtualAxis; Joystick.SetVirtualButton; Joystick.SetVirtualBall; Joystick.SetVirtualTouchpad; SDL_SetJoystickVirtualSensorData

◆ SetVirtualTouchpad()

void SDL::Joystick::SetVirtualTouchpad	(	int	touchpad,
		int	finger,
		bool	down,
		const FPointRaw &	p,
		float	pressure )

inline

Set touchpad finger state on an opened virtual joystick.

Please note that values set here will not be applied until the next call to UpdateJoysticks, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: PollEvent, PumpEvents, WaitEventTimeout, WaitEvent.

Parameters

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.
p	the x, y coordinates of the finger on the touchpad, normalized 0 to 1, with the origin in the upper left.
pressure	the pressure of the finger.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetVirtualAxis; Joystick.SetVirtualButton; Joystick.SetVirtualBall; Joystick.SetVirtualHat; SDL_SetJoystickVirtualSensorData

◆ UnlockJoysticks()

void SDL::UnlockJoysticks ( )

inline

Unlocking for atomic access to the joystick API.

Thread safety:: This should be called from the same thread that called LockJoysticks().

Since: This function is available since SDL 3.2.0.

◆ UpdateJoysticks()

void SDL::UpdateJoysticks ( )

inline

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.

Since: This function is available since SDL 3.2.0.

Variable Documentation

◆ JOYSTICK_AXIS_MAX

int SDL::JOYSTICK_AXIS_MAX = SDL_JOYSTICK_AXIS_MAX

constexpr

The largest value an Joystick's axis can report.

Since: This constant is available since SDL 3.2.0.

See also: JOYSTICK_AXIS_MIN

◆ JOYSTICK_AXIS_MIN

int SDL::JOYSTICK_AXIS_MIN = SDL_JOYSTICK_AXIS_MIN

constexpr

The smallest value an Joystick's axis can report.

This is a negative number!

Since: This constant is available since SDL 3.2.0.

See also: JOYSTICK_AXIS_MAX

◆ JOYSTICK_TYPE_WHEEL

JoystickType SDL::JOYSTICK_TYPE_WHEEL

constexpr

Initial value:

=

SDL_JOYSTICK_TYPE_WHEEL

JOYSTICK_TYPE_WHEEL.

Namespaces

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ JoystickConnectionState

◆ JoystickRef

◆ JoystickType

◆ VirtualJoystickDesc

◆ VirtualJoystickSensorDesc

◆ VirtualJoystickTouchpadDesc

Function Documentation

◆ AttachVirtualJoystick()

◆ Close()

◆ CloseJoystick()

◆ Connected()

◆ DetachVirtualJoystick() [1/2]

◆ DetachVirtualJoystick() [2/2]

◆ GetAxis()

◆ GetAxisInitialState()

◆ GetBall()

◆ GetButton()

◆ GetConnectionState()

◆ GetFirmwareVersion()

◆ GetGUID()

◆ GetHat()

◆ GetID()

◆ GetJoystickAxis()

◆ GetJoystickAxisInitialState()

◆ GetJoystickBall()

◆ GetJoystickButton()

◆ GetJoystickConnectionState()

◆ GetJoystickFirmwareVersion()

◆ GetJoystickFromID() [1/2]

◆ GetJoystickFromID() [2/2]

◆ GetJoystickFromPlayerIndex()

◆ GetJoystickGUID()

◆ GetJoystickGUIDForID() [1/2]

◆ GetJoystickGUIDForID() [2/2]

◆ GetJoystickGUIDInfo()

◆ GetJoystickHat()

◆ GetJoystickID()

◆ GetJoystickName()

◆ GetJoystickNameForID() [1/2]

◆ GetJoystickNameForID() [2/2]

◆ GetJoystickPath()

◆ GetJoystickPathForID() [1/2]

◆ GetJoystickPathForID() [2/2]

◆ GetJoystickPlayerIndex()

◆ GetJoystickPlayerIndexForID() [1/2]

◆ GetJoystickPlayerIndexForID() [2/2]

◆ GetJoystickPowerInfo()

◆ GetJoystickProduct()

◆ GetJoystickProductForID() [1/2]

◆ GetJoystickProductForID() [2/2]

◆ GetJoystickProductVersion()

◆ GetJoystickProductVersionForID() [1/2]

◆ GetJoystickProductVersionForID() [2/2]

◆ GetJoystickProperties()

◆ GetJoysticks()

◆ GetJoystickSerial()

◆ GetJoystickType()

◆ GetJoystickTypeForID() [1/2]

◆ GetJoystickTypeForID() [2/2]

◆ GetJoystickVendor()

◆ GetJoystickVendorForID() [1/2]

◆ GetJoystickVendorForID() [2/2]

◆ GetName()

◆ GetNumAxes()

◆ GetNumBalls()

◆ GetNumButtons()

◆ GetNumHats()

◆ GetNumJoystickAxes()

◆ GetNumJoystickBalls()

◆ GetNumJoystickButtons()

◆ GetNumJoystickHats()

◆ GetPath()

◆ GetPlayerIndex()