TSdlGamepad

An SDL gamepad

Definition

Unit: Neslib.Sdl3.Input

type TSdlGamepad = record ... end;

Properties

Name	Description
Axis	The current state of an axis control on the gamepad.
Bindings	Get the SDL joystick layer bindings for a gamepad.
Button	The current state of a button on the gamepad.
ConnectionState	The connection state of a gamepad.
EventsEnabled	Set the state of gamepad event processing.
FirmwareVersion	The firmware version of this opened gamepad, if available.
Gamepads	A list of currently connected gamepads.
HasGamepad	Whether a gamepad is currently connected.
ID	The instance ID of this opened gamepad.
IsConnected	Whether the gamepad has been opened and is currently connected.
Kind	The type of this opened gamepad.
Mapping	The current mapping of this gamepad.
Mappings	The current gamepad mappings.
Name	The implementation-dependent name for this opened gamepad, or an empty string if not available.
NumTouchpadFingers	The number of supported simultaneous fingers on a touchpad on a game gamepad.
NumTouchpads	The number of touchpads on the gamepad.
Path	The implementation-dependent path for this opened gamepad, or an empty string if not available.
PlayerIndex	The player index of this opened gamepad, or -1 if not available.
Product	The USB product ID of this opened gamepad, if available.
ProductVersion	The product version of this opened gamepad, if available.
Properties	The properties associated with this opened gamepad.
RealKind	The type of this opened gamepad, ignoring any mapping override.
SensorDataRate	The data rate (number of events per second) of a gamepad sensor, or 0.0 if not available.
SensorEnabled	Whether data reporting for a gamepad sensor is enabled.
Serial	The serial number of this opened gamepad, or an empty string if not available.
SteamHandle	Get the Steam Input handle of this opened gamepad, or 0 if not available.
Vendor	The USB vendor ID of this opened gamepad, if available.

Operators

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

Methods

Name	Description
AddMapping	Add support for gamepads that SDL is unaware of or change the binding of an existing gamepad.
AddMappings(String)	Load a set of gamepad mappings from a file.
AddMappings(TSdlIOStream, Boolean)	Load a set of gamepad mappings from a TSdlIOStream.
AppleSFSymbolsNameFor(TSdlGamepadAxis)	The sfSymbolsName for a given axis on a gamepad on Apple platforms, or an empty string if not found.
AppleSFSymbolsNameFor(TSdlGamepadButton)	The sfSymbolsName for a given button on a gamepad on Apple platforms, or an empty string if not found.
Close	Close the gamepad previously opened with Open.
FromID	Get the gamepad associated with a gamepad instance ID, if it has been opened.
FromPlayerIndex	Get the gamepad associated with a player index.
GetButtonLabel	Get the label of a button on the gamepad.
GetPowerInfo	Get the battery state of the gamepad.
GetSensorData	Get the current state of the gamepad sensor.
GetTouchpadFinger	Get the current state of a finger on a touchpad on a gamepad.
HasAxis	Whether the gamepad has a given axis.
HasButton	Whether the gamepad has a given button.
HasSensor	Whether a gamepad has a particular sensor.
MappingForGuid	Get the gamepad mapping string for a given GUID.
Open	Open a gamepad for use.
ReloadMappings	Reinitialize the SDL mapping database to its initial state.
Rumble	Start a rumble effect on the gamepad.
RumbleTriggers	Start a rumble effect in the gamepad's triggers.
SendEffect	Send a gamepad specific effect packet.
SetLed	Update the gamepad's LED color.
Update	Manually pump gamepad updates if not using the loop.

Property Descriptions

Axis

The current state of an axis control on the gamepad.

For thumbsticks, the state is a value ranging from -32768 (up/left) to 32767 (down/right).

Triggers range from 0 when released to 32767 when fully pressed, and never return a negative value. Note that this differs from the value reported by the lower-level TSdlJoystick.Axis, which normally uses the full range.

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

Type: Smallint

See Also

• HasAxis
• Button

---

Bindings

Get the SDL joystick layer bindings for a gamepad.

property Bindings: TArray<TSdlGamepadBinding> read GetBindings

