librashader

DirectX 11 上的 Mega Bezel SMOOTH-ADV

librashader（发音为 /ˈli:brəʃeɪdɚ/）是一个为 RetroArch 'slang' 着色器提供的预处理器、编译器和运行时，使用纯 Rust 重新编写。

安装

对于最终用户，librashader 可从 Open Build Service 获取，适用于各种 Linux 发行版和平台。Windows 和 macOS 用户可以从 GitHub 发布版 获取最新二进制文件。

支持的渲染 API

librashader 支持所有现代图形运行时，包括 wgpu、Vulkan、OpenGL 3.3+ 和 4.6（带有 DSA）、Direct3D 11、Direct3D 12 和 Metal。

librashader 不支持旧版渲染 API，例如较老的 OpenGL 或 Direct3D 版本，除非对 Direct3D 9 提供实验性支持。

✅ 完全支持 — 🆗 二级支持

在具有二级支持的渲染 API 上，不保证着色器的兼容性。

wgpu 对无法转换为 WGSL 的着色器有限制，例如使用 inverse 的着色器。Direct3D 9 不支持需要 Direct3D 10+ 功能的着色器，或无法编译为 Shader Model 3.0 的着色器。

用法

librashader 提供了两种 API：在 librashader crate 下的 Rust API 和 C API。这两个 API 都是首选并得到全面支持的。C API 更侧重于与现有项目集成。如果你希望逐部分使用 librashader，Rust librashader crate 提供了更多内部功能。

Librashader C API 的最佳使用方法是将其项目中的 librashader_ld.h 包含进来，它实现了一个动态加载程序，用于在搜索路径中加载 librashader 的实现（librashader.so、librashader.dll 或 librashader.dylib）。

C 兼容性

将 librashader 集成到项目中的推荐方法是使用 librashader_ld 单个头文件库，它实现了 librashader.dll / librashader.so / librashader.dylib 的动态加载器。有关 librashader 如何处理库更新时的 C ABI 和 API 稳定的详细信息，请参阅 版本策略。您也可以仅使用 librashader.h 和相应的 -lrashader 链接动态库。

将 librashader.h 静态链接是可能的，但官方不支持。您需要确保链接参数正确，以便成功将 librashader.lib 或 librashader.a 链接。强烈推荐使用 corrosion CMake 包。

线程安全

除了 Metal 运行时，通常情况下，从不同的线程创建过滤链实例是安全的，但绘制帧需要对外部同步过滤链对象。

可以在任何线程中创建过滤链，但对于适用的情况（在 Direct3D 11 中，即时上下文被认为是图形设备队列），需要外部同步图形设备队列。可以通过使用 filter_chain_create_deferred 函数异步延迟初始化 GPU 资源，但调用者负责将记录的命令提交到图形设备队列，并在绘制着色器传递帧之前确保工作完成。

OpenGL 有一个额外的限制，即只有在不同的线程中创建过滤链实例，并且线程本地的 OpenGL 上下文初始化为与绘图线程相同的上下文时，才安全。OpenGL 不支持 GPU 资源初始化的延迟。

Metal 运行时不支持线程安全。但是，您仍然可以通过 filter_chain_create_deferred 函数延迟提交 GPU 资源初始化。

Direct3D 9 API 不支持线程安全，除非在设备创建时启用了 D3DCREATE_MULTITHREADED。

四边形顶点和旋转

所有运行时都使用单位矩阵 MVP 和范围 [-1, 1] 的 VBO 渲染中间传递。默认情况下，最终传递使用范围 [0, 1] 的四边形 VBO 和以下投影矩阵。

static DEFAULT_MVP: &[f32; 16] = &[
  2.0, 0.0, 0.0, 0.0,
  0.0, 2.0, 0.0, 0.0,
  0.0, 0.0, 0.0, 0.0,
  -1.0, -1.0, 0.0, 1.0,
];

与 RetroArch 一样，这些运行时将仅在最终传递中应用 MVP 的旋转。这是将这些方向信息传递给着色器的唯一方法。

构建

对于 Rust 项目，只需将包添加到您的 Cargo.toml 文件中。

cargo add librashader

要构建与 C 兼容的动态库，运行构建脚本。

cargo run -p librashader-build-script -- --profile optimized

这将输出目标文件夹中的 librashader.dll 或 librashader.so。配置可以是 debug、release 或 optimized，以进行完整的 LTO。

虽然librashader没有构建时依赖，但使用librashader_ld.h可能需要相关运行时图形API的头文件。

编写librashader运行时

如果您想贡献一个尚未提供的运行时实现，请参阅librashader-runtime crate，其中包含所有librashader运行时实现所使用的辅助工具和共享逻辑。使用这些辅助工具和特性将确保您的运行时在统一和纹理语义绑定方面与现有librashader运行时具有一致的行为。

这些类型不应该在运行时的公共API中公开，而应该保留在运行时实现的内部。

示例

以下Rust示例展示了如何使用每个librashader运行时。

• Vulkan
• OpenGL
• Direct3D 11
• Direct3D 12
• wgpu
• Direct3D 9

还提供了一些使用C API的基本示例。

• Direct3D 11
• Metal与Objective-C

兼容性

librashader实现了整个RetroArch着色器管道，与现有着色器高度兼容。

如果您遇到在RetroArch中工作但在librashader下不工作的着色器，请报告问题。

• 滤镜链不会在后缓冲区终止。
  • 与RetroArch不同，librashader并不完全了解整个渲染状态，并且设计成可以在渲染管道的任何位置进行插件。相反，滤镜链在调用者提供的输出表面和视口处终止。将表面复制回后缓冲区是调用者的责任。
• 尽可能并行编译着色器。这应该会显著减少预设编译时间。OpenGL不支持并行着色器编译。
• HDR10支持不是任何着色器运行时的一部分，且librashader不支持。
• 出于性能考虑，从不为输入纹理生成Mipmap。理论上，这意味着带有mipmap_input0 = "true"的预设将不会获得Mipmap输入。在实践中，没有已知的着色器预设设置了mipmap_input0 = "true"。
• 预设解析器是一个比RetroArch中使用的更严格的实现。并非所有着色器预设都可能兼容。如果您发现这种情况，请提交问题以便添加解决方案。
• 在传递给驱动程序之前，着色器是在SPIR-V级别预链接的的。移除了片段着色器中未使用的输入，并将相应的顶点着色器中的输入降级为全局变量。