9f19533462
272: Force the wasm32 types to match Send / Sync with the native types r=kvark a=kyren This is potentially a controversial change so this is just a draft to discuss it. Currently, when building wgpu on wasm32, none of the interface types are Send or Sync, whereas on any other platform they are generally Send and Sync and this can cause a lot of pain, especially in the presence of async. This PR is the nuclear option: lie and forcibly declare nearly all interface types to be Send or Send + Sync. I think I understand the situation with proposed wasm32 threading a bit better now, and as of right now at least with my current understanding, it seems to me unlikely that javascript values held by rust could *ever* be sent transparently to another worker. The mechanism that rust apparently will use to implement transparent threading will be to use `SharedArrayBuffer` to share memory between multiple workers. Javascript provides a way for certain (serializable) objects to be shared with with other workers through `worker.postMessage()`, so Javascript has *some* story for sending javascript values to other threads, but only plain rust values that exist solely in the `SharedArrayBuffer` memory are send-able under this scheme. I've looked briefly through some of the wasm proposals like the interface types proposal, but I don't have a good sense if there's any proposed mechanism at all for interface types and threads to interact at all. If that's true that's really unfortunate because it seems like any thread safe API shared by native and web is doomed to mismatch. This is even more unfortunate because many of the webgpu types in the draft standard are marked as 'Serializable', meaning that they *are* actually safe to send to another worker via `postMessage`, but there does not appear to be a planned way for rust to do this transparently. I definitely could be misunderstanding the situation though and even if I am understanding it, the situation may have since changed. I also don't know the timing here, I don't know what the eventual timing of wasm32 threading support will be vs webgpu support and interface types support. *Right now* this PR is almost certainly sound, but there's definitely a possible future where it becomes unsound, and even maybe a possible future where it becomes unsound but then could later be made sound again. Co-authored-by: kyren <kerriganw@gmail.com>
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
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.
To run examples on the wasm32-unknown-unknown target, first build the example as usual, then run wasm-bindgen:
# 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
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 - tooKit 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:
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.