Crate sdl3 

Getting started

extern crate sdl3;

use sdl3::pixels::Color;
use sdl3::event::Event;
use sdl3::keyboard::Keycode;
use std::time::Duration;

pub fn main() {
    let sdl_context = sdl3::init().unwrap();
    let video_subsystem = sdl_context.video().unwrap();

    let window = video_subsystem.window("rust-sdl3 demo", 800, 600)
        .position_centered()
        .build()
        .unwrap();

    let mut canvas = window.into_canvas();

    canvas.set_draw_color(Color::RGB(0, 255, 255));
    canvas.clear();
    canvas.present();
    let mut event_pump = sdl_context.event_pump().unwrap();
    let mut i = 0;
    'running: loop {
        i = (i + 1) % 255;
        canvas.set_draw_color(Color::RGB(i, 64, 255 - i));
        canvas.clear();
        for event in event_pump.poll_iter() {
            match event {
                Event::Quit {..} |
                Event::KeyDown { keycode: Some(Keycode::Escape), .. } => {
                    break 'running
                },
                _ => {}
            }
        }
        // The rest of the game loop goes here...

        canvas.present();
        ::std::thread::sleep(Duration::new(0, 1_000_000_000u32 / 60));
    }
}

Feature Flags

Linking to libsdl3

This crate requires the SDL3 library to link and run.

By default without any of these features enabled, it will try to link a system SDL3 library as a dynamic/shared library using the default library search paths.

If you don’t have libsdl3 installed on your system and just want it to work, we recommend using build-from-source. Also see the different build configurations that sdl3-sys provides: https://github.com/maia-s/sdl3-sys-rs/tree/main/sdl3-sys#usage

Name	Description
build-from-source	Fetch and build the library from source
build-from-source-static	Fetch and build the library from source and link it statically
build-from-source-unix-console	Build SDL3 from source but skip the X11/Wayland dependencies for console targets
use-pkg-config	Use pkg-config to find the library
use-vcpkg	Use vcpkg to find the library
static-link	Link the library statically
link-framework	Link the library as a framework on macOS

Optional Features

Note that since sdl3 is still in the progress of migrating to and integrating the new features of libsdl3, some features might be not yet, or only partially implemented.

Name	Description	Implementation Status
ash	Use Vulkan types from the ash crate	Implemented
unsafe_textures	Skip lifetime tracking for textures; you must manage destruction safety yourself	Implemented (unsafe opt-in)
gfx	Legacy SDL_gfx drawing helpers; blocked on an SDL3_gfx C library	Blocked
mixer	SDL_mixer bindings (needs upstream SDL3_mixer and sdl3-mixer-sys)	Blocked
image	Enable SDL_image helpers for loading/saving surfaces and textures	Implemented
ttf	Enable SDL_ttf font/text rendering APIs	Implemented
hidapi	Use SDL’s hidapi backend for sensors and controllers	Implemented
test-mode	Allows SDL to be initialised from a thread that is not the main thread	Implemented
raw-window-handle	Enables integrations with the wgpu crate	Implemented

Re-exports

pub extern crate libc;

pub extern crate sdl3_sys as sys;

Modules

audio

Audio Functions

clipboard

cpuinfo

dialog

event

Event Handling

filesystem

gamepad

gpu

haptic

Haptic Functions

hint

iostream

joystick

keyboard

log

messagebox

mouse

pen

pixels

properties

raw_window_handle

rect

Rectangles and points.

render

2D accelerated rendering

surface

timer

touch

url

Opening URLs in default system handlers

version

Querying SDL Version

video

Structs

AudioSubsystem

CameraSubsystem

Error

EventPump

A thread-safe type that encapsulates SDL event-pumping functions.

EventSubsystem

GamepadSubsystem

HapticSubsystem

JoystickSubsystem

Sdl

The SDL context type. Initialize with sdl3::init().

SensorSubsystem

VideoSubsystem

Enums

IntegerOrSdlError

A given integer was so big that its representation as a C integer would be negative.

Functions

clear_error

get_error

get_platform

Get platform name

init

Initializes the SDL library. This must be called before using any other SDL function.

set_error