TSdlHaptic

The haptic record used to identify an SDL haptic.

Definition

Unit: Neslib.Sdl3.Haptic

type TSdlHaptic = record ... end;

Properties

Name	Description
Features	The haptic device's supported features.
ID	The instance ID of this opened haptic device.
IsRumbleSupported	Whether rumble is supported on this haptic device.
MaxEffects	The number of effects a haptic device can store.
MaxEffectsPlaying	The number of effects a haptic device can play at the same time.
Name	The implementation dependent name of this haptic device, or an empty string if no name can be found.
NumAxes	The number of haptic axes the device has.

Operators

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

Methods

Name	Description
Close	Close the haptic device previously opened.
CreateEffect	Create a new haptic effect on this device.
FreeEffect	Destroy a haptic effect on this device.
From	Get the haptic device associated with an instance ID, if it has been opened.
GetEffectStatus	Get the status of the current effect on this haptic device.
InitRumble	Initialize the haptic device for simple rumble playback.
IsEffectSupported	Check to see if an effect is supported by the haptic device.
Open	Open a haptic device for use.
OpenFromJoystick	Open a haptic device for use from a joystick device.
OpenFromMouse	Try to open a haptic device from the current mouse.
Pause	Pause the haptic device.
PlayRumble	Run a simple rumble effect on the haptic device.
Resume	Resume the haptic device.
RunEffect	Run the haptic effect on this haptic device.
SetAutoCenter	Set the global autocenter of the device.
SetGain	Set the global gain of the haptic device.
StopEffect	Stop the haptic effect on this device.
StopEffects	Stop all the currently playing effects on the haptic device.
StopRumble	Stop the simple rumble on the haptic device.
UpdateEffect	Update the properties of an effect.

Property Descriptions

Features

The haptic device's supported features.

property Features: TSdlHapticFeatures read GetFeatures

Type: TSdlHapticFeatures

Exceptions

ESdlError: Raised on failure.

See Also

• IsEffectSupported
• MaxEffects

---

ID

The instance ID of this opened haptic device.

property ID: TSdlHapticID read GetID

Type: TSdlHapticID

Exceptions

ESdlError: Raised on failure.

---

IsRumbleSupported

Whether rumble is supported on this haptic device.

property IsRumbleSupported: Boolean read GetIsRumbleSupported

Type: Boolean

See Also

• InitRumble

---

MaxEffects

The number of effects a haptic device can store.

On some platforms this isn't fully supported, and therefore is an approximation. Always check to see if your created effect was actually created and do not rely solely on this property.

property MaxEffects: Integer read GetMaxEffects

Type: Integer

Exceptions

ESdlError: Raised on failure.

See Also

• MaxEffectsPlaying
• Features

---

MaxEffectsPlaying

The number of effects a haptic device can play at the same time.

This is not supported on all platforms, but will always return a value.

property MaxEffectsPlaying: Integer read GetMaxEffectsPlaying

Type: Integer

Exceptions

ESdlError: Raised on failure.

See Also

• MaxEffects
• Features

---

Name

The implementation dependent name of this haptic device, or an empty string if no name can be found.

property Name: String read GetName

Type: String

See Also

• TSdlHapticID.Name

---

NumAxes

The number of haptic axes the device has.

The number of haptic axes might be useful if working with the TSdlHapticDirection effect.

property NumAxes: Integer read GetNumAxes

Type: Integer

Exceptions

ESdlError: Raised on failure.

---

Operator Descriptions

Equal(TSdlHaptic, TSdlHaptic)

Used to compare against another TSdlHaptic.

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

Parameters

ALeft: TSdlHaptic

ARight: TSdlHaptic

Returns

Boolean

---

Equal(TSdlHaptic, Pointer)

Used to compare against nil.

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

Parameters

ALeft: TSdlHaptic

ARight: Pointer

Returns

Boolean

---

Implicit(Pointer)

Used to set the value to nil.

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

Parameters

AValue: Pointer

Returns

TSdlHaptic

---

NotEqual(TSdlHaptic, TSdlHaptic)

