SDL 3.0
SDL_haptic.h File Reference
+ Include dependency graph for SDL_haptic.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  SDL_HapticDirection
 
struct  SDL_HapticConstant
 
struct  SDL_HapticPeriodic
 
struct  SDL_HapticCondition
 
struct  SDL_HapticRamp
 
struct  SDL_HapticLeftRight
 
struct  SDL_HapticCustom
 
union  SDL_HapticEffect
 

Macros

Haptic effects
#define SDL_HAPTIC_CONSTANT   (1u<<0)
 
#define SDL_HAPTIC_SINE   (1u<<1)
 
#define SDL_HAPTIC_SQUARE   (1u<<2)
 
#define SDL_HAPTIC_TRIANGLE   (1u<<3)
 
#define SDL_HAPTIC_SAWTOOTHUP   (1u<<4)
 
#define SDL_HAPTIC_SAWTOOTHDOWN   (1u<<5)
 
#define SDL_HAPTIC_RAMP   (1u<<6)
 
#define SDL_HAPTIC_SPRING   (1u<<7)
 
#define SDL_HAPTIC_DAMPER   (1u<<8)
 
#define SDL_HAPTIC_INERTIA   (1u<<9)
 
#define SDL_HAPTIC_FRICTION   (1u<<10)
 
#define SDL_HAPTIC_LEFTRIGHT   (1u<<11)
 
#define SDL_HAPTIC_RESERVED1   (1u<<12)
 
#define SDL_HAPTIC_RESERVED2   (1u<<13)
 
#define SDL_HAPTIC_RESERVED3   (1u<<14)
 
#define SDL_HAPTIC_CUSTOM   (1u<<15)
 
#define SDL_HAPTIC_GAIN   (1u<<16)
 
#define SDL_HAPTIC_AUTOCENTER   (1u<<17)
 
#define SDL_HAPTIC_STATUS   (1u<<18)
 
#define SDL_HAPTIC_PAUSE   (1u<<19)
 

Typedefs

typedef struct SDL_Haptic SDL_Haptic
 

Direction encodings

#define SDL_HAPTIC_POLAR   0
 
#define SDL_HAPTIC_CARTESIAN   1
 
#define SDL_HAPTIC_SPHERICAL   2
 
#define SDL_HAPTIC_STEERING_AXIS   3
 
#define SDL_HAPTIC_INFINITY   4294967295U
 
typedef Uint32 SDL_HapticID
 
SDL_HapticIDSDL_GetHaptics (int *count)
 
const char * SDL_GetHapticNameForID (SDL_HapticID instance_id)
 
SDL_HapticSDL_OpenHaptic (SDL_HapticID instance_id)
 
SDL_HapticSDL_GetHapticFromID (SDL_HapticID instance_id)
 
SDL_HapticID SDL_GetHapticID (SDL_Haptic *haptic)
 
const char * SDL_GetHapticName (SDL_Haptic *haptic)
 
SDL_bool SDL_IsMouseHaptic (void)
 
SDL_HapticSDL_OpenHapticFromMouse (void)
 
SDL_bool SDL_IsJoystickHaptic (SDL_Joystick *joystick)
 
SDL_HapticSDL_OpenHapticFromJoystick (SDL_Joystick *joystick)
 
void SDL_CloseHaptic (SDL_Haptic *haptic)
 
int SDL_GetMaxHapticEffects (SDL_Haptic *haptic)
 
int SDL_GetMaxHapticEffectsPlaying (SDL_Haptic *haptic)
 
Uint32 SDL_GetHapticFeatures (SDL_Haptic *haptic)
 
int SDL_GetNumHapticAxes (SDL_Haptic *haptic)
 
SDL_bool SDL_HapticEffectSupported (SDL_Haptic *haptic, const SDL_HapticEffect *effect)
 
int SDL_CreateHapticEffect (SDL_Haptic *haptic, const SDL_HapticEffect *effect)
 
int SDL_UpdateHapticEffect (SDL_Haptic *haptic, int effect, const SDL_HapticEffect *data)
 
