mirror of
https://github.com/storytold/wgpu.git
synced 2026-11-21 06:50:59 +01:00
97 lines
4.1 KiB
Markdown
97 lines
4.1 KiB
Markdown
<img align="right" width="25%" src="logo.png">
|
|
|
|
# wgpu-rs
|
|
[](https://github.com/gfx-rs/wgpu-rs/actions)
|
|
[](https://crates.io/crates/wgpu)
|
|
[](https://docs.rs/wgpu)
|
|
|
|
[](https://matrix.to/#/#wgpu:matrix.org)
|
|
[](https://matrix.to/#/#wgpu-users:matrix.org)
|
|
|
|
wgpu-rs is an idiomatic Rust wrapper over [wgpu-core](https://github.com/gfx-rs/wgpu). 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](examples) directory.
|
|
|
|
These examples use the default syntax for running examples, as found in the [Cargo](https://doc.rust-lang.org/cargo/reference/manifest.html#examples) documentation. For example, to run the `cube` example:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](https://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`:
|
|
|
|
```bash
|
|
# 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
|
|
<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](https://gpuweb.github.io/gpuweb/wgsl.html) 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.
|
|
|
|
## Friends
|
|
|
|
See [our wiki](https://github.com/gfx-rs/wgpu-rs/wiki/Applications) for the list of libraries and applications using `wgpu`.
|
|
|
|
## 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":
|
|
|
|
```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`.
|