SDL_GetRelativeMouseState(3)

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

💖 SDL_GetRelativeMouseState(3) 💖

okay bestie, this one's from the SDL3 FUNCTIONS section of the manual and it's literally the mouse-delta girlie you've been looking for 🦋

✨ NAME ✨

SDL_GetRelativeMouseState — it queries SDL's own little cache for the synchronous mouse button state plus all the mouse delta that's been piling up since the last time you called it. no cap.

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_mouse.h>

SDL_MouseButtonFlags SDL_GetRelativeMouseState(float *x, float *y);

🎀 DESCRIPTION 🎀

so the way this works is: it hands you back the cached synchronous state — like, the state as SDL understands it from the last time the event queue got pumped. that's the vibe. 💅

if you wanna go ask the platform directly for the immediate asynchronous state instead? that's a whole different function, bestie — use SDL_GetGlobalMouseState.

now, if you pass non-NULL pointers into x or y, it's gonna write into those destinations the respective x or y deltas that accumulated since the last call to this function (or since event initialization, if this is your first rodeo 🌈).

and why would you want this? because it's giving efficiency, honestly. you get to process all your relative mouse input in one go per-frame instead of doing it individually per-event, which cuts overhead. the tradeoff though — and this part matters — is that you lose the order between events within the frame. so if someone quickly presses and releases a button inside the same frame, that whole little sequence? yeah, you won't see the order of it. 😭

🫶 FUNCTION PARAMETERS 🫶

  • x — a pointer that receives the x mouse delta accumulated since last call. it can be NULL if you're not using it, no pressure 💜
  • y — a pointer that receives the y mouse delta accumulated since last call. also totally fine to be NULL if unused ✨

👑 RETURN VALUE 👑

it returns a 32-bit bitmask of the button state, which you can bitwise-compare against the SDL_BUTTON_MASK(X) macro. iconic.

💀 THREAD SAFETY 💀

this function should only be called on the main thread. like, main character energy only, fr fr. don't be out here calling it from other threads 🙈

⭐ AVAILABILITY ⭐

this one's been around since SDL 3.2.0. slay.

🌈 SEE ALSO 🌈

and that's the whole page, bestie 🍓 brought to you by Simple Directmedia Layer, SDL 3.4.18, and this very SDL_GetRelativeMouseState(3) moment. go get those deltas 💖🧚✨

📦 where this page comes from