int SDL_RunHapticEffect (SDL_Haptic *haptic, int effect, Uint32 iterations)
 
int SDL_StopHapticEffect (SDL_Haptic *haptic, int effect)
 
void SDL_DestroyHapticEffect (SDL_Haptic *haptic, int effect)
 
int SDL_GetHapticEffectStatus (SDL_Haptic *haptic, int effect)
 
int SDL_SetHapticGain (SDL_Haptic *haptic, int gain)
 
int SDL_SetHapticAutocenter (SDL_Haptic *haptic, int autocenter)
 
int SDL_PauseHaptic (SDL_Haptic *haptic)
 
int SDL_ResumeHaptic (SDL_Haptic *haptic)
 
int SDL_StopHapticEffects (SDL_Haptic *haptic)
 
SDL_bool SDL_HapticRumbleSupported (SDL_Haptic *haptic)
 
int SDL_InitHapticRumble (SDL_Haptic *haptic)
 
int SDL_PlayHapticRumble (SDL_Haptic *haptic, float strength, Uint32 length)
 
int SDL_StopHapticRumble (SDL_Haptic *haptic)
 

Macro Definition Documentation

◆ SDL_HAPTIC_AUTOCENTER

#define SDL_HAPTIC_AUTOCENTER   (1u<<17)

Device can set autocenter.

Device supports setting autocenter.

Since
This macro is available since SDL 3.0.0.
See also
SDL_SetHapticAutocenter

Definition at line 344 of file SDL_haptic.h.

◆ SDL_HAPTIC_CARTESIAN

#define SDL_HAPTIC_CARTESIAN   1

Uses cartesian coordinates for the direction.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticDirection

Definition at line 391 of file SDL_haptic.h.

◆ SDL_HAPTIC_CONSTANT

#define SDL_HAPTIC_CONSTANT   (1u<<0)

Constant effect supported.

Constant haptic effect.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticCondition

Definition at line 175 of file SDL_haptic.h.

◆ SDL_HAPTIC_CUSTOM

#define SDL_HAPTIC_CUSTOM   (1u<<15)

Custom effect is supported.

User defined custom haptic effect.

Since
This macro is available since SDL 3.0.0.

Definition at line 318 of file SDL_haptic.h.

◆ SDL_HAPTIC_DAMPER

#define SDL_HAPTIC_DAMPER   (1u<<8)

Damper effect supported - uses axes velocity.

Condition haptic effect that simulates dampening. Effect is based on the axes velocity.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticCondition

Definition at line 265 of file SDL_haptic.h.

◆ SDL_HAPTIC_FRICTION

#define SDL_HAPTIC_FRICTION   (1u<<10)

Friction effect supported - uses axes movement.

Condition haptic effect that simulates friction. Effect is based on the axes movement.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticCondition

Definition at line 289 of file SDL_haptic.h.

◆ SDL_HAPTIC_GAIN

#define SDL_HAPTIC_GAIN   (1u<<16)

Device can set global gain.

Device supports setting the global gain.

Since
This macro is available since SDL 3.0.0.
See also
SDL_SetHapticGain

Definition at line 333 of file SDL_haptic.h.

◆ SDL_HAPTIC_INERTIA

#define SDL_HAPTIC_INERTIA   (1u<<9)

Inertia effect supported - uses axes acceleration.

Condition haptic effect that simulates inertia. Effect is based on the axes acceleration.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticCondition

Definition at line 277 of file SDL_haptic.h.

◆ SDL_HAPTIC_INFINITY

#define SDL_HAPTIC_INFINITY   4294967295U

Used to play a device an infinite number of times.

Since
This macro is available since SDL 3.0.0.
See also
SDL_RunHapticEffect

Definition at line 429 of file SDL_haptic.h.

◆ SDL_HAPTIC_LEFTRIGHT

#define SDL_HAPTIC_LEFTRIGHT   (1u<<11)

Left/Right effect supported.

Haptic effect for direct control over high/low frequency motors.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticLeftRight

Definition at line 300 of file SDL_haptic.h.

