wgpu-rs
wgpu-rs is an idiomatic Rust wrapper over wgpu-core. It's designed to be suitable for general purpose graphics and computation needs of Rust community.
wgpu-rs can target both the natively supported backends and WASM directly.
See our gallery and the wiki page for the list of libraries and applications using wgpu-rs
.
Usage
How to Run Examples
All examples are located under the examples directory.
These examples use the default syntax for running examples, as found in the Cargo documentation. For example, to run the cube
example:
cargo run --example cube
The hello*
examples show bare-bones setup without any helper code. For hello-compute
, pass 4 numbers separated by spaces as arguments:
cargo run --example hello-compute 1 2 3 4
wasm32-unknown-unknown
)
Run Examples on the Web (Running on the web is still work-in-progress. You may need to enable experimental flags on your browser. Check browser implementation status on webgpu.io. Notably, wgpu-rs
is often ahead in catching up with upstream WebGPU API changes. We keep the gecko
branch pointing to the code that should work on latest Firefox.
To run examples on the wasm32-unknown-unknown
target, first build the example as usual, then run wasm-bindgen
:
# Checkout `gecko` branch that matches the state of Firefox
git checkout upstream/gecko
# Install or update wasm-bindgen-cli
cargo install -f wasm-bindgen-cli --version 0.2.68
# Build with the wasm target
RUSTFLAGS=--cfg=web_sys_unstable_apis cargo build --target wasm32-unknown-unknown --example hello-triangle
# Generate bindings in a `target/generated` directory
wasm-bindgen --out-dir target/generated --web target/wasm32-unknown-unknown/debug/examples/hello-triangle.wasm
Create an index.html
file into target/generated
directory and add the following code:
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<script type="module">
import init from "./hello-triangle.js";
init();
</script>
</body>
</html>
Now run a web server locally inside the target/generated
directory to see the hello-triangle
in the browser.
e.g. python -m http.server
How to compile the shaders in the examples
Currently, shaders in the examples are written in GLSL 4.50 and compiled to SPIR-V manually. In the future WGSL will be the shader language for WebGPU, but support is not implemented yet.
For now, the shaders can be compiled to SPIR-V by running make
, which requires you to have glslang
s glslangValidator
binary.
Logging
wgpu-core
uses tracing
for logging and wgpu-rs
uses log
for logging.
Simple Setup
If you just want log messages to show up and to use the chrome tracing infrastructure,
take a dependency on the wgpu-subscriber
crate then call initialize_default_subscriber
. It will
set up logging to stdout/stderr based on the RUST_LOG
environment variable.
Manual Conversion
tracing
also has tools available to convert all tracing
events into log
events and vise versa.
log
events -> tracing
events
The tracing_log
crate has a log
logger to translate all events into tracing
events. Call:
tracing_log::LogTracer::init().unwrap()
tracing
events -> log
events
The tracing
crate has a log
feature which will automatically use log
if no subscriber is added:
tracing = { version = "0.1", features = ["log"] }
If you want events to be handled both by tracing
and log
, enable the log-always
feature of tracing
:
tracing = { version = "0.1", features = ["log-always"] }
Development
If you need to test local fixes to gfx-rs or other dependencies, the simplest way is to add a Cargo patch. For example, when working on DX12 backend on Windows, you can check out the "hal-0.2" branch of gfx-rs repo and add this to the end of "Cargo.toml":
[patch.crates-io]
gfx-backend-dx12 = { path = "../gfx/src/backend/dx12" }
gfx-hal = { path = "../gfx/src/hal" }
If a version needs to be changed, you need to do cargo update -p gfx-backend-dx12
.