1 unstable release

0.1.0	Aug 10, 2020

#43 in #web-gpu

96 downloads per month

MPL-2.0 license

195KB
4K SLoC

NOTE: THIS IS A TEMPORARY FORK SO BEVY CAN USE A SLIGHTLY NEWER VERSION OF WGPU. WE WILL MOVE BACK TO THE OFFICIAL VERSION WHEN A NEW WGPU-RS VERSION IS PUBLISHED

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.

Gallery

Cube Shadow MipMap Skybox vange-rs Brawl GLX map Harmony

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-triangle and hello-compute 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

Run Examples on the Web (`wasm32-unknown-unknown`)

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
# 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 glslangs glslangValidator binary.

Friends

Shout out to the following projects that work best with wgpu-rs:

wgpu_glyph - for your text-y rendering needs
coffee - a whole 2D engine
iced - a cross-platform GUI library
rgx - a 2D graphics library
imgui-wgpu - Dear ImGui interfacing
pixels - the easiest way to create a hardware-accelerated pixel frame buffer
kas - toolKit Abstraction System
oxidator - RTS game engine
nannou - a creative coding framework
harmony - a modern 2D/3D engine
wgpu-pbr - realtime PBR renderer for games

Also, libraries that have support for wgpu-rs:

conrod - shader-based UI
grr-2d - experimental 2D renderer
lyon - a path tessellation library

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.

Dependencies

~2–12MB
~137K SLoC