wgpu README

The project's README from github.com/gfx-rs/wgpu. As one markdown file: README.md.

wgpu

Build Status codecov.io

wgpu is a cross-platform, safe, pure-Rust graphics API. It runs natively on Vulkan, Metal, D3D12, and OpenGL; and on top of WebGL2 and WebGPU on wasm.

The API is based on the WebGPU standard, but is a fully native Rust library. It serves as the core of the WebGPU integration in Firefox, Servo, and Deno.

Getting Started

See our examples online at https://wgpu.rs/examples/. You can see the Rust sources at examples and run them directly with cargo run --bin wgpu-examples <example>.

Learning wgpu

If you are new to wgpu and graphics programming, we recommend starting with Learn Wgpu.

Additionally, WebGPU Fundamentals is a tutorial for WebGPU which is very similar to our API, minus differences between Rust and Javascript.

Documentation Guides

We ship a set of documentation modules with information on useful architecture patterns, debugging tips, and more getting started information.

Need Help? Want to Contribute?

The wgpu community uses Matrix and Discord to discuss.

Other Languages

To use wgpu in C or dozens of other languages, look at wgpu-native. These are C bindings to wgpu and has an up-to-date list of libraries bringing support to other languages.

Learn WebGPU (for C++) is a good resource for learning how to use wgpu-native from C++.

Docs Examples Changelog
v30 v30 v30
trunk trunk trunk

Contributors are welcome! See CONTRIBUTING.md for more information.

Supported Platforms

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

✅ = First Class Support
🆗 = Downlevel/Best Effort Support
📐 = Requires the ANGLE translation layer (GL ES 3.0 only). On macOS/iOS, use the angle feature. On Windows, gles uses WGL by default; build with cfg(windows_angle) to use ANGLE instead. 🌋 = Requires the MoltenVK translation layer
🛠️ = Unsupported, though open to contributions

Environment Variables

Testing, examples, and ::from_env() methods use a standardized set of environment variables to control wgpu's behavior.

See the documentation for more environment variables.

When running the CTS, use the variables DENO_WEBGPU_ADAPTER_NAME, DENO_WEBGPU_BACKEND, DENO_WEBGPU_POWER_PREFERENCE, DENO_WEBGPU_DX12_COMPILER, and DENO_WEBGPU_STRICT_COMPLIANCE.

Repo Overview

For an overview of all the components in the gfx-rs ecosystem, see the big picture.

MSRV policy

TL;DR: If you're using wgpu, our MSRV is 1.87. If you're running our tests or examples, our MSRV is 1.93.

We will avoid bumping the MSRV of wgpu without good reason, and such a change is considered breaking.

Specific Details

Due to complex dependants, we have three MSRV policies:

  • wgpu's MSRV is 1.87
  • wgpu-core (and hence wgpu-hal, naga, naga-types and wgpu-types)'s MSRV is 1.87.
  • The rest of the workspace has an MSRV of 1.93.

It is enforced on CI (in "/.github/workflows/ci.yml") with the WGPU_MSRV, CORE_MSRV, and REPO_MSRV variables, respectively. This version can only be upgraded in breaking releases, though we release a breaking version every three months.

The following rules apply:

  • The wgpu-core crate should never require an MSRV ahead of Firefox's MSRV for nightly builds, as determined by the value of MINIMUM_RUST_VERSION in python/mozboot/mozboot/util.py.
  • The wgpu crate should never require an MSRV ahead of Servo's MSRV, as determined by the value of their rust-version declaration in Cargo.toml
  • The repository MSRV should never require an MSRV higher than stable - 3. For example, if stable is at 1.97, the repository MSRV should be no higher than 1.94. This is to allow people who are using a decently-updated OS-provided rust to be able to build our repository. Consider cross checking with NixOS, though this is not required.

Testing and Environment Variables

Information about testing, including where tests of various kinds live, and how to run the tests.

