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

Data Structures
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...
Typedefs
typedef struct _SDL_Haptic	SDL_Haptic
	The haptic structure used to identify an SDL haptic.
typedef struct SDL_HapticDirection	SDL_HapticDirection
	Structure that represents a haptic direction.
typedef struct SDL_HapticConstant	SDL_HapticConstant
	A structure containing a template for a Constant effect.
typedef struct SDL_HapticPeriodic	SDL_HapticPeriodic
	A structure containing a template for a Periodic effect.
typedef struct SDL_HapticCondition	SDL_HapticCondition
	A structure containing a template for a Condition effect.
typedef struct SDL_HapticRamp	SDL_HapticRamp
	A structure containing a template for a Ramp effect.
typedef struct SDL_HapticLeftRight	SDL_HapticLeftRight
	A structure containing a template for a Left/Right effect.
typedef struct SDL_HapticCustom	SDL_HapticCustom
	A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
typedef union SDL_HapticEffect	SDL_HapticEffect
	The generic template for any haptic effect.
Functions
DECLSPEC int SDLCALL	SDL_NumHaptics (void)
	Count the number of haptic devices attached to the system.
DECLSPEC const char *SDLCALL	SDL_HapticName (int device_index)
	Get the implementation dependent name of a Haptic device.
DECLSPEC SDL_Haptic *SDLCALL	SDL_HapticOpen (int device_index)
	Opens a Haptic device for usage.
DECLSPEC int SDLCALL	SDL_HapticOpened (int device_index)
	Checks if the haptic device at index has been opened.
DECLSPEC int SDLCALL	SDL_HapticIndex (SDL_Haptic *haptic)
	Gets the index of a haptic device.
DECLSPEC int SDLCALL	SDL_MouseIsHaptic (void)
	Gets whether or not the current mouse has haptic capabilities.
DECLSPEC SDL_Haptic *SDLCALL	SDL_HapticOpenFromMouse (void)
	Tries to open a haptic device from the current mouse.
DECLSPEC int SDLCALL	SDL_JoystickIsHaptic (SDL_Joystick *joystick)
	Checks to see if a joystick has haptic features.
DECLSPEC SDL_Haptic *SDLCALL	SDL_HapticOpenFromJoystick (SDL_Joystick *joystick)
	Opens a Haptic device for usage from a Joystick device.
DECLSPEC void SDLCALL	SDL_HapticClose (SDL_Haptic *haptic)
	Closes a Haptic device previously opened with SDL_HapticOpen().
DECLSPEC int SDLCALL	SDL_HapticNumEffects (SDL_Haptic *haptic)
	Returns the number of effects a haptic device can store.
DECLSPEC int SDLCALL	SDL_HapticNumEffectsPlaying (SDL_Haptic *haptic)
	Returns the number of effects a haptic device can play at the same time.
DECLSPEC unsigned int SDLCALL	SDL_HapticQuery (SDL_Haptic *haptic)
	Gets the haptic devices supported features in bitwise matter.
DECLSPEC int SDLCALL	SDL_HapticNumAxes (SDL_Haptic *haptic)
	Gets the number of haptic axes the device has.
DECLSPEC int SDLCALL	SDL_HapticEffectSupported (SDL_Haptic haptic, SDL_HapticEffect effect)
	Checks to see if effect is supported by haptic.
DECLSPEC int SDLCALL	SDL_HapticNewEffect (SDL_Haptic haptic, SDL_HapticEffect effect)
	Creates a new haptic effect on the device.
DECLSPEC int SDLCALL	SDL_HapticUpdateEffect (SDL_Haptic haptic, int effect, SDL_HapticEffect data)
	Updates the properties of an effect.
DECLSPEC int SDLCALL	SDL_HapticRunEffect (SDL_Haptic *haptic, int effect, Uint32 iterations)
	Runs the haptic effect on its associated haptic device.
DECLSPEC int SDLCALL	SDL_HapticStopEffect (SDL_Haptic *haptic, int effect)
	Stops the haptic effect on its associated haptic device.
DECLSPEC void SDLCALL	SDL_HapticDestroyEffect (SDL_Haptic *haptic, int effect)
	Destroys a haptic effect on the device.
DECLSPEC int SDLCALL	SDL_HapticGetEffectStatus (SDL_Haptic *haptic, int effect)
	Gets the status of the current effect on the haptic device.
DECLSPEC int SDLCALL	SDL_HapticSetGain (SDL_Haptic *haptic, int gain)
	Sets the global gain of the device.
DECLSPEC int SDLCALL	SDL_HapticSetAutocenter (SDL_Haptic *haptic, int autocenter)
	Sets the global autocenter of the device.
DECLSPEC int SDLCALL	SDL_HapticPause (SDL_Haptic *haptic)
	Pauses a haptic device.
DECLSPEC int SDLCALL	SDL_HapticUnpause (SDL_Haptic *haptic)
	Unpauses a haptic device.
DECLSPEC int SDLCALL	SDL_HapticStopAll (SDL_Haptic *haptic)
	Stops all the currently playing effects on a haptic device.
DECLSPEC int SDLCALL	SDL_HapticRumbleSupported (SDL_Haptic *haptic)
	Checks to see if rumble is supported on a haptic device.
DECLSPEC int SDLCALL	SDL_HapticRumbleInit (SDL_Haptic *haptic)
	Initializes the haptic device for simple rumble playback.
DECLSPEC int SDLCALL	SDL_HapticRumblePlay (SDL_Haptic *haptic, float strength, Uint32 length)
	Runs simple rumble on a haptic device.
DECLSPEC int SDLCALL	SDL_HapticRumbleStop (SDL_Haptic *haptic)
	Stops the simple rumble on a haptic device.

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.

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:

SDL_HAPTIC_SINE
SDL_HAPTIC_LEFTRIGHT
SDL_HAPTIC_TRIANGLE
SDL_HAPTIC_SAWTOOTHUP
SDL_HAPTIC_SAWTOOTHDOWN

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.

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

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

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

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

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

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

DECLSPEC int SDLCALL SDL_HapticNumAxes ( SDL_Haptic * haptic )

Gets the number of haptic axes the device has.

See also:: SDL_HapticDirection

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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:

haptic	Haptic device that has the effect.
effect	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

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:: 1 if the joystick is haptic, 0 if it isn't or -1 if an error ocurred.

See also:: SDL_HapticOpenFromJoystick

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

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.

Type:	Library
Created:	22 Sep 2016
Imports:	28
Forks:	0
Commits:	1
Dependents:	1
Dependencies:	0
Followers:	1

SDL_haptic.h File Reference

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

SDL_haptic.h File Reference

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning