SDL_NSTimerCallback(3type)

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

SDL_NSTimerCallback 💖

okay bestie, welcome to the SDL3 DATATYPES corner of the manual, where today's main character is SDL_NSTimerCallback — the function prototype for the nanosecond timer callback function. yes, nanoseconds. she's precise. ✨

✨ SYNOPSIS ✨

#include <SDL3/SDL_timer.h>

typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerID, Uint64 interval);

like. look at that signature. gorgeous. no notes. 💅

🌸 DESCRIPTION 🌸

so here's the vibe: this callback gets handed the current timer interval, and it hands back the next timer interval, measured in nanoseconds. that's the whole gig.

and then the rules, because there are always rules:

  • if the value you return is the same as the one that got passed in → the periodic alarm just keeps going, no drama, no interruptions. iconic behaviour. 🫶
  • if it's different → a brand new alarm gets scheduled.
  • if you return 0 → the periodic alarm is canceled and will be removed. that's it, she's gone, say bye. 😭

🎀 FUNCTION PARAMETERS 🎀

  • userdata — an arbitrary pointer that the app handed over through SDL_AddTimer, purely for its own use. it's yours, do whatever, no judgement. 🙈
  • timerID — the current timer being processed. that's the one on the table right now.
  • interval — the current callback time interval.

⭐ RETURN VALUE ⭐

you return the new callback time interval, or you return 0 to disable any further runs of the callback. that's the deal. 🍓

💜 THREAD SAFETY 💜

okay this is the part where we get serious for one sec, bestie, because it matters:

SDL may call this callback at any time from a background thread. the application is responsible for locking resources the callback touches that need to be protected.

so like. lock your stuff. protect your stuff. don't be out here raw-dogging shared state from a background thread. 💀

🌈 AVAILABILITY 🌈

this datatype has been available since SDL 3.2.0. she's not new new, but she's not ancient either. 🧚

👑 SEE ALSO 👑

and that's the page, bestie!! go forth and schedule your nanoseconds responsibly. 💖✨

Simple Directmedia Layer — SDL 3.4.18 — SDL_NSTimerCallback(3type). mwah. periodt. 🎀💅🦋

📦 where this page comes from