Crate sys

Available on crate feature dep_sdl3 only.
Expand description

§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 version 3.2.4 and earlier.

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.

SDL_image is available via the sdl3-image-sys crate. 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.

FeatureDescription
use-pkg-configUse pkg-config to find and link the SDL 3 library.
use-vcpkgUse vcpkg to find and link the SDL 3 library.
build-from-sourceBuild 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-staticShortcut for enabling both the build-from-source and link-static features. This should no longer be necessary.
link-frameworkLink 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-staticLink 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.

FeatureDescription
sdl-unix-console-buildAllow 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

FeatureDescription
target-gdkEnable 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.

FeatureDescription
use-ash-v0-38Use Vulkan types from the ash crate (v0.38).
use-libc-v0-2Use 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-59Use Windows types from the windows-sys crate (v0.59).
use-x11-v2Use X11 types from the x11 crate (v2).
use-x11-dl-v2Use 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.

FeatureDescription
assert-level-disabled0: All SDL assertion macros are disabled.
assert-level-release1: Release settings: SDL_assert disabled, SDL_assert_release enabled.
assert-level-debug2: Debug settings: SDL_assert and SDL_assert_release enabled.
assert-level-paranoid3: Paranoid settings: All SDL assertion macros enabled, including SDL_assert_paranoid.

§Other features

FeatureDescription
debug-implsImplement the Debug trait for most SDL types.
nightlyEnable features that need the nightly compiler. This enables the VaList type, as well as enabling some intrinsics.

§Version history

  • 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

Modules§

assert
A helpful assertion macro!
asyncio
SDL offers a way to perform I/O asynchronously. This allows an app to read or write files without waiting for data to actually transfer; the functions that request I/O never block while the request is fulfilled.
atomic
Atomic operations.
audio
Audio functionality for the SDL library.
bits
Functions for fiddling with bits and bitmasks.
blendmode
Blend modes decide how two colors will mix together. There are both standard modes for basic needs and a means to create custom modes, dictating what sort of math to do on what color components.
camera
Video capture for the SDL library.
clipboard
SDL provides access to the system clipboard, both for reading information from other processes and publishing information of its own.
cpuinfo
CPU feature detection for SDL.
dialog
File dialog support.
error
Simple error message routines for SDL.
events
Event queue management.
everything
Reexports of everything from the other modules
ffi
Extra ffi types for sdl3-sys
filesystem
SDL offers an API for examining and manipulating the system’s filesystem. This covers most things one would need to do with directories, except for actual file I/O (which is covered by CategoryIOStream and CategoryAsyncIO instead).
gamepad
SDL provides a low-level joystick API, which just treats joysticks as an arbitrary pile of buttons, axes, and hat switches. If you’re planning to write your own control configuration screen, this can give you a lot of flexibility, but that’s a lot of work, and most things that we consider “joysticks” now are actually console-style gamepads. So SDL provides the gamepad API on top of the lower-level joystick functionality.
gpu
The GPU API offers a cross-platform way for apps to talk to modern graphics hardware. It offers both 3D graphics and compute support, in the style of Metal, Vulkan, and Direct3D 12.
guid
A GUID is a 128-bit value that represents something that is uniquely identifiable by this value: “globally unique.”
haptic
The SDL haptic subsystem manages haptic (force feedback) devices.
hidapi
Header file for SDL HIDAPI functions.
hints
This file contains functions to set and get configuration hints, as well as listing each of them alphabetically.
init
All SDL programs need to initialize the library before starting to work with it.
iostream
SDL provides an abstract interface for reading and writing data streams. It offers implementations for files, memory, etc, and the app can provide their own implementations, too.
joystick
SDL joystick support.
keyboard
SDL keyboard management.
keycode
Defines constants which identify keyboard keys and modifiers.
loadso
System-dependent library loading routines.
locale
SDL locale services.
log
Simple log messages with priorities and categories. A message’s SDL_LogPriority signifies how important the message is. A message’s SDL_LogCategory signifies from what domain it belongs to. Every category has a minimum priority specified: when a message belongs to that category, it will only be sent out if it has that minimum priority or higher.
main
Redefine main() if necessary so that it is called by SDL.
messagebox
SDL offers a simple message box API, which is useful for simple alerts, such as informing the user when something fatal happens at startup without the need to build a UI for it (or informing the user before your UI is ready).
metal
Functions to creating Metal layers and views on SDL windows.
misc
SDL API functions that don’t fit elsewhere.
mouse
Any GUI application has to deal with the mouse, and SDL provides functions to manage mouse input and the displayed cursor.
mutex
SDL offers several thread synchronization primitives. This document can’t cover the complicated topic of thread safety, but reading up on what each of these primitives are, why they are useful, and how to correctly use them is vital to writing correct and safe multithreaded programs.
pen
SDL pen event handling.
pixels
SDL offers facilities for pixel management.
platform
SDL provides a means to identify the app’s platform, both at compile time and runtime.
power
SDL power management routines.
process
Process control support.
properties
A property is a variable that can be created and retrieved by name at runtime.
rect
Some helper functions for managing rectangles and 2D points, in both integer and floating point versions.
render
Header file for SDL 2D rendering functions.
revision
scancode
Defines keyboard scancodes.
sensor
SDL sensor management.
stdinc
SDL provides its own implementation of some of the most important C runtime functions.
storage
The storage API is a high-level API designed to abstract away the portability issues that come up when using something lower-level (in SDL’s case, this sits on top of the Filesystem and IOStream subsystems). It is significantly more restrictive than a typical filesystem API, for a number of reasons:
surface
SDL surfaces are buffers of pixels in system RAM. These are useful for passing around and manipulating images that are not stored in GPU memory.
system
Platform-specific SDL API functions. These are functions that deal with needs of specific operating systems, that didn’t make sense to offer as platform-independent, generic APIs.
thread
SDL offers cross-platform thread management functions. These are mostly concerned with starting threads, setting their priority, and dealing with their termination.
time
SDL realtime clock and date/time routines.
timer
SDL provides time management functionality. It is useful for dealing with (usually) small durations of time.
touch
SDL offers touch input, on platforms that support it. It can manage multiple touch devices and track multiple fingers on those devices.
tray
SDL offers a way to add items to the “system tray” (more correctly called the “notification area” on Windows). On platforms that offer this concept, an SDL app can add a tray icon, submenus, checkboxes, and clickable entries, and register a callback that is fired when the user clicks on these pieces.
version
Functionality to query the current SDL version, both as headers the app was compiled against, and a library the app is linked to.
video
SDL’s video subsystem is largely interested in abstracting window management from the underlying operating system. You can create windows, manage them in various ways, set them fullscreen, and get events when interesting things happen with them, such as the mouse or keyboard interacting with a window.
vulkan
Functions for creating Vulkan surfaces on SDL windows.

Functions§

breakpoint
You can set a breakpoint on this function to break into the debugger when asserts want to trigger a breakpoint.