The SDL haptic subsystem allows you to control haptic (force feedback) devices. More...

#include "SDL_stdinc.h"
#include "SDL_error.h"
#include "SDL_joystick.h"
#include "begin_code.h"
#include "close_code.h"

Classes
struct	SDL_HapticDirection
	Structure that represents a haptic direction. More...

struct	SDL_HapticConstant
	A structure containing a template for a Constant effect. More...

struct	SDL_HapticPeriodic
	A structure containing a template for a Periodic effect. More...

struct	SDL_HapticCondition
	A structure containing a template for a Condition effect. More...

struct	SDL_HapticRamp
	A structure containing a template for a Ramp effect. More...

struct	SDL_HapticLeftRight
	A structure containing a template for a Left/Right effect. More...

struct	SDL_HapticCustom
	A structure containing a template for the SDL_HAPTIC_CUSTOM effect. More...

union	SDL_HapticEffect
	The generic template for any haptic effect. More...

Macros
#define	SDL_HAPTIC_GAIN (1u<<12)
	Device can set global gain. More...

#define	SDL_HAPTIC_AUTOCENTER (1u<<13)
	Device can set autocenter. More...

#define	SDL_HAPTIC_STATUS (1u<<14)
	Device can be queried for effect status. More...

#define	SDL_HAPTIC_PAUSE (1u<<15)
	Device can be paused. More...

#define	SDL_HAPTIC_INFINITY 4294967295U
	Used to play a device an infinite number of times. More...

Haptic effects
#define	SDL_HAPTIC_CONSTANT (1u<<0)
	Constant effect supported. More...

#define	SDL_HAPTIC_SINE (1u<<1)
	Sine wave effect supported. More...

#define	SDL_HAPTIC_LEFTRIGHT (1u<<2)
	Left/Right effect supported. More...

#define	SDL_HAPTIC_TRIANGLE (1u<<3)
	Triangle wave effect supported. More...

#define	SDL_HAPTIC_SAWTOOTHUP (1u<<4)
	Sawtoothup wave effect supported. More...

#define	SDL_HAPTIC_SAWTOOTHDOWN (1u<<5)
	Sawtoothdown wave effect supported. More...

#define	SDL_HAPTIC_RAMP (1u<<6)
	Ramp effect supported. More...

#define	SDL_HAPTIC_SPRING (1u<<7)
	Spring effect supported - uses axes position. More...

#define	SDL_HAPTIC_DAMPER (1u<<8)
	Damper effect supported - uses axes velocity. More...

#define	SDL_HAPTIC_INERTIA (1u<<9)
	Inertia effect supported - uses axes acceleration. More...

#define	SDL_HAPTIC_FRICTION (1u<<10)
	Friction effect supported - uses axes movement. More...

#define	SDL_HAPTIC_CUSTOM (1u<<11)
	Custom effect is supported. More...

Direction encodings
#define	SDL_HAPTIC_POLAR 0
	Uses polar coordinates for the direction. More...

#define	SDL_HAPTIC_CARTESIAN 1
	Uses cartesian coordinates for the direction. More...

#define	SDL_HAPTIC_SPHERICAL 2
	Uses spherical coordinates for the direction. More...

Typedefs
typedef struct _SDL_Haptic	SDL_Haptic
	The haptic structure used to identify an SDL haptic. More...

typedef struct SDL_HapticDirection	SDL_HapticDirection
	Structure that represents a haptic direction. More...

typedef struct SDL_HapticConstant	SDL_HapticConstant
	A structure containing a template for a Constant effect. More...

typedef struct SDL_HapticPeriodic	SDL_HapticPeriodic
	A structure containing a template for a Periodic effect. More...

typedef struct SDL_HapticCondition	SDL_HapticCondition
	A structure containing a template for a Condition effect. More...

typedef struct SDL_HapticRamp	SDL_HapticRamp
	A structure containing a template for a Ramp effect. More...

typedef struct SDL_HapticLeftRight	SDL_HapticLeftRight
	A structure containing a template for a Left/Right effect. More...

typedef struct SDL_HapticCustom	SDL_HapticCustom
	A structure containing a template for the SDL_HAPTIC_CUSTOM effect. More...

typedef union SDL_HapticEffect	SDL_HapticEffect
	The generic template for any haptic effect. More...

Functions
DECLSPEC int SDLCALL	SDL_NumHaptics (void)
	Count the number of haptic devices attached to the system. More...

DECLSPEC const char *SDLCALL	SDL_HapticName (int device_index)
	Get the implementation dependent name of a haptic device. More...

DECLSPEC SDL_Haptic *SDLCALL	SDL_HapticOpen (int device_index)
	Opens a haptic device for use. More...

DECLSPEC int SDLCALL	SDL_HapticOpened (int device_index)
	Checks if the haptic device at index has been opened. More...

