Rust-SDL2

SDL2的Rust绑定

0.37.0版本更改日志

概述

Rust-SDL2是一个从Rust调用新SDL2.0库的库。通过Rust代码包装低级别的C组件，使其更符合习惯用法，并抽象出不适当的手动内存管理。

Rust-SDL2使用MIT许可证，但SDL2本身在zlib许可证下。

可用的Rust功能

• gfx 用于链接到SDL2_gfx并访问gfx功能
• image 用于链接到SDL2_image并访问图像读写功能
• mixer 用于链接到SDL2_mixer并访问声音混合功能
• ttf 用于链接到SDL2_ttf并访问各种字体功能
• unsafe-textures 用于不在 Texture 结构中设置生命周期。纹理仅在程序退出时释放，或者可以通过 unsafe 手动释放。
• use-bindgen 用于自定义绑定，而不是使用从Linux环境创建的预生成的 sdl_bindings。它生成您自己的自定义SDL2绑定，适用于您的发行版。对于特定窗口相关场景非常有用。
• use-vcpkg 用于从vcpkg获取SDL2而不是在系统中查找。
• use-pkgconfig 使用pkg-config检测您的库在系统中的位置。在Unix系统上，对于静态链接非常有用。
• static-link 将SDL2静态链接，而不是动态链接。
• use_mac_framework 在macOS上使用Framework中的SDL2
• bundled，这将拉取SDL仓库并从源代码编译。更多信息见下文。

文档

在此处阅读文档.

要求

Rust

我们目前针对Rust的最新稳定版。

SDL2.0开发库

建议使用SDL2 >= 2.0.26的绑定；如果低于2.0.26，您可能会遇到链接时间错误，因为这里使用了但未在SDL2中定义的一些函数。如果您遇到此问题是因为您正在使用LTS机器（例如，Ubuntu），我们强烈建议您使用“捆绑”功能，该功能将为您的项目编译最新的稳定版SDL2。

"捆绑"功能

从0.31版开始，此crate支持一个名为“捆绑”的功能，可以从源代码编译SDL2并自动链接。虽然这应该适用于任何架构，但您必须拥有C编译器（例如gcc、clang或MS自己的编译器）才能正确使用此功能。

默认情况下，macOS和Linux仅从系统目录（如/usr/lib）加载库。如果您希望将新构建的libSDL2.so/libSDL2.dylib与您的可执行文件一起分发，您需要将rpath添加到您的可执行文件中。将以下行添加到build.rs脚本

#[cfg(target_os="macos")]
println!("cargo:rustc-link-arg=-Wl,-rpath,@loader_path");

#[cfg(target_os="linux")]
println!("cargo:rustc-link-arg=-Wl,-rpath,$ORIGIN");

**这仅适用于SDL2，不适用于SDL2_image、SDL2_mixer、SDL2_ttf、SDL2_gfx**

Linux

通过您喜欢的包管理工具安装这些，或通过http://www.libsdl.org/

Ubuntu示例

sudo apt-get install libsdl2-dev

Fedora示例

sudo dnf install SDL2-devel

Arch示例
(Arch没有单独的常规和开发包，所有东西都在一起。)

sudo pacman -S sdl2

您可能还需要C编译器（gcc）。

Linux中的静态链接

您可以选择使用static-link功能将SDL2静态链接，而不是动态链接。在Linux上，您还需要执行以下操作之一

• 使用bundled功能
• 使用功能use-pkgconfig，以便rustc知道在哪里查找您的SDL2库及其静态链接的依赖项。这是必需的，因为没有内置的查找用于从系统静态链接SDL2所需资源的方法
• 使用vcpkg安装开发库。有关使用vcpkg在Linux和其他操作系统上生成静态二进制的说明，请参阅此处

macOS

Homebrew

在macOS上，建议通过homebrew安装这些。

brew install sdl2

在Homebrew的最新版本中，通常将安装的库链接到$(brew --prefix)/lib。如果您正在运行较旧版本，SDL的符号链接可能位于/usr/local/lib。

要使通过Homebrew安装的库的链接更容易，请为您各自的shell执行以下操作。

根据您是否使用ZSH或Bash，将此行添加到您的~/.zshenv或~/.bash_profile中。

export LIBRARY_PATH="$LIBRARY_PATH:$(brew --prefix)/lib"

MacPorts

您也可以通过macports获取sdl2。

sudo port install libsdl2

如果尚未存在，请将以下内容添加到您的 ~/.bash_profile 中。