Type: TArray<TSdlGamepadBinding>

Exceptions

ESdlError: Raised on failure.

---

Button

The current state of a button on the gamepad. True if the button is pressed, False otherwise.

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

Type: Boolean

See Also

• HasButton
• Axis

---

ConnectionState

The connection state of a gamepad.

property ConnectionState: TSdlGamepadConnectionState read GetConnectionState

Type: TSdlGamepadConnectionState

Exceptions

ESdlError: Raised on failure.

---

EventsEnabled

Set the state of gamepad event processing.

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

class property EventsEnabled: Boolean read GetEventsEnabled write SetEventsEnabled

Type: Boolean

See Also

• Update

---

FirmwareVersion

The firmware version of this opened gamepad, if available.

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

property FirmwareVersion: Word read GetFirmwareVersion

Type: Word

---

Gamepads

A list of currently connected gamepads.

class property Gamepads: TArray<TSdlGamepadID> read GetGamepads

Type: TArray<TSdlGamepadID>

Exceptions

ESdlError: Raised on failure.

See Also

• HasGamepad
• Open

---

HasGamepad

Whether a gamepad is currently connected.

class property HasGamepad: Boolean read GetHasGamepad

Type: Boolean

See Also

• Gamepads

---

ID

The instance ID of this opened gamepad.

property ID: TSdlGamepadID read GetID

Type: TSdlGamepadID

Exceptions

ESdlError: Raised on failure.

---

IsConnected

Whether the gamepad has been opened and is currently connected.

property IsConnected: Boolean read GetIsConnected

Type: Boolean

---

Kind

The type of this opened gamepad.

property Kind: TSdlGamepadKind read GetKind

Type: TSdlGamepadKind

See Also

• TSdlGamepadID.Kind

---

Mapping

The current mapping of this gamepad.

Details about mappings are discussed with AddMapping.

property Mapping: String read GetMapping write SetMapping

Type: String

Exceptions

ESdlError: Raised on failure.

See Also

• AddMapping
• TSdlGamepadID.Mapping
• MappingForGuid

---

Mappings

The current gamepad mappings.

class property Mappings: TArray<String> read GetMappings

Type: TArray<String>

Exceptions

ESdlError: Raised on failure.

---

Name

The implementation-dependent name for this opened gamepad, or an empty string if not available.

property Name: String read GetName

Type: String

See Also

• TSdlGamepadID.Name

---

NumTouchpadFingers

The number of supported simultaneous fingers on a touchpad on a game gamepad.

property NumTouchpadFingers[const ATouchPad: Integer]: Integer read GetNumTouchpadFingers

Type: Integer

See Also

• GetTouchpadFinger
• NumTouchpads

---

NumTouchpads

The number of touchpads on the gamepad.

property NumTouchpads: Integer read GetNumTouchpads

Type: Integer

---

Path

The implementation-dependent path for this opened gamepad, or an empty string if not available.

property Path: String read GetPath

Type: String

See Also

• TSdlGamepadID.Path

---

PlayerIndex

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

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

For XInput gamepads this returns the XInput user index.

property PlayerIndex: Integer read GetPlayerIndex write SetPlayerIndex

Type: Integer

Exceptions

ESdlError: Raised on failure.

---

Product

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

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

property Product: Word read GetProduct

Type: Word

See Also

• TSdlGamepadID.Product

---

ProductVersion

The product version of this opened gamepad, if available.

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

property ProductVersion: Word read GetProductVersion

Type: Word

See Also

• TSdlGamepadID.ProductVersion

---

Properties

The properties associated with this opened gamepad.

These properties are shared with the underlying joystick object.

The following read-only properties are provided by SDL:

• TSdlProperty.GamepadCapMonoLed: True if this gamepad has an LED that has adjustable brightness
• TSdlProperty.GamepadCapRgbLed: True if this gamepad has an LED that has adjustable color
• TSdlProperty.GamepadCapPlayerLed: True if this gamepad has a player LED
• TSdlProperty.GamepadCapRumble: True if this gamepad has left/right rumble
• TSdlProperty.GamepadCapTriggerRumble: True if this gamepad has simple trigger rumble

