mirror of
https://github.com/libsdl-org/SDL.git
synced 2025-05-29 16:09:13 +00:00
Sync SDL3 wiki -> header
This commit is contained in:
SDL Wiki Bot
parent
3348d0caaf
commit
3bd04e5a34
1 changed files with 71 additions and 66 deletions
|
|
@ -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.
|
||||
*
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue