Improve WebGPU unstable flags docs #10163

mnmaita · 2023-10-17T19:32:18Z

Objective

Fixes Mention --cfg=web_sys_unstable_apis in WebGPU build instructions #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.

mnmaita · 2023-10-17T19:33:47Z

examples/README.md

@@ -539,10 +539,18 @@ ruby -run -ehttpd examples/wasm

 #### WebGL2 and WebGPU

-Bevy support for WebGPU is being worked on, but is currently experimental.
+Bevy ships with WebGPU by default, but it is being worked on and 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.


I'm wondering if this statement is still true... Wouldn't WebGPU be enabled by default if one does not define any features and roll with bevy defaults? I can verify this sometime this week but if someone knows... Please leave a comment!

This is still true. The webgl2 feature is included in our default features.

Ah, thanks for the heads up. I re-reviewed the default feature list and now I understand. I'll adjust the language I've introduced in the previous paragraph accordingly.

github-actions · 2023-10-17T19:51:04Z

The generated examples/README.md is out of sync with the example metadata in Cargo.toml or the example readme template. Please run cargo run -p build-templated-pages -- update examples to update it, and commit the file change.

mnmaita · 2023-10-17T19:56:36Z

I realized I shouldn't update the examples/README.md file itself, but a template. Wondering if said file is docs-template\EXAMPLE_README.md.tpl?

rparrett · 2023-10-17T21:00:14Z

Wondering if said file is docs-template\EXAMPLE_README.md.tpl?

Yep!

Also, cargo_features.md is built using a similar process from the comments in Cargo.toml. That can be updated with cargo run -p build-templated-pages -- update features.

mnmaita · 2023-10-17T21:02:44Z

Wondering if said file is docs-template\EXAMPLE_README.md.tpl?

Yep!

Also, cargo_features.md is built using a similar process from the comments in Cargo.toml. That can be updated with cargo run -p build-templated-pages -- update features.

Thanks for clarifying! I'll make the changes tomorrow. Any suggestions to improve the language in the meantime will be welcomed.

rparrett · 2023-10-17T21:02:54Z

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|Given the fact that WebGPU support in Bevy is experimental, this feature will enable some limitations to be able to use WebGL2. If not enabled, it will default to WebGPU in Wasm. Keep in mind that that WebGPU depends on unstable APIs so you will also need to pass the `web_sys_unstable_apis` flag to your builds (e.g. `RUSTFLAGS=--cfg=web_sys_unstable_apis cargo run ...`). Check `wasm-bindgen` [docs on Unstable APIs](https://rustwasm.github.io/wasm-bindgen/web-sys/unstable-apis.html) for more details.|


This feels like a lot for this feature table. Maybe we could just link off to the WebGL2 and WebGPU in the examples readme?

nicopap

Once @rparrett concerns are fixed, I think it can be merged.

mnmaita · 2023-10-18T13:56:46Z

@rparrett @nicopap updated both templates, rolled back a statement that was wrong and applied the suggestion.

docs-template/EXAMPLE_README.md.tpl

github-actions · 2023-10-18T14:18:20Z

You added a new feature but didn't update the readme. Please run cargo run -p build-templated-pages -- update features to update it, and commit the file change.

mnmaita · 2023-10-18T14:20:48Z

You added a new feature but didn't update the readme. Please run cargo run -p build-templated-pages -- update features to update it, and commit the file change.

Weird, since I didn't change the features this time 😆

mockersf · 2023-10-18T16:48:44Z

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](../examples/README.md) section of the examples README for more information on how to run Wasm builds with WebGPU.


this doc is published here: https://docs.rs/bevy/latest/bevy/#default-features
how does that link works from docs.rs?

Ah, I didn't know this. Would linking to the file on the latest branch work better?

oops, yeah. what about linking straight to to https://github.com/bevyengine/bevy/tree/latest/examples#webgl2-and-webgpu? edit: sorry, couple minutes late to the party.

No prob. And how did I miss adding the reference to the heading? 🤦🏻 My bad! I'll fix both suggestions in a moment.

Fixed in 11a1caa

mockersf · 2023-10-18T16:49:22Z

docs-template/EXAMPLE_README.md.tpl

+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 run ...


Suggested change

