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_HapticCondition
	A structure containing a template for a Condition effect. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#define	SDL_HAPTIC_CUSTOM (1<<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_HapticCondition	SDL_HapticCondition
	A structure containing a template for a Condition effect. More...

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

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

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

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

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

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

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

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

DECLSPEC void SDLCALL	SDL_HapticDestroyEffect (SDL_Haptic *haptic, int effect)
	Destroys a haptic effect on the device. 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_HapticGetEffectStatus (SDL_Haptic *haptic, int effect)
	Gets the status of the current effect on the haptic device. More...

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

DECLSPEC const char *SDLCALL	SDL_HapticName (int device_index)
	Get the implementation dependent name of a Haptic device. 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_HapticNumAxes (SDL_Haptic *haptic)
	Gets the number of haptic axes the device has. 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 SDL_Haptic *SDLCALL	SDL_HapticOpen (int device_index)
	Opens a Haptic device for usage. More...

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

DECLSPEC SDL_Haptic *SDLCALL	SDL_HapticOpenFromJoystick (SDL_Joystick *joystick)
	Opens a Haptic device for usage from a Joystick device. More...

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

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

DECLSPEC unsigned int SDLCALL	SDL_HapticQuery (SDL_Haptic *haptic)
	Gets the haptic devices supported features in bitwise matter. 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...

DECLSPEC int SDLCALL	SDL_HapticRumbleSupported (SDL_Haptic *haptic)
	Checks to see if rumble is supported on a haptic device. 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_HapticSetAutocenter (SDL_Haptic *haptic, int autocenter)
	Sets the global autocenter of the device. More...

DECLSPEC int SDLCALL	SDL_HapticSetGain (SDL_Haptic *haptic, int gain)
	Sets the global gain of the 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_HapticStopEffect (SDL_Haptic *haptic, int effect)
	Stops the haptic effect on its associated haptic device. More...

DECLSPEC int SDLCALL	SDL_HapticUnpause (SDL_Haptic *haptic)
	Unpauses a haptic 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_JoystickIsHaptic (SDL_Joystick *joystick)
	Checks to see if a joystick has haptic features. More...

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

DECLSPEC int SDLCALL	SDL_NumHaptics (void)
	Count the number of haptic devices attached to the system. 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

* }

*

You can also find out more information on my blog: http://bobbens.dyndns.org/journal/2010/sdl_haptic/

Author: Edgar Simo Serra

Definition in file SDL_haptic.h.

Macro Definition Documentation

#define SDL_HAPTIC_AUTOCENTER (1<<13)

Device can set autocenter.

Device supports setting autocenter.

See Also: SDL_HapticSetAutocenter

Definition at line 285 of file SDL_haptic.h.

Referenced by SDL_HapticOpen(), and SDL_HapticSetAutocenter().

#define SDL_HAPTIC_CARTESIAN 1

Uses cartesian coordinates for the direction.

See Also: SDL_HapticDirection

Definition at line 322 of file SDL_haptic.h.

#define SDL_HAPTIC_CONSTANT (1<<0)

Constant effect supported.

Constant haptic effect.

See Also: SDL_HapticCondition

Definition at line 157 of file SDL_haptic.h.

#define SDL_HAPTIC_CUSTOM (1<<11)

Custom effect is supported.

User defined custom haptic effect.

Definition at line 263 of file SDL_haptic.h.

#define SDL_HAPTIC_DAMPER (1<<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 236 of file SDL_haptic.h.

#define SDL_HAPTIC_FRICTION (1<<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 256 of file SDL_haptic.h.

#define SDL_HAPTIC_GAIN (1<<12)

Device can set global gain.

Device supports setting the global gain.

See Also: SDL_HapticSetGain

Definition at line 276 of file SDL_haptic.h.

Referenced by SDL_HapticOpen(), and SDL_HapticSetGain().

#define SDL_HAPTIC_INERTIA (1<<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 246 of file SDL_haptic.h.

#define SDL_HAPTIC_INFINITY 4294967295U

Used to play a device an infinite number of times.

See Also: SDL_HapticRunEffect

Definition at line 344 of file SDL_haptic.h.

