wgpu

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

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

仓库概述

该仓库包含以下库

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

以下二进制文件

• - 使用 naga 在不同语言之间翻译着色器的工具。
• - 获取系统 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 教程，请参阅以下内容

• https://sotrh.github.io/learn-wgpu/

C/C++

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

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

• https://eliemichel.github.io/LearnWebGPU/

其他

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

社区

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

• - 讨论 wgpu 的开发。
• - 讨论 naga 的开发。
• - 讨论使用该库及其相关生态系统。
• - 讨论其他一切。

维基

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

支持的平台

✅ = 首选支持
🆗 = 低级/尽力支持
📐 = 需要使用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 策略

• d3d12、naga、wgpu-core、wgpu-hal 和 wgpu-types 的 MSRV 是 1.74。
• 工作区其余部分的 MSRV 是 1.76。

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

naga、wgpu-core、wgpu-hal和wgpu-types这些crate在夜间构建时不应要求高于Firefox的MSRV的MSRV，这由MINIMUM_RUST_VERSION的值决定，该值位于python/mozboot/mozboot/util.py中。

环境变量

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

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

在运行CTS时，使用变量DENO_WEBGPU_ADAPTER_NAME、DENO_WEBGPU_BACKEND和DENO_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 的坐标系

渲染	纹理