SDL joystick support. More...

Collaboration diagram for Joystick Support:

Classes
struct	SDL::JoystickParam
	Safely wrap Joystick for non owning parameters. More...

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

class	SDL::Joystick
	The joystick structure used to identify an SDL joystick. More...

struct	SDL::JoystickRef
	Semi-safe reference for Joystick. More...

Typedefs
using	SDL::JoystickRaw = SDL_Joystick *
	Alias to raw representation 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. More...

using	SDL::JoystickConnectionState = SDL_JoystickConnectionState
	Possible connection states for a joystick device. More...

using	SDL::HatState = Uint8
	Represents tbe HatState for a Joystick.

using	SDL::VirtualJoystickTouchpadDesc = SDL_VirtualJoystickTouchpadDesc
	The structure that describes a virtual joystick touchpad. More...

using	SDL::VirtualJoystickSensorDesc = SDL_VirtualJoystickSensorDesc
	The structure that describes a virtual joystick sensor. More...

using	SDL::VirtualJoystickDesc = SDL_VirtualJoystickDesc
	The structure that describes a virtual joystick. More...

Functions
void	SDL::LockJoysticks (void)
	Locking for atomic access to the joystick API. More...

void	SDL::UnlockJoysticks (void)
	Unlocking for atomic access to the joystick API. More...

bool	SDL::HasJoystick ()
	Return whether a joystick is currently connected. More...

OwnArray< JoystickID >	SDL::GetJoysticks ()
	Get a list of currently connected joysticks. More...

const char *	SDL::GetJoystickNameForID (JoystickID instance_id)
	Get the implementation dependent name of a joystick. More...

const char *	SDL::GetJoystickPathForID (JoystickID instance_id)
	Get the implementation dependent path of a joystick. More...

int	SDL::GetJoystickPlayerIndexForID (JoystickID instance_id)
	Get the player index of a joystick. More...

GUID	SDL::GetJoystickGUIDForID (JoystickID instance_id)
	Get the implementation-dependent GUID of a joystick. More...

Uint16	SDL::GetJoystickVendorForID (JoystickID instance_id)
	Get the USB vendor ID of a joystick, if available. More...

Uint16	SDL::GetJoystickProductForID (JoystickID instance_id)
	Get the USB product ID of a joystick, if available. More...

Uint16	SDL::GetJoystickProductVersionForID (JoystickID instance_id)
	Get the product version of a joystick, if available. More...

JoystickType	SDL::GetJoystickTypeForID (JoystickID instance_id)
	Get the type of a joystick, if available. More...

Joystick	SDL::OpenJoystick (JoystickID instance_id)
	Open a joystick for use. More...

JoystickRef	SDL::GetJoystickFromID (JoystickID instance_id)
	Get the Joystick associated with an instance ID, if it has been opened. More...

JoystickRef	SDL::GetJoystickFromPlayerIndex (int player_index)
	Get the Joystick associated with a player index. More...

JoystickID	SDL::AttachVirtualJoystick (const VirtualJoystickDesc &desc)
	Attach a new virtual joystick. More...

void	SDL::DetachVirtualJoystick (JoystickID instance_id)
	Detach a virtual joystick. More...

bool	SDL::IsJoystickVirtual (JoystickID instance_id)
	Query whether or not a joystick is virtual. More...

void	SDL::SetJoystickVirtualAxis (JoystickParam joystick, int axis, Sint16 value)
	Set the state of an axis on an opened virtual joystick. More...

void	SDL::SetJoystickVirtualBall (JoystickParam joystick, int ball, Sint16 xrel, Sint16 yrel)
	Generate ball motion on an opened virtual joystick. More...

void	SDL::SetJoystickVirtualButton (JoystickParam joystick, int button, bool down)
	Set the state of a button on an opened virtual joystick. More...

void	SDL::SetJoystickVirtualHat (JoystickParam joystick, int hat, Uint8 value)
	Set the state of a hat on an opened virtual joystick. More...