#define SDL_HAPTIC_LEFTRIGHT (1<<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 177 of file SDL_haptic.h.

Referenced by SDL_HapticRumbleInit(), SDL_HapticRumblePlay(), and SDL_HapticRumbleSupported().

#define SDL_HAPTIC_PAUSE (1<<15)

Device can be paused.

See Also: SDL_HapticPause; SDL_HapticUnpause

Definition at line 302 of file SDL_haptic.h.

Referenced by SDL_HapticPause(), and SDL_HapticUnpause().

#define SDL_HAPTIC_POLAR 0

Uses polar coordinates for the direction.

See Also: SDL_HapticDirection

Definition at line 315 of file SDL_haptic.h.

#define SDL_HAPTIC_RAMP (1<<6)

Ramp effect supported.

Ramp haptic effect.

See Also: SDL_HapticRamp

Definition at line 216 of file SDL_haptic.h.

#define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)

Sawtoothdown wave effect supported.

Periodic haptic effect that simulates saw tooth down waves.

See Also: SDL_HapticPeriodic

Definition at line 207 of file SDL_haptic.h.

#define SDL_HAPTIC_SAWTOOTHUP (1<<4)

Sawtoothup wave effect supported.

Periodic haptic effect that simulates saw tooth up waves.

See Also: SDL_HapticPeriodic

Definition at line 198 of file SDL_haptic.h.

#define SDL_HAPTIC_SINE (1<<1)

Sine wave effect supported.

Periodic haptic effect that simulates sine waves.

See Also: SDL_HapticPeriodic

Definition at line 166 of file SDL_haptic.h.

Referenced by SDL_HapticRumbleInit(), SDL_HapticRumblePlay(), and SDL_HapticRumbleSupported().

#define SDL_HAPTIC_SPHERICAL 2

Uses spherical coordinates for the direction.

See Also: SDL_HapticDirection

Definition at line 329 of file SDL_haptic.h.

#define SDL_HAPTIC_SPRING (1<<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 226 of file SDL_haptic.h.

#define SDL_HAPTIC_STATUS (1<<14)

Device can be queried for effect status.

See Also: SDL_HapticGetEffectStatus

Definition at line 294 of file SDL_haptic.h.

Referenced by SDL_HapticGetEffectStatus().

#define SDL_HAPTIC_TRIANGLE (1<<3)

Triangle wave effect supported.

Periodic haptic effect that simulates triangular waves.

See Also: SDL_HapticPeriodic

Definition at line 189 of file SDL_haptic.h.

Typedef Documentation

SDL_Haptic

The haptic structure used to identify an SDL haptic.

See Also: SDL_HapticOpen; SDL_HapticOpenFromJoystick; SDL_HapticClose

Definition at line 135 of file SDL_haptic.h.

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

typedef struct SDL_HapticConstant SDL_HapticConstant

A structure containing a template for a Constant effect.

The struct is exclusive to 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

typedef struct SDL_HapticCustom SDL_HapticCustom

A structure containing a template 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

typedef struct SDL_HapticDirection SDL_HapticDirection

Structure that represents a haptic direction.

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

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

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. One motor is high frequency, the other is low frequency.

See Also: SDL_HAPTIC_LEFTRIGHT; SDL_HapticEffect

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 cycle 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

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

DECLSPEC void SDLCALL SDL_HapticClose ( SDL_Haptic * haptic )

Closes a Haptic device previously opened with SDL_HapticOpen().

Parameters

haptic Haptic device to close.

Definition at line 339 of file SDL_haptic.c.

References _SDL_Haptic::effects, haptic_effect::hweffect, i, _SDL_Haptic::neffects, NULL, _SDL_Haptic::ref_count, SDL_free(), SDL_HapticDestroyEffect(), SDL_memcpy(), SDL_numhaptics, SDL_SYS_HapticClose(), and ValidHaptic().

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

Definition at line 576 of file SDL_haptic.c.

References _SDL_Haptic::effects, haptic_effect::hweffect, NULL, SDL_SYS_HapticDestroyEffect(), ValidEffect(), and ValidHaptic().