◆ SDL_HAPTIC_PAUSE

#define SDL_HAPTIC_PAUSE   (1u<<19)

Device can be paused.

Devices supports being paused.

Since
This macro is available since SDL 3.0.0.
See also
SDL_PauseHaptic
SDL_ResumeHaptic

Definition at line 367 of file SDL_haptic.h.

◆ SDL_HAPTIC_POLAR

#define SDL_HAPTIC_POLAR   0

Uses polar coordinates for the direction.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticDirection

Definition at line 382 of file SDL_haptic.h.

◆ SDL_HAPTIC_RAMP

#define SDL_HAPTIC_RAMP   (1u<<6)

Ramp effect supported.

Ramp haptic effect.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticRamp

Definition at line 241 of file SDL_haptic.h.

◆ SDL_HAPTIC_RESERVED1

#define SDL_HAPTIC_RESERVED1   (1u<<12)

Reserved for future use

Since
This macro is available since SDL 3.0.0.

Definition at line 307 of file SDL_haptic.h.

◆ SDL_HAPTIC_RESERVED2

#define SDL_HAPTIC_RESERVED2   (1u<<13)

Definition at line 308 of file SDL_haptic.h.

◆ SDL_HAPTIC_RESERVED3

#define SDL_HAPTIC_RESERVED3   (1u<<14)

Definition at line 309 of file SDL_haptic.h.

◆ SDL_HAPTIC_SAWTOOTHDOWN

#define SDL_HAPTIC_SAWTOOTHDOWN   (1u<<5)

Sawtoothdown wave effect supported.

Periodic haptic effect that simulates saw tooth down waves.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticPeriodic

Definition at line 230 of file SDL_haptic.h.

◆ SDL_HAPTIC_SAWTOOTHUP

#define SDL_HAPTIC_SAWTOOTHUP   (1u<<4)

Sawtoothup wave effect supported.

Periodic haptic effect that simulates saw tooth up waves.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticPeriodic

Definition at line 219 of file SDL_haptic.h.

◆ SDL_HAPTIC_SINE

#define SDL_HAPTIC_SINE   (1u<<1)

Sine wave effect supported.

Periodic haptic effect that simulates sine waves.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticPeriodic

Definition at line 186 of file SDL_haptic.h.

◆ SDL_HAPTIC_SPHERICAL

#define SDL_HAPTIC_SPHERICAL   2

Uses spherical coordinates for the direction.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticDirection

Definition at line 400 of file SDL_haptic.h.

◆ SDL_HAPTIC_SPRING

#define SDL_HAPTIC_SPRING   (1u<<7)

Spring effect supported - uses axes position.

Condition haptic effect that simulates a spring. Effect is based on the axes position.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticCondition

Definition at line 253 of file SDL_haptic.h.

◆ SDL_HAPTIC_SQUARE

#define SDL_HAPTIC_SQUARE   (1u<<2)

Square wave effect supported.

Periodic haptic effect that simulates square waves.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticPeriodic

Definition at line 197 of file SDL_haptic.h.

◆ SDL_HAPTIC_STATUS

#define SDL_HAPTIC_STATUS   (1u<<18)

Device can be queried for effect status.

Device supports querying effect status.

Since
This macro is available since SDL 3.0.0.
See also
SDL_GetHapticEffectStatus

Definition at line 355 of file SDL_haptic.h.

◆ SDL_HAPTIC_STEERING_AXIS

#define SDL_HAPTIC_STEERING_AXIS   3

Use this value to play an effect on the steering wheel axis.

This provides better compatibility across platforms and devices as SDL will guess the correct axis.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticDirection

Definition at line 412 of file SDL_haptic.h.

◆ SDL_HAPTIC_TRIANGLE

#define SDL_HAPTIC_TRIANGLE   (1u<<3)

Triangle wave effect supported.

Periodic haptic effect that simulates triangular waves.

Since
This macro is available since SDL 3.0.0.
See also
SDL_HapticPeriodic

Definition at line 208 of file SDL_haptic.h.

