45 个版本 (2 个稳定版)

22.1.0 2024 年 7 月 31 日
0.20.1 2024 年 6 月 13 日
0.19.3 2024 年 3 月 1 日
0.18.0 2023 年 10 月 25 日
0.2.2 2019 年 3 月 31 日

#6图形 API

Download history 50601/week @ 2024-05-04 49382/week @ 2024-05-11 50266/week @ 2024-05-18 55865/week @ 2024-05-25 55597/week @ 2024-06-01 53531/week @ 2024-06-08 54174/week @ 2024-06-15 51456/week @ 2024-06-22 52797/week @ 2024-06-29 50407/week @ 2024-07-06 61186/week @ 2024-07-13 58512/week @ 2024-07-20 58837/week @ 2024-07-27 55457/week @ 2024-08-03 68545/week @ 2024-08-10 46075/week @ 2024-08-17

每月 237,889 次下载
用于 1,495 个工具包 (395 个直接使用)

MIT/Apache

3MB
61K SLoC

wgpu

Matrix Space Dev Matrix  User Matrix Build Status codecov.io

wgpu 是一个跨平台的、安全的、纯 Rust 图形 API。它可以在 Vulkan、Metal、D3D12 和 OpenGL 上原生运行;在 wasm 上运行于 WebGL2 和 WebGPU 之上。

该 API 基于以下标准 WebGPU 标准。它是 Firefox 和 Deno 中 WebGPU 集成的核心。

仓库概述

该仓库包含以下库

  • Crates.io docs.rs - 面向用户的 Rust API。
  • Crates.io docs.rs - 内部安全实现。
  • Crates.io docs.rs - 内部不安全的 GPU API 抽象层。
  • Crates.io docs.rs - 在所有工具包之间共享的 Rust 类型。
  • Crates.io docs.rs - 独立的着色器翻译库。
  • Crates.io docs.rs - 对 d3d12 的薄抽象集合。
  • Crates.io - Deno JavaScript/TypeScript 运行时的 WebGPU 实现

以下二进制文件

  • Crates.io - 使用 naga 在不同语言之间翻译着色器的工具。
  • Crates.io - 获取系统 GPU 信息的工具。
  • cts_runner - 使用 deno_webgpu 的 WebGPU 兼容性测试套件运行器。
  • player - 重放 API 追踪的独立应用程序。

关于 gfx-rs 生态系统所有组件的概述,请参阅 整体视图

入门指南

Rust

Rust 示例可在 wgpu/examples 找到。您可以使用 cargo run --bin wgpu-examples <example> 在本地运行示例。请参阅 示例列表

要在浏览器中运行示例,请运行 cargo xtask run-wasm。然后在您的浏览器中打开 http://localhost:8000,并选择要运行的示例。当然,为了显示任何基于 WebGPU 的示例,您需要确保您的浏览器支持它。

如果您正在寻找 wgpu 教程,请参阅以下内容

C/C++

要在 C/C++ 中使用 wgpu,您需要 wgpu-native

如果您正在寻找 wgpu C++ 教程,请参阅以下内容

其他

如果您想在其他语言中使用 wgpu,有许多从 Python、D、Julia、Kotlin 等语言到 wgpu-native 的绑定。请参阅 列表

社区

我们有一个 Matrix 空间 Matrix Space,其中包含几个不同的房间,构成了 wgpu 社区

  • Wgpu Matrix - 讨论 wgpu 的开发。
  • Naga Matrix - 讨论 naga 的开发。
  • 用户矩阵 - 讨论使用该库及其相关生态系统。
  • 随机矩阵 - 讨论其他一切。

维基

我们有一个维基,作为知识库。

支持的平台

API Windows Linux/Android macOS/iOS Web (wasm)
Vulkan 🌋
Metal
DX12
OpenGL 🆗 (GL 3.3+) 🆗 (GL ES 3.0+) 📐 🆗 (WebGL2)
WebGPU

✅ = 首选支持
🆗 = 低级/尽力支持
📐 = 需要使用ANGLE转换层(仅限GL ES 3.0)
🌋 = 需要使用MoltenVK转换层
🛠️ = 不支持,但欢迎贡献

着色器支持

wgpu 支持 WGSL、SPIR-V 和 GLSL 着色器。HLSL 和 GLSL 都有编译器可以针对 SPIR-V 目标进行编译。所有这些着色器语言都可以与任何后端一起使用,因为我们处理所有的转换。此外,这些着色器输入的支持不会消失。

虽然 WebGPU 不支持除 WGSL 之外的其他着色器语言,但如果您在 WebGPU 上运行,我们将自动转换您的非 WGSL 着色器。

WGSL 默认总是支持,但 GLSL 和 SPIR-V 需要启用特性以支持编译。

请注意,WGSL 规范仍在开发中,因此草案规范并没有确切地描述 wgpu 支持什么。有关详细信息,请参阅以下内容

要启用 SPIR-V 着色器,请启用 wgpu 的 spirv 特性。要启用 GLSL 着色器,请启用 wgpu 的 glsl 特性。

Angle

Angle 是 Google 开发的从 GLES 转换到其他后端的一个转换层。我们支持在它上面运行我们的 GLES3 后端,以便达到其他平台(如 DX11 支持),否则无法访问的平台。要使用 Angle 运行,必须启用 "angle" 特性,并将 Angle 库放置在应用程序可见的位置。这些二进制文件可以从 gfbuild-angle 艺术品下载,在苹果硅的 Mac 上可能需要进行手动编译