RUSTFLAGS=--cfg=web_sys_unstable_apis cargo run ...

RUSTFLAGS=--cfg=web_sys_unstable_apis cargo build ...

cargo run doesn't work without extra config for wasm

Changed in 2f1d566

# Objective - Fixes bevyengine#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.

mnmaita commented Oct 17, 2023

View reviewed changes

mnmaita mentioned this pull request Oct 17, 2023

Mention --cfg=web_sys_unstable_apis in WebGPU build instructions #9382

Closed

mnmaita added C-Docs An addition or correction to our documentation O-Web Specific to web (WASM) builds O-WebGPU Specific to the WebGPU render API labels Oct 17, 2023

rparrett reviewed Oct 17, 2023

View reviewed changes

nicopap approved these changes Oct 18, 2023

View reviewed changes

mnmaita added 4 commits October 18, 2023 15:51

Explain web_sys_unstable_apis flag usage in cargo_features.md

0ccd471

Explain web_sys_unstable_apis flag usage in examples README.md

40a369b

Update webgl2 feature description and cargo_features.md

fd85007

Update examples README template and rolls back incorrect statement

a08937b

mnmaita force-pushed the web-gpu-docs branch from 03d79c3 to a08937b Compare October 18, 2023 13:51

Fix examples/README.md link

c2fc013

mnmaita force-pushed the web-gpu-docs branch from a403b7f to c2fc013 Compare October 18, 2023 14:03

rparrett reviewed Oct 18, 2023

View reviewed changes

docs-template/EXAMPLE_README.md.tpl Outdated Show resolved Hide resolved

Apply language suggestion

58c9cac

rparrett approved these changes Oct 18, 2023

View reviewed changes

mockersf reviewed Oct 18, 2023

View reviewed changes

mnmaita added 2 commits October 18, 2023 19:05

Fix link to examples README file for cargo_features.md file

11a1caa

Swapped cargo run to cargo build in examples README template

2f1d566

mockersf approved these changes Oct 18, 2023

View reviewed changes

mockersf added the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label Oct 18, 2023

mockersf enabled auto-merge October 18, 2023 17:13

mockersf added this pull request to the merge queue Oct 18, 2023

Merged via the queue into bevyengine:main with commit 0dc7e60 Oct 18, 2023
26 checks passed

alice-i-cecile mentioned this pull request Mar 2, 2024

Update wgpu to v0.19.3 and unpin web-sys. #12247

Merged

mnmaita deleted the web-gpu-docs branch March 30, 2024 13:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve WebGPU unstable flags docs #10163

Improve WebGPU unstable flags docs #10163

mnmaita commented Oct 17, 2023

mnmaita Oct 17, 2023

rparrett Oct 17, 2023

mnmaita Oct 17, 2023

github-actions bot commented Oct 17, 2023

mnmaita commented Oct 17, 2023

rparrett commented Oct 17, 2023

mnmaita commented Oct 17, 2023

rparrett Oct 17, 2023

nicopap left a comment

mnmaita commented Oct 18, 2023

github-actions bot commented Oct 18, 2023

mnmaita commented Oct 18, 2023

mockersf Oct 18, 2023

mnmaita Oct 18, 2023

mockersf Oct 18, 2023

rparrett Oct 18, 2023 •

edited

Loading

mnmaita Oct 18, 2023

mnmaita Oct 18, 2023

mockersf Oct 18, 2023

mnmaita Oct 18, 2023

	RUSTFLAGS=--cfg=web_sys_unstable_apis cargo run ...
	RUSTFLAGS=--cfg=web_sys_unstable_apis cargo build ...

Improve WebGPU unstable flags docs #10163

Improve WebGPU unstable flags docs #10163

Conversation

mnmaita commented Oct 17, 2023

Objective

Solution

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Oct 17, 2023

mnmaita commented Oct 17, 2023

rparrett commented Oct 17, 2023

mnmaita commented Oct 17, 2023

Choose a reason for hiding this comment

nicopap left a comment

Choose a reason for hiding this comment

mnmaita commented Oct 18, 2023

github-actions bot commented Oct 18, 2023

mnmaita commented Oct 18, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rparrett Oct 18, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rparrett Oct 18, 2023 •

edited

Loading