property Properties: TSdlProperties read GetProperties

Type: TSdlProperties

Exceptions

ESdlError: Raised on failure.

---

RealKind

The type of this opened gamepad, ignoring any mapping override.

property RealKind: TSdlGamepadKind read GetRealKind

Type: TSdlGamepadKind

See Also

• TSdlGamepadID.RealKind

---

SensorDataRate

The data rate (number of events per second) of a gamepad sensor, or 0.0 if not available.

property SensorDataRate[const AKind: TSdlSensorKind]: Single read GetSensorDataRate

Type: Single

---

SensorEnabled

Whether data reporting for a gamepad sensor is enabled.

property SensorEnabled[const AKind: TSdlSensorKind]: Boolean read GetSensorEnabled write SetSensorEnabled

Type: Boolean

Exceptions

ESdlError: Raised on failure.

See Also

• HasSensor

---

Serial

The serial number of this opened gamepad, or an empty string if not available.

property Serial: String read GetSerial

Type: String

---

SteamHandle

Get the Steam Input handle of this opened gamepad, or 0 if not available.

Returns a handle for the gamepad that can be used with Steam Input API.

property SteamHandle: UInt64 read GetSteamHandle

Type: UInt64

---

Vendor

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

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

property Vendor: Word read GetVendor

Type: Word

See Also

• TSdlGamepadID.Vendor

---

Operator Descriptions

Equal(TSdlGamepad, TSdlGamepad)

Used to compare against another TSdlGamepad.

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

Parameters

ALeft: TSdlGamepad

ARight: TSdlGamepad

Returns

Boolean

---

Equal(TSdlGamepad, Pointer)

Used to compare against nil.

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

Parameters

ALeft: TSdlGamepad

ARight: Pointer

Returns

Boolean

---

Implicit(Pointer)

Used to set the value to nil.

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

Parameters

AValue: Pointer

Returns

TSdlGamepad

---

NotEqual(TSdlGamepad, TSdlGamepad)

Used to compare against another TSdlGamepad.

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

Parameters

ALeft: TSdlGamepad

ARight: TSdlGamepad

Returns

Boolean

---

NotEqual(TSdlGamepad, Pointer)

Used to compare against nil.

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

Parameters

ALeft: TSdlGamepad

ARight: Pointer

Returns

Boolean

---

Method Descriptions

AddMapping(String)

Add support for gamepads that SDL is unaware of or change the binding of an existing gamepad.

The mapping string has the format 'GUID,Name,Mappings', where:

• GUID is the string value from TGuid.ToString, but with curly braces and dashes removed. Under Windows there is a reserved GUID of 'xinput' that covers all XInput devices
• Name is the human readable string for the device.
• Mappings are gamepad mappings to joystick ones.

The mapping format for joystick is:

• bX: a joystick button, index X
• hX.Y: hat X with value Y
• aX: axis X of the joystick

Buttons can be used as a gamepad axes and vice versa.

If a device with this GUID is already plugged in, SDL will generate an TSdlEventKind.GamepadAdded event.

This string shows an example of a valid mapping for a gamepad:

  '341a3608000000000000504944564944,Afterglow PS3 Controller,'+
  'a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,'+
  'dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,'+
  'leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,'+
  'lefttrigger:b6,righttrigger:b7'

class function AddMapping(const AMapping: String): Boolean; inline; static

Exceptions

ESdlError: Raised on failure.

Parameters

AMapping: String : The mapping string.

Returns

Boolean: True if a new mapping is added, False if an existing mapping is updated.

See Also

• AddMappings
• Mappings
• MappingForGuid
• TSdlHints.GameControllerConfig
• TSdlHints.GameControllerConfigFile

Remarks

It is safe to call this method from any thread.

---

AddMappings(String)

Load a set of gamepad mappings from a file.

You can call this method several times, if needed, to load different database files.

If a new mapping is loaded for an already known gamepad GUID, the later version will overwrite the one currently loaded.

Any new mappings for already plugged in controllers will generate TSdlEventKind.GamepadAdded events.

Mappings not belonging to the current platform or with no platform field specified will be ignored (i.e. mappings for Linux will be ignored in Windows, etc).