DECLSPEC int SDLCALL	SDL_HapticIndex (SDL_Haptic *haptic)
	Gets the index of a haptic device. More...

DECLSPEC int SDLCALL	SDL_MouseIsHaptic (void)
	Gets whether or not the current mouse has haptic capabilities. More...

DECLSPEC SDL_Haptic *SDLCALL	SDL_HapticOpenFromMouse (void)
	Tries to open a haptic device from the current mouse. More...

DECLSPEC int SDLCALL	SDL_JoystickIsHaptic (SDL_Joystick *joystick)
	Checks to see if a joystick has haptic features. More...

DECLSPEC SDL_Haptic *SDLCALL	SDL_HapticOpenFromJoystick (SDL_Joystick *joystick)
	Opens a haptic device for use from a joystick device. More...

DECLSPEC void SDLCALL	SDL_HapticClose (SDL_Haptic *haptic)
	Closes a haptic device previously opened with SDL_HapticOpen(). More...

DECLSPEC int SDLCALL	SDL_HapticNumEffects (SDL_Haptic *haptic)
	Returns the number of effects a haptic device can store. More...

DECLSPEC int SDLCALL	SDL_HapticNumEffectsPlaying (SDL_Haptic *haptic)
	Returns the number of effects a haptic device can play at the same time. More...

DECLSPEC unsigned int SDLCALL	SDL_HapticQuery (SDL_Haptic *haptic)
	Gets the haptic device's supported features in bitwise manner. More...

DECLSPEC int SDLCALL	SDL_HapticNumAxes (SDL_Haptic *haptic)
	Gets the number of haptic axes the device has. More...

DECLSPEC int SDLCALL	SDL_HapticEffectSupported (SDL_Haptic haptic, SDL_HapticEffect effect)
	Checks to see if effect is supported by haptic. More...

DECLSPEC int SDLCALL	SDL_HapticNewEffect (SDL_Haptic haptic, SDL_HapticEffect effect)
	Creates a new haptic effect on the device. More...

DECLSPEC int SDLCALL	SDL_HapticUpdateEffect (SDL_Haptic haptic, int effect, SDL_HapticEffect data)
	Updates the properties of an effect. More...

DECLSPEC int SDLCALL	SDL_HapticRunEffect (SDL_Haptic *haptic, int effect, Uint32 iterations)
	Runs the haptic effect on its associated haptic device. More...

DECLSPEC int SDLCALL	SDL_HapticStopEffect (SDL_Haptic *haptic, int effect)
	Stops the haptic effect on its associated haptic device. More...

DECLSPEC void SDLCALL	SDL_HapticDestroyEffect (SDL_Haptic *haptic, int effect)
	Destroys a haptic effect on the device. More...

DECLSPEC int SDLCALL	SDL_HapticGetEffectStatus (SDL_Haptic *haptic, int effect)
	Gets the status of the current effect on the haptic device. More...

DECLSPEC int SDLCALL	SDL_HapticSetGain (SDL_Haptic *haptic, int gain)
	Sets the global gain of the device. More...

DECLSPEC int SDLCALL	SDL_HapticSetAutocenter (SDL_Haptic *haptic, int autocenter)
	Sets the global autocenter of the device. More...

DECLSPEC int SDLCALL	SDL_HapticPause (SDL_Haptic *haptic)
	Pauses a haptic device. More...

DECLSPEC int SDLCALL	SDL_HapticUnpause (SDL_Haptic *haptic)
	Unpauses a haptic device. More...

DECLSPEC int SDLCALL	SDL_HapticStopAll (SDL_Haptic *haptic)
	Stops all the currently playing effects on a haptic device. More...

DECLSPEC int SDLCALL	SDL_HapticRumbleSupported (SDL_Haptic *haptic)
	Checks to see if rumble is supported on a haptic device. More...

DECLSPEC int SDLCALL	SDL_HapticRumbleInit (SDL_Haptic *haptic)
	Initializes the haptic device for simple rumble playback. More...

DECLSPEC int SDLCALL	SDL_HapticRumblePlay (SDL_Haptic *haptic, float strength, Uint32 length)
	Runs simple rumble on a haptic device. More...

DECLSPEC int SDLCALL	SDL_HapticRumbleStop (SDL_Haptic *haptic)
	Stops the simple rumble on a haptic device. More...

Detailed Description

The SDL haptic subsystem allows you to control haptic (force feedback) devices.

The basic usage is as follows:

Initialize the subsystem (SDL_INIT_HAPTIC).
Open a haptic device.
- SDL_HapticOpen() to open from index.
- SDL_HapticOpenFromJoystick() to open from an existing joystick.
Create an effect (SDL_HapticEffect).
Upload the effect with SDL_HapticNewEffect().
Run the effect with SDL_HapticRunEffect().
(optional) Free the effect with SDL_HapticDestroyEffect().
Close the haptic device with SDL_HapticClose().