export LIBRARY_PATH="$LIBRARY_PATH:/opt/local/lib/"

如果您在使用 Homebrew 或 MacPorts 时遇到问题，请参阅这里。

如果您正在使用 SDL2 框架

您可以从以下网址下载和安装 SDL2 Mac OS X 框架：https://www.libsdl.org/download-2.0.php

为了使 sdl2 包链接到 SDL2 框架，您需要启用 use_mac_framework 功能。要使用此功能构建和测试 sdl2 包，请使用以下命令：

cargo test --features use_mac_framework

要使用此功能依赖 sdl2 包，请将以下内容放入您的项目 Cargo.toml 文件中

[dependencies.sdl2]
features = ["use_mac_framework"]
version = ...  # Whichever version you are using

或者，您也可以通过在 Cargo.toml 文件中放入以下内容来在您的包中重新导出此功能

[features]
default = []
use_sdl2_mac_framework = ["sdl2/use_mac_framework"]

使用 vcpkg 在 macOS 上进行静态链接

有关使用 vcpkg 在 macOS 和其他操作系统上生成静态二进制文件的说明，请参阅这里。

Windows (MSVC)

1. 从 http://www.libsdl.org/ 下载 MSVC 开发库（SDL2-devel-2.0.x-VC.zip）。

2. 将 SDL2-devel-2.0.x-VC.zip 解压到您选择的文件夹中（之后您可以删除它）。

3. 将以下路径中的所有 lib 文件复制到

   SDL2-devel-2.0.x-VC\SDL2-2.0.x\lib\x64\

   到（对于 Rust 1.6 及以上版本）

   C:\Program Files\Rust\lib\rustlib\x86_64-pc-windows-msvc\lib

   或到（对于 Rust 版本 1.5 及以下）

   C:\Program Files\Rust\bin\rustlib\x86_64-pc-windows-msvc\lib

   或到您选择的库文件夹中，并确保您有一个名为

   LIB = C:\your\rust\library\folder

   对于 Rustup 用户，此文件夹位于

   C:\Users\{Your Username}\.rustup\toolchains\{current toolchain}\lib\rustlib\{current toolchain}\lib

其中当前工具链可能是 stable-x86_64-pc-windows-msvc。

4. 将 SDL2.dll 从

   SDL2-devel-2.0.x-VC\SDL2-2.0.x\lib\x64\

   复制到您的 cargo 项目中，紧挨着 Cargo.toml。

5. 当您发布游戏时，请确保将 SDL2.dll 复制到与编译后的 exe 文件相同的目录中，否则游戏无法启动。

使用 MSVC 进行静态链接

http://libsdl.org/ 提供的 MSVC 开发库不包含静态库。这意味着如果您想使用 windows-msvc 工具链的 static-link 功能，您必须执行以下操作之一：

• 自己构建 SDL2 静态库并将其复制到工具链的 lib 目录中；或者
• 同时启用 bundled 功能，这将为您构建静态库；或者
• 使用以下说明中描述的 vcpkg 中的静态 SDL2 库。

Windows (MinGW)

1. 从 http://www.libsdl.org/ 下载 mingw 开发库（SDL2-devel-2.0.x-mingw.tar.gz）。

2. 解压到您选择的文件夹中（之后您可以删除它）。

3. 将以下路径中的所有 lib 文件复制到

   SDL2-devel-2.0.x-mingw\SDL2-2.0.x\x86_64-w64-mingw32\lib

   到（对于 Rust 1.6 及以上版本）

   C:\Program Files\Rust\lib\rustlib\x86_64-pc-windows-gnu\lib

   或到（对于 Rust 版本 1.5 及以下）

   C:\Program Files\Rust\bin\rustlib\x86_64-pc-windows-gnu\lib

   或到您选择的库文件夹中，并确保您有一个名为

   LIBRARY_PATH = C:\your\rust\library\folder

   对于 Rustup 用户，此文件夹位于

   C:\Users\{Your Username}\.rustup\toolchains\{current toolchain}\lib\rustlib\{current toolchain}\lib

其中当前工具链可能是 stable-x86_64-pc-windows-gnu。

4. 将 SDL2.dll 从

   SDL2-devel-2.0.x-mingw\SDL2-2.0.x\x86_64-w64-mingw32\bin

   复制到您的 cargo 项目中，紧挨着 Cargo.toml。

5. 当您发布游戏时，请确保将 SDL2.dll 复制到与编译后的 exe 文件相同的目录中，否则游戏无法启动。

使用 MinGW 进行静态链接

