sdl3-rs

To use the SDL3 Rust bindings, add the sdl3 crate to your Cargo.toml dependencies. Note that the current version is in a migration phase, so some features may be missing or undergoing changes.

[dependencies]
sdl3 = { version = "0", features = [] }

You can view the high-level documentation for the sdl3 crate online at docs.rs. To generate and open the documentation locally for offline use, run the following command in your terminal:

cargo doc --package sdl3 --open

The Sensor API provides access to motion sensors (gyroscope and accelerometer) on compatible controllers like PlayStation, Switch, and Steam controllers.

Units

• Accelerometer: m/s²
• Gyroscope: radians per second

Axis Orientation (when holding the controller)

• X-axis: -x (left) to +x (right)
• Y-axis: -y (down) to +y (up)
• Z-axis: -z (forward) to +z (backward)

Rotations (anti-clockwise around axis)

• Pitch: -x to +x (pitch towards up)
• Yaw: -y to +y (yaw from right to left)
• Roll: -z to +z (roll from right to left)

To ensure thread-safe access to the mixer, use the lock() method. This returns a MixerLock RAII guard. The mixer is automatically unlocked when the guard is dropped.

{
    let _lock = mixer.lock();
    // Perform thread-sensitive mixer operations here
}
// _lock is dropped here, unlocking the mixer

A Track is the primary object used to play sounds on an SDL3 Mixer. Each track manages its own audio source, gain, looping, position, and effects. Multiple tracks can play simultaneously on the same mixer.

Note: A Track must not outlive its parent Mixer due to lifetime constraints.

// Conceptual usage pattern
let track = mixer.get_track();
track.set_audio(&audio_source)?;
track.play()?;

To use SDL3_mixer, you must first create a Mixer instance. You can either open a connection to the default audio device or a specific hardware device.

• Default Device: Use open_device() to let SDL choose the best format and use the default playback device.
• Specific Device: Use open_device_id(device_id, spec) to target a specific SDL_AudioDeviceID with a custom SDL_AudioSpec.
• Memory-only Mixer: Use create_memory(spec) to create a mixer that renders to a buffer instead of an audio device. This is useful for software rendering or testing.

// Open default device
let mixer = Mixer::open_device(None)?;

// Open specific device with custom spec
let mixer = Mixer::open_device_id(device_id, Some(&spec))?;

// Create a memory-only mixer for software rendering
let mixer = Mixer::create_memory(None)?;

To use SDL3, you must first initialize the library using sdl3::init(). This returns an Sdl context object. The Sdl object represents the main thread and is used to obtain access to various subsystems (audio, video, etc.).

Important Threading Rule: Sdl must be initialized on the main thread. If you attempt to initialize it from a different thread, it will return an error unless you enable the test-mode feature (intended for cargo test).

When the Sdl object is dropped, SDL_Quit() is automatically called, cleaning up the library.

let sdl_context = sdl3::init().unwrap();
// Use sdl_context to access subsystems...

To run the demo_games_02_woodeneye example from the repository, use the cargo run command with the --example flag.

cargo r --example demo_games_02_woodeneye

Not all SDL3 extension libraries are currently supported by sdl3-rs. Check the status of the library you need before proceeding with your implementation:

Suspends the current thread for the specified number of milliseconds.

Recommendation: It is recommended to use std::thread::sleep() instead of delay() for standard Rust development.

delay(16); // Sleep for approximately 1 frame at 60fps