realsense-sys

生成和使用 RealSense C 库绑定作为 Rust crate。此 crate 用作更易于使用的 realsense-rust crate 的基础层；如果可能，我们建议使用 realsense-rust 以更好地维护 Rust 内存安全性。

兼容 RealSense SDK v2.0 及以上版本。

默认绑定适用于 librealsense 版本：2.54.2

使用方法

此 crate 查找并链接 RealSense SDK。虽然可以直接使用生成的绑定，但此 crate 的目的是作为 realsense-rust 的基础层。

要使用此 crate，请在您的 Cargo.toml 中添加此行。

realsense-sys = "<current version number>"

重新生成 API 绑定

Bindgen 依赖于 clang 来生成新的 FFI 绑定。有关更多信息，请参阅下面的 OS 使用说明。

非 Linux 用户：当前的绑定格式适用于 Linux。Linux 之外的系统用户必须运行带有 buildtime-bindgen 功能的绑定以重新格式化绑定。有关您平台的更多信息，请参阅下面的说明。

向后兼容性：如果您正在使用较旧的 librealsense 版本，您可以通过启用 buildtime-bindgen 功能来重新生成绑定。我们不保证向后兼容性；祝你好运。

说了这么多：运行以下命令以重新生成 realsense2 SDK 绑定

cargobuild --featuresbuildtime-bindgen

OS 使用说明

Linux

您可以使用以下命令安装 Clang

sudoapt install libclang-dev clang

如果已安装 realsense2 SDK，pkg-config 将自动检测 realsense2.pc 配置文件。这将加载必要的头文件和库。

Windows

注意：当前的绑定格式适用于 Linux。用户必须运行带有 buildtime-bindgen 功能的绑定来重新格式化 Windows 平台的绑定。

本安装过程假设通过从librealsense资源页面可下载的.exe向导安装了RealSense SDK。此过程将在C:/Program Files (x86)/Intel RealSense SDK 2.0中安装SDK。如果您的安装位置不同，请修改realsense2.pc文件中的prefix行到正确的路径。

安装Pkg-config和Clang

通过Chocolatey安装pkg-config

1. https://chocolatey.org/install（如果系统上尚未安装）
2. choco install pkgconfiglite
3. choco install llvm用于bindgen（如果尚未安装）

指导Pkg-config使用realsense2.pc

在PowerShell中将pkg-config路径设置为realsense-sys目录。有两种方法可以做到这一点

第一种方法：修改pkg-config的环境变量

要这样做，请运行

$Env:PKG_CONFIG_PATH="C:\Users\< path_to_repo >\realsense-rust\realsense-sys\"

这将帮助pkg-config找到位于此目录中的realsense2.pc文件。此文件告诉pkg-config在哪里查找RealSense操作所需的头文件和库。Windows向导不提供此文件，因此我们自行提供。

建议通过系统属性全局设置PKG_CONFIG_PATH环境变量。但是请注意：通过Windows系统属性设置的环境变量将在主机机重启后生效。是的，这是事实。

第二种方法：将realsense2.pc添加到pkg-config的搜索目录

运行以下命令...

pkg-config--variable pc_path pkg-config

...以识别pkg-config用于查找*.pc文件的目录（或多个目录）。将realsense2.pc复制到该目录。Boom，完成。

架构说明

此crate提供对librealsense2的低级C-API的bindgen映射。

在这方面，realsense-sys将C-API中的类型映射到Rust的方式相当简单，因为没有做特别独特的事情，只是运行bindgen来生成绑定。

sys别名在realsense-rust crate中广泛使用，因此您经常会看到类似sys::rs2_XXX的代码。

理解生命周期

此库是通过使用bindgen对一组C头文件进行生成的，通常位于/usr/include/librealsense2/rs.h（或您安装librealsense2的位置）。本质上，这使得此模块中的大多数代码都是不安全的，因为它依赖于底层C库来定义每个数据类型的生命周期。

librealsense2 在记录对象的生存周期方面并不总是做得很好。请理解，该库主要是一个C++库，在其之上构建了与C兼容的API。这意味着虽然某些类型可以保证生存周期，但这些保证并不总是明确的。我的意思是，C++库中的许多数量是通过C++ shared_ptr 或 unique_ptr 来管理的。然而，在这个之上的C API无法暴露这些类型，并且在底层是否通过调用 shared_ptr::get() 或 unique_ptr::get() 获得的指针并不明确。一个很好的例子是 rs2_get_frame_sensor，它会在底层从 shared_ptr 获得一个传感器类型的指针。因此，您不需要手动管理此指针，可以在需要时将其丢弃，因为底层的 shared_ptr 将在不再持有时删除资源。然而，如果您通过在低级API中调用 rs2_create_sensor 从传感器列表中获得传感器，那么您会发现此指针是用 new 分配的，并且如果您使用它，则需要通过调用 rs2_delete_sensor 来删除它。在这两种情况下，您都会从包装器中获得一个 *mut rs2_sensor，但生存期和所有权信息被处理得非常不同。这使得API相当难以导航。

• rs2_get_frame_sensor
• rs2_create_sensor

一般来说，阅读仓库中的 bindings.rs 将对描述Intel在C-API中每个函数周围的文档很有帮助。然而，您可能会发现这样的文档是不够的，因为不是每个函数都记录了适当的所有权。因此，您最终需要理解librealsense2的C、C++和Rust，才能安全有效地使用realsense-sys库。如果您发现自己正在寻找librealsense2 C-API的入口点，我们强烈建议从 此文件 开始，并按类型逐个向外工作。

如果这看起来很费力（这确实如此！），我们强烈建议使用realsense-rust包装器，该包装器试图抽象这些并提供一个高级、Rust本机的API，避免了不安全代码。

许可证

Apache 2.0。请参阅 LICENSE 文件。