49640d2497
281: The Context trait r=grovesNL a=kvark The main motivation here is to avoid blocking the wgpu-core updates by `wgpu-native`. Instead, `wgpu-native` becomes a branch, and the dependency of `wgpu-rs` -> `wgpu-native` starts adhering to the contract/API of the standard webgpu-native headers. The biggest change is the introduction of the Context trait. I recall us discussing 2 downsides to having this trait: 1. inconvenient for the users to include. This is a non-issue here, since it's private. 2. more code to maintain. This is less of an issue if we aim to have 3 backends. What this gives in return is a well established contract with the backends. Unlike gfx-rs, the backend code is right here, a part of the crate, so the contract is only for internal use. Fixes #156 : the "direct" implementation of it goes straight to wgpu-core. What this gives us is less overhead for command recording, since there is no longer an extra indirection on every command, and no heap allocation at the end of a render pass. The downside of this PR is one extra `Arc` (with addref) per object. This commit also has small improvements: - consuming command buffers on submit (Fixes #267) - Instance type - proper call to destructors - fallible `request_device` Co-authored-by: Dzmitry Malyshau <kvarkus@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.
If you want to adapt the above to run your own crate on the web you will also need to add the following to your Cargo.toml:
[patch.crates-io]
wasm-bindgen = { git = "https://github.com/rustwasm/wasm-bindgen" }
wasm-bindgen-futures = { git = "https://github.com/rustwasm/wasm-bindgen" }
web-sys = { git = "https://github.com/rustwasm/wasm-bindgen" }
js-sys = { git = "https://github.com/rustwasm/wasm-bindgen" }
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
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.