From 0dc7e60d0e894382c3026603c8772d59d1a4f0dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=ADn=20Maita?= <47983254+mnmaita@users.noreply.github.com> Date: Wed, 18 Oct 2023 14:30:44 -0300 Subject: [PATCH] Improve WebGPU unstable flags docs (#10163) # Objective - Fixes #9382 ## Solution - Added a few extra notes in regards to WebGPU experimental state and the need of enabling unstable APIs through certain attribute flags in `cargo_features.md` and the examples `README.md` files. --- Cargo.toml | 2 +- docs-template/EXAMPLE_README.md.tpl | 8 ++++++++ docs/cargo_features.md | 2 +- examples/README.md | 8 ++++++++ 4 files changed, 18 insertions(+), 2 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index d5b1e219e4..745a02e02d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -241,7 +241,7 @@ shader_format_glsl = ["bevy_internal/shader_format_glsl"] # Enable support for shaders in SPIR-V shader_format_spirv = ["bevy_internal/shader_format_spirv"] -# Enable some limitations to be able to use WebGL2. If not enabled, it will default to WebGPU in Wasm +# Enable some limitations to be able to use WebGL2. If not enabled, it will default to WebGPU in Wasm. Please refer to the [WebGL2 and WebGPU](https://github.com/bevyengine/bevy/tree/latest/examples#webgl2-and-webgpu) section of the examples README for more information on how to run Wasm builds with WebGPU. webgl2 = ["bevy_internal/webgl"] # Enables watching the filesystem for Bevy Asset hot-reloading diff --git a/docs-template/EXAMPLE_README.md.tpl b/docs-template/EXAMPLE_README.md.tpl index 7309f21fe5..98336d4aff 100644 --- a/docs-template/EXAMPLE_README.md.tpl +++ b/docs-template/EXAMPLE_README.md.tpl @@ -240,6 +240,14 @@ Bevy support for WebGPU is being worked on, but is currently experimental. To build for WebGPU, you'll need to disable default features and add all those you need, making sure to omit the `webgl2` feature. +WebGPU depends on unstable APIs so you will also need to pass the `web_sys_unstable_apis` flag to your builds. For example: + +```sh +RUSTFLAGS=--cfg=web_sys_unstable_apis cargo build ... +``` + +Check `wasm-bindgen` [docs on Unstable APIs](https://rustwasm.github.io/wasm-bindgen/web-sys/unstable-apis.html) for more details. + Bevy has an helper to build its examples: - Build for WebGL2: `cargo run -p build-wasm-example -- --api webgl2 load_gltf` diff --git a/docs/cargo_features.md b/docs/cargo_features.md index f17962cc2d..fcc808036c 100644 --- a/docs/cargo_features.md +++ b/docs/cargo_features.md @@ -34,7 +34,7 @@ The default feature set enables most of the expected features of a game engine, |png|PNG image format support| |tonemapping_luts|Include tonemapping Look Up Tables KTX2 files| |vorbis|OGG/VORBIS audio format support| -|webgl2|Enable some limitations to be able to use WebGL2. If not enabled, it will default to WebGPU in Wasm| +|webgl2|Enable some limitations to be able to use WebGL2. If not enabled, it will default to WebGPU in Wasm. Please refer to the [WebGL2 and WebGPU](https://github.com/bevyengine/bevy/tree/latest/examples#webgl2-and-webgpu) section of the examples README for more information on how to run Wasm builds with WebGPU.| |x11|X11 display server support| |zstd|For KTX2 supercompression| diff --git a/examples/README.md b/examples/README.md index 596d9fac42..fde3898480 100644 --- a/examples/README.md +++ b/examples/README.md @@ -544,6 +544,14 @@ Bevy support for WebGPU is being worked on, but is currently experimental. To build for WebGPU, you'll need to disable default features and add all those you need, making sure to omit the `webgl2` feature. +WebGPU depends on unstable APIs so you will also need to pass the `web_sys_unstable_apis` flag to your builds. For example: + +```sh +RUSTFLAGS=--cfg=web_sys_unstable_apis cargo build ... +``` + +Check `wasm-bindgen` [docs on Unstable APIs](https://rustwasm.github.io/wasm-bindgen/web-sys/unstable-apis.html) for more details. + Bevy has an helper to build its examples: - Build for WebGL2: `cargo run -p build-wasm-example -- --api webgl2 load_gltf`