void	SDL::SetJoystickVirtualTouchpad (JoystickParam joystick, int touchpad, int finger, bool down, const FPointRaw &p, float pressure)
	Set touchpad finger state on an opened virtual joystick. More...

void	SDL::SendJoystickVirtualSensorData (JoystickParam joystick, SensorType type, Uint64 sensor_timestamp, const float *data, int num_values)
	Send a sensor update for an opened virtual joystick. More...

PropertiesRef	SDL::GetJoystickProperties (JoystickParam joystick)
	Get the properties associated with a joystick. More...

const char *	SDL::GetJoystickName (JoystickParam joystick)
	Get the implementation dependent name of a joystick. More...

const char *	SDL::GetJoystickPath (JoystickParam joystick)
	Get the implementation dependent path of a joystick. More...

int	SDL::GetJoystickPlayerIndex (JoystickParam joystick)
	Get the player index of an opened joystick. More...

void	SDL::SetJoystickPlayerIndex (JoystickParam joystick, int player_index)
	Set the player index of an opened joystick. More...

GUID	SDL::GetJoystickGUID (JoystickParam joystick)
	Get the implementation-dependent GUID for the joystick. More...

Uint16	SDL::GetJoystickVendor (JoystickParam joystick)
	Get the USB vendor ID of an opened joystick, if available. More...

Uint16	SDL::GetJoystickProduct (JoystickParam joystick)
	Get the USB product ID of an opened joystick, if available. More...

Uint16	SDL::GetJoystickProductVersion (JoystickParam joystick)
	Get the product version of an opened joystick, if available. More...

Uint16	SDL::GetJoystickFirmwareVersion (JoystickParam joystick)
	Get the firmware version of an opened joystick, if available. More...

const char *	SDL::GetJoystickSerial (JoystickParam joystick)
	Get the serial number of an opened joystick, if available. More...

JoystickType	SDL::GetJoystickType (JoystickParam joystick)
	Get the type of an opened joystick. More...

void	SDL::GetJoystickGUIDInfo (GUID guid, Uint16 vendor, Uint16 product, Uint16 version, Uint16 crc16)
	Get the device information encoded in a GUID structure. More...

bool	SDL::JoystickConnected (JoystickParam joystick)
	Get the status of a specified joystick. More...

JoystickID	SDL::GetJoystickID (JoystickParam joystick)
	Get the instance ID of an opened joystick. More...

int	SDL::GetNumJoystickAxes (JoystickParam joystick)
	Get the number of general axis controls on a joystick. More...

int	SDL::GetNumJoystickBalls (JoystickParam joystick)
	Get the number of trackballs on a joystick. More...

int	SDL::GetNumJoystickHats (JoystickParam joystick)
	Get the number of POV hats on a joystick. More...

int	SDL::GetNumJoystickButtons (JoystickParam joystick)
	Get the number of buttons on a joystick. More...

void	SDL::SetJoystickEventsEnabled (bool enabled)
	Set the state of joystick event processing. More...

bool	SDL::JoystickEventsEnabled ()
	Query the state of joystick event processing. More...

void	SDL::UpdateJoysticks ()
	Update the current state of the open joysticks. More...

Sint16	SDL::GetJoystickAxis (JoystickParam joystick, int axis)
	Get the current state of an axis control on a joystick. More...

bool	SDL::GetJoystickAxisInitialState (JoystickParam joystick, int axis, Sint16 *state)
	Get the initial state of an axis control on a joystick. More...

void	SDL::GetJoystickBall (JoystickParam joystick, int ball, int dx, int dy)
	Get the ball axis change since the last poll. More...

Uint8	SDL::GetJoystickHat (JoystickParam joystick, int hat)
	Get the current state of a POV hat on a joystick. More...

bool	SDL::GetJoystickButton (JoystickParam joystick, int button)
	Get the current state of a button on a joystick. More...

