SDL_HapticEffect(3type)

💖 SDL_HapticEffect — the vibe is: haptics, but make it a union 💖

okay so bestie, welcome to the SDL3 DATATYPES corner of the manual, where we're talking about SDL_HapticEffect — the generic template for literally any haptic effect you could ever want your controller to feel. It's giving one union to rule them all. 👑

---

✨ NAME ✨

SDL_HapticEffect — the generic template for any haptic effect. that's it, that's the whole job. 🎀

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_haptic.h>

typedef union SDL_HapticEffect
{
    /* Common for all force feedback effects */
    SDL_HapticEffectType type;      /**< Effect type. */
    SDL_HapticConstant constant;    /**< Constant effect. */
    SDL_HapticPeriodic periodic;    /**< Periodic effect. */
    SDL_HapticCondition condition;  /**< Condition effect. */
    SDL_HapticRamp ramp;            /**< Ramp effect. */
    SDL_HapticLeftRight leftright;  /**< Left/Right effect. */
    SDL_HapticCustom custom;        /**< Custom effect. */
} SDL_HapticEffect;

it's a union, so every single one of those members lives at the same address — pick your fighter based on type and go. 💅

---

💜 DESCRIPTION 💜

lowkey the most important numbers first: all values max out at 32767 (0x7FFF). Signed values can also be negative, no big deal. And time values, unless somebody says otherwise, are in milliseconds. ⏱️

You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value. BUT — and this is the part you gotta hear me on — neither delay, interval, attack_length nor fade_length support SDL_HAPTIC_INFINITY. Fade will also not be used since the effect never ends. like, it never ends, so what is there to fade into? 😭

Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of SDL_HAPTIC_INFINITY. not me finding out the hard way 🙈

Button triggers may not be supported on all devices, so it is advised to not use them if possible. Also plot twist: buttons start at index 1 instead of index 0 like the joystick. yes bestie, we know. it's a whole thing. 💀

If both attack_length and fade_level are 0, the envelope is not used. Otherwise, both values are used. fr fr.

🧚 Common parts 🧚

these are the bits every effect shares, look at her:

// 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.

🦋 The diagram, aka the main character 🦋

Here we have an example of a constant effect evolution in time:

Strength
^
|
|    effect level -->  _________________
|                     /                 \
|                    /                   \
|                   /                     \
|                  /                       \
| attack_level --> |                        \
|                  |                        |  <---  fade_level
|
+--------------------------------------------------> Time
                   [--]                 [---]
                   attack_length        fade_length

[------------------][-----------------------]
delay               length

art. absolute art. 🎨

Note: either the attack_level or the fade_level may be above the actual effect level. so don't come for her when the numbers look weird — that's just how it be. 💅

---

⭐ AVAILABILITY ⭐

This struct is available since SDL 3.2.0. so if you're on something older… bestie, upgrade. 👑

---

👀 SEE ALSO 👀

• SDL_HapticConstant(3type)
• SDL_HapticPeriodic(3type)
• SDL_HapticCondition(3type)
• SDL_HapticRamp(3type)
• SDL_HapticLeftRight(3type)
• SDL_HapticCustom(3type)

go read them all, they're all slaying in their own way. ✨

---

💖 That's the whole page! Brought to you by Simple Directmedia Layer and SDL 3.4.18 — thanks for coming to my TED talk, mwah, drink water, and may all your haptics be finite (or not, SDL_HAPTIC_INFINITY is right there). 🫶🎀🌈 SDL_HapticEffect(3type) — periodt. 💅