haptic topic
CategoryHaptic
The SDL haptic subsystem manages haptic (force feedback) devices.
The basic usage is as follows:
- Initialize the subsystem (SDL_INIT_HAPTIC).
- Open a haptic device.
- SDL_OpenHaptic() to open from index.
- SDL_OpenHapticFromJoystick() to open from an existing joystick.
- Create an effect (SDL_HapticEffect).
- Upload the effect with SDL_CreateHapticEffect().
- Run the effect with SDL_RunHapticEffect().
- (optional) Free the effect with SDL_DestroyHapticEffect().
- Close the haptic device with SDL_CloseHaptic().
Simple rumble example:
   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:
bool test_haptic(SDL_Joystick *joystick)
{
   SDL_Haptic *haptic;
   SDL_HapticEffect effect;
   SDL_HapticEffectID effect_id;
   // Open the device
   haptic = SDL_OpenHapticFromJoystick(joystick);
   if (haptic == NULL) return 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 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 true; // Success
}
Note that the SDL haptic subsystem is not thread-safe.
Classes
Extensions
- 
  SdlHapticConditionExtension
  on Pointer<SdlHapticCondition> haptic
- 
  SdlHapticConstantExtension
  on Pointer<SdlHapticConstant> haptic
- 
  SdlHapticCustomExtension
  on Pointer<SdlHapticCustom> haptic
- 
  SdlHapticEffectExtension
  on Pointer<SdlHapticEffect> haptic
- 
  SdlHapticPeriodicExtension
  on Pointer<SdlHapticPeriodic> haptic
- 
  SdlHapticRampExtension
  on Pointer<SdlHapticRamp> haptic
Functions
- 
  sdlCloseHaptic(Pointer< hapticSdlHaptic> haptic) → void
- Close a haptic device previously opened with SDL_OpenHaptic().
- 
  sdlCreateHapticEffect(Pointer< hapticSdlHaptic> haptic, Pointer<SdlHapticEffect> effect) → int
- Create a new haptic effect on a specified device.
- 
  sdlDestroyHapticEffect(Pointer< hapticSdlHaptic> haptic, int effect) → void
- Destroy a haptic effect on the device.
- 
  sdlGetHapticEffectStatus(Pointer< hapticSdlHaptic> haptic, int effect) → bool
- Get the status of the current effect on the specified haptic device.
- 
  sdlGetHapticFeatures(Pointer< hapticSdlHaptic> haptic) → int
- Get the haptic device's supported features in bitwise manner.
- 
  sdlGetHapticFromId(int instanceId) → Pointer< hapticSdlHaptic> 
- Get the SDL_Haptic associated with an instance ID, if it has been opened.
- 
  sdlGetHapticId(Pointer< hapticSdlHaptic> haptic) → int
- Get the instance ID of an opened haptic device.
- 
  sdlGetHapticName(Pointer< hapticSdlHaptic> haptic) → String?
- Get the implementation dependent name of a haptic device.
- 
  sdlGetHapticNameForId(int instanceId) → String? haptic
- Get the implementation dependent name of a haptic device.
- 
  sdlGetHaptics(Pointer< hapticInt32> count) → Pointer<Uint32> 
- Get a list of currently connected haptic devices.
- 
  sdlGetMaxHapticEffects(Pointer< hapticSdlHaptic> haptic) → int
- Get the number of effects a haptic device can store.
- 
  sdlGetMaxHapticEffectsPlaying(Pointer< hapticSdlHaptic> haptic) → int
- Get the number of effects a haptic device can play at the same time.
- 
  sdlGetNumHapticAxes(Pointer< hapticSdlHaptic> haptic) → int
- Get the number of haptic axes the device has.
- 
  sdlHapticEffectSupported(Pointer< hapticSdlHaptic> haptic, Pointer<SdlHapticEffect> effect) → bool
- Check to see if an effect is supported by a haptic device.
- 
  sdlHapticRumbleSupported(Pointer< hapticSdlHaptic> haptic) → bool
- Check whether rumble is supported on a haptic device.
- 
  sdlInitHapticRumble(Pointer< hapticSdlHaptic> haptic) → bool
- Initialize a haptic device for simple rumble playback.
- 
  sdlIsJoystickHaptic(Pointer< hapticSdlJoystick> joystick) → bool
- Query if a joystick has haptic features.
- 
  sdlIsMouseHaptic() → bool haptic
- Query whether or not the current mouse has haptic capabilities.
- 
  sdlOpenHaptic(int instanceId) → Pointer< hapticSdlHaptic> 
- Open a haptic device for use.
- 
  sdlOpenHapticFromJoystick(Pointer< hapticSdlJoystick> joystick) → Pointer<SdlHaptic> 
- Open a haptic device for use from a joystick device.
- 
  sdlOpenHapticFromMouse() → Pointer< hapticSdlHaptic> 
- Try to open a haptic device from the current mouse.
- 
  sdlPauseHaptic(Pointer< hapticSdlHaptic> haptic) → bool
- Pause a haptic device.
- 
  sdlPlayHapticRumble(Pointer< hapticSdlHaptic> haptic, double strength, int length) → bool
- Run a simple rumble effect on a haptic device.
- 
  sdlResumeHaptic(Pointer< hapticSdlHaptic> haptic) → bool
- Resume a haptic device.
- 
  sdlRunHapticEffect(Pointer< hapticSdlHaptic> haptic, int effect, int iterations) → bool
- Run the haptic effect on its associated haptic device.
- 
  sdlSetHapticAutocenter(Pointer< hapticSdlHaptic> haptic, int autocenter) → bool
- Set the global autocenter of the device.
- 
  sdlSetHapticGain(Pointer< hapticSdlHaptic> haptic, int gain) → bool
- Set the global gain of the specified haptic device.
- 
  sdlStopHapticEffect(Pointer< hapticSdlHaptic> haptic, int effect) → bool
- Stop the haptic effect on its associated haptic device.
- 
  sdlStopHapticEffects(Pointer< hapticSdlHaptic> haptic) → bool
- Stop all the currently playing effects on a haptic device.
- 
  sdlStopHapticRumble(Pointer< hapticSdlHaptic> haptic) → bool
- Stop the simple rumble on a haptic device.
- 
  sdlUpdateHapticEffect(Pointer< hapticSdlHaptic> haptic, int effect, Pointer<SdlHapticEffect> data) → bool
- Update the properties of an effect.