wgpu/documentation/platforms/
web.rs

1/*!
2# Running on the Web (WebGPU and WebGL)
3
4`wgpu` can run in the browser by compiling to WebAssembly, targeting either
5WebGPU (where available) or the WebGL2 backend as a fallback. The WebGL2
6backend is still missing some features compared to the native and WebGPU
7backends.
8
9## Running the examples
10
11### Installing the Rust WebAssembly target
12
13To build the `wgpu` examples for execution in a browser, you must first
14install the Rust toolchain for the `wasm32-unknown-unknown` target. Using
15`rustup`:
16
17```bash
18rustup target add wasm32-unknown-unknown
19```
20
21### Using `cargo xtask run-wasm`
22
23The simplest way to run the examples on the web is the `run-wasm` xtask:
24
25```bash
26cargo xtask run-wasm
27```
28
29This builds the `wgpu-examples` crate for `wasm32-unknown-unknown` (both the
30WebGPU and WebGL2 variants), runs `wasm-bindgen` on the output, and serves
31the result. It requires
32[`wasm-bindgen-cli`](https://crates.io/crates/wasm-bindgen-cli) and
33[`simple-http-server`](https://crates.io/crates/simple-http-server) to be
34installed. Once it's running, open <http://127.0.0.1:8000> in your browser
35and pick an example.
36
37> **Note:** the server binds to `127.0.0.1` on purpose. WebGPU requires a
38> [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts),
39> which `127.0.0.1` satisfies but `0.0.0.0` does not.
40
41### WebGPU browser support
42
43WebGPU is available in current versions of Chrome and other Chromium-based
44browsers, and is shipping or in progress elsewhere. For up-to-date
45implementation status, check [webgpu.io](https://webgpu.io) or
46[caniuse.com/webgpu](https://caniuse.com/webgpu). Note that `wgpu` is often
47ahead of browsers in catching up with upstream WebGPU API changes.
48
49## Manual compilation with `wasm-bindgen-cli`
50
51If you'd rather not use the xtask, you can reproduce what it does by hand.
52First install the version of `wasm-bindgen-cli` that matches the version
53used by `wgpu` (check the workspace `Cargo.lock`):
54
55```bash
56cargo install -f wasm-bindgen-cli --version <matching version>
57```
58
59Then build the examples for `wasm32-unknown-unknown` and run `wasm-bindgen`
60on the output. For WebGPU:
61
62```bash
63cargo build --target wasm32-unknown-unknown -p wgpu-examples --no-default-features --features webgpu
64wasm-bindgen target/wasm32-unknown-unknown/debug/wgpu-examples.wasm \
65    --target web --no-typescript --out-dir target/generated --out-name webgpu
66```
67
68For WebGL2, swap the `webgpu` feature for `webgl` and the `--out-name`
69accordingly:
70
71```bash
72cargo build --target wasm32-unknown-unknown -p wgpu-examples --no-default-features --features webgl
73wasm-bindgen target/wasm32-unknown-unknown/debug/wgpu-examples.wasm \
74    --target web --no-typescript --out-dir target/generated --out-name webgl2
75```
76
77### Setting up the page
78
79Create an `index.html` file in the `target/generated` directory that loads
80the generated module:
81
82```html
83<!DOCTYPE html>
84<html>
85  <head>
86    <meta charset="UTF-8" />
87    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
88  </head>
89  <body>
90    <script type="module">
91      import init from "./webgpu.js"; // or "./webgl2.js"
92      init();
93    </script>
94  </body>
95</html>
96```
97
98### Running the code
99
100Now run a web server locally inside the `target/generated` directory to view
101the example in the browser. A secure context is required for WebGPU, so
102serve from `127.0.0.1` (or `localhost`), for example with
103[`simple-http-server`](https://crates.io/crates/simple-http-server):
104
105```bash
106simple-http-server target/generated -c wasm,html,js -i --coep --coop --ip 127.0.0.1
107```
108
109The `--coep` and `--coop` flags set the cross-origin isolation headers some
110features require.
111*/
wgpu/documentation/platforms/web.rs

wgpu/documentation/platforms/
web.rs
