Module joystick

Available on crate feature dep_sdl3 only.

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.

SDL_GUID is used as a stable 128-bit identifier for a joystick device that does not change over time. It identifies class of the device (a X360 wired controller for example). This identifier is platform dependent.

In order to use these functions, [SDL_Init()] must have been called with the [SDL_INIT_JOYSTICK] flag. This causes SDL to scan the system for joysticks, and load appropriate drivers.

If you would like to receive joystick updates while the application is in the background, you should set the following hint before calling [SDL_Init()]: [SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS]

Structs

SDL_Joystick

The joystick structure used to identify an SDL joystick.

SDL_JoystickConnectionState

Possible connection states for a joystick device.

SDL_JoystickType

An enum of some common joystick types.

SDL_VirtualJoystickDesc

The structure that describes a virtual joystick.

SDL_VirtualJoystickSensorDesc

The structure that describes a virtual joystick sensor.

SDL_VirtualJoystickTouchpadDesc

The structure that describes a virtual joystick touchpad.

Constants

SDL_HAT_CENTERED

SDL_HAT_DOWN

SDL_HAT_LEFT

SDL_HAT_LEFTDOWN

SDL_HAT_LEFTUP

SDL_HAT_RIGHT

SDL_HAT_RIGHTDOWN

SDL_HAT_RIGHTUP

SDL_HAT_UP

SDL_JOYSTICK_AXIS_MAX

The largest value an SDL_Joystick’s axis can report.

SDL_JOYSTICK_AXIS_MIN

The smallest value an SDL_Joystick’s axis can report.

SDL_JOYSTICK_CONNECTION_INVALID

SDL_JOYSTICK_CONNECTION_UNKNOWN

SDL_JOYSTICK_CONNECTION_WIRED

SDL_JOYSTICK_CONNECTION_WIRELESS

SDL_JOYSTICK_TYPE_ARCADE_PAD

SDL_JOYSTICK_TYPE_ARCADE_STICK

SDL_JOYSTICK_TYPE_COUNT

SDL_JOYSTICK_TYPE_DANCE_PAD

SDL_JOYSTICK_TYPE_DRUM_KIT

SDL_JOYSTICK_TYPE_FLIGHT_STICK

SDL_JOYSTICK_TYPE_GAMEPAD

SDL_JOYSTICK_TYPE_GUITAR

SDL_JOYSTICK_TYPE_THROTTLE

SDL_JOYSTICK_TYPE_UNKNOWN

SDL_JOYSTICK_TYPE_WHEEL

SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN

SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN

SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN

SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN

SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN

Functions

SDL_AttachVirtualJoystick^⚠

Attach a new virtual joystick.

SDL_CloseJoystick^⚠

Close a joystick previously opened with SDL_OpenJoystick().

SDL_DetachVirtualJoystick^⚠

Detach a virtual joystick.

SDL_GetJoystickAxis^⚠

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

SDL_GetJoystickAxisInitialState^⚠

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

SDL_GetJoystickBall^⚠

Get the ball axis change since the last poll.

SDL_GetJoystickButton^⚠

Get the current state of a button on a joystick.

SDL_GetJoystickConnectionState^⚠

Get the connection state of a joystick.

SDL_GetJoystickFirmwareVersion^⚠

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

SDL_GetJoystickFromID^⚠

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

SDL_GetJoystickFromPlayerIndex^⚠

Get the SDL_Joystick associated with a player index.

SDL_GetJoystickGUID^⚠

Get the implementation-dependent GUID for the joystick.

SDL_GetJoystickGUIDForID^⚠

Get the implementation-dependent GUID of a joystick.

SDL_GetJoystickGUIDInfo^⚠

Get the device information encoded in a SDL_GUID structure.

SDL_GetJoystickHat^⚠

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

SDL_GetJoystickID^⚠

Get the instance ID of an opened joystick.

SDL_GetJoystickName^⚠

Get the implementation dependent name of a joystick.

SDL_GetJoystickNameForID^⚠

Get the implementation dependent name of a joystick.

SDL_GetJoystickPath^⚠

Get the implementation dependent path of a joystick.

SDL_GetJoystickPathForID^⚠

Get the implementation dependent path of a joystick.

SDL_GetJoystickPlayerIndex^⚠

Get the player index of an opened joystick.

SDL_GetJoystickPlayerIndexForID^⚠

Get the player index of a joystick.

SDL_GetJoystickPowerInfo^⚠

Get the battery state of a joystick.

SDL_GetJoystickProduct^⚠

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

SDL_GetJoystickProductForID^⚠

Get the USB product ID of a joystick, if available.

SDL_GetJoystickProductVersion^⚠

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

SDL_GetJoystickProductVersionForID^⚠

Get the product version of a joystick, if available.

SDL_GetJoystickProperties^⚠

Get the properties associated with a joystick.

SDL_GetJoystickSerial^⚠

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

SDL_GetJoystickType^⚠

Get the type of an opened joystick.

SDL_GetJoystickTypeForID^⚠

Get the type of a joystick, if available.

SDL_GetJoystickVendor^⚠

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

SDL_GetJoystickVendorForID^⚠

Get the USB vendor ID of a joystick, if available.

SDL_GetJoysticks^⚠

Get a list of currently connected joysticks.

SDL_GetNumJoystickAxes^⚠

Get the number of general axis controls on a joystick.

SDL_GetNumJoystickBalls^⚠

Get the number of trackballs on a joystick.

SDL_GetNumJoystickButtons^⚠

Get the number of buttons on a joystick.

SDL_GetNumJoystickHats^⚠

Get the number of POV hats on a joystick.

SDL_HasJoystick^⚠

Return whether a joystick is currently connected.

SDL_IsJoystickVirtual^⚠

Query whether or not a joystick is virtual.

SDL_JoystickConnected^⚠

Get the status of a specified joystick.

SDL_JoystickEventsEnabled^⚠

Query the state of joystick event processing.

SDL_LockJoysticks^⚠

Locking for atomic access to the joystick API.

SDL_OpenJoystick^⚠

Open a joystick for use.

SDL_RumbleJoystick^⚠

Start a rumble effect.

SDL_RumbleJoystickTriggers^⚠

Start a rumble effect in the joystick’s triggers.

SDL_SendJoystickEffect^⚠

Send a joystick specific effect packet.

SDL_SendJoystickVirtualSensorData^⚠

Send a sensor update for an opened virtual joystick.

SDL_SetJoystickEventsEnabled^⚠

Set the state of joystick event processing.

SDL_SetJoystickLED^⚠

Update a joystick’s LED color.

SDL_SetJoystickPlayerIndex^⚠

Set the player index of an opened joystick.

SDL_SetJoystickVirtualAxis^⚠

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

SDL_SetJoystickVirtualBall^⚠

Generate ball motion on an opened virtual joystick.

SDL_SetJoystickVirtualButton^⚠

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

SDL_SetJoystickVirtualHat^⚠

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

SDL_SetJoystickVirtualTouchpad^⚠

Set touchpad finger state on an opened virtual joystick.

SDL_UnlockJoysticks^⚠

Unlocking for atomic access to the joystick API.

SDL_UpdateJoysticks^⚠

Update the current state of the open joysticks.

Type Aliases

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.