class function AddMappings(const AFilename: String): Integer; overload; inline; static

Exceptions

ESdlError: Raised on failure.

Parameters

AFilename: String : The mappings file to load.

Returns

Integer: The number of mappings added.

See Also

• AddMapping
• Mappings
• MappingForGuid
• TSdlHints.GameControllerConfig
• TSdlHints.GameControllerConfigFile

Remarks

It is safe to call this method from any thread.

---

AddMappings(TSdlIOStream, Boolean)

Load a set of gamepad mappings from a TSdlIOStream.

You can call this method several times, if needed, to load different database files.

If a new mapping is loaded for an already known gamepad GUID, the later version will overwrite the one currently loaded.

Any new mappings for already plugged in controllers will generate TSdlEventKind.GamepadAdded events.

Mappings not belonging to the current platform or with no platform field specified will be ignored (i.e. mappings for Linux will be ignored in Windows, etc).

This function will load the text database entirely in memory before processing it, so take this into consideration if you are in a memory constrained environment.

class function AddMappings(const ASrc: TSdlIOStream; const ACloseIO: Boolean): Integer; overload; inline; static

Exceptions

ESdlError: Raised on failure.

Parameters

ASrc: TSdlIOStream : The data stream for the mappings to be added.

ACloseIO: Boolean : If true, calls TSdlIOStream.Close on ASrc before returning, even in the case of an error.

Returns

Integer: The number of mappings added.

See Also

• AddMapping
• Mappings
• MappingForGuid
• TSdlHints.GameControllerConfig
• TSdlHints.GameControllerConfigFile

Remarks

It is safe to call this method from any thread.

---

AppleSFSymbolsNameFor(TSdlGamepadAxis)

The sfSymbolsName for a given axis on a gamepad on Apple platforms, or an empty string if not found.

function AppleSFSymbolsNameFor(const AAxis: TSdlGamepadAxis): String; overload; inline

Parameters

AAxis: TSdlGamepadAxis : A button on the gamepad.

Returns

String

---

AppleSFSymbolsNameFor(TSdlGamepadButton)

The sfSymbolsName for a given button on a gamepad on Apple platforms, or an empty string if not found.

function AppleSFSymbolsNameFor(const AButton: TSdlGamepadButton): String; overload; inline

Parameters

AButton: TSdlGamepadButton : A button on the gamepad.

Returns

String

---

Close

Close the gamepad previously opened with Open.

procedure Close; inline

See Also

• Open

---

FromID(TSdlGamepadID)

Get the gamepad associated with a gamepad instance ID, if it has been opened.

class function FromID(const AInstanceID: TSdlGamepadID): TSdlGamepad; inline; static

Exceptions

ESdlError: Raised on failure (eg. when the gamepad has not been opened).

Parameters

AInstanceID: TSdlGamepadID : The gamepad instance ID.

Returns

TSdlGamepad: The gamepad.

---

FromPlayerIndex(Integer)

Get the gamepad associated with a player index.

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

Exceptions

ESdlError: Raised on failure.

Parameters

APlayerIndex: Integer : The player index.

Returns

TSdlGamepad: The gamepad.

See Also

• PlayerIndex

---

GetButtonLabel(TSdlGamepadButton)

Get the label of a button on the gamepad.

function GetButtonLabel(const AButton: TSdlGamepadButton): TSdlGamepadButtonLabel; inline

Parameters

AButton: TSdlGamepadButton : The button.

Returns

TSdlGamepadButtonLabel: The TSdlGamepadButtonLabel enum corresponding to the button label.

See Also

• TSdlGamepadKind.GetButtonLabel

---

GetPowerInfo(Integer)

Get the battery state of the gamepad.

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.

---

GetSensorData(TSdlSensorKind, TArray<Single>)

Get the current state of the gamepad sensor.

The number of values and interpretation of the data is sensor dependent. The length of the AData array is the maximum number of values that will be written to the array.

procedure GetSensorData(const AKind: TSdlSensorKind; const AData: TArray<Single>); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AKind: TSdlSensorKind : The type of sensor to query.

AData: TArray<Single> : An array filled with the current sensor state.

