Lib.rs

› Game dev
#sdl #env-var #bit-flags #windowing #gamedev #graphics #multimedia

sys no-std sdl3-sys

Low level Rust bindings for SDL 3

by Maia and 2 contributors. Co-owned by Lokathor.

24 releases (4 breaking)

new 0.4.8+SDL3-3.2.12 May 5, 2025
0.4.6+SDL3-3.2.8 Mar 5, 2025
0.1.3+SDL3-preview-3.1.6 Nov 20, 2024
0.0.7+sdl3-dev-2023-10-08 Oct 9, 2023
0.0.1+sdl3-dev-2023-01-23 Jan 23, 2023

#163 in Game dev

Download history 429/week @ 2025-01-14 711/week @ 2025-01-21 712/week @ 2025-01-28 847/week @ 2025-02-04 418/week @ 2025-02-11 448/week @ 2025-02-18 596/week @ 2025-02-25 889/week @ 2025-03-04 595/week @ 2025-03-11 520/week @ 2025-03-18 485/week @ 2025-03-25 565/week @ 2025-04-01 429/week @ 2025-04-08 528/week @ 2025-04-15 499/week @ 2025-04-22 445/week @ 2025-04-29

1,968 downloads per month
Used in 11 crates (5 directly)

Zlib license

3MB
23K SLoC

Rust 16K SLoC // 0.0% comments C 6K SLoC // 0.1% comments Objective-C 498 SLoC // 0.1% comments Visual Studio Project 251 SLoC C++ 123 SLoC // 0.1% comments Perl 113 SLoC // 0.1% comments Python 102 SLoC // 0.1% comments Java 101 SLoC // 0.2% comments Visual Studio Solution 18 SLoC Shell 16 SLoC // 0.1% comments Metal Shading Language 8 SLoC HLSL 6 SLoC M4 6 SLoC // 0.4% comments Automake 4 SLoC Batch 3 SLoC GLSL 1 SLoC C# 1 SLoC Prolog 1 SLoC

sdl3-sys: Low level Rust bindings for SDL 3

These are low level Rust bindings for SDL, the Simple DirectMedia Layer. This version of sdl3-sys has bindings for SDL versions 3.2.0 to 3.2.12, inclusive.

Many types can be initialized to all zero with the Default trait for convenience. However, many of these aren't valid when passed to SDL without further modification. They're intended to be used with ..Default::default() in initializers. The Default impl of interface types also sets the version field to the correct value.

Add-on crates:

Other satellite libraries aren't stable yet, but will be released as they're available.

Most of the docs are generated directly from the C headers and document how SDL works in C. Using it from Rust might work differently in some cases. For example, macros in C are usually translated to constants or constant functions in Rust. Documentation specific to these Rust bindings are tagged with sdl3-sys.

Browse the API at docs.rs!

If you're looking for more idiomatic or higher level bindings, check out the sdl3 crate.

Usage

sdl3-sys requires SDL version 3.1.3 or later, but 3.2.0 or later is preferred. Some APIs may require a later version. You can check availability in the documentation.

By default, sdl3-sys will attempt to link to a dynamic/shared library named SDL3 in the default library search path, using the usual platform specific naming convention for libraries. You can change this behaviour with the following feature flags.

Feature Description
use-pkg-config Use pkg-config to find and link the SDL 3 library.
use-vcpkg Use vcpkg to find and link the SDL 3 library.
build-from-source Build and link SDL 3 from source. You have to install any dependencies SDL needs to build for your target first. See below for build related features.
build-from-source-static Shortcut for enabling both the build-from-source and link-static features. This should no longer be necessary.
link-framework Link to a framework on Apple targets. This currently requires SDL3.xcframework to be located at ~/Library/Frameworks or /Library/Frameworks. The built executable has to be put in a signed app bundle to be able to run.
link-static Link SDL statically. SDL doesn't recommend doing this.
  • On targets that only support static linking, such as emscripten, you don't have to enable this feature.
  • On Apple targets, this currently requires frameworks that should be optional.
no-link Don't link anything, and provide linking flags via Cargo metadata so you can do manual linking if desired.

Building from source

When building from source with the build-from-source feature flag, you can enable these additional features to configure the build. These have no effect when not building from source.

Feature Description
sdl-unix-console-build Allow building SDL without X11 or Wayland support on Linux and other targets that usually use X11/Wayland. By default, SDL requires either X11 or Wayland on these targets as a sanity check.

Target specific features

Feature Description
target-gdk Enable APIs that require Microsoft's Game Development Kit (GDK). (This is not related to Gnome's GDK.)

Optional integrations

sdl3-sys can use definitions from other crates for some foreign types that it needs, e.g. for Vulkan types. By default it'll use opaque structs or pointers to opaque structs for these types unless otherwise specified.

Feature Description
use-ash-v0-38 Use Vulkan types from the ash crate (v0.38).
use-libc-v0-2 Use wchar_t type from the libc crate (v0.2). By default sdl3-sys will alias wchar_t to u16 on Windows and u32 otherwise.
use-windows-sys-v0-59 Use Windows types from the windows-sys crate (v0.59).
use-x11-v2 Use X11 types from the x11 crate (v2).
use-x11-dl-v2 Use X11 types from the x11-dl crate (v2).

Assert level

You can set the default assertion level for SDL using the assert-level-* features. This affects the assert macros in the assert module and the value of the SDL_ASSERT_LEVEL constant.

If no assert-level-* features are enabled, assert-level-debug will be enabled by default for debug builds, and assert-level-release otherwise.

These features are mutually exclusive. Features higher in this list override later ones.

Feature Description
assert-level-disabled 0: All SDL assertion macros are disabled.
assert-level-release 1: Release settings: SDL_assert disabled, SDL_assert_release enabled.
assert-level-debug 2: Debug settings: SDL_assert and SDL_assert_release enabled.
assert-level-paranoid 3: Paranoid settings: All SDL assertion macros enabled, including SDL_assert_paranoid.

Other features

Feature Description
debug-impls Implement the Debug trait for most SDL types.
nightly Enable features that need the nightly compiler. This enables the VaList type, as well as enabling some intrinsics.

Recent changes

  • 0.4.8:
    • Update SDL to 3.2.12
    • Add no-link feature
    • On Apple targets, look for frameworks in ~/Library/Frameworks too
  • 0.4.7:
    • Update SDL to 3.2.10
    • Derive PartialEq/Eq/Hash traits for applicable types
  • 0.4.6: Update SDL to 3.2.8
  • 0.4.5: Update SDL to 3.2.6
  • 0.4.4: Update SDL to 3.2.4
  • 0.4.3: Update SDL to 3.2.2
  • 0.4.2: Add homebrew to library search path on macos (fix for Apple Silicon)
  • 0.4.1: Fix linking on Fedora and other Linux distros that use lib64
  • 0.4.0: First stable release of SDL 3

Dependencies

~0–11MB
~87K SLoC