Lib.rs

› 模拟器 | 编程语言 › librashader
#retro-arch #shader #spir-v #graphics

librashader-presets

适用于所有 RetroArch 着色器

由 Ronny Chan 和 4 个贡献者 提供

68 个版本

0.40.0-beta.12024 年 8 月 11 日
0.2.8 2024 年 7 月 29 日
0.2.7 2024 年 3 月 8 日
0.2.0-beta.22023 年 11 月 30 日
0.1.0-alpha.42022 年 12 月 5 日

#252 在 模拟器 中

Download history 33/week @ 2024-05-03 23/week @ 2024-05-10 47/week @ 2024-05-17 38/week @ 2024-05-24 33/week @ 2024-05-31 25/week @ 2024-06-07 39/week @ 2024-06-14 36/week @ 2024-06-21 11/week @ 2024-06-28 12/week @ 2024-07-05 40/week @ 2024-07-12 39/week @ 2024-07-19 184/week @ 2024-07-26 220/week @ 2024-08-02 142/week @ 2024-08-09 378/week @ 2024-08-16

930 每月下载量
用于 12 个crate（10个直接）

MPL-2.0 OR GPL-3.0-only

155KB
2.5K SLoC

librashader

Mega Bezel SMOOTH-ADV

DirectX 11 上的 Mega Bezel SMOOTH-ADV

librashader (/ˈli:brəʃeɪdɚ/) 是一个用于 RetroArch 'slang' 着色器的预处理器、编译器和运行时，使用纯 Rust 重写。

Latest Version Docs build result License Nightly rust

安装

对于最终用户，librashader 可从多种 Linux 发行版和平台的开源构建服务（Open Build Service）获取。Windows 和 macOS 用户可以从 GitHub Releases 获取最新二进制文件。

支持的渲染 API

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

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

API 状态 librashader 功能
OpenGL 3.3+ ✅ gl
OpenGL 4.6 ✅ gl
Vulkan ✅ vk
Direct3D 9 ⚠️ d3d9
Direct3D 11 ✅ d3d11
Direct3D 12 ✅ d3d12
Metal ✅ metal
wgpu 🆗 wgpu

✅ 完全支持 — 🆗 二级支持 — ⚠️ 实验性支持

由于 WGSL 的限制，wgpu 可能不支持所有着色器。Direct3D 9 的支持是实验性的，并且不完全支持如前帧反馈或历史等功能，也无法支持需要 Direct3D 10+ 特性的着色器。

用法

librashader 提供了在 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中，即时上下文被视为图形设备队列），因为加载查找表需要向GPU提交命令。可以使用filter_chain_create_deferred函数异步延迟GPU资源的初始化，但调用者负责向图形设备队列提交记录的命令，并在绘制着色器传递帧之前确保工作完成。

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

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

四边形顶点和旋转

所有运行时都使用单位矩阵MVP和范围在[-1, 1]的VBO渲染中间传递。默认情况下，最后一步使用范围在[0, 1]的Quad 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项目，只需将crate添加到您的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 运行时。

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

兼容性

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

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

  • 过滤器链不会在后缓冲区终止。
    • 与 RetroArch 不同，librashader 并不知道整个渲染状态，并设计为可以在您的渲染管道的任何位置插入。相反，过滤器链在调用者提供的输出表面和视口处终止。将表面复制回后缓冲区的责任在于调用者。
  • 尽可能并行编译着色器。这应该会显着减少预设编译时间。OpenGL 不支持并行着色器编译。
  • HDR10 支持不是任何着色器运行时的一部分，也不受 librashader 支持。
  • 出于性能原因，输入纹理从不生成 mipmap。理论上，这意味着具有 mipmap_input0 = "true" 的预设不会获得 mipmap 输入。实际上，没有已知的着色器预设设置了 mipmap_input0 = "true"。
  • 预设解析器是一个比 RetroArch 中的更严格的实现。并非所有着色器预设都兼容。如果您发现这是这种情况，请提交问题以便添加解决方案。

