SDL_AppEvent(3)

💖 SDL_AppEvent(3) — the glow-up entry point 💖

okay bestie, welcome to the SDL3 FUNCTIONS section of the manual, and today's main character is SDL_AppEvent. grab a boba, we're doing event callbacks 🧋✨

---

✨ NAME ✨

SDL_AppEvent — the app-implemented event entry point for SDL_MAIN_USE_CALLBACKS apps. yes, you write it, and SDL comes knocking every time something happens. it's giving "you're the bouncer and every event is a guest" 💅

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_main.h>

SDL_AppResult SDL_AppEvent(void *appstate, SDL_Event *event);

that's the whole vibe. two params, one return. no cap.

---

🦋 DESCRIPTION 🦋

so here's the tea: apps implement this function when they're using SDL_MAIN_USE_CALLBACKS. if you're on a standard "main" function instead, you should not supply this. like, at all. don't do it. 🙈

SDL calls this function as needed, after SDL_AppInit returns SDL_APP_CONTINUE. and it gets called once for each new event. one event, one call. very demure, very mindful.

now, the thread situation: there is (currently) no guarantee about what thread this will be called from 😭. literally whatever thread pushes an event onto SDL's queue is the one that triggers this function. SDL itself is responsible for pumping the event queue between each call to SDL_AppIterate, so in normal operation you should only be getting events in a serial fashion — but be careful if you have a thread that explicitly calls SDL_PushEvent. SDL itself pushes events to the queue on the main thread, fyi.

big yikes warning: events sent to this function are not owned by the app. if you need to save the data, you gotta copy it. no keeping references to stuff that's about to vanish, bestie, that's how you get undefined chaos 💀

also, this function should not go into an infinite mainloop. handle the provided event appropriately and then return. that's it. we do not live here. 🚪

the appstate parameter is an optional pointer that the app provided back during SDL_AppInit(). if the app never provided a pointer, it'll be NULL. (crying in NULL, honestly.)

and now the return values, aka the three doors 🚪🚪🚪:

• if this function returns SDL_APP_CONTINUE, the app just keeps vibing — it'll get repeated calls to SDL_AppIterate and SDL_AppEvent for the life of the program.
• if it 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. 👑

---

🎀 FUNCTION PARAMETERS 🎀

• appstate — an optional pointer, provided by the app in SDL_AppInit. could be NULL, could be your whole personality. who's to say 🫶
• event — the new event for the app to examine. this is the whole reason you're here, bestie, look at it. 👀

---

🌈 RETURN VALUE 🌈

returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to terminate with success, SDL_APP_CONTINUE to continue. three options, zero ambiguity, we love a clear contract ✨

---

💜 THREAD SAFETY 💜

this function may get called concurrently with SDL_AppIterate() or SDL_AppQuit() for events not pushed from the main thread. so like. lock your stuff. i'm serious. 🔒😭

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0. if you're on something older, sorry babe, you're on your own 🧚

---

👑 SEE ALSO 👑

• SDL_AppInit(3)
• SDL_AppIterate(3)

---

and that's the page, bestie 💖 written by the fine folks at Simple Directmedia Layer, from SDL 3.4.18, and yeah the page itself is SDL_AppEvent(3) — the header AND the footer said so, and now you know too. slay, go handle some events, and remember: copy the data, return the result, don't loop forever. periodt. 💅🌸✨