Code Map
module lib.sdl2.haptic;
//! \name Haptic features
enum SDL_HAPTIC_CONSTANT;
//! \brief Sine wave effect supported.
enum SDL_HAPTIC_SINE;
//! \brief Square wave effect supported.
enum SDL_HAPTIC_SQUARE;
//! \brief Triangle wave effect supported.
enum SDL_HAPTIC_TRIANGLE;
//! \brief Sawtoothup wave effect supported.
enum SDL_HAPTIC_SAWTOOTHUP;
//! \brief Sawtoothdown wave effect supported.
enum SDL_HAPTIC_SAWTOOTHDOWN;
//! \brief Ramp effect supported.
enum SDL_HAPTIC_RAMP;
//! \brief Spring effect supported - uses axes position.
enum SDL_HAPTIC_SPRING;
//! \brief Damper effect supported - uses axes velocity.
enum SDL_HAPTIC_DAMPER;
//! \brief Inertia effect supported - uses axes acceleration.
enum SDL_HAPTIC_INERTIA;
//! \brief Friction effect supported - uses axes movement.
enum SDL_HAPTIC_FRICTION;
//! \brief Custom effect is supported.
enum SDL_HAPTIC_CUSTOM;
//! \brief Device can set global gain.
enum SDL_HAPTIC_GAIN;
//! \brief Device can set autocenter.
enum SDL_HAPTIC_AUTOCENTER;
//! \brief Device can be queried for effect status.
enum SDL_HAPTIC_STATUS;
//! \brief Device can be paused.
enum SDL_HAPTIC_PAUSE;
//! \name Direction encodings
enum SDL_HAPTIC_POLAR;
//! \brief Uses cartesian coordinates for the direction.
enum SDL_HAPTIC_CARTESIAN;
//! \brief Uses spherical coordinates for the direction.
enum SDL_HAPTIC_SPHERICAL;
//! \typedef SDL_Haptic
struct SDL_Haptic
{
}
//! \brief Structure that represents a haptic direction.
struct SDL_HapticDirection
{
public:
type: Uint8;
dir: Sint32[3];
}
//! \brief A structure containing a template for a Constant effect.
struct SDL_HapticConstant
{
public:
type: Uint16;
direction: SDL_HapticDirection;
length: Uint32;
delay: Uint16;
button: Uint16;
interval: Uint16;
level: Sint16;
attack_length: Uint16;
attack_level: Uint16;
fade_length: Uint16;
fade_level: Uint16;
}
//! \brief A structure containing a template for a Periodic effect.
struct SDL_HapticPeriodic
{
public:
type: Uint16;
direction: SDL_HapticDirection;
length: Uint32;
delay: Uint16;
button: Uint16;
interval: Uint16;
period: Uint16;
magnitude: Sint16;
offset: Sint16;
phase: Uint16;
attack_length: Uint16;
attack_level: Uint16;
fade_length: Uint16;
fade_level: Uint16;
}
//! \brief A structure containing a template for a Condition effect.
struct SDL_HapticCondition
{
public:
type: Uint16;
direction: SDL_HapticDirection;
length: Uint32;
delay: Uint16;
button: Uint16;
interval: Uint16;
right_sat: Uint16[3];
left_sat: Uint16[3];
right_coeff: Sint16[3];
left_coeff: Sint16[3];
deadband: Uint16[3];
center: Sint16[3];
}
//! \brief A structure containing a template for a Ramp effect.
struct SDL_HapticRamp
{
public:
type: Uint16;
direction: SDL_HapticDirection;
length: Uint32;
delay: Uint16;
button: Uint16;
interval: Uint16;
start: Sint16;
end: Sint16;
attack_length: Uint16;
attack_level: Uint16;
fade_length: Uint16;
fade_level: Uint16;
}
//! \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM
//! effect.
struct SDL_HapticCustom
{
public:
type: Uint16;
direction: SDL_HapticDirection;
length: Uint32;
delay: Uint16;
button: Uint16;
interval: Uint16;
channels: Uint8;
period: Uint16;
samples: Uint16;
data: Uint16*;
attack_length: Uint16;
attack_level: Uint16;
fade_length: Uint16;
fade_level: Uint16;
}
//! \brief The generic template for any haptic effect.
union SDL_HapticEffect
{
public:
type: Uint16;
constant: SDL_HapticConstant;
periodic: SDL_HapticPeriodic;
condition: SDL_HapticCondition;
ramp: SDL_HapticRamp;
custom: SDL_HapticCustom;
}
//! \brief Used to play a device an infinite number of times.
fn SDL_HAPTIC_INFINITY() u32 { }
//! \brief Count the number of haptic devices attached to the system.
fn SDL_NumHaptics() i32;
//! \brief Get the implementation dependent name of a Haptic device.
fn SDL_HapticName(device_index: i32) char*;
//! \brief Opens a Haptic device for usage.
fn SDL_HapticOpen(device_index: i32) SDL_Haptic*;
//! \brief Checks if the haptic device at index has been opened.
fn SDL_HapticOpened(device_index: i32) i32;
//! \brief Gets the index of a haptic device.
fn SDL_HapticIndex(haptic: SDL_Haptic*) i32;
//! \brief Gets whether or not the current mouse has haptic capabilities.
fn SDL_MouseIsHaptic() i32;
//! \brief Tries to open a haptic device from the current mouse.
fn SDL_HapticOpenFromMouse() SDL_Haptic*;
//! \brief Checks to see if a joystick has haptic features.
fn SDL_JoystickIsHaptic(joystick: SDL_Joystick*) i32;
//! \brief Opens a Haptic device for usage from a Joystick device.
fn SDL_HapticOpenFromJoystick(joystick: SDL_Joystick*) SDL_Haptic*;
//! \brief Closes a Haptic device previously opened with SDL_HapticOpen().
fn SDL_HapticClose(haptic: SDL_Haptic*);
//! \brief Returns the number of effects a haptic device can store.
fn SDL_HapticNumEffects(haptic: SDL_Haptic*) i32;
//! \brief Returns the number of effects a haptic device can play at the
//! same time.
fn SDL_HapticNumEffectsPlaying(haptic: SDL_Haptic*) i32;
//! \brief Gets the haptic devices supported features in bitwise matter.
fn SDL_HapticQuery(haptic: SDL_Haptic*) u32;
//! \brief Gets the number of haptic axes the device has.
fn SDL_HapticNumAxes(haptic: SDL_Haptic*) i32;
//! \brief Checks to see if effect is supported by haptic.
fn SDL_HapticEffectSupported(haptic: SDL_Haptic*, effect: SDL_HapticEffect*) i32;
//! \brief Creates a new haptic effect on the device.
fn SDL_HapticNewEffect(haptic: SDL_Haptic*, effect: SDL_HapticEffect*) i32;
//! \brief Updates the properties of an effect.
fn SDL_HapticUpdateEffect(haptic: SDL_Haptic*, effect: i32, data: SDL_HapticEffect*) i32;
//! \brief Runs the haptic effect on its associated haptic device.
fn SDL_HapticRunEffect(haptic: SDL_Haptic*, effect: i32, iterations: Uint32) i32;
//! \brief Stops the haptic effect on its associated haptic device.
fn SDL_HapticStopEffect(haptic: SDL_Haptic*, effect: i32) i32;
//! \brief Destroys a haptic effect on the device.
fn SDL_HapticDestroyEffect(haptic: SDL_Haptic*, effect: i32);
//! \brief Gets the status of the current effect on the haptic device.
fn SDL_HapticGetEffectStatus(haptic: SDL_Haptic*, effect: i32) i32;
//! \brief Sets the global gain of the device.
fn SDL_HapticSetGain(haptic: SDL_Haptic*, gain: i32) i32;
//! \brief Sets the global autocenter of the device.
fn SDL_HapticSetAutocenter(haptic: SDL_Haptic*, autocenter: i32) i32;
//! \brief Pauses a haptic device.
fn SDL_HapticPause(haptic: SDL_Haptic*) i32;
//! \brief Unpauses a haptic device.
fn SDL_HapticUnpause(haptic: SDL_Haptic*) i32;
//! \brief Stops all the currently playing effects on a haptic device.
fn SDL_HapticStopAll(haptic: SDL_Haptic*) i32;
//! \brief Checks to see if rumble is supported on a haptic device..
fn SDL_HapticRumbleSupported(haptic: SDL_Haptic*) i32;
//! \brief Initializes the haptic device for simple rumble playback.
fn SDL_HapticRumbleInit(haptic: SDL_Haptic*) i32;
//! \brief Runs simple rumble on a haptic device
fn SDL_HapticRumblePlay(haptic: SDL_Haptic*, strength: f32, length: Uint32) i32;
//! \brief Stops the simple rumble on a haptic device.
fn SDL_HapticRumbleStop(haptic: SDL_Haptic*) i32;
\typedef SDL_Haptic
\brief The haptic structure used to identify an SDL haptic.
\sa SDL_HapticOpen \sa SDL_HapticOpenFromJoystick \sa SDL_HapticClose
\name Haptic features
Different haptic features a device can have.
\name Haptic effects
\brief Constant effect supported.
Constant haptic effect.
\sa SDL_HapticCondition
\brief Sine wave effect supported.
Periodic haptic effect that simulates sine waves.
\sa SDL_HapticPeriodic
\brief Square wave effect supported.
Periodic haptic effect that simulates square waves.
\sa SDL_HapticPeriodic
\brief Triangle wave effect supported.
Periodic haptic effect that simulates triangular waves.
\sa SDL_HapticPeriodic
\brief Sawtoothup wave effect supported.
Periodic haptic effect that simulates saw tooth up waves.
\sa SDL_HapticPeriodic
\brief Sawtoothdown wave effect supported.
Periodic haptic effect that simulates saw tooth down waves.
\sa SDL_HapticPeriodic
\brief Ramp effect supported.
Ramp haptic effect.
\sa SDL_HapticRamp
\brief Spring effect supported - uses axes position.
Condition haptic effect that simulates a spring. Effect is based on the axes position.
\sa SDL_HapticCondition
\brief Damper effect supported - uses axes velocity.
Condition haptic effect that simulates dampening. Effect is based on the axes velocity.
\sa SDL_HapticCondition
\brief Inertia effect supported - uses axes acceleration.
Condition haptic effect that simulates inertia. Effect is based on the axes acceleration.
\sa SDL_HapticCondition
\brief Friction effect supported - uses axes movement.
Condition haptic effect that simulates friction. Effect is based on the axes movement.
\sa SDL_HapticCondition
\brief Custom effect is supported.
User defined custom haptic effect.
\brief Device can set global gain.
Device supports setting the global gain.
\sa SDL_HapticSetGain
\brief Device can set autocenter.
Device supports setting autocenter.
\sa SDL_HapticSetAutocenter
\brief Device can be queried for effect status.
Device can be queried for effect status.
\sa SDL_HapticGetEffectStatus
\brief Device can be paused.
\sa SDL_HapticPause \sa SDL_HapticUnpause
\name Direction encodings
\brief Uses polar coordinates for the direction.
\sa SDL_HapticDirection
\brief Uses cartesian coordinates for the direction.
\sa SDL_HapticDirection
\brief Uses spherical coordinates for the direction.
\sa SDL_HapticDirection
\brief Used to play a device an infinite number of times.
\sa SDL_HapticRunEffect
\brief 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: \verbatim .--. || .-------. |=.| |.-----.| |--| || || | | |'-----'| ||~')_____(' [ COMPUTER ]
North (0,-1)
^
|
|
(1,0) West <----[ HAPTIC ]----> East (-1,0) | | v South (0,1)
[ USER ]
\|||/
(o o)
---ooO-(_)-Ooo---
\endverbatim
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 \c 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 \c 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 \c dir parameters are used. The \c 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): \code 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. \endcode
\sa SDL_HAPTIC_POLAR \sa SDL_HAPTIC_CARTESIAN \sa SDL_HAPTIC_SPHERICAL \sa SDL_HapticEffect \sa SDL_HapticNumAxes
\brief 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.
\sa SDL_HAPTIC_CONSTANT \sa SDL_HapticEffect
\brief A structure containing a template for a Periodic effect.
The struct handles the following effects:
- ::SDL_HAPTIC_SINE
- ::SDL_HAPTIC_SQUARE
- ::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:
-
- 9000: Displaced 25% of its period.0: No phase displacement.
- 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: \verbatim SDL_HAPTIC_SINE
/ \ / \ / \ / / __/ __/ __/
SDL_HAPTIC_SQUARE
| | | | | | | | | | | || || || || |
SDL_HAPTIC_TRIANGLE
/\ /\ /\ /\ /
/ \ / \ / \ / \ /
/ / / / /
SDL_HAPTIC_SAWTOOTHUP /| /| /| /| /| /| /| / | / | / | / | / | / | / | / |/ |/ |/ |/ |/ |/ |
SDL_HAPTIC_SAWTOOTHDOWN \ |\ |\ |\ |\ |\ |\ | \ | \ | \ | \ | \ | \ | \ | | | | | | | | \endverbatim
\sa SDL_HAPTIC_SINE \sa SDL_HAPTIC_SQUARE \sa SDL_HAPTIC_TRIANGLE \sa SDL_HAPTIC_SAWTOOTHUP \sa SDL_HAPTIC_SAWTOOTHDOWN \sa SDL_HapticEffect
\brief 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.
\sa SDL_HapticDirection \sa SDL_HAPTIC_SPRING \sa SDL_HAPTIC_DAMPER \sa SDL_HAPTIC_INERTIA \sa SDL_HAPTIC_FRICTION \sa SDL_HapticEffect
\brief 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.
\sa SDL_HAPTIC_RAMP \sa SDL_HapticEffect
\brief 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.
\sa SDL_HAPTIC_CUSTOM \sa SDL_HapticEffect
\brief 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: \code // 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. \endcode
Here we have an example of a constant effect evolution in time:
\verbatim
Strength
^
|
| effect level --> _________________
| /
| /
| /
| /
| attack_level --> |
| | | <--- fade_level
|
+--------------------------------------------------> Time
[--] [---]
attack_length fade_length
[------------------][-----------------------] delay length \endverbatim
Note either the attack_level or the fade_level may be above the actual effect level.
\sa SDL_HapticConstant \sa SDL_HapticPeriodic \sa SDL_HapticCondition \sa SDL_HapticRamp \sa SDL_HapticCustom
\brief Count the number of haptic devices attached to the system.
\return Number of haptic devices detected on the system.
\brief 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.
\param device_index Index of the device to get its name. \return Name of the device or NULL on error.
\sa SDL_NumHaptics
\brief 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().
\param device_index Index of the device to open. \return Device identifier or NULL on error.
\sa SDL_HapticIndex \sa SDL_HapticOpenFromMouse \sa SDL_HapticOpenFromJoystick \sa SDL_HapticClose \sa SDL_HapticSetGain \sa SDL_HapticSetAutocenter \sa SDL_HapticPause \sa SDL_HapticStopAll
\brief Checks if the haptic device at index has been opened.
\param device_index Index to check to see if it has been opened. \return 1 if it has been opened or 0 if it hasn't.
\sa SDL_HapticOpen \sa SDL_HapticIndex
\brief Gets the index of a haptic device.
\param haptic Haptic device to get the index of. \return The index of the haptic device or -1 on error.
\sa SDL_HapticOpen \sa SDL_HapticOpened
\brief Gets whether or not the current mouse has haptic capabilities.
\return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
\sa SDL_HapticOpenFromMouse
\brief Tries to open a haptic device from the current mouse.
\return The haptic device identifier or NULL on error.
\sa SDL_MouseIsHaptic \sa SDL_HapticOpen
\brief Checks to see if a joystick has haptic features.
\param joystick Joystick to test for haptic capabilities. \return 1 if the joystick is haptic, 0 if it isn't or -1 if an error ocurred.
\sa SDL_HapticOpenFromJoystick
\brief 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.
\param joystick Joystick to create a haptic device from. \return A valid haptic device identifier on success or NULL on error.
\sa SDL_HapticOpen \sa SDL_HapticClose
\brief Closes a Haptic device previously opened with SDL_HapticOpen().
\param haptic Haptic device to close.
\brief 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().
\param haptic The haptic device to query effect max. \return The number of effects the haptic device can store or -1 on error.
\sa SDL_HapticNumEffectsPlaying \sa SDL_HapticQuery
\brief 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.
\param haptic The haptic device to query maximum playing effects. \return The number of effects the haptic device can play at the same time or -1 on error.
\sa SDL_HapticNumEffects \sa SDL_HapticQuery
\brief Gets the haptic devices supported features in bitwise matter.
Example: \code if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) { printf("We have constant haptic effect!"); } \endcode
\param haptic The haptic device to query. \return Haptic features in bitwise manner (OR'd).
\sa SDL_HapticNumEffects \sa SDL_HapticEffectSupported
\brief Gets the number of haptic axes the device has.
\sa SDL_HapticDirection
\brief Checks to see if effect is supported by haptic.
\param haptic Haptic device to check on. \param effect Effect to check to see if it is supported. \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
\sa SDL_HapticQuery \sa SDL_HapticNewEffect
\brief Creates a new haptic effect on the device.
\param haptic Haptic device to create the effect on. \param effect Properties of the effect to create. \return The id of the effect on success or -1 on error.
\sa SDL_HapticUpdateEffect \sa SDL_HapticRunEffect \sa SDL_HapticDestroyEffect
\brief 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().
\param haptic Haptic device that has the effect. \param effect Effect to update. \param data New effect properties to use. \return The id of the effect on success or -1 on error.
\sa SDL_HapticNewEffect \sa SDL_HapticRunEffect \sa SDL_HapticDestroyEffect
\brief 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.
\param haptic Haptic device to run the effect on. \param effect Identifier of the haptic effect to run. \param iterations Number of iterations to run the effect. Use ::SDL_HAPTIC_INFINITY for infinity. \return 0 on success or -1 on error.
\sa SDL_HapticStopEffect \sa SDL_HapticDestroyEffect \sa SDL_HapticGetEffectStatus
\brief Stops the haptic effect on its associated haptic device.
\param haptic Haptic device to stop the effect on. \param effect Identifier of the effect to stop. \return 0 on success or -1 on error.
\sa SDL_HapticRunEffect \sa SDL_HapticDestroyEffect
\brief 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.
\param haptic Device to destroy the effect on. \param effect Identifier of the effect to destroy.
\sa SDL_HapticNewEffect
\brief Gets the status of the current effect on the haptic device.
Device must support the ::SDL_HAPTIC_STATUS feature.
\param haptic Haptic device to query the effect status on. \param effect Identifier of the effect to query its status. \return 0 if it isn't playing, 1 if it is playing or -1 on error.
\sa SDL_HapticRunEffect \sa SDL_HapticStopEffect
\brief 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.
\param haptic Haptic device to set the gain on. \param gain Value to set the gain to, should be between 0 and 100. \return 0 on success or -1 on error.
\sa SDL_HapticQuery
\brief 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.
\param haptic Haptic device to set autocentering on. \param autocenter Value to set autocenter to, 0 disables autocentering. \return 0 on success or -1 on error.
\sa SDL_HapticQuery
\brief 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.
\param haptic Haptic device to pause. \return 0 on success or -1 on error.
\sa SDL_HapticUnpause
\brief Unpauses a haptic device.
Call to unpause after SDL_HapticPause().
\param haptic Haptic device to pause. \return 0 on success or -1 on error.
\sa SDL_HapticPause
\brief Stops all the currently playing effects on a haptic device.
\param haptic Haptic device to stop. \return 0 on success or -1 on error.
\brief Checks to see if rumble is supported on a haptic device..
\param haptic Haptic device to check to see if it supports rumble. \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
\sa SDL_HapticRumbleInit \sa SDL_HapticRumblePlay \sa SDL_HapticRumbleStop
\brief Initializes the haptic device for simple rumble playback.
\param haptic Haptic device to initialize for simple rumble playback. \return 0 on success or -1 on error.
\sa SDL_HapticOpen \sa SDL_HapticRumbleSupported \sa SDL_HapticRumblePlay \sa SDL_HapticRumbleStop
\brief Runs simple rumble on a haptic device
\param haptic Haptic device to play rumble effect on. \param strength Strength of the rumble to play as a 0-1 float value. \param length Length of the rumble to play in milliseconds. \return 0 on success or -1 on error.
\sa SDL_HapticRumbleSupported \sa SDL_HapticRumbleInit \sa SDL_HapticRumbleStop
\brief Stops the simple rumble on a haptic device.
\param haptic Haptic to stop the rumble on. \return 0 on success or -1 on error.
\sa SDL_HapticRumbleSupported \sa SDL_HapticRumbleInit \sa SDL_HapticRumblePlay