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.