Used to compare against another TSdlHaptic.

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

Parameters

ALeft: TSdlHaptic

ARight: TSdlHaptic

Returns

Boolean

---

NotEqual(TSdlHaptic, Pointer)

Used to compare against nil.

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

Parameters

ALeft: TSdlHaptic

ARight: Pointer

Returns

Boolean

---

Method Descriptions

Close

Close the haptic device previously opened.

procedure Close; inline

See Also

• Open
• OpenFromMouse
• OpenFromJoystick

---

CreateEffect(TSdlHapticEffect)

Create a new haptic effect on this device.

function CreateEffect(const AEffect: TSdlHapticEffect): TSdlHapticEffectID; inline

Exceptions

ESdlError: Raised on failure.

Parameters

AEffect: TSdlHapticEffect : A TSdlHapticEffect record containing the properties of the effect to create.

Returns

TSdlHapticEffectID: The effect ID.

See Also

• FreeEffect
• RunEffect
• UpdateEffect

---

FreeEffect(TSdlHapticEffectID)

Destroy a haptic effect on this device.

This will stop the effect if it's running. Effects are automatically destroyed when the device is closed.

procedure FreeEffect(const AEffect: TSdlHapticEffectID); inline

Parameters

AEffect: TSdlHapticEffectID : The ID of the haptic effect to destroy.

See Also

• CreateEffect

---

From(TSdlHapticID)

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

class function From(const AInstanceID: TSdlHapticID): TSdlHaptic; inline; static

Exceptions

