Crate sdl3_sys

sdl3-sys: Low level Rust bindings for SDL 3

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

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

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.

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
  Message box support routines.
• metal
  Functions to creating Metal layers and views on SDL windows.
• misc
  SDL API functions that don’t fit elsewhere.
• mouse
  SDL mouse handling.
• mutex
  Functions to provide thread synchronization primitives.
• 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 thread management routines.
• time
  SDL realtime clock and date/time routines.
• timer
  SDL time management routines.
• touch
  SDL touch management.
• tray
  System tray menu support.
• 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.