Lib.rs

› Rendering | Game dev
#sdl #graphics #windowing

sys no-std sdl3-sys

Low level Rust bindings for SDL 3

by Maia Co-owned by Lokathor.

12 releases

0.1.3+SDL3-preview-3.1.6 Nov 20, 2024
0.0.10+SDL-preview-3.1.3 Oct 11, 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

#48 in Rendering

Download history 8/week @ 2024-08-30 153/week @ 2024-09-06 46/week @ 2024-09-13 30/week @ 2024-09-20 68/week @ 2024-09-27 32/week @ 2024-10-04 328/week @ 2024-10-11 316/week @ 2024-10-18 64/week @ 2024-10-25 399/week @ 2024-11-01 106/week @ 2024-11-08 160/week @ 2024-11-15 125/week @ 2024-11-22 239/week @ 2024-11-29 406/week @ 2024-12-06 186/week @ 2024-12-13

1,007 downloads per month
Used in 5 crates (2 directly)

Zlib license

2.5MB
24K SLoC

Rust 15K SLoC // 0.0% comments C 7.5K SLoC // 0.1% comments Objective-C 475 SLoC // 0.1% comments Visual Studio Project 246 SLoC C++ 145 SLoC // 0.2% comments Perl 104 SLoC // 0.1% comments Python 104 SLoC // 0.1% comments Java 102 SLoC // 0.1% comments Shell 18 SLoC // 0.1% comments Visual Studio Solution 18 SLoC Metal Shading Language 9 SLoC HLSL 7 SLoC M4 6 SLoC // 0.4% comments Automake 4 SLoC Batch 3 SLoC GLSL 2 SLoC JavaScript 1 SLoC Prolog 1 SLoC C# 1 SLoC Lua 1 SLoC

sdl3-sys: Low level Rust bindings for SDL 3

This version of sdl3-sys has bindings for SDL version 3.1.6-preview 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!

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
  • Some less common targets are missing detection or features to enable corresponding SDL features

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

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 that is only available in nightly, as well as enabling some intrinsics.

Dependencies

~0–9MB
~89K SLoC