TSdlJoystick

An SDL joystick

Definition

Unit: Neslib.Sdl3.Input

type TSdlJoystick = record ... end;

Properties

Name	Description
Axis	The current state of an axis control on the joystick.
Ball	The ball axis change since the last poll.
Button	The current state of a button on the joystick.
ConnectionState	The connection state of the joystick.
EventsEnabled	The state of joystick event processing.
FirmwareVersion	The firmware version of this opened joystick, if available.
Guid	The implementation-dependent GUID for the joystick.
HasJoystick	Whether a joystick is currently connected.
Hats	The current state of a POV hat on the joystick.
ID	The instance ID of this opened joystick.
IsConnected	Whether the joystick has been opened and is connected.
Joysticks	A list of currently connected joysticks.
Kind	The type of this opened joystick.
Name	The implementation dependent name of a joystick or an empty string if no name can be found.
NumAxes	The number of general axis controls on this joystick.
NumBalls	The number of trackballs on this joystick.
NumButtons	The number of buttons on this joystick.
NumHats	The number of POV hats on this joystick.
Path	The implementation dependent path of a joystick or an empty string if no path can be found.
PlayerIndex	The player index of this opened joystick or -1 if not available.
Product	The USB product ID of this opened joystick, if available.
ProductVersion	The product version of this opened joystick, if available.
Properties	The properties associated with the joystick.
Serial	The serial number of this opened joystick, if available.
Vendor	The USB vendor ID of this opened joystick, if available.

Operators

Name	Description
Equal(TSdlJoystick, TSdlJoystick)	Used to compare against another TSdlJoystick.
Equal(TSdlJoystick, Pointer)	Used to compare against nil.
Implicit	Used to set the value to nil.
NotEqual(TSdlJoystick, TSdlJoystick)	Used to compare against another TSdlJoystick.
NotEqual(TSdlJoystick, Pointer)	Used to compare against nil.

Methods

Name	Description
AxisInitialState	Get the initial state of an axis control on the joystick.
Close	Close a joystick previously opened with Open.
FromGamepad	Get the underlying joystick from a gamepad.
FromID	Get the joystick associated with an instance ID, if it has been opened.
FromPlayerIndex	Get the joystick associated with a player index.
GetPowerInfo	Get the battery state of the joystick.
GuidInfo	Get the device information encoded in a joystick GUID structure.
Lock	Locking for atomic access to the joystick API.
Open	Open a joystick for use.
Rumble	Start a rumble effect.
RumbleTriggers	Start a rumble effect in the joystick's triggers.
SendEffect	Send a joystick specific effect packet.
SetLed	Update the joystick's LED color.
SetVirtualAxis	Set the state of an axis on this opened virtual joystick.
SetVirtualBall	Generate ball motion on this opened virtual joystick.
SetVirtualButton	Set the state of a button on this opened virtual joystick.
SetVirtualHat	Set the state of a hat on an opened virtual joystick.
SetVirtualSensorData	Send a sensor update for an opened virtual joystick.
SetVirtualTouchpad	Set touchpad finger state on an opened virtual joystick.
Unlock	Unlocking for atomic access to the joystick API.
Update	Update the current state of the open joysticks.

Property Descriptions

Axis

The current state of an axis control on the 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 is a signed 16-bit 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.

property Axis[const AAxis: Integer]: Smallint read GetAxis

Type: Smallint

See Also

• NumAxes

---

Ball

The ball axis change since the last poll.

Trackballs can only return relative motion since the last retrieval if this property. It returns the difference in axis position since the last poll.

Most joysticks do not have trackballs.

property Ball[const ABall: Integer]: TSdlPoint read GetBall

Type: TSdlPoint

Exceptions

ESdlError: Raised on failure.

See Also

• NumBalls

---

Button

The current state of a button on the joystick.

property Button[const AButton: Integer]: Boolean read GetButton

Type: Boolean

See Also

• NumButtons

---

ConnectionState

The connection state of the joystick.

property ConnectionState: TsdlJoystickConnectionState read GetConnectionState

Type: TsdlJoystickConnectionState

---

EventsEnabled

The state of joystick event processing.

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

class property EventsEnabled: Boolean read GetEventsEnabled write SetEventsEnabled

Type: Boolean

See Also

• Update

---

FirmwareVersion

The firmware version of this opened joystick, if available.

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

property FirmwareVersion: Word read GetFirmwareVersion

Type: Word

---

Guid

The implementation-dependent GUID for the joystick.

This property requires an open joystick.

property Guid: TGuid read GetGuid

Type: TGuid

Exceptions

ESdlError: Raised on failure.

See Also

• TSdlJoystickID.Guid

---

HasJoystick

Whether a joystick is currently connected.

class property HasJoystick: Boolean read GetHasJoystick

Type: Boolean

See Also

