65 个版本
| 0.40.0-beta.1 | 2024 年 8 月 11 日 |
|---|---|
| 0.2.8 | 2024 年 7 月 29 日 |
| 0.2.7 | 2024 年 3 月 8 日 |
| 0.2.0-beta.2 | 2023 年 11 月 30 日 |
| 0.1.0-alpha.4 | 2022 年 12 月 5 日 |
#385 在 模拟器 中
每月 937 次下载
用于 11 个crate（10 个直接）
415KB
7K SLoC
librashader
DirectX 11 上的 Mega Bezel SMOOTH-ADV
librashader （/ˈli:brəʃeɪdɚ/） 是一个预处理程序、编译器和 RetroArch 'slang' 着色器的运行时，使用纯 Rust 重新编写。
安装
对于最终用户，librashader 可从各种 Linux 发行版和平台的 Open Build Service 获取。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 | 状态 | librashader 功能 |
|---|---|---|
| OpenGL 3.3+ | ✅ | gl |
| OpenGL 4.6 | ✅ | gl |
| Vulkan | ✅ | vk |
| Direct3D 9 | ⚠️ | d3d9 |
| Direct3D 11 | ✅ | d3d11 |
| Direct3D 12 | ✅ | d3d12 |
| Metal | ✅ | metal |
| wgpu | 🆗 | wgpu |
✅ 完全支持 — 🆗 二级支持 — ⚠️ 实验性支持
wgpu 可能由于 WGSL 的限制而无法支持所有着色器。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]的四边形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存储库，其中包含所有librashader运行时实现使用的辅助工具和共享逻辑。使用这些辅助工具和特性和物将确保您的运行时与现有的librashader运行时在均匀和纹理语义绑定方面具有一致的行为。
这些类型不应在运行时的公共API中公开，而应保留在运行时实现的内部。
示例
以下Rust示例展示了如何使用每个librashader运行时。
还提供了一些使用C API的基本示例。
兼容性
librashader实现了整个RetroArch着色器管道，并且与现有着色器高度兼容。
如果您遇到在RetroArch中工作但在librashader下不工作的着色器，请报告问题。
- 过滤器链不会在后缓冲区终止。
- 与RetroArch不同，librashader并不完全了解整个渲染状态，并设计为可以在渲染管道的任何位置插入。相反，过滤器链在调用者提供的输出表面和视口处终止。将表面复制回后缓冲区是调用者的责任。
- 尽可能并行编译着色器。这应该会显著减少预设编译时间。OpenGL不支持并行着色器编译。
- HDR10支持不是任何着色器运行时的一部分，并且librashader不支持。
- 出于性能原因，从不为输入纹理生成MIP贴图。从理论上讲，这意味着具有
mipmap_input0 = "true"的预设将不会获得MIP贴图输入。实际上，没有已知的着色器预设设置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而不是手动处理来完成的。
- Vulkan运行时可以使用
- 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着色器编译器 的
dxcompiler.dll，它可能已经作为Direct3D12的一部分安装。不需要dxil.dll。
- Metal
- Metal运行时使用与其他运行时相同的VBO以及中间通道的恒等矩阵MVP。RetroArch的Metal驱动器只使用最终的VBO。
大多数（如果不是全部）着色器预设应在librashader上运行良好。运行时特定的差异不应影响输出，更多的是提醒您将librashader集成到项目中。
版本
librashader通常遵循与Rust API相关的 语义版本控制，其中小版本号的增加表示在 0.x.y 期间有“破坏性变更”，而 1.x.y 之后则没有“破坏性变更”。然而，导致版本号增加的“破坏性变更”并不对应于0.1.0版本之后的C API中断。
C API是单独进行版本控制的，通过两个单调递增的版本号导出到librashader C头文件中
LIBRASHADER_CURRENT_VERSION指定了librashader实现导出的 API 版本。LIBRASHADER_CURRENT_ABI指定了librashader实现导出的 ABI 版本。
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，则表示“null”实例，其中每个操作都是无操作，这发生在找不到兼容的librashader实现时。
当通过包管理器安装时，SONAME 的 librashader.so 被设置为 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 公共许可证第 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。
依赖项
~20–41MB
~895K SLoC