Referenced by SDL_HapticClose().

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

Definition at line 446 of file SDL_haptic.c.

References SDL_FALSE, SDL_TRUE, _SDL_Haptic::supported, SDL_HapticEffect::type, and ValidHaptic().

Referenced by Zeni::Controllers::device_added(), and SDL_HapticNewEffect().

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

Definition at line 594 of file SDL_haptic.c.

References _SDL_Haptic::effects, SDL_HAPTIC_STATUS, SDL_SetError(), SDL_SYS_HapticGetEffectStatus(), _SDL_Haptic::supported, ValidEffect(), and ValidHaptic().

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

Definition at line 203 of file SDL_haptic.c.

References _SDL_Haptic::index, and ValidHaptic().

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

Definition at line 101 of file SDL_haptic.c.

References NULL, SDL_numhaptics, SDL_SetError(), and SDL_SYS_HapticName().

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 id of the effect on success or -1 on error.

See Also: SDL_HapticUpdateEffect; SDL_HapticRunEffect; SDL_HapticDestroyEffect

Definition at line 461 of file SDL_haptic.c.

References haptic_effect::effect, _SDL_Haptic::effects, haptic_effect::hweffect, i, _SDL_Haptic::neffects, NULL, SDL_FALSE, SDL_HapticEffectSupported(), SDL_memcpy(), SDL_SetError(), SDL_SYS_HapticNewEffect(), and ValidHaptic().

Referenced by Zeni::Controllers::device_added(), and SDL_HapticRumbleInit().

DECLSPEC int SDLCALL SDL_HapticNumAxes ( SDL_Haptic * haptic )

Gets the number of haptic axes the device has.

See Also: SDL_HapticDirection

Definition at line 433 of file SDL_haptic.c.

References _SDL_Haptic::naxes, and ValidHaptic().

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

Definition at line 391 of file SDL_haptic.c.

References _SDL_Haptic::neffects, and ValidHaptic().

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

Definition at line 405 of file SDL_haptic.c.

References _SDL_Haptic::nplaying, and ValidHaptic().

DECLSPEC SDL_Haptic* SDLCALL SDL_HapticOpen ( int device_index )

Opens a Haptic device for usage.

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

Definition at line 116 of file SDL_haptic.c.

References i, _SDL_Haptic::index, NULL, _SDL_Haptic::ref_count, _SDL_Haptic::rumble_id, SDL_free(), SDL_HAPTIC_AUTOCENTER, SDL_HAPTIC_GAIN, SDL_HapticSetAutocenter(), SDL_HapticSetGain(), SDL_malloc(), SDL_memset(), SDL_numhaptics, SDL_OutOfMemory, SDL_SetError(), SDL_SYS_HapticOpen(), and _SDL_Haptic::supported.

Referenced by SDL_HapticOpenFromMouse().

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

Definition at line 177 of file SDL_haptic.c.

References i, SDL_numhaptics, and SDL_SetError().

DECLSPEC SDL_Haptic* SDLCALL SDL_HapticOpenFromJoystick ( SDL_Joystick * joystick )

Opens a Haptic device for usage from a Joystick device.

You must still close the haptic device seperately. 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

Definition at line 272 of file SDL_haptic.c.

References i, NULL, _SDL_Haptic::ref_count, _SDL_Haptic::rumble_id, SDL_free(), SDL_malloc(), SDL_memset(), SDL_numhaptics, SDL_OutOfMemory, SDL_PrivateJoystickValid(), SDL_SetError(), SDL_SYS_HapticOpenFromJoystick(), SDL_SYS_JoystickIsHaptic(), and SDL_SYS_JoystickSameHaptic().

Referenced by Zeni::Controllers::device_added().

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

Definition at line 229 of file SDL_haptic.c.

References NULL, SDL_HapticOpen(), SDL_SetError(), and SDL_SYS_HapticMouse().

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

Definition at line 681 of file SDL_haptic.c.

References SDL_HAPTIC_PAUSE, SDL_SetError(), SDL_SYS_HapticPause(), _SDL_Haptic::supported, and ValidHaptic().

DECLSPEC unsigned int SDLCALL SDL_HapticQuery ( SDL_Haptic * haptic )

