(This is the documentation for SDL3, which is the current stable version. SDL2 was the previous version!)

SDL_AppIterate

App-implemented iteration entry point for SDL_MAIN_USE_CALLBACKS apps.

Header File

Syntax

SDL_AppResult SDL_AppIterate(void *appstate);

Function Parameters

void *

appstate

an optional pointer, provided by the app in SDL_AppInit.

Return Value

(SDL_AppResult) Returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to terminate with success, SDL_APP_CONTINUE to continue.

Remarks

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.

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.

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 SDL_APP_CONTINUE, 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 SDL_APP_FAILURE, SDL will call SDL_AppQuit and terminate the process with an exit code that reports an error to the platform. If it returns SDL_APP_SUCCESS, SDL calls SDL_AppQuit and terminates with an exit code that reports success to the platform.

This function is called by SDL on the main thread.

Thread Safety

This function may get called concurrently with SDL_AppEvent() for events not pushed on the main thread.

Version

This function is available since SDL 3.1.3.