# CategoryHaptic

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

The basic usage is as follows:

- Initialize the subsystem ([SDL_INIT_HAPTIC](SDL_INIT_HAPTIC)).
- Open a haptic device.
- [SDL_OpenHaptic](SDL_OpenHaptic)() to open from index.
- [SDL_OpenHapticFromJoystick](SDL_OpenHapticFromJoystick)() to open from
  an existing joystick.
- Create an effect ([SDL_HapticEffect](SDL_HapticEffect)).
- Upload the effect with
  [SDL_CreateHapticEffect](SDL_CreateHapticEffect)().
- Run the effect with [SDL_RunHapticEffect](SDL_RunHapticEffect)().
- (optional) Free the effect with
  [SDL_DestroyHapticEffect](SDL_DestroyHapticEffect)().
- Close the haptic device with [SDL_CloseHaptic](SDL_CloseHaptic)().

Simple rumble example:

```c
   SDL_Haptic *haptic = NULL;

   // Open the device
   SDL_HapticID *haptics = SDL_GetHaptics(NULL);
   if (haptics) {
       haptic = SDL_OpenHaptic(haptics[0]);
       SDL_free(haptics);
   }
   if (haptic == NULL)
      return;

   // Initialize simple rumble
   if (!SDL_InitHapticRumble(haptic))
      return;

   // Play effect at 50% strength for 2 seconds
   if (!SDL_PlayHapticRumble(haptic, 0.5, 2000))
      return;
   SDL_Delay(2000);

   // Clean up
   SDL_CloseHaptic(haptic);
```

Complete example:

```c
SDL_bool test_haptic(SDL_Joystick *joystick)
{
   SDL_Haptic *haptic;
   SDL_HapticEffect effect;
   int effect_id;

   // Open the device
   haptic = SDL_OpenHapticFromJoystick(joystick);
   if (haptic == NULL) return SDL_FALSE; // Most likely joystick isn't haptic

   // See if it can do sine waves
   if ((SDL_GetHapticFeatures(haptic) & SDL_HAPTIC_SINE)==0) {
      SDL_CloseHaptic(haptic); // No sine effect
      return SDL_FALSE;
   }

   // Create the effect
   SDL_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_CreateHapticEffect(haptic, &effect);

   // Test the effect
   SDL_RunHapticEffect(haptic, effect_id, 1);
   SDL_Delay(5000); // Wait for the effect to finish

   // We destroy the effect, although closing the device also does this
   SDL_DestroyHapticEffect(haptic, effect_id);

   // Close the device
   SDL_CloseHaptic(haptic);

   return SDL_TRUE; // Success
}
```

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

<!-- END CATEGORY DOCUMENTATION -->

## Functions

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryHaptic, CategoryAPIFunction -->
- [SDL_CloseHaptic](SDL_CloseHaptic)
- [SDL_CreateHapticEffect](SDL_CreateHapticEffect)
- [SDL_DestroyHapticEffect](SDL_DestroyHapticEffect)
- [SDL_GetHapticEffectStatus](SDL_GetHapticEffectStatus)
- [SDL_GetHapticFeatures](SDL_GetHapticFeatures)
- [SDL_GetHapticFromID](SDL_GetHapticFromID)
- [SDL_GetHapticID](SDL_GetHapticID)
- [SDL_GetHapticName](SDL_GetHapticName)
- [SDL_GetHapticNameForID](SDL_GetHapticNameForID)
- [SDL_GetHaptics](SDL_GetHaptics)
- [SDL_GetMaxHapticEffects](SDL_GetMaxHapticEffects)
- [SDL_GetMaxHapticEffectsPlaying](SDL_GetMaxHapticEffectsPlaying)
- [SDL_GetNumHapticAxes](SDL_GetNumHapticAxes)
- [SDL_HapticEffectSupported](SDL_HapticEffectSupported)
- [SDL_HapticRumbleSupported](SDL_HapticRumbleSupported)
- [SDL_InitHapticRumble](SDL_InitHapticRumble)
- [SDL_IsJoystickHaptic](SDL_IsJoystickHaptic)
- [SDL_IsMouseHaptic](SDL_IsMouseHaptic)
- [SDL_OpenHaptic](SDL_OpenHaptic)
- [SDL_OpenHapticFromJoystick](SDL_OpenHapticFromJoystick)
- [SDL_OpenHapticFromMouse](SDL_OpenHapticFromMouse)
- [SDL_PauseHaptic](SDL_PauseHaptic)
- [SDL_PlayHapticRumble](SDL_PlayHapticRumble)
- [SDL_ResumeHaptic](SDL_ResumeHaptic)
- [SDL_RunHapticEffect](SDL_RunHapticEffect)
- [SDL_SetHapticAutocenter](SDL_SetHapticAutocenter)
- [SDL_SetHapticGain](SDL_SetHapticGain)
- [SDL_StopHapticEffect](SDL_StopHapticEffect)
- [SDL_StopHapticEffects](SDL_StopHapticEffects)
- [SDL_StopHapticRumble](SDL_StopHapticRumble)
- [SDL_UpdateHapticEffect](SDL_UpdateHapticEffect)
<!-- END CATEGORY LIST -->