Gets the haptic devices supported features in bitwise matter.

Example:

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

Parameters

haptic The haptic device to query.

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

See Also: SDL_HapticNumEffects; SDL_HapticEffectSupported

Definition at line 419 of file SDL_haptic.c.

References _SDL_Haptic::supported, and ValidHaptic().

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

Definition at line 742 of file SDL_haptic.c.

References SDL_HapticPeriodic::attack_length, SDL_HapticPeriodic::fade_length, SDL_HapticLeftRight::large_magnitude, SDL_HapticEffect::leftright, SDL_HapticPeriodic::length, SDL_HapticLeftRight::length, SDL_HapticPeriodic::magnitude, SDL_HapticPeriodic::period, SDL_HapticEffect::periodic, _SDL_Haptic::rumble_effect, _SDL_Haptic::rumble_id, SDL_HAPTIC_LEFTRIGHT, SDL_HAPTIC_SINE, SDL_HapticNewEffect(), SDL_SetError(), SDL_zerop, SDL_HapticLeftRight::small_magnitude, _SDL_Haptic::supported, SDL_HapticEffect::type, and ValidHaptic().

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

Definition at line 783 of file SDL_haptic.c.

References SDL_HapticLeftRight::large_magnitude, SDL_HapticEffect::leftright, SDL_HapticPeriodic::length, SDL_HapticLeftRight::length, SDL_HapticPeriodic::magnitude, SDL_HapticEffect::periodic, _SDL_Haptic::rumble_effect, _SDL_Haptic::rumble_id, SDL_assert, SDL_HAPTIC_LEFTRIGHT, SDL_HAPTIC_SINE, SDL_HapticRunEffect(), SDL_HapticUpdateEffect(), SDL_SetError(), SDL_HapticLeftRight::small_magnitude, SDL_HapticEffect::type, and ValidHaptic().

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

Definition at line 826 of file SDL_haptic.c.

References _SDL_Haptic::rumble_id, SDL_HapticStopEffect(), SDL_SetError(), and ValidHaptic().

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

Definition at line 728 of file SDL_haptic.c.

References SDL_HAPTIC_LEFTRIGHT, SDL_HAPTIC_SINE, _SDL_Haptic::supported, and ValidHaptic().

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

Definition at line 539 of file SDL_haptic.c.

References _SDL_Haptic::effects, SDL_SYS_HapticRunEffect(), ValidEffect(), and ValidHaptic().

Referenced by Zeni::Controllers::device_added(), and SDL_HapticRumblePlay().

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

Definition at line 656 of file SDL_haptic.c.

References SDL_HAPTIC_AUTOCENTER, SDL_SetError(), SDL_SYS_HapticSetAutocenter(), _SDL_Haptic::supported, and ValidHaptic().

Referenced by SDL_HapticOpen().

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

Definition at line 611 of file SDL_haptic.c.

References env, NULL, SDL_atoi(), SDL_getenv(), SDL_HAPTIC_GAIN, SDL_SetError(), SDL_SYS_HapticSetGain(), _SDL_Haptic::supported, and ValidHaptic().

Referenced by SDL_HapticOpen().

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.

Definition at line 715 of file SDL_haptic.c.

References SDL_SYS_HapticStopAll(), and ValidHaptic().

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

Definition at line 558 of file SDL_haptic.c.

References _SDL_Haptic::effects, SDL_SYS_HapticStopEffect(), ValidEffect(), and ValidHaptic().

Referenced by SDL_HapticRumbleStop().

DECLSPEC int SDLCALL SDL_HapticUnpause ( SDL_Haptic * haptic )

Unpauses a haptic device.

Call to unpause after SDL_HapticPause().

Parameters

haptic Haptic device to pause.

Returns: 0 on success or -1 on error.

See Also: SDL_HapticPause

Definition at line 698 of file SDL_haptic.c.

References SDL_HAPTIC_PAUSE, SDL_SYS_HapticUnpause(), _SDL_Haptic::supported, and ValidHaptic().

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

Updates the properties of an effect.

Can be used dynamically, although behaviour 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