Typedef Documentation

◆ SDL_Haptic

CategoryHaptic

The SDL haptic subsystem manages haptic (force feedback) devices.

The basic usage is as follows:

Simple rumble example:

SDL_Haptic *haptic = NULL;
// Open the device
if (haptics) {
haptic = SDL_OpenHaptic(haptics[0]);
SDL_free(haptics);
}
if (haptic == NULL)
return -1;
// Initialize simple rumble
if (SDL_InitHapticRumble(haptic) != 0)
return -1;
// Play effect at 50% strength for 2 seconds
if (SDL_PlayHapticRumble(haptic, 0.5, 2000) != 0)
return -1;
SDL_Delay(2000);
// Clean up
#define NULL
SDL_Haptic * SDL_OpenHaptic(SDL_HapticID instance_id)
struct SDL_Haptic SDL_Haptic
Definition SDL_haptic.h:151
int SDL_PlayHapticRumble(SDL_Haptic *haptic, float strength, Uint32 length)
Uint32 SDL_HapticID
Definition SDL_haptic.h:927
void SDL_CloseHaptic(SDL_Haptic *haptic)
int SDL_InitHapticRumble(SDL_Haptic *haptic)
SDL_HapticID * SDL_GetHaptics(int *count)
void SDL_free(void *mem)
void SDL_Delay(Uint32 ms)

Complete example:

int test_haptic(SDL_Joystick *joystick)
{
SDL_Haptic *haptic;
int effect_id;
// Open the device
haptic = SDL_OpenHapticFromJoystick(joystick);
if (haptic == NULL) return -1; // Most likely joystick isn't haptic
// See if it can do sine waves
if ((SDL_GetHapticFeatures(haptic) & SDL_HAPTIC_SINE)==0) {
SDL_CloseHaptic(haptic); // No sine effect
return -1;
}
// Create the effect
SDL_memset(&effect, 0, sizeof(SDL_HapticEffect)); // 0 is safe default
effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
effect.periodic.direction.dir[0] = 18000; // Force comes from south
effect.periodic.period = 1000; // 1000 ms
effect.periodic.magnitude = 20000; // 20000/32767 strength
effect.periodic.length = 5000; // 5 seconds long
effect.periodic.attack_length = 1000; // Takes 1 second to get max strength
effect.periodic.fade_length = 1000; // Takes 1 second to fade away
// Upload the effect
effect_id = SDL_CreateHapticEffect(haptic, &effect);
// Test the effect
SDL_RunHapticEffect(haptic, effect_id, 1);
SDL_Delay(5000); // Wait for the effect to finish
// We destroy the effect, although closing the device also does this
SDL_DestroyHapticEffect(haptic, effect_id);
// Close the device
SDL_CloseHaptic(haptic);
return 0; // Success
}
int SDL_CreateHapticEffect(SDL_Haptic *haptic, const SDL_HapticEffect *effect)
SDL_Haptic * SDL_OpenHapticFromJoystick(SDL_Joystick *joystick)
int SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, Uint32 iterations)
#define SDL_HAPTIC_SINE
Definition SDL_haptic.h:186
#define SDL_HAPTIC_POLAR
Definition SDL_haptic.h:382
Uint32 SDL_GetHapticFeatures(SDL_Haptic *haptic)
void SDL_DestroyHapticEffect(SDL_Haptic *haptic, int effect)
struct SDL_Joystick SDL_Joystick
#define SDL_memset
Definition SDL_stdinc.h:956
SDL_HapticDirection direction
Definition SDL_haptic.h:647
SDL_HapticPeriodic periodic
Definition SDL_haptic.h:909

Note that the SDL haptic subsystem is not thread-safe.

The haptic structure used to identify an SDL haptic.

See also
SDL_OpenHaptic
SDL_OpenHapticFromJoystick
SDL_CloseHaptic

Definition at line 151 of file SDL_haptic.h.

◆ SDL_HapticID

This is a unique ID for a haptic device for the time it is connected to the system, and is never reused for the lifetime of the application.

