Lib.rs

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

nightly librashader-runtime-wgpu

适用于所有 RetroArch 着色器

由 Ronny Chan 和 4 个贡献者 开发

26 个版本

新版本 0.3.3 2024年8月22日
0.3.1 2024年8月21日
0.2.8 2024年7月29日
0.2.7 2024年3月8日
0.2.3 2024年2月24日

386 在 模拟器

Download history 7/week @ 2024-05-19 5/week @ 2024-06-02 1/week @ 2024-06-09 1/week @ 2024-06-16 248/week @ 2024-07-28 42/week @ 2024-08-04 12/week @ 2024-08-11

每月302 次下载
用于 librashader

MPL-2.0 OR GPL-3.0-only

605KB
10K SLoC

librashader

Mega Bezel SMOOTH-ADV

DirectX 11 上的 Mega Bezel SMOOTH-ADV

librashader (ˈliːbrəʃeɪdər/) 是一个用于 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

✅ 完全支持 — 🆗 二级支持

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

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

用法

librashader 提供了在 librashader 包中的 Rust API 和 C API。这两个 API 都是第一类并且完全受支持。C API 更适合与现有项目集成。如果你希望逐部分使用 librashader，Rust librashader 包会暴露更多内部功能。

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中，立即上下文被视为图形设备队列），因为加载LUT需要向GPU提交命令。可以使用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]的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 不支持 HDR10。
  • 出于性能原因，输入纹理从不生成米柏。在理论上，这意味着具有 mipmap_input0 = "true" 的预设将不会获得米柏化的输入。实际上，没有已知的着色器预设设置了 mipmap_input0 = "true"。
  • 预设解析器是一个比 RetroArch 中更严格的实现。并非所有着色器预设都可能兼容。如果您发现这种情况，请提交问题以便添加绕过方法。
  • 着色器在传递给驱动程序之前在 SPIR-V 级别预先链接。在片段着色器中移除未使用的输入，并将相应的顶点着色器中的输入降级为全局变量。

运行时特定差异

  • OpenGL
    • 通过 glBlitFramebuffer 而不是绘制一个四边形到中间 FBO 来将正在进行的帧缓冲区内容复制到历史记录中。
    • 使用采样器对象而不是 glTexParameter。
    • 采样器输入和输出不会被重命名。这对于在 RenderDoc 中调试着色器很有用。
    • UBO 和 Push Constant 缓冲区的大小填充到 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 运行时使用 渲染通道。此功能自 Windows 10 版本 1809 以来一直可用，该版本于 2018 年晚些时候发布。
    • 为了与着色器实现最大兼容性，使用了基于 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，则表示“空”实例，其中每个操作都是无操作，这发生在找不到兼容的 librashader 实现时。

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

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

MSRV 政策

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

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

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

许可证

librashader 的核心部分，如预处理器、预设解析器、反射库和运行时，均在 Mozilla 公共许可证版本 2.0 下授权。

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

为了便于在不符合 MPL-2.0 的项目中使用 librashader，librashader_ld 实现了一个加载器，该加载器将其调用委派给在加载路径中找到的任何 librashader.so、librashader.dll 或 librashader.dylib 库。一个项目可以链接到 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。

依赖项

~36–69MB
~1M SLoC