devela::_dep::sdl3::sys::main

Function SDL_AppEvent

pub unsafe extern "C" fn SDL_AppEvent(
    appstate: *mut c_void,
    event: *mut SDL_Event,
) -> SDL_AppResult
Available on crate feature dep_sdl3 only.
Expand description

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.

This function is called as needed by SDL after SDL_AppInit returns SDL_APP_CONTINUE. 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. SDL itself will push events to the queue on the main thread.

Events sent to this function are not owned by the app; if you need to save the data, you should copy it.

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

§Parameters

  • appstate: an optional pointer, provided by the app in SDL_AppInit.
  • event: the new event for the app to examine.

§Return value

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_AppIterate() or SDL_AppQuit() for events not pushed from the main thread.

§Availability

This function is available since SDL 3.2.0.

§See also