在 Windows 上,通常需要将它们复制到工作目录中,与可执行文件在同一目录中,或者在您的路径中的某个位置。在 Linux 上,您可以使用 LD_LIBRARY_PATH 环境变量指向它们。

MSRV 策略

由于依赖关系复杂,我们有两种 MSRV 策略

  • d3d12nagawgpu-corewgpu-halwgpu-types 的 MSRV 是 1.74
  • 工作区其余部分的 MSRV 是 1.76

在 CI 中强制执行(在 "/.github/workflows/ci.yml" 中),使用 CORE_MSRVREPO_MSRV 变量。尽管我们每三个月发布一个破坏性版本,但该版本只能在破坏性版本中升级。

nagawgpu-corewgpu-halwgpu-types这些crate在夜间构建时不应要求高于Firefox的MSRV的MSRV,这由MINIMUM_RUST_VERSION的值决定,该值位于python/mozboot/mozboot/util.py中。

环境变量

所有测试和示例基础设施共享同一组环境变量,用于确定将运行在哪个后端/GPU上。

  • WGPU_ADAPTER_NAME包含您想使用的适配器名称的子串(例如,1080将匹配NVIDIA GeForce 1080ti)。
  • WGPU_BACKEND包含您想使用的后端的逗号分隔列表(vulkanmetaldx12gl)。
  • WGPU_POWER_PREF指定当未指定特定适配器名称时的电源偏好(highlownone)。
  • WGPU_DX12_COMPILER指定您想使用的DX12着色器编译器(dxcfxc,注意dxc需要在工作目录中包含dxil.dlldxcompiler.dll,否则将回退到fxc)。
  • WGPU_GLES_MINOR_VERSION指定要请求的OpenGL ES 3的次要版本号(012automatic)。
  • WGPU_ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER指定是否枚举不合规的驱动程序(0表示false,1表示true)。

在运行CTS时,使用变量DENO_WEBGPU_ADAPTER_NAMEDENO_WEBGPU_BACKENDDENO_WEBGPU_POWER_PREFERENCE

测试

我们有多种测试方法,每种方法都测试wgpu的不同质量。我们自动在CI上运行我们的测试。CI测试的当前状态

平台/后端 测试 说明
Windows/DX12 ✔️ 使用WARP
Windows/OpenGL ✔️ 使用llvmpipe
MacOS/Metal ✔️ 使用硬件运行器
Linux/Vulkan ✔️ 使用lavapipe
Linux/OpenGL ES ✔️ 使用llvmpipe
Chrome/WebGL ✔️ 使用swiftshader
Chrome/WebGPU 未设置

核心测试基础设施

我们使用一个名为cargo nextest的工具来运行我们的测试。要安装它,运行cargo install cargo-nextest

要运行测试套件

cargo xtask test

要运行WebGL上的测试套件(目前不完整)

cd wgpu
wasm-pack test --headless --chrome --no-default-features --features webgl --workspace

这将自动使用打包的浏览器运行测试。删除--headless以在http://localhost:8000使用您想要的任何浏览器运行测试。

如果您是用户并想帮助为wgpu做出贡献,我们始终需要更多帮助编写测试用例。

WebGPU符合性测试套件

WebGPU包含一个符合性测试套件,以验证实现是否正确工作。我们可以将CTS与wgpu一起运行。

要运行CTS,首先需要检出它

git clone https://github.com/gpuweb/cts.git
cd cts
# works in bash and powershell
git checkout $(cat ../cts_runner/revision.txt)

要运行一组特定的测试

# Must be inside the `cts` folder we just checked out, else this will fail
cargo run --manifest-path ../Cargo.toml -p cts_runner --bin cts_runner -- ./tools/run_deno --verbose "<test string>"

要找到完整的测试列表,请访问在线 cts 查看器

当前启用的 CTS 测试列表可以在这里找到。

跟踪 WebGPU 和 WGSL 草案规范

wgpu 包旨在成为 WebGPU API 的 Rust 语言的规范翻译。该规范及其着色语言 WGSL 目前都处于“工作草案”阶段,尽管总体框架稳定,但细节经常变化。在规范稳定之前,wgpu 包以及它实现的 WGSL 版本可能会与规范不同,因为实现正在赶超。

wgpu 支持哪些 WGSL 特性取决于您如何使用它

  • 当以原生代码运行时,wgpu 使用 Naga 包将 WGSL 代码翻译成您平台原生 GPU API 的着色语言。Naga 有一个目标来赶超 WGSL 规范,但总的来说,没有关于 Naga 和 WGSL 规范之间差异的最新总结。

  • 在没有启用 "webgl" 特性的情况下,通过编译为 WebAssembly 在网页浏览器中运行时,wgpu 依赖于浏览器自身的 WebGPU 实现。WGSL 着色器被直接传递到浏览器,因此这决定了您可以使用哪些 WGSL 特性。

  • 在启用 wgpu"webgl" 特性并在网页浏览器中运行时,wgpu 使用 Naga 将 WGSL 程序翻译成 GLSL。这使用了与您以原生代码运行 wgpu 时相同的 Naga 版本。

坐标系

wgpu 使用 D3D 和 Metal 的坐标系

渲染 纹理
render_coordinates texture_coordinates

依赖

~0.9–32MB
~472K SLoC