## Datatypes

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryHaptic, CategoryAPIDatatype -->
- [SDL_Haptic](SDL_Haptic)
- [SDL_HapticID](SDL_HapticID)
<!-- END CATEGORY LIST -->

## Structs

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryHaptic, CategoryAPIStruct -->
- [SDL_HapticCondition](SDL_HapticCondition)
- [SDL_HapticConstant](SDL_HapticConstant)
- [SDL_HapticCustom](SDL_HapticCustom)
- [SDL_HapticDirection](SDL_HapticDirection)
- [SDL_HapticEffect](SDL_HapticEffect)
- [SDL_HapticLeftRight](SDL_HapticLeftRight)
- [SDL_HapticPeriodic](SDL_HapticPeriodic)
- [SDL_HapticRamp](SDL_HapticRamp)
<!-- END CATEGORY LIST -->

## Enums

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryHaptic, CategoryAPIEnum -->
- (none.)
<!-- END CATEGORY LIST -->

## Macros

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryHaptic, CategoryAPIMacro -->
- [SDL_HAPTIC_AUTOCENTER](SDL_HAPTIC_AUTOCENTER)
- [SDL_HAPTIC_CARTESIAN](SDL_HAPTIC_CARTESIAN)
- [SDL_HAPTIC_CONSTANT](SDL_HAPTIC_CONSTANT)
- [SDL_HAPTIC_CUSTOM](SDL_HAPTIC_CUSTOM)
- [SDL_HAPTIC_DAMPER](SDL_HAPTIC_DAMPER)
- [SDL_HAPTIC_FRICTION](SDL_HAPTIC_FRICTION)
- [SDL_HAPTIC_GAIN](SDL_HAPTIC_GAIN)
- [SDL_HAPTIC_INERTIA](SDL_HAPTIC_INERTIA)
- [SDL_HAPTIC_INFINITY](SDL_HAPTIC_INFINITY)
- [SDL_HAPTIC_LEFTRIGHT](SDL_HAPTIC_LEFTRIGHT)
- [SDL_HAPTIC_PAUSE](SDL_HAPTIC_PAUSE)
- [SDL_HAPTIC_POLAR](SDL_HAPTIC_POLAR)
- [SDL_HAPTIC_RAMP](SDL_HAPTIC_RAMP)
- [SDL_HAPTIC_RESERVED1](SDL_HAPTIC_RESERVED1)
- [SDL_HAPTIC_SAWTOOTHDOWN](SDL_HAPTIC_SAWTOOTHDOWN)
- [SDL_HAPTIC_SAWTOOTHUP](SDL_HAPTIC_SAWTOOTHUP)
- [SDL_HAPTIC_SINE](SDL_HAPTIC_SINE)
- [SDL_HAPTIC_SPHERICAL](SDL_HAPTIC_SPHERICAL)
- [SDL_HAPTIC_SPRING](SDL_HAPTIC_SPRING)
- [SDL_HAPTIC_SQUARE](SDL_HAPTIC_SQUARE)
- [SDL_HAPTIC_STATUS](SDL_HAPTIC_STATUS)
- [SDL_HAPTIC_STEERING_AXIS](SDL_HAPTIC_STEERING_AXIS)
- [SDL_HAPTIC_TRIANGLE](SDL_HAPTIC_TRIANGLE)
<!-- END CATEGORY LIST -->


----
[CategoryAPICategory](CategoryAPICategory)