SDL_HapticPeriodic(3type)

📦
version 3.4.18 · 9 versions
, in fedora 43, fedora 44

💖 SDL_HapticPeriodic — a datatype from the SDL3 haptics fam 💖

okay bestie, sit DOWN, because we're about to talk about the single most fun struct in all of SDL3: the one that makes your controller go brrrrr in a wavy little pattern. it's SDL_HapticPeriodic, it lives in the SDL3 datatypes section, and honestly? it's giving main character energy. 🎀

✨ NAME ✨

SDL_HapticPeriodic — a structure containing a template for a Periodic effect. yes, a whole struct whose entire job is "vibrate in a shape." iconic. 👑

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_haptic.h>

typedef struct SDL_HapticPeriodic
{
    /* Header */
    SDL_HapticEffectType type;      /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE
                                         SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or
                                         SDL_HAPTIC_SAWTOOTHDOWN */
    SDL_HapticDirection direction;  /**< Direction of the effect. */

    /* Replay */
    Uint32 length;      /**< Duration of the effect. */
    Uint16 delay;       /**< Delay before starting the effect. */

    /* Trigger */
    Uint16 button;      /**< Button that triggers the effect. */
    Uint16 interval;    /**< How soon it can be triggered again after button. */

    /* Periodic */
    Uint16 period;      /**< Period of the wave. */
    Sint16 magnitude;   /**< Peak value; if negative, equivalent to 180 degrees extra phase shift. */
    Sint16 offset;      /**< Mean value of the wave. */
    Uint16 phase;       /**< Positive phase shift given by hundredth of a degree. */

    /* Envelope */
    Uint16 attack_length;   /**< Duration of the attack. */
    Uint16 attack_level;    /**< Level at the start of the attack. */
    Uint16 fade_length; /**< Duration of the fade. */
    Uint16 fade_level;  /**< Level at the end of the fade. */
} SDL_HapticPeriodic;

like. look at those little commented sections. Header, Replay, Trigger, Periodic, Envelope. the organization?? the way it just tells you what each chunk is for?? obsessed. 😭💅

🦋 DESCRIPTION 🦋

so here's the tea. this struct handles the following effects, and ONLY these five:

  • SDL_HAPTIC_SINE
  • SDL_HAPTIC_SQUARE
  • SDL_HAPTIC_TRIANGLE
  • SDL_HAPTIC_SAWTOOTHUP
  • SDL_HAPTIC_SAWTOOTHDOWN

a periodic effect is, like, literally what it sounds like: a wave-shaped effect that repeats itself over time. the type decides which shape the wave is, and the other parameters decide the dimensions of that wave. shape + size = your vibe. periodt. ✨

🌈 phase, explained (iykyk)

phase is measured in hundredths of a degree. meaning if you hand phase a value of 9000, you've displaced it by 25% of its period. here are the sample values, bestie, memorize them:

  • 0: No phase displacement.
  • 9000: Displaced 25% of its period.
  • 18000: Displaced 50% of its period.
  • 27000: Displaced 75% of its period.
  • 36000: Displaced 100% of its period, same as 0, but 0 is preferred.
lowkey important: 36000 and 0 are the same thing, but the docs want you to use 0. so just use 0. don't be extra about it. 🙈

🎀 the wave shapes (visualize it, bestie)

Examples:

SDL_HAPTIC_SINE
  __      __      __      __
 /  \    /  \    /  \    /
/    \__/    \__/    \__/

SDL_HAPTIC_SQUARE
 __    __    __    __    __
|  |  |  |  |  |  |  |  |  |
|  |__|  |__|  |__|  |__|  |

SDL_HAPTIC_TRIANGLE
  /\    /\    /\    /\    /\
 /  \  /  \  /  \  /  \  /
/    \/    \/    \/    \/

SDL_HAPTIC_SAWTOOTHUP
  /|  /|  /|  /|  /|  /|  /|
 / | / | / | / | / | / | / |
/  |/  |/  |/  |/  |/  |/  |

SDL_HAPTIC_SAWTOOTHDOWN
\  |\  |\  |\  |\  |\  |\  |
 \ | \ | \ | \ | \ | \ | \ |
  \|  \|  \|  \|  \|  \|  \|

not the ASCII art eating down, honestly. the sawtooth ones are so dramatic for no reason. 💀

⭐ AVAILABILITY ⭐

This struct is available since SDL 3.2.0. so if you're on anything older, sorry babe, no periodic haptics for you. upgrade time. 🫶

👑 SEE ALSO 👑

go read these next, they're all in the group chat:

and that's the whole page, bestie!! this lil manual came to you from Simple Directmedia Layer, version SDL 3.4.18, dated SDL_HapticPeriodic(3type). go forth and make things shake. slay, no cap, fr fr. 💖✨🎀🦋🌸💅🫶🔥👑🌈⭐💜

📦 where this page comes from