bool	SDL::RumbleJoystick (JoystickParam joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms)
	Start a rumble effect. More...

void	SDL::RumbleJoystickTriggers (JoystickParam joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms)
	Start a rumble effect in the joystick's triggers. More...

void	SDL::SetJoystickLED (JoystickParam joystick, Uint8 red, Uint8 green, Uint8 blue)
	Update a joystick's LED color. More...

void	SDL::SendJoystickEffect (JoystickParam joystick, const void *data, int size)
	Send a joystick specific effect packet. More...

void	SDL::CloseJoystick (JoystickRaw joystick)
	Close a joystick previously opened with JoystickID.OpenJoystick(). More...

JoystickConnectionState	SDL::GetJoystickConnectionState (JoystickParam joystick)
	Get the connection state of a joystick. More...

PowerState	SDL::GetJoystickPowerInfo (JoystickParam joystick, int *percent)
	Get the battery state of a joystick. More...

const char *	SDL::JoystickID::GetJoystickNameForID ()
	Get the implementation dependent name of a joystick. More...

const char *	SDL::JoystickID::GetJoystickPathForID ()
	Get the implementation dependent path of a joystick. More...

int	SDL::JoystickID::GetJoystickPlayerIndexForID ()
	Get the player index of a joystick. More...

GUID	SDL::JoystickID::GetJoystickGUIDForID ()
	Get the implementation-dependent GUID of a joystick. More...

Uint16	SDL::JoystickID::GetJoystickVendorForID ()
	Get the USB vendor ID of a joystick, if available. More...

Uint16	SDL::JoystickID::GetJoystickProductForID ()
	Get the USB product ID of a joystick, if available. More...

Uint16	SDL::JoystickID::GetJoystickProductVersionForID ()
	Get the product version of a joystick, if available. More...

JoystickType	SDL::JoystickID::GetJoystickTypeForID ()
	Get the type of a joystick, if available. More...

Joystick	SDL::JoystickID::OpenJoystick ()
	Open a joystick for use. More...

JoystickRef	SDL::JoystickID::GetJoystickFromID ()
	Get the Joystick associated with an instance ID, if it has been opened. More...

void	SDL::JoystickID::DetachVirtualJoystick ()
	Detach a virtual joystick. More...

bool	SDL::JoystickID::IsJoystickVirtual ()
	Query whether or not a joystick is virtual. More...

void	SDL::Joystick::SetVirtualAxis (int axis, Sint16 value)
	Set the state of an axis on an opened virtual joystick. More...

void	SDL::Joystick::SetVirtualBall (int ball, Sint16 xrel, Sint16 yrel)
	Generate ball motion on an opened virtual joystick. More...

void	SDL::Joystick::SetVirtualButton (int button, bool down)
	Set the state of a button on an opened virtual joystick. More...

void	SDL::Joystick::SetVirtualHat (int hat, Uint8 value)
	Set the state of a hat on an opened virtual joystick. More...

void	SDL::Joystick::SetVirtualTouchpad (int touchpad, int finger, bool down, const FPointRaw &p, float pressure)
	Set touchpad finger state on an opened virtual joystick. More...

void	SDL::Joystick::SendVirtualSensorData (SensorType type, Uint64 sensor_timestamp, const float *data, int num_values)
	Send a sensor update for an opened virtual joystick. More...

PropertiesRef	SDL::Joystick::GetProperties ()
	Get the properties associated with a joystick. More...

const char *	SDL::Joystick::GetName ()
	Get the implementation dependent name of a joystick. More...

const char *	SDL::Joystick::GetPath ()
	Get the implementation dependent path of a joystick. More...

int	SDL::Joystick::GetPlayerIndex ()
	Get the player index of an opened joystick. More...

void	SDL::Joystick::SetPlayerIndex (int player_index)
	Set the player index of an opened joystick. More...

GUID	SDL::Joystick::GetGUID ()
	Get the implementation-dependent GUID for the joystick. More...

