Lib.rs

› Rendering | Game dev | Multimedia
#sdl

sys no-std sdl3-sys

Low level Rust bindings for SDL 3

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

15 unstable releases (3 breaking)

new 0.3.0+SDL3-prerelease-3… Jan 16, 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.5+sdl3-dev-2023-06-04 Jun 5, 2023
0.0.1+sdl3-dev-2023-01-23 Jan 23, 2023

#39 in Rendering

Download history 75/week @ 2024-09-28 102/week @ 2024-10-05 260/week @ 2024-10-12 321/week @ 2024-10-19 57/week @ 2024-10-26 427/week @ 2024-11-02 75/week @ 2024-11-09 175/week @ 2024-11-16 159/week @ 2024-11-23 223/week @ 2024-11-30 401/week @ 2024-12-07 253/week @ 2024-12-14 84/week @ 2024-12-21 62/week @ 2024-12-28 273/week @ 2025-01-04 342/week @ 2025-01-11

835 downloads per month
Used in 5 crates (2 directly)

Zlib license

3MB
23K SLoC

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

sdl3-sys: Low level Rust bindings for SDL 3

This version of sdl3-sys has bindings for SDL version 3.1.10-prerelease and earlier.

SDL 3 is ABI stable as of the 3.1.3 preview release, but sdl3-sys is new and may have bugs. Please submit an issue at github if you have any issues or comments!

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.

Known issues:

  • Satellite libraries (mixer, image, ttf) aren't available yet
  • There are no tests yet, except for static asserts translated from the original headers

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-preview or later. Some APIs may require a later version. You can check availability in the documentation. Starting with version 3.1.3-preview, all later releases of SDL 3 are ABI compatible with earlier ones.

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

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.

Dependencies

~0–9MB
~90K SLoC