Improve examples documentation.

Better explain the shaders and runners, and explain how to invoke them,
and even document the `+`/`-` feature of the sky shader on ash, which
is currently invisible unless you read the code.

Author: nnethercote

examples/README.md

@@ -1,10 +1,59 @@
 # Examples
 
-The examples here are split into a few categories:
-
-- The shaders folder contain various rust-gpu shaders, and are examples of how to use rust-gpu.
-- The runners folder contains programs that build and execute the shaders in the shaders folder using, for example,
-  Vulkan. These programs are not exactly examples of how to use rust-gpu, as they're rather generic vulkan sample apps,
-  but they do contain some infrastructure examples of how to integrate rust-gpu shaders into a build system (although
-  both aren't the cleanest of examples, as they're also testing some of the more convoluted ways of consuming rust-gpu).
-- Finally, the multibuilder folder is a very short sample app of how to use the `multimodule` feature of `spirv-builder`.
+This directory contains several examples of rust-gpu use. There are shader
+examples in `shaders`, and runner programs that build and execute the shaders
+in a variety of ways in `runners`.
+
+The shaders:
+- **sky:** draws a landscape with a small white sun, blue sky, and yellow
+  ground. This is the default shader.
+- **simplest:** draws a red triangle on a green background.
+- **mouse:** a swirling animation that can be influenced by clicking and
+  dragging the mouse cursor.
+- **compute:** a compute shader that prints a sequence of integers from the
+  '3x+1' problem.
+
+The runners:
+- **WGPU:** runs the shader code on the GPU using [wgpu](https://wgpu.rs), a
+  graphics crate based on WebGPU.
+- **WGPU+wasm:** like WGPU but runs in a web browser.
+- **ash:** runs the shader code on the GPU using
+  [ash](https://crates.io/crates/ash), a Vulkan wrapper crate for Rust.
+- **CPU:** runs the shader code directly on the CPU, using rayon for
+  parallelism.
+
+Not all shaders work with all runners. The following combinations are
+supported.
+
+- WGPU runner:
+  - `cargo run --release -p example-runner-wgpu` runs the sky shader.
+  - `cargo run --release -p example-runner-wgpu -- --shader=sky` also runs the
+    sky shader.
+  - `cargo run --release -p example-runner-wgpu -- --shader=simplest` runs the
+    simplest shader.
+  - `cargo run --release -p example-runner-wgpu -- --shader=mouse` runs the
+    mouse shader.
+  - `cargo run --release -p example-runner-wgpu -- --shader=compute` runs the
+    compute shader.
+
+- WGPU+wasm runner in the browser (requires browser WebGPU support, most
+  recently tested with Chromium 140 on Linux):
+  - `rustup target add wasm32-unknown-unknown` installs the necessary wasm
+    support for Rust.
+  - `cargo run-wasm -p example-runner-wgpu` runs the local server hosting the
+    mouse shader.
+  - `chromium --enable-unsafe-webgpu http://localhost:8000` runs Chromium with
+    WebGPU enabled and views the mouse shader. (The mouse shader is the default
+    on WGPU+wasm.)
+
+- ash runner:
+  - `cargo run --release -p example-runner-ash` runs the sky shader. Use the up and
+    down arrows to adjust the sun's intensity. Use F5 to recompile the shader
+    code (but note that the image won't redraw afterwards unless the intensity is
+    adjusted).
+
+- CPU runner:
+  - `cargo run --release -p example-runner-cpu` runs the sky shader.
+
+Finally, the `multibuilder` folder is a very short example of how to use the
+`multimodule` feature of `spirv-builder`.