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.

This macro must be called at the root of main.rs in your crate.

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.

These macros must be called at the root of main.rs in your crate. In the case of app_impl, the impl block for that must be at the root of main.rs, but the rest of the app struct and other impl blocks can be defined elsewhere.

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

  • Support renamed or relocated sdl3_main crate when calling attribute macros. Pass sdl3_main = ::path::to::sdl3_main as an argument to the macro, e.g. #[::path::to::sdl3_main::app_impl(sdl3_main = ::path::to::sdl3_main)]

• 0.6.3:

  • Implement IntoAppResult for bool and Option<bool> so that these can be returned from app_iterate and app_event. For bool, true translates to Continue and false translates to Success. For Option<bool>, Some translates as for bool, and None translates to Failure.

• 0.6.2:

  • Fix using app_* macros with app states that have generic arguments (all generics have to be known)

• 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. This macro must be called at the root of main.rs in your crate.

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. The impl block must be at the root of main.rs in your crate, but the rest of the struct and other impl blocks can be defined elsewhere.

app_init

The function tagged with app_init is called by SDL at the start of the program on the main thread. This macro must be called at the root of main.rs in your crate.

app_iterate

The function tagged with app_iterate is called continuously by SDL on the main thread while the app is running. This macro must be called at the root of main.rs in your crate.

app_quit

The function tagged with app_quit is called by SDL on the main thread when the app quits. This macro must be called at the root of main.rs in your crate.

main

Use this attribute macro if you want to provide your own main, but run it through SDL. This macro must be called at the root of main.rs in your crate.