eden-emu/SDL
20
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

main: Add an optional appstate param to main callback entry points.

Browse source 
This allows apps to maintain state data without using global variables.

Fixes #9377.
This commit is contained in:
Ryan C. Gordon 2024-03-27 17:22:08 -04:00
parent a9dbdb1947
commit 38e3c6a4aa
No known key found for this signature in database
GPG key ID: FA148B892AB48044
7 changed files with 57 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

39
include/SDL3/SDL_main.h
View file

@ -158,10 +158,10 @@
extern "C" {
#endif
typedef int (SDLCALL *SDL_AppInit_func)(int argc, char *argv[]);
typedef int (SDLCALL *SDL_AppIterate_func)(void);
typedef int (SDLCALL *SDL_AppEvent_func)(const SDL_Event *event);
typedef void (SDLCALL *SDL_AppQuit_func)(void);
typedef int (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]);
typedef int (SDLCALL *SDL_AppIterate_func)(void *appstate);
typedef int (SDLCALL *SDL_AppEvent_func)(void *appstate, const SDL_Event *event);
typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate);
/**
* You can (optionally!) define SDL_MAIN_USE_CALLBACKS before including
@ -203,6 +203,12 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void);
* 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
@ -210,6 +216,7 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void);
* 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.
@ -222,7 +229,7 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void);
* \sa SDL_AppEvent
* \sa SDL_AppQuit
*/
extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(int argc, char *argv[]);
extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(void **appstate, int argc, char *argv[]);
/**
* App-implemented iteration entry point for SDL_MAIN_USE_CALLBACKS apps.
@ -248,6 +255,9 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(int argc, char *argv[]);
* This function should not go into an infinite mainloop; it should do one
* iteration of whatever the program does 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
@ -255,6 +265,7 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(int argc, char *argv[]);
* 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.
*
* \threadsafety This function is not thread safe.
@ -264,7 +275,7 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(int argc, char *argv[]);
* \sa SDL_AppInit
* \sa SDL_AppEvent
*/
extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppIterate(void);
extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppIterate(void *appstate);
/**
* App-implemented event entry point for SDL_MAIN_USE_CALLBACKS apps.
@ -293,6 +304,9 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppIterate(void);
* 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
@ -300,6 +314,8 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppIterate(void);
* 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.
*
* \threadsafety This function is not thread safe.
@ -309,7 +325,7 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppIterate(void);
* \sa SDL_AppInit
* \sa SDL_AppIterate
*/
extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppEvent(const SDL_Event *event);
extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppEvent(void *appstate, const SDL_Event *event);
/**
* App-implemented deinit entry point for SDL_MAIN_USE_CALLBACKS apps.
@ -330,13 +346,20 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppEvent(const SDL_Event *event);
* 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.
*
* \param appstate an optional pointer, provided by the app in SDL_AppInit.
*
* \threadsafety This function is not thread safe.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_AppInit
*/
extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void);
extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate);
#endif /* SDL_MAIN_USE_CALLBACKS */