SDL_AppInit(3)

💖 SDL_AppInit — the manual page (SDL3 FUNCTIONS, bestie) 💖

okay so you're in the SDL3 FUNCTIONS section of the manual and you clicked on SDL_AppInit?? slay, this is literally the first thing that happens in your app, it's giving opening night. 🌟

---

✨ NAME ✨

SDL_AppInit — the app-implemented initial entry point for SDL_MAIN_USE_CALLBACKS apps. 🎬

---

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_main.h>

SDL_AppResult SDL_AppInit(void **appstate, int argc, char *argv[]);

---

🦋 DESCRIPTION 🦋

So here's the vibe: you implement this function only when you're using SDL_MAIN_USE_CALLBACKS. If you're out here using a standard "main" function, then nope, you should not supply this one. pick a lane bestie 💅

This function gets called by SDL once, right at startup. It's your moment to initialize whatever needs initializing — possibly create windows, open audio devices, etc. The argc and argv parameters work exactly like they would with a standard "main" function. ✨

🚨 IMPORTANT: this function should not go into an infinite mainloop. do your one-time setup, and then return. that's it. no loitering. 🫶

The app may optionally assign a pointer to *appstate. That pointer will be handed to you on every future call to the other entry points, so you can preserve application state between functions without needing a global variable. and if you don't set it? then the pointer will be NULL in future entry points. so like... set it, or don't, but know the consequences. 😭

Now for the return value drama, and this part matters:

• If this function returns SDL_APP_CONTINUE, the app proceeds to normal operation and will begin receiving repeated calls to SDL_AppIterate and SDL_AppEvent for the life of the program. iconic. this is the "we're so back" path. 🔥
• 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. 👑

Also, for the record: this function is called by SDL on the main thread. 🧵

---

🌸 FUNCTION PARAMETERS 🌸

• appstate — a place where the app can optionally store a pointer for future use. your little state drawer. 🗄️
• argc — the standard ANSI C main's argc; number of elements in argv.
• argv — the standard ANSI C main's argv; array of command line arguments.

---

⭐ RETURN VALUE ⭐

Returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to terminate with success, SDL_APP_CONTINUE to continue. three doors, pick one. 🚪🚪🚪

---

🧚 THREAD SAFETY 🧚

This function is called once by SDL, at startup, on a single thread. no threads fighting over it, it's a one-and-done situation. periodt. 💅

---

🌈 AVAILABILITY 🌈

This function is available since SDL 3.2.0. so if you're on something older... girl. update. 🙈

---

💜 SEE ALSO 💜

• SDL_AppIterate(3)
• SDL_AppEvent(3)
• SDL_AppQuit(3)

the whole callback friend group, honestly. iykyk. 🫶

---

and that's the page!! brought to you by Simple Directmedia Layer, version SDL 3.4.18 — go forth and initialize your windows, bestie, you've got this 💖✨🎀🦋🌸