运行时特定差异

  • OpenGL
    • 通过 glBlitFramebuffer 将运行中的帧缓冲区内容复制到历史记录中，而不是在中间 FBO 中绘制一个四边形。
    • 使用采样器对象而不是 glTexParameter。
    • 采样器输入和输出不会被重命名。这对于在 RenderDoc 中调试着色器很有用。
    • UBO 和 Push Constant Buffer 的大小填充到 16 字节边界。
    • OpenGL 运行时与其他运行时使用相同的 VBO，以及中间传递的恒等矩阵 MVP。RetroArch 的 OpenGL 驱动程序仅使用最终的 VBO。
  • OpenGL 4.6+
    • 应考虑 OpenGL 3.3+ 部分的所有注意事项。
    • 应在 OpenGL 4.5 上正常工作，但这没有保证。OpenGL 4.6 运行时最终可能切换到使用 ARB_spirv_extensions 来加载着色器，这不会被视为破坏性更改。
    • OpenGL 4.6 运行时使用直接状态访问以最小化对 OpenGL 状态的更改。对于过去 5 年内发布的 GPU，这可能提高性能。
    • OpenGL 运行时与其他运行时使用相同的 VBO，以及中间传递的恒等矩阵 MVP。RetroArch 的 OpenGL 驱动程序仅使用最终的 VBO。
  • Vulkan
    • Vulkan运行时可以使用VK_KHR_dynamic_rendering扩展。此扩展必须在创建设备时启用。启用动态渲染可能提高性能，并受主机硬件支持。
    • 运行时内的分配是通过gpu-allocator而不是手动处理来完成的。
  • Direct3D 11
    • 帧缓冲区复制是通过ID3D11DeviceContext::CopySubresourceRegion而不是CPU转换加复制来完成的。
  • Direct3D 12
    • Direct3D 12运行时使用渲染流。此功能自2018年底发布的Windows 10版本1809以来一直可用。
    • 为了与着色器实现最大兼容性，使用基于spirv-to-dxil的着色器编译管道，SPIRV-Cross HLSL管道作为后备使用。这带来了比RetroArch Direct3D 12驱动程序提供的着色器兼容性更广泛的兼容性。随着spirv-to-dxil的改进，HLSL管道后备可能在未来被删除。
    • Direct3D 12运行时需要从DirectX Shader Compiler中的dxcompiler.dll，这可能是作为Direct3D12的一部分预先安装的。dxil.dll不是必需的。
  • Metal
    • Metal运行时与其他运行时使用相同的VBO，以及用于中间流的单位矩阵MVP。RetroArch的Metal驱动程序仅使用最终的VBO。

大多数（如果不是所有）着色器预设应在librashader上正常工作。运行时特定的差异不应影响输出，更多的是提醒您将librashader集成到项目中。

版本

Latest Version C ABI C API

librashader通常遵循语义版本与Rust API相关，其中小版本号的增加表示在0.x.y期间发生“重大变更”，而在1.x.y之后发生“非重大变更”。然而，导致版本号增加的“重大变更”并不对应于0.1.0版本之后的C API的“中断”。

C API以两种单调递增的版本号分别进行版本控制，并导出到librashader C头文件。

LIBRASHADER_CURRENT_VERSION的增加将保证与相同的LIBRASHADER_CURRENT_ABI向后兼容。这在语义版本术语中类似于“次要”版本，但它始终是单调递增的。向后兼容的C API添加将导致LIBRASHADER_CURRENT_VERSION的增加。

在某个LIBRASHADER_CURRENT_VERSION之后引入的API可能可能或可能不对先前版本可用。特别是，由筛选器或帧选项结构启用的新功能需要LIBRASHADER_CURRENT_VERSION大于或等于引入该选项的版本，否则将传递默认值，这可能会或可能不会启用该功能，具体取决于该特定功能的向后兼容性。

对 LIBRASHADER_CURRENT_ABI 的任何更改都表示 C ABI 发生了 重大变化。出于安全考虑，librashader_ld.h 将检查确保 LIBRASHADER_CURRENT_ABI 与加载的 librashader 二进制文件匹配。如果不匹配，librashader 将不会加载。LIBRASHADER_CURRENT_ABI 的值为 0 表示“空”实例，其中每个操作都是无操作（no-op），这种情况发生在找不到兼容的 librashader 实现时。

当通过软件包管理器安装时，librashader.so 的 SONAME 设置为 LIBRASHADER_CURRENT_ABI。

以上内容不适用于 0.1.0 之前的 librashader 版本，这些版本允许在不增加 LIBRASHADER_CURRENT_VERSION 或 LIBRASHADER_CURRENT_ABI 的情况下，同时破坏 Rust 和 C API 的 API 和 ABI 兼容性。

MSRV 政策

虽然 librashader 需要 nightly Rust，但以下 MSRV 政策强制执行不稳定库功能。

  • Windows 和 macOS：最新版 nightly
  • Linux：1.76

每周运行 CI 作业以确保 librashader 继续在 nightly 上构建。请注意，MSRV 仅为方便 Linux 的分发而设计，并且可以随时更改。它通常跟踪 Ubuntu 最新版本中可用的最新 Rust 版本，但在补丁版本中可能会没有警告地更改。

许可证

librashader 的核心部分，如预处理器、预设解析器、反射库和运行时，均采用 Mozilla Public License version 2.0 许可。

librashader 的 C API，即其头文件和定义（而不是在 librashader-capi 中的实现），采用更为宽松的许可证，可能允许你在许可宽松或专有项目中使用 librashader。

为了便于在不兼容 MPL-2.0 的项目中使用 librashader，librashader_ld 实现了一个加载器，该加载器将调用传递给任何在加载路径中找到的 librashader.so、librashader.dll 或 librashader.dylib 库。一个非 MPL-2.0 兼容的项目可以链接到 librashader_ld 来使用 librashader 运行时，前提是 librashader.so、librashader.dll 或 librashader.dylib 在 MPLv2 的限制下分发。

请注意，这意味着如果你的项目无法遵守 MPL-2.0 的要求，你 不能与你的项目一起分发 librashader.so、librashader.dll 或 librashader.dylib。最终用户必须自己获取 librashader 的实现。更多信息，请参阅 MPL 2.0 FAQ。

您可以选择在 GPLv3 而不是 MPL-2.0 的条款下分发 librashader。

依赖关系

~5–7MB
~118K SLoC