From 3bd04e5a34de75e4b427e31a48f61c57fd5566b8 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Fri, 3 May 2024 13:32:31 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
---
include/SDL3/SDL_main.h | 141 +++++++++++++++++++++-------------------
1 file changed, 73 insertions(+), 68 deletions(-)
diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h
index 6f214faac9b78..afb80df50f5ab 100644
--- a/include/SDL3/SDL_main.h
+++ b/include/SDL3/SDL_main.h
@@ -194,34 +194,37 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate);
/**
* App-implemented initial entry point for SDL_MAIN_USE_CALLBACKS apps.
*
- * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If
- * using a standard "main" function, you should not supply this.
+ * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a
+ * standard "main" function, you should not supply this.
*
* This function is called by SDL once, at startup. The function should
- * initialize whatever is necessary, possibly create windows and open
- * audio devices, etc. The `argc` and `argv` parameters work like they would
- * with a standard "main" function.
+ * initialize whatever is necessary, possibly create windows and open audio
+ * devices, etc. The `argc` and `argv` parameters work like they would with a
+ * standard "main" function.
*
* This function should not go into an infinite mainloop; it should do any
* one-time setup it requires and then return.
*
* The app may optionally assign a pointer to `*appstate`. This pointer will
* be provided on every future call to the other entry points, to allow
- * application state to be preserved between functions without the app
- * needing to use a global variable. If this isn't set, the pointer will
- * be NULL in future entry points.
- *
- * If this function returns 0, the app will proceed to normal operation,
- * and will begin receiving repeated calls to SDL_AppIterate and SDL_AppEvent
- * for the life of the program. If this function returns < 0, SDL will
- * call SDL_AppQuit and terminate the process with an exit code that reports
- * an error to the platform. If it returns > 0, the SDL calls SDL_AppQuit
- * and terminates with an exit code that reports success to the platform.
- *
- * \param appstate a place where the app can optionally store a pointer for future use.
+ * application state to be preserved between functions without the app needing
+ * to use a global variable. If this isn't set, the pointer will be NULL in
+ * future entry points.
+ *
+ * If this function returns 0, the app will proceed to normal operation, and
+ * will begin receiving repeated calls to SDL_AppIterate and SDL_AppEvent for
+ * the life of the program. If this function returns < 0, SDL will call
+ * SDL_AppQuit and terminate the process with an exit code that reports an
+ * error to the platform. If it returns > 0, the SDL calls SDL_AppQuit and
+ * terminates with an exit code that reports success to the platform.
+ *
+ * \param appstate a place where the app can optionally store a pointer for
+ * future use.
* \param argc The standard ANSI C main's argc; number of elements in `argv`
- * \param argv The standard ANSI C main's argv; array of command line arguments.
- * \returns -1 to terminate with an error, 1 to terminate with success, 0 to continue.
+ * \param argv The standard ANSI C main's argv; array of command line
+ * arguments.
+ * \returns -1 to terminate with an error, 1 to terminate with success, 0 to
+ * continue.
*
* \threadsafety This function is not thread safe.
*
@@ -236,23 +239,23 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(void **appstate, int argc, char
/**
* App-implemented iteration entry point for SDL_MAIN_USE_CALLBACKS apps.
*
- * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If
- * using a standard "main" function, you should not supply this.
+ * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a
+ * standard "main" function, you should not supply this.
*
- * This function is called repeatedly by SDL after SDL_AppInit returns 0.
- * The function should operate as a single iteration the program's primary
- * loop; it should update whatever state it needs and draw a new frame of
- * video, usually.
+ * This function is called repeatedly by SDL after SDL_AppInit returns 0. The
+ * function should operate as a single iteration the program's primary loop;
+ * it should update whatever state it needs and draw a new frame of video,
+ * usually.
*
- * On some platforms, this function will be called at the refresh rate of
- * the display (which might change during the life of your app!). There are
- * no promises made about what frequency this function might run at. You
- * should use SDL's timer functions if you need to see how much time has
- * passed since the last iteration.
+ * On some platforms, this function will be called at the refresh rate of the
+ * display (which might change during the life of your app!). There are no
+ * promises made about what frequency this function might run at. You should
+ * use SDL's timer functions if you need to see how much time has passed since
+ * the last iteration.
*
- * 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.
+ * 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.
*
* This function should not go into an infinite mainloop; it should do one
* iteration of whatever the program does and return.
@@ -261,14 +264,15 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(void **appstate, int argc, char
* SDL_AppInit(). If the app never provided a pointer, this will be NULL.
*
* If this function returns 0, the app will continue normal operation,
- * receiving repeated calls to SDL_AppIterate and SDL_AppEvent for the life
- * of the program. If this function returns < 0, SDL will call SDL_AppQuit
- * and terminate the process with an exit code that reports an error to the
+ * receiving repeated calls to SDL_AppIterate and SDL_AppEvent for the life of
+ * the program. If this function returns < 0, SDL will call SDL_AppQuit and
+ * terminate the process with an exit code that reports an error to the
* platform. If it returns > 0, the SDL calls SDL_AppQuit and terminates with
* an exit code that reports success to the platform.
*
* \param appstate an optional pointer, provided by the app in SDL_AppInit.
- * \returns -1 to terminate with an error, 1 to terminate with success, 0 to continue.
+ * \returns -1 to terminate with an error, 1 to terminate with success, 0 to
+ * continue.
*
* \threadsafety This function is not thread safe.
*
@@ -282,43 +286,44 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppIterate(void *appstate);
/**
* App-implemented event entry point for SDL_MAIN_USE_CALLBACKS apps.
*
- * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If
- * using a standard "main" function, you should not supply this.
+ * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a
+ * standard "main" function, you should not supply this.
*
- * This function is called as needed by SDL after SDL_AppInit returns 0;
- * It is called once for each new event.
+ * This function is called as needed by SDL after SDL_AppInit returns 0; It is
+ * called once for each new event.
*
* There is (currently) no guarantee about what thread this will be called
* from; whatever thread pushes an event onto SDL's queue will trigger this
- * function. SDL is responsible for pumping the event queue between
- * each call to SDL_AppIterate, so in normal operation one should only
- * get events in a serial fashion, but be careful if you have a thread that
- * explicitly calls SDL_PushEvent.
+ * function. SDL is responsible for pumping the event queue between each call
+ * to SDL_AppIterate, so in normal operation one should only get events in a
+ * serial fashion, but be careful if you have a thread that explicitly calls
+ * SDL_PushEvent.
*
- * Events sent to this function are not owned by the app; if you need to
- * save the data, you should copy it.
+ * Events sent to this function are not owned by the app; if you need to save
+ * the data, you should copy it.
*
* You do not need to free event data (such as the `file` string in
- * SDL_EVENT_DROP_FILE), as SDL will free it once this function returns.
- * Note that this is different than one might expect when using a standard
- * "main" function!
+ * SDL_EVENT_DROP_FILE), as SDL will free it once this function returns. Note
+ * that this is different than one might expect when using a standard "main"
+ * function!
*
- * This function should not go into an infinite mainloop; it should handle
- * the provided event appropriately and return.
+ * This function should not go into an infinite mainloop; it should handle the
+ * provided event appropriately and return.
*
* 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.
*
* If this function returns 0, the app will continue normal operation,
- * receiving repeated calls to SDL_AppIterate and SDL_AppEvent for the life
- * of the program. If this function returns < 0, SDL will call SDL_AppQuit
- * and terminate the process with an exit code that reports an error to the
+ * receiving repeated calls to SDL_AppIterate and SDL_AppEvent for the life of
+ * the program. If this function returns < 0, SDL will call SDL_AppQuit and
+ * terminate the process with an exit code that reports an error to the
* platform. If it returns > 0, the SDL calls SDL_AppQuit and terminates with
* an exit code that reports success to the platform.
*
* \param appstate an optional pointer, provided by the app in SDL_AppInit.
* \param event the new event for the app to examine.
- * \returns -1 to terminate with an error, 1 to terminate with success, 0 to continue.
+ * \returns -1 to terminate with an error, 1 to terminate with success, 0 to
+ * continue.
*
* \threadsafety This function is not thread safe.
*
@@ -332,26 +337,26 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppEvent(void *appstate, const SDL_Event
/**
* App-implemented deinit entry point for SDL_MAIN_USE_CALLBACKS apps.
*
- * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If
- * using a standard "main" function, you should not supply this.
+ * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a
+ * standard "main" function, you should not supply this.
*
* This function is called once by SDL before terminating the program.
*
- * This function will be called no matter what, even if SDL_AppInit
- * requests termination.
+ * This function will be called no matter what, even if SDL_AppInit requests
+ * termination.
*
* This function should not go into an infinite mainloop; it should
- * deinitialize any resources necessary, perform whatever shutdown
- * activities, and return.
+ * deinitialize any resources necessary, perform whatever shutdown activities,
+ * and return.
*
- * You do not need to call SDL_Quit() in this function, as SDL will call
- * it after this function returns and before the process terminates, but
- * it is safe to do so.
+ * You do not need to call SDL_Quit() in this function, as SDL will call it
+ * after this function returns and before the process terminates, but it is
+ * safe to do so.
*
* 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.
- * This function call is the last time this pointer will be provided, so
- * any resources to it should be cleaned up here.
+ * SDL_AppInit(). If the app never provided a pointer, this will be NULL. This
+ * function call is the last time this pointer will be provided, so any
+ * resources to it should be cleaned up here.
*
* \param appstate an optional pointer, provided by the app in SDL_AppInit.
*