如果您想使用 windows-gnu 工具链的 static-link 功能，则需要以下库

libimm32.a
libversion.a
libdinput8.a
libdxguid.a

这些文件目前没有包含在 windows-gnu 工具链中，但可以从这里下载。对于 x86_64 工具链，您想要的是 x86_64-win32-seh 软件包，对于 i686，您想要的是 i686-win32-dwarf 软件包。

您可以在以下路径找到上述库：对于 x86_64，为 mingw64/x86_64-w64-mingw32/lib/；对于 i686，为 mingw32/i686-w64-mingw32/lib/。将它们复制到您的工具链的 lib 目录（与您复制 SDL .a 文件相同的目录）。

带有构建脚本的 Windows

1. 从 http://www.libsdl.org/（SDL2-devel-2.0.x-mingw.tar.gz & SDL2-devel-2.0.x-VC.zip）下载 mingw 和 msvc 开发库。
2. 解压缩到您选择的文件夹（之后您可以删除它）。
3. 在 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

4. 将源存档中的 lib 和 dll 文件按如下方式复制到步骤 3 中创建的目录中

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

5. 如果您还没有构建脚本，请创建一个构建脚本，并将其放在 Cargo.toml 下的 [package]

build = "build.rs"

6. 在 Cargo.toml 所在的同级目录中创建一个名为 build.rs 的文件（如果您还没有构建脚本），并将其粘贴到其中

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");
                }
            }
        }
    }
}

7. 在构建时，构建脚本将把所需的 DLLs 复制到与 Cargo.toml 相同的目录，但是您可能不希望将这些文件提交到任何 Git 仓库，因此请将以下行添加到 .gitignore 文件中

