SDL_AddTimerNS(3)

✨ SDL_AddTimerNS(3) ✨

okay bestie, we're in the SDL3 FUNCTIONS section today and this one is literally so fun — it's giving "set an alarm for future me" energy 🫶

---

🌸 NAME 🌸

SDL_AddTimerNS — call a callback function at a future time. no cap, that's the whole vibe 💅

---

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_timer.h>

SDL_TimerID SDL_AddTimerNS(Uint64 interval, SDL_NSTimerCallback callback, void *userdata);

---

🦋 DESCRIPTION 🦋

so here's the tea ☕ — your callback function gets handed the current timer interval and the userdata pointer you passed in when you called SDL_AddTimerNS(). and then it has to return the next timer interval. and if the value it returns is 0? yeah, the timer is canceled and will be removed. gone. bye. 💀

the callback runs on a separate thread, which is iconic of it. and heads up: for short timeouts, it can potentially be called before this function even returns. like it's that fast, she's an overachiever 🧚

now, timers take into account how long the callback itself took to execute. for example — if the callback took 250 ns to execute and returned 1000 (ns), the timer would only wait another 750 ns before its next iteration. math ate that one, fr fr 🔥

timing may be inexact due to OS scheduling. so be sure to note the current time with SDL_GetTicksNS() or SDL_GetPerformanceCounter() in case your callback needs to adjust for variances. iykyk 🌈

---

👑 FUNCTION PARAMETERS 👑

• interval — the timer delay, in nanoseconds, passed to callback. ⏱️
• callback — the SDL_TimerCallback function to call when the specified interval elapses.
• userdata — a pointer that is passed to callback. 🎁

---

⭐ RETURN VALUE ⭐

returns a timer ID, or 0 on failure 😭 — and if it fails you gotta call SDL_GetError() for more information, that's where the lore lives.

---

💜 THREAD SAFETY 💜

it is safe to call this function from any thread. go off, multitasking queen 👑

---

🌈 AVAILABILITY 🌈

this function is available since SDL 3.2.0. vintage-ish but still fresh ✨

---

🍓 SEE ALSO 🍓

• SDL_AddTimer(3)
• SDL_RemoveTimer(3)

---

and that's the whole page bestie!! 💖 brought to you by Simple Directmedia Layer, version SDL 3.4.18, dated SDL_AddTimerNS(3) — mwah, slay, periodt 🎀✨🫶