---

GetTouchpadFinger(Integer, Integer, Boolean, Single, Single, Single)

Get the current state of a finger on a touchpad on a gamepad.

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

Exceptions

ESdlError: Raised on failure.

Parameters

ATouchpad: Integer : The touchpad index.

AFinger: Integer : The finger index.

AIsDown: Boolean : Is set to True if the finger is down, False otherwise.

AX: Single : Is set to the X position, normalized 0 to 1, with the origin in the upper left.

AY: Single : Is set to the Y position, normalized 0 to 1, with the origin in the upper left.

APressure: Single : Is set to the pressure value.

See Also

• NumTouchpadFingers

---

HasAxis(TSdlGamepadAxis)

Whether the gamepad has a given axis.

This merely reports whether the gamepad's mapping defined this axis, as that is all the information SDL has about the physical device.

function HasAxis(const AAxis: TSdlGamepadAxis): Boolean; inline

Parameters

AAxis: TSdlGamepadAxis : The axis enum value.

Returns

Boolean: True if the gamepad has this axis, False otherwise.

See Also

• HasButton
• Axis

---

HasButton(TSdlGamepadButton)

Whether the gamepad has a given button.

This merely reports whether the gamepad's mapping defined this button, as that is all the information SDL has about the physical device.

function HasButton(const AButton: TSdlGamepadButton): Boolean; inline

Parameters

AButton: TSdlGamepadButton : The button enum value.

Returns

Boolean: True if the gamepad has this button, False otherwise.

See Also

• HasAxis
• Button

---

HasSensor(TSdlSensorKind)

Whether a gamepad has a particular sensor.

function HasSensor(const AKind: TSdlSensorKind): Boolean; inline

Parameters

AKind: TSdlSensorKind : The type of sensor to query.

Returns

Boolean: True if the sensor exists, False otherwise.

See Also

• GetSensorData
• SensorDataRate
• SensorEnabled

Remarks

This function is available since SDL 3.2.0.

---

MappingForGuid(TGuid)

Get the gamepad mapping string for a given GUID.

class function MappingForGuid(const AGuid: TGuid): String; static

Exceptions

ESdlError: Raised on failure.

Parameters

AGuid: TGuid : The GUID for which a mapping is desired.

Returns

String: The mapping string.

See Also

• TSdlJoystickID.Guid
• TSdlJoystick.Guid

---

Open(TSdlGamepadID)

Open a gamepad for use.

class function Open(const AInstanceID: TSdlGamepadID): TSdlGamepad; inline; static

Exceptions

ESdlError: Raised on failure.

Parameters

AInstanceID: TSdlGamepadID : The gamepad instance ID.

Returns

TSdlGamepad: The gamepad.

See Also

• Close
• TSdlJoystickID.IsGamepad

---

ReloadMappings

Reinitialize the SDL mapping database to its initial state.

This will generate gamepad events as needed if device mappings change.

class procedure ReloadMappings; inline; static

Exceptions

ESdlError: Raised on failure.

---

Rumble(Word, Word, Integer)

Start a rumble effect on the gamepad.

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 TSdlJoysticks.Update to update rumble state.

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

Exceptions

ESdlError: Raised on failure.

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.

---

RumbleTriggers(Word, Word, Integer)

Start a rumble effect in the gamepad'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 gamepad as a whole. This is currently only supported on Xbox One gamepads. If you want the (more common) whole-gamepad rumble, use Rumble instead.

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

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

Exceptions

ESdlError: Raised on failure.

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, from 0 to $FFFF.

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

See Also

• Rumble

---

SendEffect(TBytes)

Send a gamepad specific effect packet.

procedure SendEffect(const AData: TBytes); inline

Exceptions

ESdlError: Raised on failure.

Parameters

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

---

SetLed(Byte, Byte, Byte)

Update the gamepad's LED color.

An example of a joystick LED is the light on the back of a PlayStation 4's DualShock 4 controller.

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

---

Update

Manually pump gamepad updates if not using the loop.

This method is called automatically by the event loop if events are enabled. Under such circumstances, it will not be necessary to call this method.

class procedure Update; inline; static

---