SDL_AppIterate(3)

💖 SDL_AppIterate(3) — the SDL3 FUNCTIONS girlies' edition 💖

okay so bestie, this is SDL_AppIterate(3), and it's literally the heartbeat of your SDL3 app. no cap.

---

✨ NAME ✨

SDL_AppIterate — the app-implemented iteration entry point for SDL_MAIN_USE_CALLBACKS apps. it's giving "main loop, but make it a callback." 🦋

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_main.h>

SDL_AppResult SDL_AppIterate(void *appstate);

---

✨ DESCRIPTION ✨

so here's the vibe: you implement this function when you're using SDL_MAIN_USE_CALLBACKS. if you're doing a standard "main" function instead? then bestie, do not supply this. not the moment. 🙈

this function gets called repeatedly by SDL after SDL_AppInit returns SDL_APP_CONTINUE. it should act as a single iteration of your program's primary loop — like, it should update whatever state it needs to update and draw a new frame of video, usually. one lap around the track, then dip. 🏃♀️

on some platforms, this function will be called at the refresh rate of the display — and plot twist, that rate might literally change during the life of your app! there are no promises made about what frequency this function might run at. so if you need to know how much time has passed since the last iteration, you should use SDL's timer functions. don't guess, bestie. ⏰

good news tho: there is no need to process the SDL event queue during this function. SDL will send events as they arrive in SDL_AppEvent, and in most cases the event queue will be empty when this function runs anyhow. so you can just vibe. 💅

⚠️ real talk: this function should not go into an infinite mainloop. it should do one iteration of whatever the program does and return. no holding the group chat hostage. periodt.

the appstate parameter is an optional pointer provided by the app during SDL_AppInit(). if the app never provided a pointer, this will be NULL. 🤷♀️

now for the return value drama, because this is where your app's whole fate lives:

• if this function returns SDL_APP_CONTINUE, the app continues normal operation, receiving repeated calls to SDL_AppIterate and SDL_AppEvent for the life of the program. iconic, thriving, slaying. 👑
• if this function returns SDL_APP_FAILURE, SDL will call SDL_AppQuit and terminate the process with an exit code that reports an error to the platform. 💀
• if it returns SDL_APP_SUCCESS, SDL calls SDL_AppQuit and terminates with an exit code that reports success to the platform. 🎀

and one more thing: this function is called by SDL on the main thread. main character energy, main thread. obviously. 🌟

---

✨ FUNCTION PARAMETERS ✨

• appstate — an optional pointer, provided by the app in SDL_AppInit. 🫶

---

✨ RETURN VALUE ✨

returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to terminate with success, SDL_APP_CONTINUE to continue. pick your fighter. 🥊

---

✨ THREAD SAFETY ✨

this function may get called concurrently with SDL_AppEvent() for events not pushed on the main thread. so like... be aware. sharing is caring but also sometimes sharing is a data race. 😭

---

✨ AVAILABILITY ✨

this function is available since SDL 3.2.0. not me being a relatively recent addition and still eating every single time. ⭐

---

✨ SEE ALSO ✨

• SDL_AppInit(3)
• SDL_AppEvent(3)

---

and that's the whole page, bestie!! brought to you by Simple Directmedia Layer, running SDL 3.4.18, mwah 💜 go forth and iterate, one frame at a time ✨🦋🎀