Uint16	SDL::Joystick::GetVendor ()
	Get the USB vendor ID of an opened joystick, if available. More...

Uint16	SDL::Joystick::GetProduct ()
	Get the USB product ID of an opened joystick, if available. More...

Uint16	SDL::Joystick::GetProductVersion ()
	Get the product version of an opened joystick, if available. More...

Uint16	SDL::Joystick::GetFirmwareVersion ()
	Get the firmware version of an opened joystick, if available. More...

const char *	SDL::Joystick::GetSerial ()
	Get the serial number of an opened joystick, if available. More...

JoystickType	SDL::Joystick::GetType ()
	Get the type of an opened joystick. More...

bool	SDL::Joystick::Connected ()
	Get the status of a specified joystick. More...

JoystickID	SDL::Joystick::GetID ()
	Get the instance ID of an opened joystick. More...

int	SDL::Joystick::GetNumAxes ()
	Get the number of general axis controls on a joystick. More...

int	SDL::Joystick::GetNumBalls ()
	Get the number of trackballs on a joystick. More...

int	SDL::Joystick::GetNumHats ()
	Get the number of POV hats on a joystick. More...

int	SDL::Joystick::GetNumButtons ()
	Get the number of buttons on a joystick. More...

Sint16	SDL::Joystick::GetAxis (int axis)
	Get the current state of an axis control on a joystick. More...

bool	SDL::Joystick::GetAxisInitialState (int axis, Sint16 *state)
	Get the initial state of an axis control on a joystick. More...

void	SDL::Joystick::GetBall (int ball, int dx, int dy)
	Get the ball axis change since the last poll. More...

Uint8	SDL::Joystick::GetHat (int hat)
	Get the current state of a POV hat on a joystick. More...

bool	SDL::Joystick::GetButton (int button)
	Get the current state of a button on a joystick. More...

bool	SDL::Joystick::Rumble (Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms)
	Start a rumble effect. More...

void	SDL::Joystick::RumbleTriggers (Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms)
	Start a rumble effect in the joystick's triggers. More...

void	SDL::Joystick::SetLED (Uint8 red, Uint8 green, Uint8 blue)
	Update a joystick's LED color. More...

void	SDL::Joystick::SendEffect (const void *data, int size)
	Send a joystick specific effect packet. More...

void	SDL::Joystick::Close ()
	Close a joystick previously opened with JoystickID.OpenJoystick(). More...

JoystickConnectionState	SDL::Joystick::GetConnectionState ()
	Get the connection state of a joystick. More...

PowerState	SDL::Joystick::GetPowerInfo (int *percent)
	Get the battery state of a joystick. More...

Variables
constexpr JoystickType	SDL::JOYSTICK_TYPE_UNKNOWN
	JOYSTICK_TYPE_UNKNOWN. More...

constexpr JoystickType	SDL::JOYSTICK_TYPE_GAMEPAD
	JOYSTICK_TYPE_GAMEPAD. More...

constexpr JoystickType	SDL::JOYSTICK_TYPE_WHEEL
	JOYSTICK_TYPE_WHEEL. More...

constexpr JoystickType	SDL::JOYSTICK_TYPE_ARCADE_STICK
	JOYSTICK_TYPE_ARCADE_STICK. More...

constexpr JoystickType	SDL::JOYSTICK_TYPE_FLIGHT_STICK
	JOYSTICK_TYPE_FLIGHT_STICK. More...

constexpr JoystickType	SDL::JOYSTICK_TYPE_DANCE_PAD
	JOYSTICK_TYPE_DANCE_PAD. More...

constexpr JoystickType	SDL::JOYSTICK_TYPE_GUITAR
	JOYSTICK_TYPE_GUITAR. More...

constexpr JoystickType	SDL::JOYSTICK_TYPE_DRUM_KIT
	JOYSTICK_TYPE_DRUM_KIT. More...

