Bindings for SDL2 in Rust
Rust-SDL2 is a library for talking to the new SDL2.0 libraries from Rust. Low-level C components are wrapped in Rust code to make them more idiomatic and abstract away inappropriate manual memory management.
Rust-SDL2 uses the MIT license.
If you want a library compatible with earlier versions of SDL, please see here
- crates.io documentation, with no features at all.
- master documentation with the following features:
- gfx
- image
- mixer
- ttf
We currently target the latest stable release of Rust.
SDL2 >= 2.0.8 is recommended to use these bindings, but note that SDL2 >= 2.0.5 is also supported. Below 2.0.5, you may experience link-time errors as some functions are used here but are not defined in SDL2. If you experience this issue because you are on a LTS machine (for instance, Ubuntu 12.04 or Ubuntu 14.04), we definitely recommend you to use the feature "bundled" which will compile the lastest stable version of SDL2 for your project.
Since 0.31, this crate supports a feature named "bundled" which downloads SDL2 from source, compiles it and links it automatically. While this should work for any architecture, you will need a C compiler (like gcc, clang, or MS's own compiler) to use this feature properly.
Install these through your favourite package management tool, or via http://www.libsdl.org/
Ubuntu example:
sudo apt-get install libsdl2-dev
Fedora example:
sudo dnf install SDL2-devel
Arch example:
(Arch doesn't have separate regular and development packages, everything goes together.)
sudo pacman -S sdl2
You might also need a C compiler (gcc).
On OSX, it's a good idea to install these via homebrew.
brew install sdl2
Then add the following to your ~/.bash_profile if not already present.
export LIBRARY_PATH="$LIBRARY_PATH:/usr/local/lib"
You can also get sdl2 via macports.
sudo port install libsdl2
Then add the following to your ~/.bash_profile if not already present.
export LIBRARY_PATH="$LIBRARY_PATH:/opt/local/lib/"
If you're having issues with either homebrew or macports, see here.
You can download and install the SDL2 Mac OS X framework from: https://www.libsdl.org/download-2.0.php
To make the sdl2 crate link with the SDL2 framework, you will need to enable
the use_mac_framework feature. To build and test the sdl2 crate with this
feature, use:
cargo test --features use_mac_framework
To depend on the sdl2 crate with this feature enabled, put the following in
your project's Cargo.toml file:
[dependencies.sdl2]
features = ["use_mac_framework"]
version = ... # Whichever version you are usingAlternatively, you can re-export the feature in your package by putting the
following in your Cargo.toml file:
[features]
default = []
use_sdl2_mac_framework = ["sdl2/use_mac_framework"]- Download mingw and msvc development libraries from http://www.libsdl.org/ (SDL2-devel-2.0.x-mingw.tar.gz & SDL2-devel-2.0.x-VC.zip).
- Unpack to folders of your choosing (You can delete it afterwards).
- Create the following folder structure in the same folder as your Cargo.toml:
gnu-mingw\dll\32
gnu-mingw\dll\64
gnu-mingw\lib\32
gnu-mingw\lib\64
msvc\dll\32
msvc\dll\64
msvc\lib\32
msvc\lib\64
- Copy the lib and dll files from the source archive to the directories we created in step 3 like so:
SDL2-devel-2.0.x-mingw.tar.gz\SDL2-2.0.x\i686-w64-mingw32\bin -> gnu-mingw\dll\32
SDL2-devel-2.0.x-mingw.tar.gz\SDL2-2.0.x\x86_64-w64-mingw32\bin -> gnu-mingw\dll\64
SDL2-devel-2.0.x-mingw.tar.gz\SDL2-2.0.x\i686-w64-mingw32\lib -> gnu-mingw\lib\32
SDL2-devel-2.0.x-mingw.tar.gz\SDL2-2.0.x\x86_64-w64-mingw32\lib -> gnu-mingw\lib\64
SDL2-devel-2.0.8-VC.zip\SDL2-2.0.x\lib\x86\*.dll -> msvc\dll\32
SDL2-devel-2.0.8-VC.zip\SDL2-2.0.x\lib\x64\*.dll -> msvc\dll\64
SDL2-devel-2.0.8-VC.zip\SDL2-2.0.x\lib\x86\*.lib -> msvc\lib\32
SDL2-devel-2.0.8-VC.zip\SDL2-2.0.x\lib\x64\*.lib -> msvc\lib\64
- Create a build script, if you don't already have one put this in your Cargo.toml under
[package]:
build = "build.rs"
- Create a file in the same directory as Cargo.toml called build.rs (if you didn't already have a build script) and paste this into it:
use std::env;
use std::path::PathBuf;
fn main() {
let target = env::var("TARGET").unwrap();
if target.contains("pc-windows") {
let manifest_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
let mut lib_dir = manifest_dir.clone();
let mut dll_dir = manifest_dir.clone();
if target.contains("msvc") {
lib_dir.push("msvc");
dll_dir.push("msvc");
}
else {
lib_dir.push("gnu-mingw");
dll_dir.push("gnu-mingw");
}
lib_dir.push("lib");
dll_dir.push("dll");
if target.contains("x86_64") {
lib_dir.push("64");
dll_dir.push("64");
}
else {
lib_dir.push("32");
dll_dir.push("32");
}
println!("cargo:rustc-link-search=all={}", lib_dir.display());
for entry in std::fs::read_dir(dll_dir).expect("Can't read DLL dir") {
let entry_path = entry.expect("Invalid fs entry").path();
let file_name_result = entry_path.file_name();
let mut new_file_path = manifest_dir.clone();
if let Some(file_name) = file_name_result {
let file_name = file_name.to_str().unwrap();
if file_name.ends_with(".dll") {
new_file_path.push(file_name);
std::fs::copy(&entry_path, new_file_path.as_path()).expect("Can't copy from DLL dir");
}
}
}
}
}- On build the build script will copy the needed DLLs into the same directory as your Cargo.toml, you probably don't want to commit these to any Git repositories though so add the following line to your .gitignore file
/*.dll
- When you're publish your game make sure to copy the corresponding SDL2.dll to the same directory that your compiled exe is in, otherwise the game won't launch.
And now your project should build and run on any Windows computer!
-
Download mingw development libraries from http://www.libsdl.org/ (SDL2-devel-2.0.x-mingw.tar.gz).
-
Unpack to a folder of your choosing (You can delete it afterwards).
-
Copy all lib files from
SDL2-devel-2.0.x-mingw\SDL2-2.0.x\x86_64-w64-mingw32\lib
to (for Rust 1.6 and above)
C:\Program Files\Rust\lib\rustlib\x86_64-pc-windows-gnu\lib
or to (for Rust versions 1.5 and below)
C:\Program Files\Rust\bin\rustlib\x86_64-pc-windows-gnu\lib
or to your library folder of choice, and ensure you have a system environment variable of
LIBRARY_PATH = C:\your\rust\library\folder
For Rustup users, this folder will be in
C:\Users\{Your Username}\.rustup\toolchains\{current toolchain}\lib\rustlib\{current toolchain}\lib
Where current toolchain is likely stable-x86_64-pc-windows-gnu.
-
Copy SDL2.dll from
SDL2-devel-2.0.x-mingw\SDL2-2.0.x\x86_64-w64-mingw32\bin
into your cargo project, right next to your Cargo.toml.
-
When you're shipping your game make sure to copy SDL2.dll to the same directory that your compiled exe is in, otherwise the game won't launch.
If you want to use the static-link feature with the windows-gnu toolchain, then you will also need the following libraries:
libimm32.a
libversion.a
libdinput8.a
libdxguid.a
These files are not currently included with the windows-gnu toolchain, but can be downloaded here. For the x86_64 toolchain, you want the x86_64-win32-seh package, and for i686 you want the i686-win32-dwarf one.
You will find the aforementioned libraries under mingw64/x86_64-w64-mingw32/lib/ (for x86_64) or mingw32/i686-w64-mingw32/lib/ (for i686). Copy them to your toolchain's lib directory (the same one you copied the SDL .a files to).
- Install MS build tools and vcpkg
- Install the needed SDL2 libs:
vcpkg.exe install sdl2-ttf:x64-windows sdl2:x64-windows - Open a x64 native tools prompt (x64 Native Tools Command Prompt for VS 2019)
- set env vars:
SET PATH=%PATH%;C:\Users\my_user\dev\vcpkg\installed\x64-windows\bin
SET INCLUDE=%INCLUDE%;C:\Users\my_user\dev\vcpkg\installed\x64-windows\include
SET LIB=%LIB%;C:\Users\my_user\dev\vcpkg\installed\x64-windows\lib
cargo build
-
Download MSVC development libraries from http://www.libsdl.org/ (SDL2-devel-2.0.x-VC.zip).
-
Unpack SDL2-devel-2.0.x-VC.zip to a folder of your choosing (You can delete it afterwards).
-
Copy all lib files from
SDL2-devel-2.0.x-VC\SDL2-2.0.x\lib\x64\
to (for Rust 1.6 and above)
C:\Program Files\Rust\lib\rustlib\x86_64-pc-windows-msvc\lib
or to (for Rust versions 1.5 and below)
C:\Program Files\Rust\bin\rustlib\x86_64-pc-windows-msvc\lib
or to your library folder of choice, and ensure you have a system environment variable of
LIB = C:\your\rust\library\folder
For Rustup users, this folder will be in
C:\Users\{Your Username}\.rustup\toolchains\{current toolchain}\lib\rustlib\{current toolchain}\lib
Where current toolchain is likely stable-x86_64-pc-windows-msvc.
-
Copy SDL2.dll from
SDL2-devel-2.0.x-VC\SDL2-2.0.x\lib\x64\
into your cargo project, right next to your Cargo.toml.
-
When you're shipping your game make sure to copy SDL2.dll to the same directory that your compiled exe is in, otherwise the game won't launch.
The MSVC development libraries provided by http://libsdl.org/ don't include a static library. This means that if you want to use the static-link feature with the windows-msvc toolchain, you have to either
- build an SDL2 static library yourself and copy it to your toolchain's
libdirectory; or - also enable the
bundledfeature, which will build a static library for you.
If you're using cargo to manage your project, you can download through Crates.io:
[dependencies]
sdl2 = "0.33"Alternatively, pull it from GitHub to obtain the latest version from master
[dependencies.sdl2]
git = "https://github.com/AngryLawyer/rust-sdl2"Otherwise, clone this repo and run cargo
cargo build
You can enable features such as ttf, image, gfx and mixer by adding this instead:
[dependencies.sdl2]
version = "0.33"
default-features = false
features = ["ttf","image","gfx","mixer"]Those features need their respective libraries, which can be found at these locations : (the install process is the same as SDL2)
As of now, sdl2_net is meaningless compared to what other crates
such as serde and bincode can offer.
We highly recommend using those to develop anything UDP or TCP
related (along with futures or TCP/UDP from the standard library).
If you still want an implementation of sdl2_net, you can try to add it in this repo as a feature via a Pull Request. A somewhat outdated version of this binding can be found here
We have several simple example projects included:
cargo run --example demo
You can see the full list in the examples/ folder. Some examples require some features, you can enable them like so:
cargo run --example gfx-demo --features "gfx"
Replace "gfx" by the feature(s) needed for the example you want.
In the sdl2::render module, Texture has by default lifetimes to prevent it from out-living its parent TextureCreator.
These lifetimes are sometimes too hard to deal with in Rust, and so you have the option to enable the unsafe_textures feature.
This removes the lifetimes on the Textures, at the cost of optional manual memory management. If you want to manually destroy
the Textures you use, you can call the destroy method of your Textures, but beware that it should not be called if none of
the parents (Canvas or TextureCreator) are alive. If you do not call this method, the memory will simply be freed when
the last Canvas or the last TextureCreator will be freed.
There is no online documentation for this feature, however you can build it yourself in your project by enabling the feature in your
Cargo.toml, running cargo doc and accessing target/doc/sdl2/index.html via a browser.
The sdl2-sys that was generated for this crate is very generic and can be used on a lot of platforms with very few limitations. However, you may sometimes face trouble when using platform-specific features of SDL2, for instance the WindowManager category.
The feature "use-bindgen" allows you to avoid this limitation by generating the proper bindings depending on your target. It will take
the headers based on what pkg-config outputs (if you enabled the feature "use-pkg-config") and generate bindings based on them.
If you don't have pkg-config or disabled the feature, it will try to get the headers in SDL-2.0.8/include of this crate instead.
If somehow you have your own headers that you want to use (use a beta version, an older version, ...), you can set the environment variable "SDL2_INCLUDE_PATH" and those headers will be used by bindgen instead.
If you are creating a *-sys crate for a library which requires SDL2, you can use sdl2-sys to provide both the compiled library
and the headers for SDL2.
Follow the following process to get the header directory. In the Cargo.toml for your crate, add sdl2-sys as a dependency (not a build-dependency).
Cargo will then provide your build script with an environment variable DEP_SDL2_INCLUDE which is populated with the include directory for SDL2.
If there is more than one directory, they are combined with : as a separator. Pass these directories to whatever is building your C/C++.
Once everything is linked together, there will be a single copy of SDL2 (the one provided by sdl2-sys) for all C, C++, and Rust code.
For more discussion see the corresponding issue
If you want to use OpenGL, you also need the gl-rs package. If you're using cargo, just add these lines to your Cargo.toml:
[dependencies.gl]
git = "https://github.com/bjz/gl-rs"You have two options to use OpenGL with sdl2:
- Use OpenGL with Canvas and use sdl2::render
- Use OpenGL directly on the Window "shell" and use manual OpenGL calls to render something
First, find the OpenGL driver from SDL:
fn find_sdl_gl_driver() -> Option<u32> {
for (index, item) in sdl2::render::drivers().enumerate() {
if item.name == "opengl" {
return Some(index as u32);
}
}
None
}This is especially relevant on non-linux systems where the default render engine will something else (for instance DirectX on Windows).
Next, initialize the SDL2 subsystems, and create your window with the OpenGL canvas:
let sdl_context = sdl2::init().unwrap();
let video_subsystem = sdl_context.video().unwrap();
let window = video_subsystem.window("Window", 800, 600)
.opengl()
.build()
.unwrap();
let canvas = window.into_canvas()
.index(find_sdl_gl_driver().unwrap())
.build()
.unwrap();
gl::load_with(|name| video_subsystem.gl_get_proc_address(name) as *const _);
canvas.window().gl_set_context_to_current();
unsafe {
gl::ClearColor(0.6, 0.0, 0.8, 1.0);
gl::Clear(gl::COLOR_BUFFER_BIT);
}
canvas.present();
// opengl code hereBe wary though, sdl2 has its own internal state which you should avoid messing with. Avoid using manual OpenGL in the middle of SDL2 calls, or change the state in between.
You cannot override the OpenGL version with this method unless via changing the gl state
extern crate sdl2;
extern crate gl;
use sdl2::event::Event;
use sdl2::keyboard::Keycode;
use sdl2::video::GLProfile;
fn main() {
let sdl_context = sdl2::init().unwrap();
let video_subsystem = sdl_context.video().unwrap();
let gl_attr = video_subsystem.gl_attr();
gl_attr.set_context_profile(GLProfile::Core);
gl_attr.set_context_version(3, 3);
let window = video_subsystem.window("Window", 800, 600)
.opengl()
.build()
.unwrap();
let ctx = window.gl_create_context().unwrap();
gl::load_with(|name| video_subsystem.gl_get_proc_address(name) as *const _);
debug_assert_eq!(gl_attr.context_profile(), GLProfile::Core);
debug_assert_eq!(gl_attr.context_version(), (3, 3));
let mut event_pump = sdl_context.event_pump().unwrap();
'running: loop {
unsafe {
gl::ClearColor(0.6, 0.0, 0.8, 1.0);
gl::Clear(gl::COLOR_BUFFER_BIT);
}
window.gl_swap_window();
for event in event_pump.poll_iter() {
match event {
Event::Quit {..} | Event::KeyDown { keycode: Some(Keycode::Escape), .. } => {
break 'running
},
_ => {}
}
}
::std::thread::sleep(::std::time::Duration::new(0, 1_000_000_000u32 / 60));
}
}This method is useful when you don't care about sdl2's render capabilities, but you do care about its audio, controller and other neat features that sdl2 has.
To use Vulkan, you need a Vulkan library for Rust. This example uses the Vulkano library. Other libraries may use different data types for raw Vulkan object handles. The procedure to interface SDL2's Vulkan functions with these will be different for each one.
extern crate sdl2;
extern crate vulkano;
use sdl2::event::Event;
use sdl2::keyboard::Keycode;
use std::ffi::CString;
use vulkano::VulkanObject;
use vulkano::instance::{Instance, RawInstanceExtensions};
use vulkano::swapchain::Surface;
fn main() {
let sdl_context = sdl2::init().unwrap();
let video_subsystem = sdl_context.video().unwrap();
let window = video_subsystem.window("Window", 800, 600)
.vulkan()
.build()
.unwrap();
let instance_extensions = window.vulkan_instance_extensions().unwrap();
let raw_instance_extensions = RawInstanceExtensions::new(instance_extensions.iter().map(
|&v| CString::new(v).unwrap()
));
let instance = Instance::new(None, raw_instance_extensions, None).unwrap();
let surface_handle = window.vulkan_create_surface(instance.internal_object()).unwrap();
let surface = unsafe { Surface::from_raw_surface(instance, surface_handle, window.context()) };
let mut event_pump = sdl_context.event_pump().unwrap();
'running: loop {
for event in event_pump.poll_iter() {
match event {
Event::Quit {..} | Event::KeyDown { keycode: Some(Keycode::Escape), .. } => {
break 'running
},
_ => {}
}
}
::std::thread::sleep(::std::time::Duration::new(0, 1_000_000_000u32 / 60));
}
}raw-window-handle can be enabled using the feature name:
[dependencies.sdl2]
version = "0.32"
features = ["raw-window-handle"]An example working with wgpu is also available:
cargo run --example raw-window-handle-with-wgpu --features raw-window-handleOn macOS the RawWindowHandle.ns_view field is returned null. Libraries consuming the RawWindowHandle (such as
wgpu) should determine a sane default for ns_view. If they do not, please file an issue with the associated
project.
Rust, and Rust-SDL2, are both still heavily in development, and you may run
into teething issues when using this. Before panicking, check that you're using
the latest version of both Rust and Cargo, check that you've updated Rust-SDL2
to the latest version, and run cargo clean. If that fails, please let us know
on the issue tracker.
Any Pull Request is welcome, however small your contribution may be ! There are, however, conditions to contribute:
- New features must be properly documented, be it via examples or inline documentation (via
cargo doc). Documentation must be for the end user as well as your next fellow contributor. - Breaking changes must have a proper argumentation with it. While the pre-1.0 state of this crate allows us to be somewhat unstable, useless breaking changes will be denied.
- Minor changes, breaking changes and new features added via Pull Request must be added in the changelog file. It is now mandatory to log your changes in the changelog. A short description with a link to your commit/pull request within GitHub is fine. Internal, documentation or meta-changes (travis build change, README instructions updates, ...) don't have to be added in the changelog.