NAME¶

SDL_AppIterate - App-implemented iteration entry point for SDL_MAIN_USE_CALLBACKS
apps.

HEADER FILE¶

Defined in SDL3/SDL_main.h

SYNOPSIS¶

#include "SDL3/SDL.h"

SDL_AppResult SDL_AppIterate(void *appstate);

DESCRIPTION¶

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.

FUNCTION PARAMETERS¶

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.

THREAD SAFETY¶

This function may get called concurrently with

SDL_AppEvent () for events not pushed on the main thread.

AVAILABILITY¶

This function is available since SDL 3.1.3.

SEE ALSO¶

•(3), SDL_AppInit(3), •(3), SDL_AppEvent(3)