constexpr JoystickType	SDL::JOYSTICK_TYPE_ARCADE_PAD
	JOYSTICK_TYPE_ARCADE_PAD. More...

constexpr JoystickType	SDL::JOYSTICK_TYPE_THROTTLE
	JOYSTICK_TYPE_THROTTLE. More...

constexpr JoystickType	SDL::JOYSTICK_TYPE_COUNT
	JOYSTICK_TYPE_COUNT. More...

constexpr JoystickConnectionState	SDL::JOYSTICK_CONNECTION_INVALID
	JOYSTICK_CONNECTION_INVALID. More...

constexpr JoystickConnectionState	SDL::JOYSTICK_CONNECTION_UNKNOWN
	JOYSTICK_CONNECTION_UNKNOWN. More...

constexpr JoystickConnectionState	SDL::JOYSTICK_CONNECTION_WIRED
	JOYSTICK_CONNECTION_WIRED. More...

constexpr JoystickConnectionState	SDL::JOYSTICK_CONNECTION_WIRELESS
	JOYSTICK_CONNECTION_WIRELESS. More...

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

constexpr int	SDL::JOYSTICK_AXIS_MIN = SDL_JOYSTICK_AXIS_MIN
	The smallest value an Joystick's axis can report. More...

Detailed Description

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

Typedef Documentation

◆ JoystickConnectionState

using SDL::JoystickConnectionState = typedef SDL_JoystickConnectionState

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.

◆ JoystickType

using SDL::JoystickType = typedef SDL_JoystickType

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.

Since: This enum is available since SDL 3.2.0.

◆ VirtualJoystickDesc

using SDL::VirtualJoystickDesc = typedef SDL_VirtualJoystickDesc

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

Since: This struct is available since SDL 3.2.0.

See also: AttachVirtualJoystick; SDL_INIT_INTERFACE; VirtualJoystickSensorDesc; VirtualJoystickTouchpadDesc

◆ VirtualJoystickSensorDesc

using SDL::VirtualJoystickSensorDesc = typedef SDL_VirtualJoystickSensorDesc

Since: This struct is available since SDL 3.2.0.

See also: VirtualJoystickDesc

◆ VirtualJoystickTouchpadDesc

using SDL::VirtualJoystickTouchpadDesc = typedef SDL_VirtualJoystickTouchpadDesc

Since: This struct is available since SDL 3.2.0.

See also: VirtualJoystickDesc

Function Documentation

◆ AttachVirtualJoystick()

JoystickID SDL::AttachVirtualJoystick ( const VirtualJoystickDesc & desc )

inline

Parameters

desc	joystick description, initialized using SDL_INIT_INTERFACE().

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

Since: This function is available since SDL 3.2.0.

See also: JoystickID.DetachVirtualJoystick

◆ Close()

void SDL::Joystick::Close ( )

inline

Since: This function is available since SDL 3.2.0.

See also: JoystickID.OpenJoystick

◆ CloseJoystick()

void SDL::CloseJoystick ( JoystickRaw joystick )

inline

Parameters

joystick the joystick device to close.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.OpenJoystick

◆ Connected()

bool SDL::Joystick::Connected ( )

inline

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

Since: This function is available since SDL 3.2.0.

◆ DetachVirtualJoystick() [1/2]

void SDL::JoystickID::DetachVirtualJoystick ( )

inline

               AttachVirtualJoystick().

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: AttachVirtualJoystick

◆ DetachVirtualJoystick() [2/2]

void SDL::DetachVirtualJoystick ( JoystickID instance_id )

inline

Parameters

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

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: AttachVirtualJoystick

◆ GetAxis()

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

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumAxes

◆ GetAxisInitialState()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ GetBall()

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

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumBalls

◆ GetButton()

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

inline

Parameters

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

Returns: true if the button is pressed, false otherwise.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumButtons

◆ GetConnectionState()

JoystickConnectionState SDL::Joystick::GetConnectionState ( )

