1 files changed, 236 insertions, 0 deletions

diff --git a/src/contrib/SDL-3.2.20/docs/README-main-functions.md b/src/contrib/SDL-3.2.20/docs/README-main-functions.md
new file mode 100644
index 0000000..75b9e2c
--- /dev/null
+++ b/src/contrib/SDL-3.2.20/docs/README-main-functions.md
@@ -0,0 +1,236 @@
+# Where an SDL program starts running.
+
+## History
+
+SDL has a long, complicated history with starting a program.
+
+In most of the civilized world, an application starts in a C-callable
+function named "main". You probably learned it a long time ago:
+
+```c
+int main(int argc, char **argv)
+{
+    printf("Hello world!\n");
+    return 0;
+}
+```
+
+But not all platforms work like this. Windows apps might want a different
+function named "WinMain", for example, so SDL set out to paper over this
+difference.
+
+Generally how this would work is: your app would always use the "standard"
+`main(argc, argv)` function as its entry point, and `#include` the proper
+SDL header before that, which did some macro magic. On platforms that used
+a standard `main`, it would do nothing and what you saw was what you got.
+
+But those other platforms! If they needed something that _wasn't_ `main`,
+SDL's macro magic would quietly rename your function to `SDL_main`, and
+provide its own entry point that called it. Your app was none the wiser and
+your code worked everywhere without changes.
+
+
+## The main entry point in SDL3
+
+Previous versions of SDL had a static library, SDLmain, that you would link
+your app against. SDL3 still has the same macro tricks, but the static library
+is gone. Now it's supplied by a "single-header library," which means you
+`#include <SDL3/SDL_main.h>` and that header will insert a small amount of
+code into the source file that included it, so you no longer have to worry
+about linking against an extra library that you might need on some platforms.
+You just build your app and it works.
+
+You should _only_ include SDL_main.h from one file (the umbrella header,
+SDL.h, does _not_ include it), and know that it will `#define main` to
+something else, so if you use this symbol elsewhere as a variable name, etc,
+it can cause you unexpected problems.
+
+SDL_main.h will also include platform-specific code (WinMain or whatnot) that
+calls your _actual_ main function. This is compiled directly into your
+program.
+
+If for some reason you need to include SDL_main.h in a file but also _don't_
+want it to generate this platform-specific code, you should define a special
+macro before including the header:
+
+
+```c
+#define SDL_MAIN_NOIMPL
+```
+
+If you are moving from SDL2, remove any references to the SDLmain static
+library from your build system, and you should be done. Things should work as
+they always have.
+
+If you have never controlled your process's entry point (you are using SDL
+as a module from a general-purpose scripting language interpreter, or you're
+using SDL in a plugin for some otherwise-unrelated app), then there is nothing
+required of you here; there is no startup code in SDL's entry point code that
+is required, so using SDL_main.h is completely optional. Just start using
+the SDL API when you are ready.
+
+
+## Main callbacks in SDL3
+
+There is a second option in SDL3 for how to structure your program. This is
+completely optional and you can ignore it if you're happy using a standard
+"main" function.
+
+Some platforms would rather your program operate in chunks. Most of the time,
+games tend to look like this at the highest level:
+
+```c
+int main(int argc, char **argv)
+{
+    initialize();
+    while (keep_running()) {
+        handle_new_events();
+        do_one_frame_of_stuff();
+    }
+    deinitialize();
+}
+```
+
+There are platforms that would rather be in charge of that `while` loop:
+iOS would rather you return from main() immediately and then it will let you
+know that it's time to update and draw the next frame of video. Emscripten
+(programs that run on a web page) absolutely requires this to function at all.
+Video targets like Wayland can notify the app when to draw a new frame, to
+save battery life and cooperate with the compositor more closely.
+
+In most cases, you can add special-case code to your program to deal with this
+on different platforms, but SDL3 offers a system to handle this transparently on
+the app's behalf.
+
+To use this, you have to redesign the highest level of your app a little. Once
+you do, it'll work on all supported SDL platforms without problems and
+`#ifdef`s in your code.
+
+Instead of providing a "main" function, under this system, you would provide
+several functions that SDL will call as appropriate.
+
+Using the callback entry points works on every platform, because on platforms
+that don't require them, we can fake them with a simple loop in an internal
+implementation of the usual SDL_main.
+
+The primary way we expect people to write SDL apps is still with SDL_main, and
+this is not intended to replace it. If the app chooses to use this, it just
+removes some platform-specific details they might have to otherwise manage,
+and maybe removes a barrier to entry on some future platform. And you might
+find you enjoy structuring your program like this more!
+
+
+## How to use main callbacks in SDL3
+
+To enable the callback entry points, you include SDL_main.h with an extra define,
+from a single source file in your project:
+
+```c
+#define SDL_MAIN_USE_CALLBACKS
+#include <SDL3/SDL_main.h>
+```
+
+Once you do this, you do not write a "main" function at all (and if you do,
+the app will likely fail to link). Instead, you provide the following
+functions:
+
+First:
+
+```c
+SDL_AppResult SDL_AppInit(void **appstate, int argc, char **argv);
+```
+
+This will be called _once_ before anything else. argc/argv work like they
+always do. If this returns SDL_APP_CONTINUE, the app runs. If it returns
+SDL_APP_FAILURE, the app calls SDL_AppQuit and terminates with an exit
+code that reports an error to the platform. If it returns SDL_APP_SUCCESS,
+the app calls SDL_AppQuit and terminates with an exit code that reports
+success to the platform. This function should not go into an infinite
+mainloop; it should do any one-time startup it requires and then return.
+
+If you want to, you can assign a pointer to `*appstate`, and this pointer
+will be made available to you in later functions calls in their `appstate`
+parameter. This allows you to avoid global variables, but is totally
+optional. If you don't set this, the pointer will be NULL in later function
+calls.
+
+
+Then:
+
+```c
+SDL_AppResult SDL_AppIterate(void *appstate);
+```
+
+This is called over and over, possibly at the refresh rate of the display or
+some other metric that the platform dictates. This is where the heart of your
+app runs. It should return as quickly as reasonably possible, but it's not a
+"run one memcpy and that's all the time you have" sort of thing. The app
+should do any game updates, and render a frame of video. 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, the app calls SDL_AppQuit and terminates with an exit code
+that reports success to the platform. If it returns SDL_APP_CONTINUE, then
+SDL_AppIterate will be called again at some regular frequency. The platform
+may choose to run this more or less (perhaps less in the background, etc),
+or it might just call this function in a loop as fast as possible. You do
+not check the  event queue in this function (SDL_AppEvent exists for that).
+
+Next:
+
+```c
+SDL_AppResult SDL_AppEvent(void *appstate, SDL_Event *event);
+```
+
+This will be called whenever an SDL event arrives. Your app should not call
+SDL_PollEvent, SDL_PumpEvent, etc, as  SDL will manage all this for you. Return
+values are the same as from SDL_AppIterate(), so you can terminate in response
+to SDL_EVENT_QUIT, etc.
+
+
+Finally:
+
+```c
+void SDL_AppQuit(void *appstate, SDL_AppResult result);
+```
+
+This is called once before terminating the app--assuming the app isn't being
+forcibly killed or crashed--as a last chance to clean up. After this returns,
+SDL will call SDL_Quit so the app doesn't have to (but it's safe for the app
+to call it, too). Process termination proceeds as if the app returned normally
+from main(), so atexit handles will run, if your platform supports that.
+
+If you set `*appstate` during SDL_AppInit, this is where you should free that
+data, as this pointer will not be provided to your app again.
+
+The SDL_AppResult value that terminated the app is provided here, in case
+it's useful to know if this was a successful or failing run of the app.
+
+
+## Summary and Best Practices
+
+- **Always Include SDL_main.h in One Source File:** When working with SDL,
+  remember that SDL_main.h must only be included in one source file in your
+  project. Including it in multiple files will lead to conflicts and undefined
+  behavior.
+
+- **Avoid Redefining main:** If you're using SDL's entry point system (which
+  renames `main` to `SDL_main`), do not define `main` yourself. SDL takes care
+  of this for you, and redefining it can cause issues, especially when linking
+  with SDL libraries.
+
+- **Using SDL's Callback System:** If you're working with more complex
+  scenarios, such as requiring more control over your application's flow
+  (e.g., with games or apps that need extensive event handling), consider
+  using SDL's callback system. Define the necessary callbacks and SDL will
+  handle initialization, event processing, and cleanup automatically.
+
+- **Platform-Specific Considerations:** On platforms like Windows, SDL handles
+  the platform-specific entry point (like `WinMain`) automatically. This means
+  you don't need to worry about writing platform-specific entry code when
+  using SDL.
+
+- **When to Skip SDL_main.h:** If you do not require SDL's custom entry point
+  (for example, if you're integrating SDL into an existing application or a
+  scripting environment), you can omit SDL_main.h. However, this will limit
+  SDL's ability to abstract away platform-specific entry point details.
+