ESdlError: Raised on failure (eg. if it hasn't been opened yet).

Parameters

AInstanceID: TSdlHapticID : The instance ID to get the haptic device for.

Returns

TSdlHaptic

---

GetEffectStatus(TSdlHapticEffectID)

Get the status of the current effect on this haptic device.

Device must support the TSdlHapticFeature.Status feature.

function GetEffectStatus(const AEffect: TSdlHapticEffectID): Boolean; inline

Parameters

AEffect: TSdlHapticEffectID : The ID of the haptic effect to query its status.

Returns

Boolean: True if it is playing, False if it isn't playing or haptic status isn't supported.

See Also

• Features

---

InitRumble

Initialize the haptic device for simple rumble playback.

procedure InitRumble; inline

Exceptions

ESdlError: Raised on failure.

See Also

• PlayRumble
• StopRumble
• IsRumbleSupported

---

IsEffectSupported(TSdlHapticEffect)

Check to see if an effect is supported by the haptic device.

function IsEffectSupported(const AEffect: TSdlHapticEffect): Boolean; inline

Parameters

AEffect: TSdlHapticEffect : The desired effect to query.

Returns

Boolean: True if the effect is supported or False if it isn't.

See Also

• TSdlHapticEffect
• Features

---

Open(TSdlHapticID)

Open a haptic device for use.

When opening a haptic device, its gain will be set to maximum and autocenter will be disabled. To modify these values use TSdlHaptic.SetGain and TSdlHaptic.SetAutoCenter.

class function Open(const AInstanceID: TSdlHapticID): TSdlHaptic; inline; static

Exceptions

ESdlError: Raised on failure.

Parameters

AInstanceID: TSdlHapticID : The haptic device instance ID.

Returns

TSdlHaptic: The haptic device.

See Also

• TSdlHapticID.Open
• TSdlHaptic.Close
• TSdlHapticID.Devices
• TSdlHaptic.SetAutoCenter
• TSdlHaptic.SetGain

---

OpenFromJoystick(TSdlJoystick)

Open a haptic device for use from a joystick device.

You must still close the haptic device separately. It will not be closed with the joystick.

When opened from a joystick you should first close the haptic device before closing the joystick device. If not, on some implementations the haptic device will also get unallocated and you'll be unable to use force feedback on that device.

class function OpenFromJoystick(const AJoystick: TSdlJoystick): TSdlHaptic; inline; static

Exceptions

ESdlError: Raised on failure.

Parameters

AJoystick: TSdlJoystick : The joystick to create a haptic device from.

Returns

TSdlHaptic: The haptic device.

See Also

• Close
• SdlIsJoystickHaptic

---

OpenFromMouse

Try to open a haptic device from the current mouse.

class function OpenFromMouse: TSdlHaptic; inline; static

Exceptions

ESdlError: Raised on failure.

Returns

TSdlHaptic: The haptic device.

See Also

• Close
• SdlIsMouseHaptic

---

Pause

Pause the haptic device.

Device must support the TSdlHapticFeature.Pause feature. Call Resume to resume playback.

Do not modify the effects nor add new ones while the device is paused. That can cause all sorts of weird errors.

procedure Pause; inline

Exceptions

ESdlError: Raised on failure.

See Also

• Resume

---

PlayRumble(Single, Integer)

Run a simple rumble effect on the haptic device.

procedure PlayRumble(const AStrength: Single; const ALengthMs: Integer); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AStrength: Single : Strength of the rumble to play as a 0-1 float value.

ALengthMs: Integer : Length of the rumble to play in milliseconds.

See Also

• InitRumble
• StopRumble

---

Resume

Resume the haptic device.

Call to unpause after Pause.

procedure Resume; inline

Exceptions

ESdlError: Raised on failure.

See Also

• Pause

---

RunEffect(TSdlHapticEffectID, Cardinal)

Run the haptic effect on this haptic device.

To repeat the effect over and over indefinitely, set AIterations to SDL_HAPTIC_INFINITY. (Repeats the envelope - attack and fade.) To make one instance of the effect last indefinitely (so the effect does not fade), set the effect's Length in its record to SDL_HAPTIC_INFINITY instead.

procedure RunEffect(const AEffect: TSdlHapticEffectID; const AIterations: Cardinal); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AEffect: TSdlHapticEffectID : The ID of the haptic effect to run.

AIterations: Cardinal : The number of iterations to run the effect; use SDL_HAPTIC_INFINITY to repeat forever.

See Also

• GetEffectStatus
• StopEffect
• StopEffects

---

SetAutoCenter(Integer)

Set the global autocenter of the device.

Autocenter should be between 0 and 100. Setting it to 0 will disable autocentering.

Device must support the TSdlHapticFeature.AutoCenter feature.

procedure SetAutoCenter(const AAutoCenter: Integer); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AAutoCenter: Integer : Value to set autocenter to (0-100).

See Also

• Features

---

SetGain(Integer)

Set the global gain of the haptic device.

Device must support the TSdlHapticFeature.Gain feature.

The user may specify the maximum gain by setting the environment variable SDL_HAPTIC_GAIN_MAX which should be between 0 and 100. All calls to SetGain will scale linearly using SDL_HAPTIC_GAIN_MAX as the maximum.

procedure SetGain(const AGain: Integer); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AGain: Integer : Value to set the gain to, should be between 0 and 100.

See Also

• Features

---

StopEffect(TSdlHapticEffectID)

Stop the haptic effect on this device.

procedure StopEffect(const AEffect: TSdlHapticEffectID); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AEffect: TSdlHapticEffectID : The ID of the haptic effect to stop.

See Also

• RunEffect
• StopEffects

---

StopEffects

Stop all the currently playing effects on the haptic device.

procedure StopEffects; inline

Exceptions

ESdlError: Raised on failure.

See Also

• RunEffect
• StopEffect

---

StopRumble

Stop the simple rumble on the haptic device.

procedure StopRumble; inline

See Also

• PlayRumble

---

UpdateEffect(TSdlHapticEffectID, TSdlHapticEffect)

Update the properties of an effect.

Can be used dynamically, although behavior when dynamically changing direction may be strange. Specifically the effect may re-upload itself and start playing from the start. You also cannot change the type either when running UpdateEffect.

procedure UpdateEffect(const AEffect: TSdlHapticEffectID; const AData: TSdlHapticEffect); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AEffect: TSdlHapticEffectID : The identifier of the effect to update.

AData: TSdlHapticEffect : A TSdlHapticEffect structure containing the new effect properties to use.

See Also

• CreateEffect
• RunEffect

---