inline

Returns: the connection state on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetFirmwareVersion()

Uint16 SDL::Joystick::GetFirmwareVersion ( )

inline

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

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

Since: This function is available since SDL 3.2.0.

◆ GetGUID()

GUID SDL::Joystick::GetGUID ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickGUIDForID; GUID.ToString

◆ GetHat()

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

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumHats

◆ GetID()

JoystickID SDL::Joystick::GetID ( )

inline

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

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickAxis()

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

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumAxes

◆ GetJoystickAxisInitialState()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickBall()

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

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumBalls

◆ GetJoystickButton()

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

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumButtons

◆ GetJoystickConnectionState()

JoystickConnectionState SDL::GetJoystickConnectionState ( JoystickParam joystick )

inline

Parameters

joystick the joystick to query.

Returns: the connection state on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickFirmwareVersion()

Uint16 SDL::GetJoystickFirmwareVersion ( JoystickParam joystick )

inline

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.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickFromID() [1/2]

JoystickRef SDL::JoystickID::GetJoystickFromID ( )

inline

Returns: an Joystick on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickFromID() [2/2]

JoystickRef SDL::GetJoystickFromID ( JoystickID instance_id )

inline

Parameters

instance_id the instance ID to get the Joystick for.

Returns: an Joystick on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickFromPlayerIndex()

JoystickRef SDL::GetJoystickFromPlayerIndex ( int player_index )

inline

Parameters

player_index the player index to get the Joystick for.

Returns: an Joystick on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPlayerIndex; Joystick.SetPlayerIndex

◆ GetJoystickGUID()

GUID SDL::GetJoystickGUID ( JoystickParam joystick )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickGUIDForID; GUID.ToString

◆ GetJoystickGUIDForID() [1/2]

GUID SDL::JoystickID::GetJoystickGUIDForID ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetGUID; GUID.ToString

◆ GetJoystickGUIDForID() [2/2]

GUID SDL::GetJoystickGUIDForID ( JoystickID instance_id )

inline

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.

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

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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickGUIDForID

◆ GetJoystickHat()

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

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetNumHats

◆ GetJoystickID()

JoystickID SDL::GetJoystickID ( JoystickParam joystick )

inline

Parameters

joystick an Joystick structure containing joystick information.

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

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickName()

const char * SDL::GetJoystickName ( JoystickParam joystick )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickNameForID

◆ GetJoystickNameForID() [1/2]

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

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetName; GetJoysticks

◆ GetJoystickNameForID() [2/2]

const char * SDL::GetJoystickNameForID ( JoystickID instance_id )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetName; GetJoysticks

◆ GetJoystickPath()

const char * SDL::GetJoystickPath ( JoystickParam joystick )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickPathForID

◆ GetJoystickPathForID() [1/2]

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

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPath; GetJoysticks

◆ GetJoystickPathForID() [2/2]

const char * SDL::GetJoystickPathForID ( JoystickID instance_id )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPath; GetJoysticks

◆ GetJoystickPlayerIndex()

int SDL::GetJoystickPlayerIndex ( JoystickParam joystick )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetPlayerIndex

◆ GetJoystickPlayerIndexForID() [1/2]

int SDL::JoystickID::GetJoystickPlayerIndexForID ( )

inline

This can be called before any joysticks are opened.

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

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPlayerIndex; GetJoysticks

◆ GetJoystickPlayerIndexForID() [2/2]

int SDL::GetJoystickPlayerIndexForID ( JoystickID instance_id )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPlayerIndex; GetJoysticks

◆ GetJoystickPowerInfo()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickProduct()

Uint16 SDL::GetJoystickProduct ( JoystickParam joystick )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickProductForID

◆ GetJoystickProductForID() [1/2]

Uint16 SDL::JoystickID::GetJoystickProductForID ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetProduct; GetJoysticks

