joystick topic

CategoryJoystick

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

SDL can provide virtual joysticks as well: the app defines an imaginary controller with SDL_AttachVirtualJoystick(), and then can provide inputs for it via SDL_SetJoystickVirtualAxis(), SDL_SetJoystickVirtualButton(), 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.

Functions

sdlAttachVirtualJoystick(Pointer<SdlVirtualJoystickDesc> desc) → int joystick
Attach a new virtual joystick.
sdlCloseJoystick(Pointer<SdlJoystick> joystick) → void joystick
Close a joystick previously opened with SDL_OpenJoystick().
sdlDetachVirtualJoystick(int instanceId) → bool joystick
Detach a virtual joystick.
sdlGetJoystickAxis(Pointer<SdlJoystick> joystick, int axis) → int joystick
Get the current state of an axis control on a joystick.
sdlGetJoystickAxisInitialState(Pointer<SdlJoystick> joystick, int axis, Pointer<Int16> state) → bool joystick
Get the initial state of an axis control on a joystick.
sdlGetJoystickBall(Pointer<SdlJoystick> joystick, int ball, Pointer<Int32> dx, Pointer<Int32> dy) → bool joystick
Get the ball axis change since the last poll.
sdlGetJoystickButton(Pointer<SdlJoystick> joystick, int button) → bool joystick
Get the current state of a button on a joystick.
sdlGetJoystickConnectionState(Pointer<SdlJoystick> joystick) → int joystick
Get the connection state of a joystick.
sdlGetJoystickFirmwareVersion(Pointer<SdlJoystick> joystick) → int joystick
Get the firmware version of an opened joystick, if available.
sdlGetJoystickFromId(int instanceId) → Pointer<SdlJoystick> joystick
Get the SDL_Joystick associated with an instance ID, if it has been opened.
sdlGetJoystickFromPlayerIndex(int playerIndex) → Pointer<SdlJoystick> joystick
Get the SDL_Joystick associated with a player index.
sdlGetJoystickGuid(Pointer<SdlJoystick> joystick) → SdlGuid joystick
Get the implementation-dependent GUID for the joystick.
sdlGetJoystickGuidForId(int instanceId) → SdlGuid joystick
Get the implementation-dependent GUID of a joystick.
sdlGetJoystickGuidInfo(SdlGuid guid, Pointer<Uint16> vendor, Pointer<Uint16> product, Pointer<Uint16> version, Pointer<Uint16> crc16) → void joystick
Get the device information encoded in a SDL_GUID structure.
sdlGetJoystickHat(Pointer<SdlJoystick> joystick, int hat) → int joystick
Get the current state of a POV hat on a joystick.
sdlGetJoystickId(Pointer<SdlJoystick> joystick) → int joystick
Get the instance ID of an opened joystick.
sdlGetJoystickName(Pointer<SdlJoystick> joystick) → String? joystick
Get the implementation dependent name of a joystick.
sdlGetJoystickNameForId(int instanceId) → String? joystick
Get the implementation dependent name of a joystick.
sdlGetJoystickPath(Pointer<SdlJoystick> joystick) → String? joystick
Get the implementation dependent path of a joystick.
sdlGetJoystickPathForId(int instanceId) → String? joystick
Get the implementation dependent path of a joystick.
sdlGetJoystickPlayerIndex(Pointer<SdlJoystick> joystick) → int joystick
Get the player index of an opened joystick.
sdlGetJoystickPlayerIndexForId(int instanceId) → int joystick
Get the player index of a joystick.
sdlGetJoystickPowerInfo(Pointer<SdlJoystick> joystick, Pointer<Int32> percent) → int joystick
Get the battery state of a joystick.
sdlGetJoystickProduct(Pointer<SdlJoystick> joystick) → int joystick
Get the USB product ID of an opened joystick, if available.
sdlGetJoystickProductForId(int instanceId) → int joystick
Get the USB product ID of a joystick, if available.
sdlGetJoystickProductVersion(Pointer<SdlJoystick> joystick) → int joystick
Get the product version of an opened joystick, if available.
sdlGetJoystickProductVersionForId(int instanceId) → int joystick
Get the product version of a joystick, if available.
sdlGetJoystickProperties(Pointer<SdlJoystick> joystick) → int joystick
Get the properties associated with a joystick.
sdlGetJoysticks(Pointer<Int32> count) → Pointer<Uint32> joystick
Get a list of currently connected joysticks.
sdlGetJoystickSerial(Pointer<SdlJoystick> joystick) → String? joystick
Get the serial number of an opened joystick, if available.
sdlGetJoystickType(Pointer<SdlJoystick> joystick) → int joystick
Get the type of an opened joystick.
sdlGetJoystickTypeForId(int instanceId) → int joystick
Get the type of a joystick, if available.
sdlGetJoystickVendor(Pointer<SdlJoystick> joystick) → int joystick
Get the USB vendor ID of an opened joystick, if available.
sdlGetJoystickVendorForId(int instanceId) → int joystick
Get the USB vendor ID of a joystick, if available.
sdlGetNumJoystickAxes(Pointer<SdlJoystick> joystick) → int joystick
Get the number of general axis controls on a joystick.
sdlGetNumJoystickBalls(Pointer<SdlJoystick> joystick) → int joystick
Get the number of trackballs on a joystick.
sdlGetNumJoystickButtons(Pointer<SdlJoystick> joystick) → int joystick
Get the number of buttons on a joystick.
sdlGetNumJoystickHats(Pointer<SdlJoystick> joystick) → int joystick
Get the number of POV hats on a joystick.
sdlHasJoystick() → bool joystick
Return whether a joystick is currently connected.
sdlIsJoystickVirtual(int instanceId) → bool joystick
Query whether or not a joystick is virtual.
sdlJoystickConnected(Pointer<SdlJoystick> joystick) → bool joystick
Get the status of a specified joystick.
sdlJoystickEventsEnabled() → bool joystick
Query the state of joystick event processing.
sdlLockJoysticks(Pointer<NativeType> arg0) → void joystick
Locking for atomic access to the joystick API.
sdlOpenJoystick(int instanceId) → Pointer<SdlJoystick> joystick
Open a joystick for use.
sdlRumbleJoystick(Pointer<SdlJoystick> joystick, int lowFrequencyRumble, int highFrequencyRumble, int durationMs) → bool joystick
Start a rumble effect.
sdlRumbleJoystickTriggers(Pointer<SdlJoystick> joystick, int leftRumble, int rightRumble, int durationMs) → bool joystick
Start a rumble effect in the joystick's triggers.
sdlSendJoystickEffect(Pointer<SdlJoystick> joystick, Pointer<NativeType> data, int size) → bool joystick
Send a joystick specific effect packet.
sdlSendJoystickVirtualSensorData(Pointer<SdlJoystick> joystick, int type, int sensorTimestamp, Pointer<Float> data, int numValues) → bool joystick
Send a sensor update for an opened virtual joystick.
sdlSetJoystickEventsEnabled(bool enabled) → void joystick
Set the state of joystick event processing.
sdlSetJoystickLed(Pointer<SdlJoystick> joystick, int red, int green, int blue) → bool joystick
Update a joystick's LED color.
sdlSetJoystickPlayerIndex(Pointer<SdlJoystick> joystick, int playerIndex) → bool joystick
Set the player index of an opened joystick.
sdlSetJoystickVirtualAxis(Pointer<SdlJoystick> joystick, int axis, int value) → bool joystick
Set the state of an axis on an opened virtual joystick.
sdlSetJoystickVirtualBall(Pointer<SdlJoystick> joystick, int ball, int xrel, int yrel) → bool joystick
Generate ball motion on an opened virtual joystick.
sdlSetJoystickVirtualButton(Pointer<SdlJoystick> joystick, int button, bool down) → bool joystick
Set the state of a button on an opened virtual joystick.
sdlSetJoystickVirtualHat(Pointer<SdlJoystick> joystick, int hat, int value) → bool joystick
Set the state of a hat on an opened virtual joystick.
sdlSetJoystickVirtualTouchpad(Pointer<SdlJoystick> joystick, int touchpad, int finger, bool down, double x, double y, double pressure) → bool joystick
Set touchpad finger state on an opened virtual joystick.
sdlUnlockJoysticks(Pointer<NativeType> arg0) → void joystick
Unlocking for atomic access to the joystick API.
sdlUpdateJoysticks() → void joystick
Update the current state of the open joysticks.