• Joysticks

---

Hats

The current state of a POV hat on the joystick.

property Hats[const AHat: Integer]: TSdlHats read GetHats

Type: TSdlHats

See Also

• NumHats

---

ID

The instance ID of this opened joystick.

property ID: TSdlJoystickID read GetID

Type: TSdlJoystickID

Exceptions

ESdlError: Raised on failure.

---

IsConnected

Whether the joystick has been opened and is connected.

property IsConnected: Boolean read GetIsConnected

Type: Boolean

---

Joysticks

A list of currently connected joysticks.

class property Joysticks: TArray<TSdlJoystickID> read GetJoysticks

Type: TArray<TSdlJoystickID>

Exceptions

ESdlError: Raised on failure.

See Also

• HasJoystick
• Open

---

Kind

The type of this opened joystick.

property Kind: TSdlJoystickKind read GetKind

Type: TSdlJoystickKind

See Also

• TSdlJoystickID.Kind

---

Name

The implementation dependent name of a joystick or an empty string if no name can be found.

property Name: String read GetName

Type: String

See Also

• TSdlJoystickID.Name

---

NumAxes

The number of general axis controls on this 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.

property NumAxes: Integer read GetNumAxes

Type: Integer

Exceptions

ESdlError: Raised on failure.

See Also

• Axis
• NumBalls
• NumButtons
• NumHats

---

NumBalls

The number of trackballs on this joystick.

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

Most joysticks do not have trackballs.

property NumBalls: Integer read GetNumBalls

Type: Integer

Exceptions

ESdlError: Raised on failure.

See Also

• Ball
• NumAxes
• NumButtons
• NumHats

---

NumButtons

The number of buttons on this joystick.

property NumButtons: Integer read GetNumButtons

Type: Integer

Exceptions

ESdlError: Raised on failure.

See Also

• Button
• NumAxes
• NumBalls
• NumHats

---

NumHats

The number of POV hats on this joystick.

property NumHats: Integer read GetNumHats

Type: Integer

Exceptions

ESdlError: Raised on failure.

See Also

• Hats
• NumAxes
• NumBalls
• NumButtons

---

Path

The implementation dependent path of a joystick or an empty string if no path can be found.

property Path: String read GetPath

Type: String

See Also

• TSdlJoystickID.Path

---

PlayerIndex

The player index of this opened joystick or -1 if not available.

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

Set this property to -1 to clear the player index and turn off player LEDs.

property PlayerIndex: Integer read GetPlayerIndex write SetPlayerIndex

Type: Integer

Exceptions

ESdlError: Raised on failure.

See Also

• TSdlJoystickID.PlayerIndex

---

Product

The USB product ID of this opened joystick, if available.

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

property Product: Word read GetProduct

Type: Word

See Also

• TSdlJoystickID.Product

---

ProductVersion

The product version of this opened joystick, if available.

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

property ProductVersion: Word read GetProductVersion

Type: Word

See Also

• TSdlJoystickID.ProductVersion

---

Properties

The properties associated with the joystick.

The following read-only properties are provided by SDL:

• TSdlProperty.JoystickCapMonoLed: True if this joystick has an LED that has adjustable brightness
• TSdlProperty.JoystickCapRgbLed: True if this joystick has an LED that has adjustable color
• TSdlProperty.JoystickCapPlayerLed: True if this joystick has a player LED
• TSdlProperty.JoystickCapRumble: True if this joystick has left/right rumble
• TSdlProperty.JoystickCapTriggerRumble: True if this joystick has simple trigger rumble

property Properties: TSdlProperties read GetProperties

Type: TSdlProperties

Exceptions

ESdlError: Raised on failure.

---

Serial

The serial number of this opened joystick, if available.

Returns the serial number of the joystick, or an empty string if it is not available.

property Serial: String read GetSerial

Type: String

---

Vendor

The USB vendor ID of this opened joystick, if available.

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

property Vendor: Word read GetVendor

Type: Word

See Also

• TSdlJoystickID.Vendor

---

Operator Descriptions

Equal(TSdlJoystick, TSdlJoystick)

Used to compare against another TSdlJoystick.

class operator Equal(const ALeft, ARight: TSdlJoystick): Boolean; inline; static

Parameters

ALeft: TSdlJoystick

ARight: TSdlJoystick

Returns

Boolean

---

Equal(TSdlJoystick, Pointer)

Used to compare against nil.