◆ GetJoystickProductForID() [2/2]

Uint16 SDL::GetJoystickProductForID ( JoystickID instance_id )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetProduct; GetJoysticks

◆ GetJoystickProductVersion()

Uint16 SDL::GetJoystickProductVersion ( JoystickParam joystick )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickProductVersionForID

◆ GetJoystickProductVersionForID() [1/2]

Uint16 SDL::JoystickID::GetJoystickProductVersionForID ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetProductVersion; GetJoysticks

◆ GetJoystickProductVersionForID() [2/2]

Uint16 SDL::GetJoystickProductVersionForID ( JoystickID instance_id )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetProductVersion; GetJoysticks

◆ GetJoystickProperties()

PropertiesRef SDL::GetJoystickProperties ( JoystickParam joystick )

inline

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.

Since: This function is available since SDL 3.2.0.

◆ GetJoysticks()

OwnArray< JoystickID > SDL::GetJoysticks ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: HasJoystick; JoystickID.OpenJoystick

◆ GetJoystickSerial()

const char * SDL::GetJoystickSerial ( JoystickParam joystick )

inline

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.

Since: This function is available since SDL 3.2.0.

◆ GetJoystickType()

JoystickType SDL::GetJoystickType ( JoystickParam joystick )

inline

Parameters

joystick the Joystick obtained from JoystickID.OpenJoystick().

Returns: the JoystickType of the selected joystick.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickTypeForID

◆ GetJoystickTypeForID() [1/2]

JoystickType SDL::JoystickID::GetJoystickTypeForID ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetType; GetJoysticks

◆ GetJoystickTypeForID() [2/2]

JoystickType SDL::GetJoystickTypeForID ( JoystickID instance_id )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetType; GetJoysticks

◆ GetJoystickVendor()

Uint16 SDL::GetJoystickVendor ( JoystickParam joystick )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickVendorForID

◆ GetJoystickVendorForID() [1/2]

Uint16 SDL::JoystickID::GetJoystickVendorForID ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetVendor; GetJoysticks

◆ GetJoystickVendorForID() [2/2]

Uint16 SDL::GetJoystickVendorForID ( JoystickID instance_id )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetVendor; GetJoysticks

◆ GetName()

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

inline

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

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickNameForID

◆ GetNumAxes()

int SDL::Joystick::GetNumAxes ( )

inline

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.

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

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.

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

Returns: the number of buttons on success.

Exceptions

Error on failure.

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

Returns: the number of POV hats on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

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

◆ GetNumJoystickAxes()

int SDL::GetNumJoystickAxes ( JoystickParam joystick )

inline

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.

Since: This function is available since SDL 3.2.0.

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

◆ GetNumJoystickBalls()

int SDL::GetNumJoystickBalls ( JoystickParam joystick )

inline

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.

Since: This function is available since SDL 3.2.0.

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

◆ GetNumJoystickButtons()

int SDL::GetNumJoystickButtons ( JoystickParam joystick )

inline

Parameters

joystick an Joystick structure containing joystick information.

Returns: the number of buttons on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

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

◆ GetNumJoystickHats()

int SDL::GetNumJoystickHats ( JoystickParam joystick )

inline

Parameters

joystick an Joystick structure containing joystick information.

Returns: the number of POV hats on success.

Exceptions

Error on failure.

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

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

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickPathForID

◆ GetPlayerIndex()

int SDL::Joystick::GetPlayerIndex ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.SetPlayerIndex

◆ GetPowerInfo()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ GetProduct()

Uint16 SDL::Joystick::GetProduct ( )

inline

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

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

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickProductForID

◆ GetProductVersion()

Uint16 SDL::Joystick::GetProductVersion ( )

inline

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

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

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickProductVersionForID

◆ GetProperties()

PropertiesRef SDL::Joystick::GetProperties ( )

inline

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.

Since: This function is available since SDL 3.2.0.

◆ GetSerial()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ GetType()

