Crate sdl3_main 

sdl3-main

This crate provides tools for using SDL 3’s main and callback APIs, and for interfacing with the main thread of the process.

SDL main

To provide your own main but call it through SDL, use the main attribute macro. See the documentation for that for more information.

Callback API

To use the SDL callback API, you can use either the app_impl attribute macro, or all four of the app_init, app_iterate, app_event and app_quit attribute macros. Don’t use the main attribute macro in this mode. See the documentation for more information.

Main thread helpers

Some SDL functions have to be called on the main thread of the process. This crate provides some helper types and functions to alleviate this.

• MainThreadToken: Zero-sized token that can only exist on the main thread.
• MainThreadData: Wrapper for data that can move between threads but that should only be accessed on the main thread.
• run_sync_on_main_thread(): Run a callback on the main thread, synchronously.
• run_async_on_main_thread(): Run a callback on the main thread, asynchronously.

Features

Feature	Description
alloc	Enable features that require allocation (enabled by default)
std	Enable features that require the standard library (enabled by default)
nightly	Enable the ? operator to convert Result::Err and Option::None to AppResult*::Failure
use-parking-lot-v0-12	Support parking_lot 0.12 locks in app state accessors

Recent changes

• 0.6.1:

  • Make MainThreadToken::init() safe
  • Fix undefined reference to main_with_result when using the main macro in some cases

• 0.6.0:

  • Update sdl3-sys to 0.6.0
  • MainThreadToken::init() is no longer necessary in most cases
  • Pass arguments to main on std (!std already did)
  • Add MainThreadData::assert_new/get/get_mut
  • Log error when converting to AppResult*
  • MSRV 1.85

See ChangeLog.md for older changes

Modules

app

state

Structs

MainThreadData

Data that can only be accessed from the main thread. Accessors take a MainThreadToken.

MainThreadToken

Zero sized token that can only exist on the main thread.

Enums

AppResult

This is the Rust enum equivalent to SDL_AppResult.

AppResultWithState

An AppResult with an app state, for returning from the function tagged with app_init.

Traits

IntoAppResult

This trait is used for converting a type into an SDL_AppResult or AppResult.

Functions

run_async_on_main_thread

Schedule a callback to run on the main thread and immediately return without waiting for it.

run_sync_on_main_thread

Run a callback on the main thread and wait for it to complete before returning.

Attribute Macros

app_event

The function tagged with app_event is called by SDL when an event is delivered. This may get called on the main thread or on another thread.

app_impl

This attribute macro can be applied to an impl block for a type to assign the associated functions or methods named app_init, app_iterate, app_event and app_quit to the respective sdl main callbacks, as if the corresponding attribute macros were used. All four must be defined in a single impl block, but app_quit is optional and will be defined as an empty function if omitted.

app_init

The function tagged with app_init is called by SDL at the start of the program on the main thread.

app_iterate

The function tagged with app_iterate is called continuously by SDL on the main thread while the app is running.

app_quit

The function tagged with app_quit is called by SDL on the main thread when the app quits.

main

Use this attribute macro if you want to provide your own main, but run it through SDL.