SDL_HapticDirection(3type)

💫 NAME 💫

SDL_HapticDirection — bestie, it's the struct that represents a haptic direction 💅

And yeah, this is the SDL_HapticDirection(3type) page from the SDL3 DATATYPES crew, iykyk 🦋

---

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_haptic.h>

typedef struct SDL_HapticDirection
{
    SDL_HapticDirectionType type;  /**< The type of encoding. */
    Sint32 dir[3];                 /**< The encoded direction. */
} SDL_HapticDirection;

---

✨ DESCRIPTION ✨

Okay so here's the thing that trips literally everyone up: this is the direction the force comes from, not the direction the force gets exerted in. Yes fr fr, it's backwards on purpose. Read it twice, queen. 👑

Directions can be specified by:

• SDL_HAPTIC_POLAR — specified by polar coordinates.
• SDL_HAPTIC_CARTESIAN — specified by cartesian coordinates.
• SDL_HAPTIC_SPHERICAL — specified by spherical coordinates.

Cardinal directions of the haptic device are relative to the positioning of the device. North is considered to be away from the user. That's the whole compass, bestie, and it's anchored to where the device is sitting, not to you 🌸

The following diagram represents the cardinal directions:

                         .--.
                         |__| .-------.
                         |=.| |.-----.|
                         |--| ||     ||
                         |  | |'-----'|
                         |__|~')_____('
                           [ COMPUTER ]

                             North (0,-1)
                                 ^
                                 |
                                 |
           (-1,0)  West <----[ HAPTIC ]----> East (1,0)
                                 |
                                 |
                                 v
                              South (0,1)

                              [ USER ]
                                \|||/
                                (o o)
                          ---ooO-(_)-Ooo---

🌈 Polar, but make it numbers

If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a degree starting north and turning clockwise. SDL_HAPTIC_POLAR only uses the first dir parameter. The cardinal directions would be:

• North: 0 (0 degrees)
• East: 9000 (90 degrees)
• South: 18000 (180 degrees)
• West: 27000 (270 degrees)

🧚 Cartesian, aka the XYZ girlies

If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first three dir parameters. The cardinal directions would be:

• North: 0,-1, 0
• East: 1, 0, 0
• South: 0, 1, 0
• West: -1, 0, 0

The Z axis represents the height of the effect if supported, otherwise it's unused. And listen — in cartesian encoding (1, 2) would be the same as (2, 4), you can use any multiple you want, only the direction matters. Ratios only, periodt 💅

🦋 Spherical, the two-rotation moment

If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. The first two dir parameters are used. The dir parameters are as follows (all values are in hundredths of degrees):

• Degrees from (1, 0) rotated towards (0, 1).
• Degrees towards (0, 0, 1) (device needs at least 3 axes).

💀 Example time

Example of force coming from the south with all encodings (force coming from the south means the user will have to pull the stick to counteract):

SDL_HapticDirection direction;

// Cartesian directions
direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
direction.dir[0] = 0; // X position
direction.dir[1] = 1; // Y position
// Assuming the device has 2 axes, we don't need to specify third parameter.

// Polar directions
direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
direction.dir[0] = 18000; // Polar only uses first parameter

// Spherical coordinates
direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.

---

👑 AVAILABILITY 👑

This struct is available since SDL 3.2.0. Not ancient, not brand new — just a cute lil era ✨

---

🫶 SEE ALSO 🫶

• SDL_HAPTIC_POLAR(3)
• SDL_HAPTIC_CARTESIAN(3)
• SDL_HAPTIC_SPHERICAL(3)
• SDL_HAPTIC_STEERING_AXIS(3)
• SDL_HapticEffect(3type)
• SDL_GetNumHapticAxes(3)

---

Simple Directmedia Layer · SDL 3.4.18 · SDL_HapticDirection(3type)

and that's the whole page bestie, go forth and encode your directions correctly, mwah 💖🎀🦋🌸✨