/*.dll

8. 当您发布游戏时，请确保将相应的 SDL2.dll 复制到与编译后的 exe 文件相同的目录，否则游戏将无法启动。

现在，您的项目应该可以在任何 Windows 计算机上构建和运行！

带有 vcpkg 的 Windows (MSVC)

1. 安装 MS build tools 和 vcpkg
2. 安装所需的 SDL2 库：vcpkg.exe install sdl2:ttf:x64-windows sdl2:x64-windows
3. 打开 x64 native tools 命令提示符（VS 2019 的 x64 Native Tools Command Prompt）
4. 设置环境变量

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

5. cargobuild

带有 vcpkg 的 Windows、Linux 和 macOS

获取开发库的另一种方法是使用 vcpkg。为了设置一个项目，以在 Windows (MSVC)、Linux 或 macOS 上构建可静态编译的二进制文件，可按如下方式构建

cargo install cargo-vcpkg
cargo vcpkg build
cargo build

将以下内容添加到您的 Cargo.toml

[dependencies.sdl2]
version = "0.37"
default-features = false
features = ["ttf","image","gfx","mixer","static-link","use-vcpkg"]

[package.metadata.vcpkg]
dependencies = ["sdl2", "sdl2-image[libjpeg-turbo,tiff,libwebp]", "sdl2-ttf", "sdl2-gfx", "sdl2-mixer"]
git = "https://github.com/microsoft/vcpkg"
rev = "2024.05.24" # release 2024.05.24 # to check for a new one, check https://github.com/microsoft/vcpkg/releases

[package.metadata.vcpkg.target]
x86_64-pc-windows-msvc = { triplet = "x64-windows-static-md" }

有关 cargo vcpkg 工具的更多信息，请参阅 此处。

安装

如果您使用 cargo 管理项目，您可以通过 Crates.io 下载

    [dependencies]
    sdl2 = "0.37"

或者，从 GitHub 拉取以获取最新版本的 master

    [dependencies.sdl2]
    git = "https://github.com/rust-sdl2/rust-sdl2"

否则，克隆此存储库并运行 cargo

cargo build

您可以通过添加以下内容来启用功能，如 ttf、image、gfx 和 mixer

    [dependencies.sdl2]
    version = "0.37"
    default-features = false
    features = ["ttf","image","gfx","mixer"]

这些功能需要它们各自的库，它们的位置如下：（安装过程与 SDL2 相同）

• image、ttf、mixer
• gfx

关于 sdl2_net 呢？

到目前为止，与诸如 serde 和 bincode 等其他 crate 相比，sdl2_net 没有意义。我们强烈建议使用这些库来开发任何与 UDP 或 TCP 相关的应用（同时使用 futures 或标准库中的 TCP/UDP）。

如果您仍然想要 sdl2_net 的实现，您可以通过拉取请求（Pull Request）在此存储库中添加它作为功能。此绑定的一个较旧版本可以在 此处 找到

示例

我们包含了一些简单的示例项目

cargo run --example demo

您可以在 examples/ 文件夹中查看完整列表。一些示例需要某些功能，您可以通过以下方式启用它们

cargo run --example gfx-demo --features "gfx"

将“gfx”替换为您想要示例所需的功能。

关于unsafe_textures功能

在sdl2::render模块中，Texture默认具有生命周期，以防止其超出其父TextureCreator的生命周期。这些生命周期有时在Rust中很难处理，因此您可以选择启用unsafe_textures功能。

这将移除Texture的生命周期，但需要手动管理内存。如果您想要手动销毁使用的Texture，可以调用您的Texture的destroy方法，但请注意，如果父对象（Canvas或TextureCreator）中的任何一个都不存在，则不应调用此方法。如果您不调用此方法，内存将在最后一个Canvas或最后一个TextureCreator被释放时自动释放。

此功能没有在线文档，但是您可以在项目中通过在Cargo.toml中启用功能，运行cargo doc并在浏览器中访问target/doc/sdl2/index.html来自动构建它。

使用bindgen生成sdl2-sys

为该crate生成的sdl2-sys非常通用，可以在许多平台上使用，且限制很少。然而，您可能会在使用SDL2的平台特定功能时遇到麻烦，例如窗口管理器类别。

“use-bindgen”功能允许您通过根据目标生成适当的绑定来避免这种限制。它将使用pkg-config输出的头文件（如果您启用了“use-pkg-config”功能）来生成绑定。如果没有pkg-config或禁用了此功能，它将尝试从该crate的SDL-2.0.8/include中获取头文件。

如果您有自己的头文件想要使用（使用beta版本、旧版本等），可以设置环境变量“SDL2_INCLUDE_PATH”，这些头文件将由bindgen使用。

使用sdl2-sys提供SDL2头文件/库

如果您正在为需要SDL2的库创建一个*-sys crate，您可以使用sdl2-sys来提供编译后的库和SDL2的头文件。

    [dependencies.gl]
    git = "https://github.com/bjz/gl-rs"

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
}

fn main() {
    let sdl_context = sdl2::init().unwrap();
    let video_subsystem = sdl_context.video().unwrap();
    let window = video_subsystem.window("Window", 800, 600)
        .opengl() // this line DOES NOT enable opengl, but allows you to create/get an OpenGL context from your window.
        .build()
        .unwrap();
    let canvas = window.into_canvas()
        .index(find_sdl_gl_driver().unwrap())
        .build()
        .unwrap();

    // ...
}

// initialization
gl::load_with(|name| video_subsystem.gl_get_proc_address(name) as *const _);

// sdl::render creates a context for you, if you use a Canvas you need to use it.
canvas.window().gl_set_context_to_current();

// ... in the main loop ...
unsafe {
    gl::ClearColor(0.6, 0.0, 0.8, 1.0);
    gl::Clear(gl::COLOR_BUFFER_BIT);
}
canvas.present();

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();

    // Unlike the other example above, nobody created a context for your window, so you need to create one.
    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));
    }
}

extern crate sdl2;
extern crate vulkano;

use sdl2::event::Event;
use sdl2::keyboard::Keycode;
use vulkano::instance::{Instance, InstanceCreateInfo, InstanceExtensions};
use vulkano::swapchain::Surface;
use vulkano::VulkanLibrary;

fn main() {
    let sdl_context = sdl2::init().unwrap();
    let video_subsystem = sdl_context.video().unwrap();

    let window = video_subsystem
        .window("Window Title - My Vulkano-SDL2 application", 1024, 768)
        .vulkan()
        .build()
        .unwrap();

    let instance_extensions =
        InstanceExtensions::from_iter(window.vulkan_instance_extensions().unwrap());

    let instance = Instance::new(
        VulkanLibrary::new().unwrap(),
        InstanceCreateInfo {
            enabled_extensions: instance_extensions,
            ..Default::default()
        },
    )
    .unwrap();

    // SAFETY: Be sure not to drop the `window` before the `Surface` or vulkan `Swapchain`!
    // (SIGSEGV otherwise)
    let surface = unsafe { Surface::from_window_ref(instance.clone(), &window) };

    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));
    }
}

[dependencies.sdl2]
version = "0.37"
features = ["raw-window-handle"]

cargo run --example raw-window-handle-with-wgpu --features raw-window-handle

sdl2::hint::set("SDL_VIDEO_EXTERNAL_CONTEXT", "1")