class operator Equal(const ALeft: TSdlJoystick; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlJoystick

ARight: Pointer

Returns

Boolean

---

Implicit(Pointer)

Used to set the value to nil.

class operator Implicit(const AValue: Pointer): TSdlJoystick; inline; static

Parameters

AValue: Pointer

Returns

TSdlJoystick

---

NotEqual(TSdlJoystick, TSdlJoystick)

Used to compare against another TSdlJoystick.

class operator NotEqual(const ALeft, ARight: TSdlJoystick): Boolean; inline; static

Parameters

ALeft: TSdlJoystick

ARight: TSdlJoystick

Returns

Boolean

---

NotEqual(TSdlJoystick, Pointer)

Used to compare against nil.

class operator NotEqual(const ALeft: TSdlJoystick; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlJoystick

ARight: Pointer

Returns

Boolean

---

Method Descriptions

AxisInitialState(Integer, Smallint)

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

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

The axis indices start at index 0.

function AxisInitialState(const AAxis: Integer; out AState: Smallint): Boolean; inline

Parameters

AAxis: Integer : The axis to query; the axis indices start at index 0.

AState: Smallint : Upon return, the initial value is supplied here.

Returns

Boolean: True if this axis has any initial value, or False if not.

---

Close

Close a joystick previously opened with Open.

procedure Close; inline

See Also

• Open

---

FromGamepad(TSdlGamepad)

Get the underlying joystick from a gamepad.

This function will give you a TSdlJoystick object, which allows you to use its properties and methods a TSdlGamepad object. This would be useful for getting a joystick's position at any given time, even if it hasn't moved (moving it would produce an event, which would have the axis' value).

The returned joystick is owned by the gamepad. You should not call Close on it, for example, since doing so will likely cause SDL to crash.

class function FromGamepad(const AGamepad: TSdlGamepad): TSdlJoystick; inline; static

Exceptions

ESdlError: Raised on failure.

Parameters

AGamepad: TSdlGamepad : The gamepad object that you want to get a joystick from.

Returns

TSdlJoystick

---

FromID(TSdlJoystickID)

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

class function FromID(const AInstanceID: TSdlJoystickID): TSdlJoystick; inline; static

Exceptions

ESdlError: Raised on failure (eg. when the joystick hasn't been opened).

Parameters

AInstanceID: TSdlJoystickID : The instance ID to get the joystick for.

Returns

TSdlJoystick: The opened joystick.

---

FromPlayerIndex(Integer)

Get the joystick associated with a player index.

class function FromPlayerIndex(const APlayerIndex: Integer): TSdlJoystick; inline; static

Exceptions

ESdlError: Raised on failure.

Parameters

APlayerIndex: Integer : The player index to get the joystick for.

Returns

TSdlJoystick: The opened joystick.

See Also

• PlayerIndex

---

GetPowerInfo(Integer)

Get the battery state of the 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.

function GetPowerInfo(out APercent: Integer): TSdlPowerState; inline

Exceptions

ESdlError: Raised on failure.

Parameters

APercent: Integer : Set to the percentage of battery life left, between 0 and 100. Will be set to -1 if we can't determine a value or there is no battery.

Returns

TSdlPowerState: The current battery state.

---

GuidInfo(TGuid, Word, Word, Word, Word)

Get the device information encoded in a joystick GUID structure.

class procedure GuidInfo(const AGuid: TGuid; out AVendor, AProduct, AVersion, ACrc16: Word); inline; static

Parameters

AGuid: TGuid : The GUID you wish to get info about.

AVendor: Word : Is set to the device VID, or 0 if not available.

AProduct: Word : Is set to the device PID, or 0 if not available.

AVersion: Word : Is set to the device version, or 0 if not available.

ACrc16: Word : Is set to a CRC used to distinguish different products with the same VID/PID, or 0 if not available.

See Also

• Guid
• TSdlJoystickID.Guid

---

Lock

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.

class procedure Lock; inline; static

---

Open(TSdlJoystickID)

Open a joystick for use.

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

class function Open(const AInstanceID: TSdlJoystickID): TSdlJoystick; inline; static

Exceptions

ESdlError: Raised on failure.

Parameters

AInstanceID: TSdlJoystickID

Returns

TSdlJoystick: The opened joystick.

See Also

• Close

---

Rumble(Word, Word, Integer)

Start a rumble effect.

Each call to this method cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.

This method requires you to process SDL events or call Update to update rumble state.

function Rumble(const ALowFrequencyRumble, AHighFrequencyRumble: Word; const ADurationMs: Integer): Boolean; inline

Parameters

ALowFrequencyRumble: Word : The intensity of the low frequency (left) rumble motor, from 0 to $FFFF.

AHighFrequencyRumble: Word : The intensity of the high frequency (right) rumble motor, from 0 to $FFFF.

ADurationMs: Integer : The duration of the rumble effect, in milliseconds.

Returns

Boolean: True, or False if rumble isn't supported on this joystick.

---

RumbleTriggers(Word, Word, Integer)

Start a rumble effect in the joystick's triggers.

Each call to this method 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, Rumble instead.

This method requires you to process SDL events or call Update to update rumble state.

function RumbleTriggers(const ALeftRumble, ARightRumble: Word; const ADurationMs: Integer): Boolean; inline

Parameters

ALeftRumble: Word : The intensity of the left trigger rumble motor, from 0 to $FFFF.

ARightRumble: Word : The intensity of the right trigger rumble motor, The duration of the rumble effect, in milliseconds.True, or False if rumble isn't supported on this joystick.

ADurationMs: Integer

Returns

Boolean

---

SendEffect(TBytes)

Send a joystick specific effect packet.

procedure SendEffect(const AData: TBytes); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AData: TBytes : The data to send to the joystick.

---

SetLed(Byte, Byte, Byte)

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

procedure SetLed(const ARed, AGreen, ABlue: Byte); inline

Exceptions

ESdlError: Raised on failure.

Parameters

ARed: Byte : The intensity of the red LED.

AGreen: Byte : The intensity of the green LED.

ABlue: Byte : The intensity of the blue LED.

---

SetVirtualAxis(Integer, Smallint)

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

Please note that values set here will not be applied until the next call to Update, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: TSdlEvents.Poll, TSdlEvents.Pump and TSdlEvents.Wait.

Note that when sending trigger axes, you should scale the value to the full range of Int16. For example, a trigger at rest would have the value of SDL_JOYSTICK_AXIS_MIN.

procedure SetVirtualAxis(const AAxis: Integer; const AValue: Smallint); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AAxis: Integer : The index of the axis on the virtual joystick to update.

AValue: Smallint : The new value for the specified axis.

---

SetVirtualBall(Integer, Smallint, Smallint)

Generate ball motion on this opened virtual joystick.

Please note that values set here will not be applied until the next call to Update, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: TSdlEvents.Poll, TSdlEvents.Pump and TSdlEvents.Wait.

procedure SetVirtualBall(const ABall: Integer; const AXRel, AYRel: Smallint); inline

Exceptions

ESdlError: Raised on failure.

Parameters

ABall: Integer : The index of the ball on the virtual joystick to update.

AXRel: Smallint : The relative motion on the X axis.

AYRel: Smallint : The relative motion on the Y axis.

---

SetVirtualButton(Integer, Boolean)

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

Please note that values set here will not be applied until the next call to Update, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: TSdlEvents.Poll, TSdlEvents.Pump and TSdlEvents.Wait.

procedure SetVirtualButton(const AButton: Integer; const AIsDown: Boolean); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AButton: Integer : The index of the button on the virtual joystick to update.

AIsDown: Boolean : True if the button is pressed, False otherwise.

---

SetVirtualHat(Integer, Byte)

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 Update, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: TSdlEvents.Poll, TSdlEvents.Pump and TSdlEvents.Wait.

procedure SetVirtualHat(const AHat: Integer; const AValue: Byte); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AHat: Integer : The index of the hat on the virtual joystick to update.

AValue: Byte : The new value for the specified hat.

---

SetVirtualSensorData(TSdlSensorKind, Int64, TArray<Single>)

Send a sensor update for an opened virtual joystick.

Please note that values set here will not be applied until the next call to Update, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: TSdlEvents.Poll, TSdlEvents.Pump and TSdlEvents.Wait.

procedure SetVirtualSensorData(const AKind: TSdlSensorKind; const ATimestamp: Int64; const AData: TArray<Single>); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AKind: TSdlSensorKind : The type of the sensor on the virtual joystick to update.

ATimestamp: Int64 : A 64-bit timestamp in nanoseconds associated with the sensor reading.

AData: TArray<Single> : The data associated with the sensor reading.

---

SetVirtualTouchpad(Integer, Integer, Boolean, Single, Single, Single)

Set touchpad finger state on an opened virtual joystick.

Please note that values set here will not be applied until the next call to Update, which can either be called directly, or can be called indirectly through various other SDL APIs, including, but not limited to the following: TSdlEvents.Poll, TSdlEvents.Pump and TSdlEvents.Wait.

procedure SetVirtualTouchpad(const ATouchpad, AFinger: Integer; const AIsDown: Boolean; const AX, AY, APressure: Single); inline

Exceptions

ESdlError: Raised on failure.

Parameters

ATouchpad: Integer : The index of the touchpad on the virtual joystick to update.

AFinger: Integer : The index of the finger on the touchpad to set.

AIsDown: Boolean : True if the finger is pressed, False if the finger is released.

AX: Single : The X coordinate of the finger on the touchpad, normalized 0 to 1, with the origin in the upper left.

AY: Single : The Y coordinate of the finger on the touchpad, normalized 0 to 1, with the origin in the upper left.

APressure: Single : The pressure of the finger.

---

Unlock

Unlocking for atomic access to the joystick API.

class procedure Unlock; inline; static

---

Update

Update the current state of the open joysticks.

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

class procedure Update; inline; static

---