If the haptic device is disconnected and reconnected, it will get a new ID.

The ID value starts at 1 and increments from there. The value 0 is an invalid ID.

Since
This datatype is available since SDL 3.0.0.

Definition at line 927 of file SDL_haptic.h.

Function Documentation

◆ SDL_CloseHaptic()

void SDL_CloseHaptic ( SDL_Haptic haptic)
extern

Close a haptic device previously opened with SDL_OpenHaptic().

Parameters
hapticthe SDL_Haptic device to close.
Since
This function is available since SDL 3.0.0.
See also
SDL_OpenHaptic

◆ SDL_CreateHapticEffect()

int SDL_CreateHapticEffect ( SDL_Haptic haptic,
const SDL_HapticEffect effect 
)
extern

Create a new haptic effect on a specified device.

Parameters
haptican SDL_Haptic device to create the effect on.
effectan SDL_HapticEffect structure containing the properties of the effect to create.
Returns
the ID of the effect on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_DestroyHapticEffect
SDL_RunHapticEffect
SDL_UpdateHapticEffect

◆ SDL_DestroyHapticEffect()

void SDL_DestroyHapticEffect ( SDL_Haptic haptic,
int  effect 
)
extern

Destroy a haptic effect on the device.

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

Parameters
hapticthe SDL_Haptic device to destroy the effect on.
effectthe ID of the haptic effect to destroy.
Since
This function is available since SDL 3.0.0.
See also
SDL_CreateHapticEffect

◆ SDL_GetHapticEffectStatus()

int SDL_GetHapticEffectStatus ( SDL_Haptic haptic,
int  effect 
)
extern

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

Device must support the SDL_HAPTIC_STATUS feature.

Parameters
hapticthe SDL_Haptic device to query for the effect status on.
effectthe ID of the haptic effect to query its status.
Returns
0 if it isn't playing, 1 if it is playing, or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetHapticFeatures()

Uint32 SDL_GetHapticFeatures ( SDL_Haptic haptic)
extern

Get the haptic device's supported features in bitwise manner.

