eden-emu/SDL
15
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-05-28 15:39:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Sync SDL3 wiki -> header

Browse source
This commit is contained in:
SDL Wiki Bot 2024-05-03 13:32:31 +00:00
parent 3348d0caaf
commit 3bd04e5a34
1 changed files with 71 additions and 66 deletions
Download patch file Download diff file Expand all files Collapse all files

137
include/SDL3/SDL_main.h
View file

@ -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.
*