diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h index 6f214faac9..afb80df50f 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. + * 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. + * 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 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. *