JoystickType SDL::Joystick::GetType ( )

inline

Returns: the JoystickType of the selected joystick.

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickTypeForID

◆ GetVendor()

Uint16 SDL::Joystick::GetVendor ( )

inline

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

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

Since: This function is available since SDL 3.2.0.

See also: JoystickID.GetJoystickVendorForID

◆ HasJoystick()

bool SDL::HasJoystick ( )

inline

Returns: true if a joystick is connected, false otherwise.

Since: This function is available since SDL 3.2.0.

See also: GetJoysticks

◆ IsJoystickVirtual() [1/2]

bool SDL::JoystickID::IsJoystickVirtual ( )

inline

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

Since: This function is available since SDL 3.2.0.

◆ IsJoystickVirtual() [2/2]

bool SDL::IsJoystickVirtual ( JoystickID instance_id )

inline

Parameters

instance_id the joystick instance ID.

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

Since: This function is available since SDL 3.2.0.

◆ JoystickConnected()

bool SDL::JoystickConnected ( JoystickParam joystick )

inline

Parameters

joystick the joystick to query.

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

Since: This function is available since SDL 3.2.0.

◆ JoystickEventsEnabled()

bool SDL::JoystickEventsEnabled ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: SetJoystickEventsEnabled

◆ LockJoysticks()

void SDL::LockJoysticks ( void )

inline

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

Since: This function is available since SDL 3.2.0.

◆ OpenJoystick() [1/2]

Joystick SDL::JoystickID::OpenJoystick ( )

inline

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

Returns: an Joystick on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: Joystick.Close

◆ OpenJoystick() [2/2]

Joystick SDL::OpenJoystick ( JoystickID instance_id )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.Close

◆ Rumble()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ RumbleJoystick()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ RumbleJoystickTriggers()

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

inline

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.

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

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.

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

Parameters

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

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ SendJoystickEffect()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SendJoystickVirtualSensorData()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SendVirtualSensorData()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SetJoystickEventsEnabled()

void SDL::SetJoystickEventsEnabled ( bool enabled )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: JoystickEventsEnabled; UpdateJoysticks

◆ SetJoystickLED()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SetJoystickPlayerIndex()

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

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPlayerIndex

◆ SetJoystickVirtualAxis()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SetJoystickVirtualBall()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SetJoystickVirtualButton()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SetJoystickVirtualHat()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SetJoystickVirtualTouchpad()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SetLED()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SetPlayerIndex()

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

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Joystick.GetPlayerIndex

◆ SetVirtualAxis()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SetVirtualBall()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SetVirtualButton()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SetVirtualHat()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ SetVirtualTouchpad()

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

inline

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.

Since: This function is available since SDL 3.2.0.

◆ UnlockJoysticks()

void SDL::UnlockJoysticks ( void )

inline

Since: This function is available since SDL 3.2.0.

◆ UpdateJoysticks()

void SDL::UpdateJoysticks ( )

inline

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

Since: This function is available since SDL 3.2.0.

Variable Documentation

◆ JOYSTICK_AXIS_MAX

constexpr int SDL::JOYSTICK_AXIS_MAX = SDL_JOYSTICK_AXIS_MAX

constexpr

Since: This macro is available since SDL 3.2.0.

See also: JOYSTICK_AXIS_MIN

◆ JOYSTICK_AXIS_MIN

constexpr int SDL::JOYSTICK_AXIS_MIN = SDL_JOYSTICK_AXIS_MIN

constexpr

This is a negative number!

Since: This macro is available since SDL 3.2.0.

See also: JOYSTICK_AXIS_MAX

◆ JOYSTICK_TYPE_WHEEL

constexpr JoystickType SDL::JOYSTICK_TYPE_WHEEL

constexpr

Initial value:

=

SDL_JOYSTICK_TYPE_WHEEL

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ JoystickConnectionState

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

◆ GetPowerInfo()

◆ GetProduct()