Tracking the WebGPU and WGSL draft specifications

The wgpu crate is meant to be an idiomatic Rust translation of the WebGPU API. That specification, along with its shading language, WGSL, are both still in the "Working Draft" phase, and while the general outlines are stable, details change frequently. Until the specification is stabilized, the wgpu crate and the version of WGSL it implements will likely differ from what is specified, as the implementation catches up.

Exactly which WGSL features wgpu supports depends on how you are using it:

wgpu (gfx-rs/wgpu)

Searching Database…

18.3K ·GitHub
Wgpu
Что это такое?wgpu — это кроссплатформенная безопасная графическая библиотека на чистом Rust, основанная на стандарте WebGPU. Она нативно работает поверх Vulkan, Metal, D3D12 и OpenGL, а в браузере — поверх WebGL2 и WebGPU через WebAssembly.
Это библиотека Rust, которую я подключаю к своему проекту, или отдельное приложение, которое нужно установить?Это полностью нативная библиотека Rust, которую вы добавляете как крейт — устанавливать никакого приложения не нужно. Код на C и на десятках других языков может обращаться к ней через C-биндинги wgpu-native.
С чего начать работу с ней?Добавьте крейт wgpu в свой Cargo-проект. Если вы новичок в графическом программировании, в README рекомендуют учебник Learn Wgpu, а официальные примеры доступны онлайн.
Какая версия Rust мне нужна?Минимум Rust 1.87 для самой библиотеки (1.93 — чтобы запускать тесты и примеры из репозитория). Повышение MSRV считается ломающим изменением, а ломающая версия выходит раз в три месяца.
Спецификация WebGPU и WGSL всё ещё в статусе черновиков — насколько рискованно строить на wgpu что-то серьёзное?Отчасти рискованно. Общие контуры спецификации стабильны, но детали часто меняются, а поддержка WGSL в wgpu может пока отличаться от спецификации, пока реализация её догоняет.
Есть ли уже что-то реальное, что построено на ней?Да — wgpu лежит в основе интеграции WebGPU в Firefox, Servo и Deno, то есть активно используется в продакшене.
Какие платформы и графические бэкенды она поддерживает?Поддержка первого класса: Vulkan (Windows, Linux, Android), Metal (macOS, iOS) и DX12 (Windows). OpenGL — поддержка второго уровня на отдельных стараниях, а веб-сборка на wasm нацелена на WebGPU или WebGL2.
Как мои шейдеры на WGSL компилируются под каждый бэкенд?Нативно собственный компилятор wgpu — Naga — переводит WGSL на шейдерный язык платформы. В браузере без фичи webgl WGSL передаётся напрямую в реализацию WebGPU браузера; если webgl включена, Naga конвертирует его в GLSL.
В чём подвох с поддержкой OpenGL, особенно на macOS и iOS?OpenGL — это поддержка второго уровня, на отдельных стараниях: GL 3.3+ на Windows и GL ES 3.0+ на Linux/Android. На macOS и iOS нужен слой трансляции ANGLE (фича angle), а для Vulkan там требуется MoltenVK.
Могу ли я управлять тем, какой бэкенд или GPU-адаптер выберет wgpu во время работы?Да, через переменные окружения: WGPU_BACKEND принимает список бэкендов через запятую (vulkan, metal, dx12, gl), а WGPU_ADAPTER_NAME ищет подстроку в имени адаптера без учёта регистра — например, 1080 выберет NVIDIA GeForce 1080ti.
What are similar projects?filament, bgfx, renderdoc, crosstl, sokol, egui, Vulkan, framefields
Which topics is it in?d3d12, graphics-programming, webgpu, shaders, opengl, computer-graphics, metal, vulkan, rendering, wasm, hacktoberfest, ios
Creator
gfx-rs
Size
85.3 MB
Stars
18.3K
Updated
CommitOct 18Releasev30.0.1Aug 22
Age
8y
Commits · 90 Days