Simple rumble example:: SDL_Haptic *haptic;
// Open the device
haptic = SDL_HapticOpen( 0 );
if (haptic == NULL)
return -1;
// Initialize simple rumble
if (SDL_HapticRumbleInit( haptic ) != 0)
return -1;
// Play effect at 50% strength for 2 seconds
if (SDL_HapticRumblePlay( haptic, 0.5, 2000 ) != 0)
return -1;
SDL_Delay( 2000 );
// Clean up
SDL_HapticClose( haptic );

Complete example:: int test_haptic( SDL_Joystick * joystick ) {
SDL_Haptic *haptic;
SDL_HapticEffect effect;
int effect_id;
// Open the device
haptic = SDL_HapticOpenFromJoystick( joystick );
if (haptic == NULL) return -1; // Most likely joystick isn't haptic
// See if it can do sine waves
if ((SDL_HapticQuery(haptic) & SDL_HAPTIC_SINE)==0) {
SDL_HapticClose(haptic); // No sine effect
return -1;
}
// Create the effect
memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
effect.type = SDL_HAPTIC_SINE;
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_HapticNewEffect( haptic, &effect );
// Test the effect
SDL_HapticRunEffect( 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_HapticDestroyEffect( haptic, effect_id );
// Close the device
SDL_HapticClose(haptic);
return 0; // Success
}

Definition in file SDL_haptic.h.

Macro Definition Documentation

◆ SDL_HAPTIC_AUTOCENTER

#define SDL_HAPTIC_AUTOCENTER (1u<<13)

Device can set autocenter.

Device supports setting autocenter.

See also: SDL_HapticSetAutocenter

Definition at line 291 of file SDL_haptic.h.

◆ SDL_HAPTIC_CARTESIAN

#define SDL_HAPTIC_CARTESIAN 1

Uses cartesian coordinates for the direction.

See also: SDL_HapticDirection

Definition at line 330 of file SDL_haptic.h.

◆ SDL_HAPTIC_CONSTANT

#define SDL_HAPTIC_CONSTANT (1u<<0)

Constant effect supported.

Constant haptic effect.

See also: SDL_HapticCondition

Definition at line 163 of file SDL_haptic.h.

◆ SDL_HAPTIC_CUSTOM

#define SDL_HAPTIC_CUSTOM (1u<<11)

Custom effect is supported.

User defined custom haptic effect.

Definition at line 269 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.

See also: SDL_HapticCondition

Definition at line 242 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.

See also: SDL_HapticCondition

Definition at line 262 of file SDL_haptic.h.

◆ SDL_HAPTIC_GAIN

#define SDL_HAPTIC_GAIN (1u<<12)

Device can set global gain.

Device supports setting the global gain.

See also: SDL_HapticSetGain

Definition at line 282 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.

See also: SDL_HapticCondition

Definition at line 252 of file SDL_haptic.h.

◆ SDL_HAPTIC_INFINITY

#define SDL_HAPTIC_INFINITY 4294967295U

Used to play a device an infinite number of times.

See also: SDL_HapticRunEffect

Definition at line 352 of file SDL_haptic.h.

◆ SDL_HAPTIC_LEFTRIGHT

#define SDL_HAPTIC_LEFTRIGHT (1u<<2)

Left/Right effect supported.

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

See also: SDL_HapticLeftRight

Warning: this value was SDL_HAPTIC_SQUARE right before 2.0.0 shipped. Sorry, we ran out of bits, and this is important for XInput devices.

Definition at line 183 of file SDL_haptic.h.

◆ SDL_HAPTIC_PAUSE

#define SDL_HAPTIC_PAUSE (1u<<15)

Device can be paused.

Devices supports being paused.

See also: SDL_HapticPause; SDL_HapticUnpause

Definition at line 310 of file SDL_haptic.h.

◆ SDL_HAPTIC_POLAR

#define SDL_HAPTIC_POLAR 0

Uses polar coordinates for the direction.

See also: SDL_HapticDirection

Definition at line 323 of file SDL_haptic.h.

◆ SDL_HAPTIC_RAMP

#define SDL_HAPTIC_RAMP (1u<<6)

Ramp effect supported.

Ramp haptic effect.

See also: SDL_HapticRamp

Definition at line 222 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.

See also: SDL_HapticPeriodic

Definition at line 213 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.

See also: SDL_HapticPeriodic

Definition at line 204 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.

See also: SDL_HapticPeriodic

Definition at line 172 of file SDL_haptic.h.

◆ SDL_HAPTIC_SPHERICAL

#define SDL_HAPTIC_SPHERICAL 2

Uses spherical coordinates for the direction.

See also: SDL_HapticDirection

Definition at line 337 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.

See also: SDL_HapticCondition

Definition at line 232 of file SDL_haptic.h.

◆ SDL_HAPTIC_STATUS

#define SDL_HAPTIC_STATUS (1u<<14)

Device can be queried for effect status.

Device supports querying effect status.

See also: SDL_HapticGetEffectStatus

Definition at line 300 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.

See also: SDL_HapticPeriodic

Definition at line 195 of file SDL_haptic.h.

Typedef Documentation

◆ SDL_Haptic

SDL_Haptic

The haptic structure used to identify an SDL haptic.

See also: SDL_HapticOpen; SDL_HapticOpenFromJoystick; SDL_HapticClose

Definition at line 141 of file SDL_haptic.h.

◆ SDL_HapticCondition

typedef struct SDL_HapticCondition SDL_HapticCondition

A structure containing a template for a Condition effect.

The struct handles the following effects:

SDL_HAPTIC_SPRING: Effect based on axes position.
SDL_HAPTIC_DAMPER: Effect based on axes velocity.
SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
SDL_HAPTIC_FRICTION: Effect based on axes movement.

Direction is handled by condition internals instead of a direction member. The condition effect specific members have three parameters. The first refers to the X axis, the second refers to the Y axis and the third refers to the Z axis. The right terms refer to the positive side of the axis and the left terms refer to the negative side of the axis. Please refer to the SDL_HapticDirection diagram for which side is positive and which is negative.

See also: SDL_HapticDirection; SDL_HAPTIC_SPRING; SDL_HAPTIC_DAMPER; SDL_HAPTIC_INERTIA; SDL_HAPTIC_FRICTION; SDL_HapticEffect

◆ SDL_HapticConstant

typedef struct SDL_HapticConstant SDL_HapticConstant

A structure containing a template for a Constant effect.

This struct is exclusively for the SDL_HAPTIC_CONSTANT effect.

A constant effect applies a constant force in the specified direction to the joystick.

See also: SDL_HAPTIC_CONSTANT; SDL_HapticEffect

◆ SDL_HapticCustom

typedef struct SDL_HapticCustom SDL_HapticCustom

A structure containing a template for the SDL_HAPTIC_CUSTOM effect.

This struct is exclusively for the SDL_HAPTIC_CUSTOM effect.

A custom force feedback effect is much like a periodic effect, where the application can define its exact shape. You will have to allocate the data yourself. Data should consist of channels * samples Uint16 samples.

If channels is one, the effect is rotated using the defined direction. Otherwise it uses the samples in data for the different axes.

See also: SDL_HAPTIC_CUSTOM; SDL_HapticEffect

◆ SDL_HapticDirection

typedef struct SDL_HapticDirection SDL_HapticDirection

Structure that represents a haptic direction.

This is the direction where the force comes from, instead of the direction in which the force is exerted.

Directions can be specified by:

SDL_HAPTIC_POLAR : Specified by polar coordinates.
SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.

Cardinal directions of the haptic device are relative to the positioning of the device. North is considered to be away from the user.

The following diagram represents the cardinal directions:

              .--.
              |__| .-------.
              |=.| |.-----.|
              |--| ||     ||
              |  | |'-----'|
              |__|~')_____('
                [ COMPUTER ]


                  North (0,-1)
                      ^
                      |
                      |
(-1,0)  West <----[ HAPTIC ]----> East (1,0)
                      |
                      |
                      v
                   South (0,1)


                   [ USER ]
                     \|||/
                     (o o)
               ---ooO-(_)-Ooo---

If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a degree starting north and turning clockwise. SDL_HAPTIC_POLAR only uses the first dir parameter. The cardinal directions would be:

North: 0 (0 degrees)
East: 9000 (90 degrees)
South: 18000 (180 degrees)
West: 27000 (270 degrees)

If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first three dir parameters. The cardinal directions would be:

North: 0,-1, 0
East: 1, 0, 0
South: 0, 1, 0
West: -1, 0, 0

The Z axis represents the height of the effect if supported, otherwise it's unused. In cartesian encoding (1, 2) would be the same as (2, 4), you can use any multiple you want, only the direction matters.

If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. The first two dir parameters are used. The dir parameters are as follows (all values are in hundredths of degrees):

Degrees from (1, 0) rotated towards (0, 1).
Degrees towards (0, 0, 1) (device needs at least 3 axes).

Example of force coming from the south with all encodings (force coming from the south means the user will have to pull the stick to counteract):

SDL_HapticDirection direction;
// Cartesian directions
direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
direction.dir[0] = 0; // X position
direction.dir[1] = 1; // Y position
// Assuming the device has 2 axes, we don't need to specify third parameter.
// Polar directions
direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
direction.dir[0] = 18000; // Polar only uses first parameter
// Spherical coordinates
direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.

See also: SDL_HAPTIC_POLAR; SDL_HAPTIC_CARTESIAN; SDL_HAPTIC_SPHERICAL; SDL_HapticEffect; SDL_HapticNumAxes

◆ SDL_HapticEffect

typedef union SDL_HapticEffect SDL_HapticEffect

The generic template for any haptic effect.

All values max at 32767 (0x7FFF). Signed values also can be negative. Time values unless specified otherwise are in milliseconds.

You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value. Neither delay, interval, attack_length nor fade_length support SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends.

Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of SDL_HAPTIC_INFINITY.

Button triggers may not be supported on all devices, it is advised to not use them if possible. Buttons start at index 1 instead of index 0 like the joystick.

If both attack_length and fade_level are 0, the envelope is not used, otherwise both values are used.

Common parts:

// Replay - All effects have this
Uint32 length;        // Duration of effect (ms).
Uint16 delay;         // Delay before starting effect.
// Trigger - All effects have this
Uint16 button;        // Button that triggers effect.
Uint16 interval;      // How soon before effect can be triggered again.
// Envelope - All effects except condition effects have this
Uint16 attack_length; // Duration of the attack (ms).
Uint16 attack_level;  // Level at the start of the attack.
Uint16 fade_length;   // Duration of the fade out (ms).
Uint16 fade_level;    // Level at the end of the fade.

Here we have an example of a constant effect evolution in time:

Strength
^
|
|    effect level -->  _________________
|                     /                 \
|                    /                   \
|                   /                     \
|                  /                       \
| attack_level --> |                        \
|                  |                        |  <---  fade_level
|
+--------------------------------------------------> Time
                   [--]                 [---]
                   attack_length        fade_length

[------------------][-----------------------]
delay               length

Note either the attack_level or the fade_level may be above the actual effect level.

See also: SDL_HapticConstant; SDL_HapticPeriodic; SDL_HapticCondition; SDL_HapticRamp; SDL_HapticLeftRight; SDL_HapticCustom

◆ SDL_HapticLeftRight

typedef struct SDL_HapticLeftRight SDL_HapticLeftRight

A structure containing a template for a Left/Right effect.

This struct is exclusively for the SDL_HAPTIC_LEFTRIGHT effect.

The Left/Right effect is used to explicitly control the large and small motors, commonly found in modern game controllers. The small (right) motor is high frequency, and the large (left) motor is low frequency.

See also: SDL_HAPTIC_LEFTRIGHT; SDL_HapticEffect

◆ SDL_HapticPeriodic

typedef struct SDL_HapticPeriodic SDL_HapticPeriodic

A structure containing a template for a Periodic effect.

The struct handles the following effects:

A periodic effect consists in a wave-shaped effect that repeats itself over time. The type determines the shape of the wave and the parameters determine the dimensions of the wave.

Phase is given by hundredth of a degree meaning that giving the phase a value of 9000 will displace it 25% of its period. Here are sample values:

0: No phase displacement.
9000: Displaced 25% of its period.
18000: Displaced 50% of its period.
27000: Displaced 75% of its period.
36000: Displaced 100% of its period, same as 0, but 0 is preferred.

Examples:

SDL_HAPTIC_SINE
  __      __      __      __
 /  \    /  \    /  \    /
/    \__/    \__/    \__/

SDL_HAPTIC_SQUARE
 __    __    __    __    __
|  |  |  |  |  |  |  |  |  |
|  |__|  |__|  |__|  |__|  |

SDL_HAPTIC_TRIANGLE
  /\    /\    /\    /\    /\
 /  \  /  \  /  \  /  \  /
/    \/    \/    \/    \/

SDL_HAPTIC_SAWTOOTHUP
  /|  /|  /|  /|  /|  /|  /|
 / | / | / | / | / | / | / |
/  |/  |/  |/  |/  |/  |/  |

SDL_HAPTIC_SAWTOOTHDOWN
\  |\  |\  |\  |\  |\  |\  |
 \ | \ | \ | \ | \ | \ | \ |
  \|  \|  \|  \|  \|  \|  \|

See also: SDL_HAPTIC_SINE; SDL_HAPTIC_LEFTRIGHT; SDL_HAPTIC_TRIANGLE; SDL_HAPTIC_SAWTOOTHUP; SDL_HAPTIC_SAWTOOTHDOWN; SDL_HapticEffect

◆ SDL_HapticRamp

typedef struct SDL_HapticRamp SDL_HapticRamp

A structure containing a template for a Ramp effect.

This struct is exclusively for the SDL_HAPTIC_RAMP effect.

The ramp effect starts at start strength and ends at end strength. It augments in linear fashion. If you use attack and fade with a ramp the effects get added to the ramp effect making the effect become quadratic instead of linear.

See also: SDL_HAPTIC_RAMP; SDL_HapticEffect

Function Documentation

◆ SDL_HapticClose()

DECLSPEC void SDLCALL SDL_HapticClose ( SDL_Haptic * haptic )

Closes a haptic device previously opened with SDL_HapticOpen().

Parameters

haptic Haptic device to close.

◆ SDL_HapticDestroyEffect()

DECLSPEC void SDLCALL SDL_HapticDestroyEffect	(	SDL_Haptic *	haptic,
		int	effect
	)

Destroys 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

haptic	Device to destroy the effect on.
effect	Identifier of the effect to destroy.

See also: SDL_HapticNewEffect

◆ SDL_HapticEffectSupported()

DECLSPEC int SDLCALL SDL_HapticEffectSupported	(	SDL_Haptic *	haptic,
		SDL_HapticEffect *	effect
	)

Checks to see if effect is supported by haptic.

Parameters

haptic	Haptic device to check on.
effect	Effect to check to see if it is supported.

Returns: SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.

See also: SDL_HapticQuery; SDL_HapticNewEffect

◆ SDL_HapticGetEffectStatus()

DECLSPEC int SDLCALL SDL_HapticGetEffectStatus	(	SDL_Haptic *	haptic,
		int	effect
	)

Gets the status of the current effect on the haptic device.

Device must support the SDL_HAPTIC_STATUS feature.

Parameters

haptic	Haptic device to query the effect status on.
effect	Identifier of the effect to query its status.

Returns: 0 if it isn't playing, 1 if it is playing or -1 on error.

See also: SDL_HapticRunEffect; SDL_HapticStopEffect

◆ SDL_HapticIndex()

DECLSPEC int SDLCALL SDL_HapticIndex ( SDL_Haptic * haptic )

Gets the index of a haptic device.

Parameters

haptic Haptic device to get the index of.

Returns: The index of the haptic device or -1 on error.

See also: SDL_HapticOpen; SDL_HapticOpened

◆ SDL_HapticName()

DECLSPEC const char* SDLCALL SDL_HapticName ( int device_index )

Get the implementation dependent name of a haptic device.

This can be called before any joysticks are opened. If no name can be found, this function returns NULL.

Parameters

device_index Index of the device to get its name.

Returns: Name of the device or NULL on error.

See also: SDL_NumHaptics

◆ SDL_HapticNewEffect()

DECLSPEC int SDLCALL SDL_HapticNewEffect	(	SDL_Haptic *	haptic,
		SDL_HapticEffect *	effect
	)

Creates a new haptic effect on the device.

Parameters

haptic	Haptic device to create the effect on.
effect	Properties of the effect to create.

Returns: The identifier of the effect on success or -1 on error.

See also: SDL_HapticUpdateEffect; SDL_HapticRunEffect; SDL_HapticDestroyEffect

◆ SDL_HapticNumAxes()

DECLSPEC int SDLCALL SDL_HapticNumAxes ( SDL_Haptic * haptic )

Gets the number of haptic axes the device has.

See also: SDL_HapticDirection

◆ SDL_HapticNumEffects()

DECLSPEC int SDLCALL SDL_HapticNumEffects ( SDL_Haptic * haptic )

Returns 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_HapticNumEffects().

Parameters

haptic The haptic device to query effect max.

Returns: The number of effects the haptic device can store or -1 on error.

See also: SDL_HapticNumEffectsPlaying; SDL_HapticQuery

◆ SDL_HapticNumEffectsPlaying()

DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying ( SDL_Haptic * haptic )

Returns 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. Added here for the sake of completeness.

Parameters

haptic The haptic device to query maximum playing effects.

Returns: The number of effects the haptic device can play at the same time or -1 on error.

See also: SDL_HapticNumEffects; SDL_HapticQuery

◆ SDL_HapticOpen()

DECLSPEC SDL_Haptic* SDLCALL SDL_HapticOpen ( int device_index )

Opens 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_HapticSetGain() and SDL_HapticSetAutocenter().

Parameters

device_index Index of the device to open.

Returns: Device identifier or NULL on error.

See also: SDL_HapticIndex; SDL_HapticOpenFromMouse; SDL_HapticOpenFromJoystick; SDL_HapticClose; SDL_HapticSetGain; SDL_HapticSetAutocenter; SDL_HapticPause; SDL_HapticStopAll

◆ SDL_HapticOpened()

DECLSPEC int SDLCALL SDL_HapticOpened ( int device_index )

Checks if the haptic device at index has been opened.

Parameters

device_index Index to check to see if it has been opened.

Returns: 1 if it has been opened or 0 if it hasn't.

See also: SDL_HapticOpen; SDL_HapticIndex

◆ SDL_HapticOpenFromJoystick()

DECLSPEC SDL_Haptic* SDLCALL SDL_HapticOpenFromJoystick ( SDL_Joystick * joystick )

Opens 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 opening 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

joystick Joystick to create a haptic device from.

Returns: A valid haptic device identifier on success or NULL on error.

See also: SDL_HapticOpen; SDL_HapticClose

◆ SDL_HapticOpenFromMouse()

DECLSPEC SDL_Haptic* SDLCALL SDL_HapticOpenFromMouse ( void )

Tries to open a haptic device from the current mouse.

Returns: The haptic device identifier or NULL on error.

See also: SDL_MouseIsHaptic; SDL_HapticOpen

◆ SDL_HapticPause()

DECLSPEC int SDLCALL SDL_HapticPause ( SDL_Haptic * haptic )

Pauses a haptic device.

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

haptic Haptic device to pause.

Returns: 0 on success or -1 on error.

See also: SDL_HapticUnpause

◆ SDL_HapticQuery()

DECLSPEC unsigned int SDLCALL SDL_HapticQuery ( SDL_Haptic * haptic )

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

Example:

if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {
    printf("We have constant haptic effect!\n");
}

Parameters

haptic The haptic device to query.

Returns: Haptic features in bitwise manner (OR'd).

See also: SDL_HapticNumEffects; SDL_HapticEffectSupported

◆ SDL_HapticRumbleInit()

DECLSPEC int SDLCALL SDL_HapticRumbleInit ( SDL_Haptic * haptic )

Initializes the haptic device for simple rumble playback.

Parameters

haptic Haptic device to initialize for simple rumble playback.

Returns: 0 on success or -1 on error.

See also: SDL_HapticOpen; SDL_HapticRumbleSupported; SDL_HapticRumblePlay; SDL_HapticRumbleStop

◆ SDL_HapticRumblePlay()

DECLSPEC int SDLCALL SDL_HapticRumblePlay	(	SDL_Haptic *	haptic,
		float	strength,
		Uint32	length
	)

Runs simple rumble on a haptic device.

Parameters

haptic	Haptic device to play rumble effect on.
strength	Strength of the rumble to play as a 0-1 float value.
length	Length of the rumble to play in milliseconds.

Returns: 0 on success or -1 on error.

See also: SDL_HapticRumbleSupported; SDL_HapticRumbleInit; SDL_HapticRumbleStop

◆ SDL_HapticRumbleStop()

DECLSPEC int SDLCALL SDL_HapticRumbleStop ( SDL_Haptic * haptic )

Stops the simple rumble on a haptic device.

Parameters

haptic Haptic to stop the rumble on.

Returns: 0 on success or -1 on error.

See also: SDL_HapticRumbleSupported; SDL_HapticRumbleInit; SDL_HapticRumblePlay

◆ SDL_HapticRumbleSupported()

DECLSPEC int SDLCALL SDL_HapticRumbleSupported ( SDL_Haptic * haptic )

Checks to see if rumble is supported on a haptic device.

Parameters

haptic Haptic device to check to see if it supports rumble.

Returns: SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.

See also: SDL_HapticRumbleInit; SDL_HapticRumblePlay; SDL_HapticRumbleStop

◆ SDL_HapticRunEffect()

DECLSPEC int SDLCALL SDL_HapticRunEffect	(	SDL_Haptic *	haptic,
		int	effect,
		Uint32	iterations
	)

Runs the haptic effect on its associated haptic device.

If iterations are SDL_HAPTIC_INFINITY, it'll run the effect over and over repeating the envelope (attack and fade) every time. If you only want the effect to last forever, set SDL_HAPTIC_INFINITY in the effect's length parameter.

Parameters

haptic	Haptic device to run the effect on.
effect	Identifier of the haptic effect to run.
iterations	Number of iterations to run the effect. Use SDL_HAPTIC_INFINITY for infinity.

Returns: 0 on success or -1 on error.

See also: SDL_HapticStopEffect; SDL_HapticDestroyEffect; SDL_HapticGetEffectStatus

◆ SDL_HapticSetAutocenter()

DECLSPEC int SDLCALL SDL_HapticSetAutocenter	(	SDL_Haptic *	haptic,
		int	autocenter
	)

Sets 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

haptic	Haptic device to set autocentering on.
autocenter	Value to set autocenter to, 0 disables autocentering.

Returns: 0 on success or -1 on error.

See also: SDL_HapticQuery

◆ SDL_HapticSetGain()

DECLSPEC int SDLCALL SDL_HapticSetGain	(	SDL_Haptic *	haptic,
		int	gain
	)

Sets the global gain of the 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_HapticSetGain() will scale linearly using SDL_HAPTIC_GAIN_MAX as the maximum.

Parameters

haptic	Haptic device to set the gain on.
gain	Value to set the gain to, should be between 0 and 100.

Returns: 0 on success or -1 on error.

See also: SDL_HapticQuery

◆ SDL_HapticStopAll()

DECLSPEC int SDLCALL SDL_HapticStopAll ( SDL_Haptic * haptic )

Stops all the currently playing effects on a haptic device.

Parameters

haptic Haptic device to stop.

Returns: 0 on success or -1 on error.

◆ SDL_HapticStopEffect()

DECLSPEC int SDLCALL SDL_HapticStopEffect	(	SDL_Haptic *	haptic,
		int	effect
	)

Stops the haptic effect on its associated haptic device.

Parameters

haptic	Haptic device to stop the effect on.
effect	Identifier of the effect to stop.

Returns: 0 on success or -1 on error.

See also: SDL_HapticRunEffect; SDL_HapticDestroyEffect

◆ SDL_HapticUnpause()

DECLSPEC int SDLCALL SDL_HapticUnpause ( SDL_Haptic * haptic )

Unpauses a haptic device.

Call to unpause after SDL_HapticPause().

Parameters

haptic Haptic device to unpause.

Returns: 0 on success or -1 on error.

See also: SDL_HapticPause

◆ SDL_HapticUpdateEffect()

DECLSPEC int SDLCALL SDL_HapticUpdateEffect	(	SDL_Haptic *	haptic,
		int	effect,
		SDL_HapticEffect *	data
	)

Updates the properties of an effect.

Can be used dynamically, although behavior when dynamically changing direction may be strange. Specifically the effect may reupload itself and start playing from the start. You cannot change the type either when running SDL_HapticUpdateEffect().

Parameters

haptic	Haptic device that has the effect.
effect	Identifier of the effect to update.
data	New effect properties to use.

Returns: 0 on success or -1 on error.

See also: SDL_HapticNewEffect; SDL_HapticRunEffect; SDL_HapticDestroyEffect

◆ SDL_JoystickIsHaptic()

DECLSPEC int SDLCALL SDL_JoystickIsHaptic ( SDL_Joystick * joystick )

Checks to see if a joystick has haptic features.

Parameters

joystick Joystick to test for haptic capabilities.

Returns: SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't or -1 if an error occurred.

See also: SDL_HapticOpenFromJoystick

◆ SDL_MouseIsHaptic()

DECLSPEC int SDLCALL SDL_MouseIsHaptic ( void )

Gets whether or not the current mouse has haptic capabilities.

Returns: SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.

See also: SDL_HapticOpenFromMouse

◆ SDL_NumHaptics()

DECLSPEC int SDLCALL SDL_NumHaptics ( void )

Count the number of haptic devices attached to the system.

Returns: Number of haptic devices detected on the system.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SDL_HAPTIC_AUTOCENTER

◆ SDL_HAPTIC_CARTESIAN

◆ SDL_HAPTIC_CONSTANT

◆ SDL_HAPTIC_CUSTOM

◆ SDL_HAPTIC_DAMPER

◆ SDL_HAPTIC_FRICTION

◆ SDL_HAPTIC_GAIN

◆ SDL_HAPTIC_INERTIA

◆ SDL_HAPTIC_INFINITY

◆ SDL_HAPTIC_LEFTRIGHT

◆ SDL_HAPTIC_PAUSE

◆ SDL_HAPTIC_POLAR

◆ SDL_HAPTIC_RAMP

◆ SDL_HAPTIC_SAWTOOTHDOWN

◆ SDL_HAPTIC_SAWTOOTHUP

◆ SDL_HAPTIC_SINE

◆ SDL_HAPTIC_SPHERICAL

◆ SDL_HAPTIC_SPRING

◆ SDL_HAPTIC_STATUS

◆ SDL_HAPTIC_TRIANGLE

Typedef Documentation

◆ SDL_Haptic

◆ SDL_HapticCondition

◆ SDL_HapticConstant

◆ SDL_HapticCustom

◆ SDL_HapticDirection

◆ SDL_HapticEffect

◆ SDL_HapticLeftRight

◆ SDL_HapticPeriodic

◆ SDL_HapticRamp

Function Documentation

◆ SDL_HapticClose()

◆ SDL_HapticDestroyEffect()

◆ SDL_HapticEffectSupported()

◆ SDL_HapticGetEffectStatus()

◆ SDL_HapticIndex()

◆ SDL_HapticName()

◆ SDL_HapticNewEffect()

◆ SDL_HapticNumAxes()

◆ SDL_HapticNumEffects()

◆ SDL_HapticNumEffectsPlaying()

◆ SDL_HapticOpen()

◆ SDL_HapticOpened()

◆ SDL_HapticOpenFromJoystick()

◆ SDL_HapticOpenFromMouse()

◆ SDL_HapticPause()

◆ SDL_HapticQuery()

◆ SDL_HapticRumbleInit()

◆ SDL_HapticRumblePlay()

◆ SDL_HapticRumbleStop()

◆ SDL_HapticRumbleSupported()

◆ SDL_HapticRunEffect()

◆ SDL_HapticSetAutocenter()

◆ SDL_HapticSetGain()

◆ SDL_HapticStopAll()

◆ SDL_HapticStopEffect()

◆ SDL_HapticUnpause()

◆ SDL_HapticUpdateEffect()

◆ SDL_JoystickIsHaptic()

◆ SDL_MouseIsHaptic()

◆ SDL_NumHaptics()