devela::_dep::sdl3::sys

Module haptic

Help

Available on crate feature dep_sdl3 only.

Expand description

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;
   int 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.

Structs§

SDL_Haptic: The haptic structure used to identify an SDL haptic.
SDL_HapticCondition: A structure containing a template for a Condition effect.
SDL_HapticConstant: A structure containing a template for a Constant effect.
SDL_HapticCustom: A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
SDL_HapticDirection: Structure that represents a haptic direction.
SDL_HapticLeftRight: A structure containing a template for a Left/Right effect.
SDL_HapticPeriodic: A structure containing a template for a Periodic effect.
SDL_HapticRamp: A structure containing a template for a Ramp effect.

Constants§

SDL_HAPTIC_AUTOCENTER: Device can set autocenter.
SDL_HAPTIC_CARTESIAN: Uses cartesian coordinates for the direction.
SDL_HAPTIC_CONSTANT: Constant effect supported.
SDL_HAPTIC_CUSTOM: Custom effect is supported.
SDL_HAPTIC_DAMPER: Damper effect supported - uses axes velocity.
SDL_HAPTIC_FRICTION: Friction effect supported - uses axes movement.
SDL_HAPTIC_GAIN: Device can set global gain.
SDL_HAPTIC_INERTIA: Inertia effect supported - uses axes acceleration.
SDL_HAPTIC_INFINITY: Used to play a device an infinite number of times.
SDL_HAPTIC_LEFTRIGHT: Left/Right effect supported.
SDL_HAPTIC_PAUSE: Device can be paused.
SDL_HAPTIC_POLAR: Uses polar coordinates for the direction.
SDL_HAPTIC_RAMP: Ramp effect supported.
SDL_HAPTIC_RESERVED1: Reserved for future use.
SDL_HAPTIC_RESERVED2: Reserved for future use.
SDL_HAPTIC_RESERVED3: Reserved for future use.
SDL_HAPTIC_SAWTOOTHDOWN: Sawtoothdown wave effect supported.
SDL_HAPTIC_SAWTOOTHUP: Sawtoothup wave effect supported.
SDL_HAPTIC_SINE: Sine wave effect supported.
SDL_HAPTIC_SPHERICAL: Uses spherical coordinates for the direction.
SDL_HAPTIC_SPRING: Spring effect supported - uses axes position.
SDL_HAPTIC_SQUARE: Square wave effect supported.
SDL_HAPTIC_STATUS: Device can be queried for effect status.
SDL_HAPTIC_STEERING_AXIS: Use this value to play an effect on the steering wheel axis.
SDL_HAPTIC_TRIANGLE: Triangle wave effect supported.

Functions§

SDL_CloseHaptic^⚠: Close a haptic device previously opened with SDL_OpenHaptic().
SDL_CreateHapticEffect^⚠: Create a new haptic effect on a specified device.
SDL_DestroyHapticEffect^⚠: Destroy a haptic effect on the device.
SDL_GetHapticEffectStatus^⚠: Get the status of the current effect on the specified haptic device.
SDL_GetHapticFeatures^⚠: Get the haptic device’s supported features in bitwise manner.
SDL_GetHapticFromID^⚠: Get the SDL_Haptic associated with an instance ID, if it has been opened.
SDL_GetHapticID^⚠: Get the instance ID of an opened haptic device.
SDL_GetHapticName^⚠: Get the implementation dependent name of a haptic device.
SDL_GetHapticNameForID^⚠: Get the implementation dependent name of a haptic device.
SDL_GetHaptics^⚠: Get a list of currently connected haptic devices.
SDL_GetMaxHapticEffects^⚠: Get the number of effects a haptic device can store.
SDL_GetMaxHapticEffectsPlaying^⚠: Get the number of effects a haptic device can play at the same time.
SDL_GetNumHapticAxes^⚠: Get the number of haptic axes the device has.
SDL_HapticEffectSupported^⚠: Check to see if an effect is supported by a haptic device.
SDL_HapticRumbleSupported^⚠: Check whether rumble is supported on a haptic device.
SDL_InitHapticRumble^⚠: Initialize a haptic device for simple rumble playback.
SDL_IsJoystickHaptic^⚠: Query if a joystick has haptic features.
SDL_IsMouseHaptic^⚠: Query whether or not the current mouse has haptic capabilities.
SDL_OpenHaptic^⚠: Open a haptic device for use.
SDL_OpenHapticFromJoystick^⚠: Open a haptic device for use from a joystick device.
SDL_OpenHapticFromMouse^⚠: Try to open a haptic device from the current mouse.
SDL_PauseHaptic^⚠: Pause a haptic device.
SDL_PlayHapticRumble^⚠: Run a simple rumble effect on a haptic device.
SDL_ResumeHaptic^⚠: Resume a haptic device.
SDL_RunHapticEffect^⚠: Run the haptic effect on its associated haptic device.
SDL_SetHapticAutocenter^⚠: Set the global autocenter of the device.
SDL_SetHapticGain^⚠: Set the global gain of the specified haptic device.
SDL_StopHapticEffect^⚠: Stop the haptic effect on its associated haptic device.
SDL_StopHapticEffects^⚠: Stop all the currently playing effects on a haptic device.
SDL_StopHapticRumble^⚠: Stop the simple rumble on a haptic device.
SDL_UpdateHapticEffect^⚠: Update the properties of an effect.

Type Aliases§

SDL_HapticID: This is a unique ID for a haptic device for the time it is connected to the system, and is never reused for the lifetime of the application.

Unions§

SDL_HapticEffect: The generic template for any haptic effect.