Parameters
hapticthe SDL_Haptic device to query.
Returns
a list of supported haptic features in bitwise manner (OR'd), or 0 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_HapticEffectSupported
SDL_GetMaxHapticEffects

◆ SDL_GetHapticFromID()

SDL_Haptic * SDL_GetHapticFromID ( SDL_HapticID  instance_id)
extern

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

Parameters
instance_idthe instance ID to get the SDL_Haptic for.
Returns
an SDL_Haptic on success or NULL on failure or if it hasn't been opened yet; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetHapticID()

SDL_HapticID SDL_GetHapticID ( SDL_Haptic haptic)
extern

Get the instance ID of an opened haptic device.

Parameters
hapticthe SDL_Haptic device to query.
Returns
the instance ID of the specified haptic device on success or 0 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetHapticName()

const char * SDL_GetHapticName ( SDL_Haptic haptic)
extern

Get the implementation dependent name of a haptic device.

Parameters
hapticthe SDL_Haptic obtained from SDL_OpenJoystick().
Returns
the name of the selected haptic device. If no name can be found, this function returns NULL; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetHapticNameForID

◆ SDL_GetHapticNameForID()

const char * SDL_GetHapticNameForID ( SDL_HapticID  instance_id)
extern

Get the implementation dependent name of a haptic device.

This can be called before any haptic devices are opened.

Parameters
instance_idthe haptic device instance ID.
Returns
the name of the selected haptic device. If no name can be found, this function returns NULL; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetHapticName
SDL_OpenHaptic

◆ SDL_GetHaptics()

SDL_HapticID * SDL_GetHaptics ( int *  count)
extern

Get a list of currently connected haptic devices.

Parameters
counta pointer filled in with the number of haptic devices returned, may be NULL.
Returns
a 0 terminated array of haptic device instance IDs or NULL on failure; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
Since
This function is available since SDL 3.0.0.
See also
SDL_OpenHaptic

◆ SDL_GetMaxHapticEffects()

int SDL_GetMaxHapticEffects ( SDL_Haptic haptic)
extern

Get 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 SDL_GetMaxHapticEffects().

Parameters
hapticthe SDL_Haptic device to query.
Returns
the number of effects the haptic device can store or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetMaxHapticEffectsPlaying
SDL_GetHapticFeatures

◆ SDL_GetMaxHapticEffectsPlaying()

int SDL_GetMaxHapticEffectsPlaying ( SDL_Haptic haptic)
extern

Get 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.

Parameters
hapticthe SDL_Haptic device to query maximum playing effects.
Returns
the number of effects the haptic device can play at the same time or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetMaxHapticEffects
SDL_GetHapticFeatures

◆ SDL_GetNumHapticAxes()

int SDL_GetNumHapticAxes ( SDL_Haptic haptic)
extern

Get the number of haptic axes the device has.

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

Parameters
hapticthe SDL_Haptic device to query.
Returns
the number of axes on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_HapticEffectSupported()

SDL_bool SDL_HapticEffectSupported ( SDL_Haptic haptic,
const SDL_HapticEffect effect 
)
extern

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

Parameters
hapticthe SDL_Haptic device to query.
effectthe desired effect to query.
Returns
SDL_TRUE if the effect is supported or SDL_FALSE if it isn't.
Since
This function is available since SDL 3.0.0.
See also
SDL_CreateHapticEffect
SDL_GetHapticFeatures

◆ SDL_HapticRumbleSupported()

SDL_bool SDL_HapticRumbleSupported ( SDL_Haptic haptic)
extern

Check whether rumble is supported on a haptic device.

Parameters
haptichaptic device to check for rumble support.
Returns
SDL_TRUE if the effect is supported or SDL_FALSE if it isn't.
Since
This function is available since SDL 3.0.0.
See also
SDL_InitHapticRumble

◆ SDL_InitHapticRumble()

int SDL_InitHapticRumble ( SDL_Haptic haptic)
extern

Initialize a haptic device for simple rumble playback.

Parameters
hapticthe haptic device to initialize for simple rumble playback.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_PlayHapticRumble
SDL_StopHapticRumble
SDL_HapticRumbleSupported

◆ SDL_IsJoystickHaptic()

SDL_bool SDL_IsJoystickHaptic ( SDL_Joystick joystick)
extern

Query if a joystick has haptic features.

Parameters
joystickthe SDL_Joystick to test for haptic capabilities.
Returns
SDL_TRUE if the joystick is haptic or SDL_FALSE if it isn't.
Since
This function is available since SDL 3.0.0.
See also
SDL_OpenHapticFromJoystick

◆ SDL_IsMouseHaptic()

SDL_bool SDL_IsMouseHaptic ( void  )
extern

Query whether or not the current mouse has haptic capabilities.

Returns
SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't.
Since
This function is available since SDL 3.0.0.
See also
SDL_OpenHapticFromMouse

◆ SDL_OpenHaptic()

SDL_Haptic * SDL_OpenHaptic ( SDL_HapticID  instance_id)
extern

Open a haptic device for use.

The index passed as an argument refers to the N'th haptic device on this system.

When opening a haptic device, its gain will be set to maximum and autocenter will be disabled. To modify these values use SDL_SetHapticGain() and SDL_SetHapticAutocenter().

Parameters
instance_idthe haptic device instance ID.
Returns
the device identifier or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_CloseHaptic
SDL_GetHaptics
SDL_OpenHapticFromJoystick
SDL_OpenHapticFromMouse
SDL_SetHapticAutocenter
SDL_SetHapticGain

◆ SDL_OpenHapticFromJoystick()

SDL_Haptic * SDL_OpenHapticFromJoystick ( SDL_Joystick joystick)
extern

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.

Parameters
joystickthe SDL_Joystick to create a haptic device from.
Returns
a valid haptic device identifier on success or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_CloseHaptic
SDL_IsJoystickHaptic

◆ SDL_OpenHapticFromMouse()

SDL_Haptic * SDL_OpenHapticFromMouse ( void  )
extern

Try to open a haptic device from the current mouse.

Returns
the haptic device identifier or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_CloseHaptic
SDL_IsMouseHaptic

◆ SDL_PauseHaptic()

int SDL_PauseHaptic ( SDL_Haptic haptic)
extern

Pause a haptic device.

Device must support the SDL_HAPTIC_PAUSE feature. Call SDL_ResumeHaptic() 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.

Parameters
hapticthe SDL_Haptic device to pause.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_ResumeHaptic

◆ SDL_PlayHapticRumble()

int SDL_PlayHapticRumble ( SDL_Haptic haptic,
float  strength,
Uint32  length 
)
extern

Run a simple rumble effect on a haptic device.

Parameters
hapticthe haptic device to play the rumble effect on.
strengthstrength of the rumble to play as a 0-1 float value.
lengthlength of the rumble to play in milliseconds.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_InitHapticRumble
SDL_StopHapticRumble

◆ SDL_ResumeHaptic()

int SDL_ResumeHaptic ( SDL_Haptic haptic)
extern

Resume a haptic device.

Call to unpause after SDL_PauseHaptic().

Parameters
hapticthe SDL_Haptic device to unpause.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_PauseHaptic

◆ SDL_RunHapticEffect()

int SDL_RunHapticEffect ( SDL_Haptic haptic,
int  effect,
Uint32  iterations 
)
extern

Run the haptic effect on its associated haptic device.

To repeat the effect over and over indefinitely, set iterations 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 structure/union to SDL_HAPTIC_INFINITY instead.

Parameters
hapticthe SDL_Haptic device to run the effect on.
effectthe ID of the haptic effect to run.
iterationsthe number of iterations to run the effect; use SDL_HAPTIC_INFINITY to repeat forever.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetHapticEffectStatus
SDL_StopHapticEffect
SDL_StopHapticEffects

◆ SDL_SetHapticAutocenter()

int SDL_SetHapticAutocenter ( SDL_Haptic haptic,
int  autocenter 
)
extern

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 SDL_HAPTIC_AUTOCENTER feature.

Parameters
hapticthe SDL_Haptic device to set autocentering on.
autocentervalue to set autocenter to (0-100).
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetHapticFeatures

◆ SDL_SetHapticGain()

int SDL_SetHapticGain ( SDL_Haptic haptic,
int  gain 
)
extern

Set the global gain of the specified haptic device.

Device must support the SDL_HAPTIC_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 SDL_SetHapticGain() will scale linearly using SDL_HAPTIC_GAIN_MAX as the maximum.

Parameters
hapticthe SDL_Haptic device to set the gain on.
gainvalue to set the gain to, should be between 0 and 100 (0 - 100).
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetHapticFeatures

◆ SDL_StopHapticEffect()

int SDL_StopHapticEffect ( SDL_Haptic haptic,
int  effect 
)
extern

Stop the haptic effect on its associated haptic device.

Parameters
hapticthe SDL_Haptic device to stop the effect on.
effectthe ID of the haptic effect to stop.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_RunHapticEffect
SDL_StopHapticEffects

◆ SDL_StopHapticEffects()

int SDL_StopHapticEffects ( SDL_Haptic haptic)
extern

Stop all the currently playing effects on a haptic device.

Parameters
hapticthe SDL_Haptic device to stop.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_RunHapticEffect
SDL_StopHapticEffects

◆ SDL_StopHapticRumble()

int SDL_StopHapticRumble ( SDL_Haptic haptic)
extern

Stop the simple rumble on a haptic device.

Parameters
hapticthe haptic device to stop the rumble effect on.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_PlayHapticRumble

◆ SDL_UpdateHapticEffect()

int SDL_UpdateHapticEffect ( SDL_Haptic haptic,
int  effect,
const SDL_HapticEffect data 
)
extern

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 SDL_UpdateHapticEffect().

Parameters
hapticthe SDL_Haptic device that has the effect.
effectthe identifier of the effect to update.
dataan SDL_HapticEffect structure containing the new effect properties to use.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_CreateHapticEffect
SDL_RunHapticEffect