From 12ee31d6f90c016f47575d5088d1eb21f68ec827 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gerard=20Fabreg=C3=B3?= <40269083+roffs@users.noreply.github.com> Date: Sat, 25 Nov 2023 23:59:40 +0100 Subject: [PATCH] Update examples readme files (#4774) * Fix indentation in main examples readme file * Update examples readme files * Update hello_compute example readme and fix example not running with new command * Fix srgb_blend example not working correctly and set readme accordingly --- examples/README.md | 18 +++++++++--------- examples/src/boids/README.md | 2 +- examples/src/bunnymark/README.md | 12 ++++++++++++ examples/src/conservative_raster/README.md | 4 ++-- examples/src/cube/README.md | 2 +- examples/src/hello/README.md | 2 +- examples/src/hello_compute/README.md | 2 +- examples/src/hello_compute/mod.rs | 2 +- examples/src/hello_synchronization/README.md | 8 +++++++- examples/src/hello_triangle/README.md | 4 ++-- examples/src/hello_windows/README.md | 4 ++-- examples/src/hello_workgroups/README.md | 8 +++++++- examples/src/mipmap/README.md | 2 +- examples/src/msaa_line/README.md | 4 ++-- examples/src/render_to_texture/README.md | 10 ++++++++-- examples/src/repeated_compute/README.md | 8 +++++++- examples/src/shadow/README.md | 2 +- examples/src/skybox/README.md | 2 +- examples/src/srgb_blend/README.md | 10 +++++----- examples/src/srgb_blend/mod.rs | 2 +- examples/src/stencil_triangles/README.md | 4 ++-- examples/src/storage_texture/README.md | 9 ++++++++- examples/src/texture_arrays/README.md | 11 +++++++++++ examples/src/timestamp_queries/README.md | 4 ++-- examples/src/uniform_values/README.md | 8 +++++++- examples/src/water/README.md | 2 +- 26 files changed, 103 insertions(+), 43 deletions(-) create mode 100644 examples/src/bunnymark/README.md create mode 100644 examples/src/texture_arrays/README.md diff --git a/examples/README.md b/examples/README.md index 50e409e835..09a33bbbf0 100644 --- a/examples/README.md +++ b/examples/README.md @@ -19,20 +19,20 @@ The rest of the example are for demonstrating specific features that you can com #### Graphics - `hello-triangle` - Provides an example of a bare-bones WGPU workflow using the Winit crate that simply renders a red triangle on a green background. - - `uniform-values` - Demonstrates the basics of enabling shaders and the GPU in general to access app state through uniform variables. `uniform-values` also serves as an example of rudimentary app building as the app stores state and takes window-captured keyboard events. The app displays the Mandelbrot Set in grayscale (similar to `storage-texture`) but allows the user to navigate and explore it using their arrow keys and scroll wheel. - - `cube` - Introduces the user to slightly more advanced models. The example creates a set of triangles to form a cube on the CPU and then uses a vertex and index buffer to send the generated model to the GPU for usage in rendering. It also uses a texture generated on the CPU to shade the sides of the cube and a uniform variable to apply a transformation matrix to the cube in the shader. - - `bunnymark` - Demonstrates many things but chief among them, preforming numerous draw calls with different bind groups in one render pass. The example also uses textures for the icon and uniform buffers to transfer both global and per-particle state. - - `skybox` - Shows off too many concepts to list here. The name comes from game development where a "skybox" acts as a background for rendering, usually to add a sky texture for immersion although they can also be used for backdrops to give the idea of a world beyond of the game scene. This example does so much more than this though as it uses a car model loaded from a file and uses the user's mouse to rotate the car model in 3d. `skybox` also makes use of depth textures and similar app patterns to `uniform-values`. - - `shadow` - Likely by far the most complex example (certainly the largest in lines of code) of the official WGPU examples. `shadow` demonstrates basic scene rendering with the main attraction being lighting and shadows (as the name implies). It is recommended that any user looking into lighting be very familiar with the basic concepts of not only rendering with WGPU but the primary mathematical ideas of computer graphics. +- `uniform-values` - Demonstrates the basics of enabling shaders and the GPU in general to access app state through uniform variables. `uniform-values` also serves as an example of rudimentary app building as the app stores state and takes window-captured keyboard events. The app displays the Mandelbrot Set in grayscale (similar to `storage-texture`) but allows the user to navigate and explore it using their arrow keys and scroll wheel. +- `cube` - Introduces the user to slightly more advanced models. The example creates a set of triangles to form a cube on the CPU and then uses a vertex and index buffer to send the generated model to the GPU for usage in rendering. It also uses a texture generated on the CPU to shade the sides of the cube and a uniform variable to apply a transformation matrix to the cube in the shader. +- `bunnymark` - Demonstrates many things but chief among them, preforming numerous draw calls with different bind groups in one render pass. The example also uses textures for the icon and uniform buffers to transfer both global and per-particle state. +- `skybox` - Shows off too many concepts to list here. The name comes from game development where a "skybox" acts as a background for rendering, usually to add a sky texture for immersion although they can also be used for backdrops to give the idea of a world beyond of the game scene. This example does so much more than this though as it uses a car model loaded from a file and uses the user's mouse to rotate the car model in 3d. `skybox` also makes use of depth textures and similar app patterns to `uniform-values`. +- `shadow` - Likely by far the most complex example (certainly the largest in lines of code) of the official WGPU examples. `shadow` demonstrates basic scene rendering with the main attraction being lighting and shadows (as the name implies). It is recommended that any user looking into lighting be very familiar with the basic concepts of not only rendering with WGPU but the primary mathematical ideas of computer graphics. - `render-to-texture` - Renders to an image texture offscreen, demonstrating both off-screen rendering as well as how to add a sort of resolution-agnostic screenshot feature to an engine. This example either outputs an image file of your naming (pass command line arguments after specifying a `--` like `cargo run --bin render-to-texture -- "test.png"`) or adds an `img` element containing the image to the page in WASM. #### Compute - `hello-compute` - Demonstrates the basic workflow for getting arrays of numbers to the GPU, executing a shader on them, and getting the results back. The operation it preforms is finding the Collatz value (how many iterations of the [Collatz equation](https://en.wikipedia.org/wiki/Collatz_conjecture) it takes for the number to either reach 1 or overflow) of a set of numbers and prints the results. - - `repeated-compute` - Mostly for going into detail on subjects `hello-compute` did not. It, too, computes the Collatz conjecture but this time, it automatically loads large arrays of randomly generated numbers, prints them, runs them, and prints the result. It does this cycle 10 times. - - `hello-workgroups` - Teaches the user about the basics of compute workgroups; what they are and what they can do. - - `hello-synchronization` - Teaches the user about synchronization in WGSL, the ability to force all invocations in a workgroup to synchronize with each other before continuing via a sort of barrier. - - `storage-texture` - Demonstrates the use of storage textures as outputs to compute shaders. The example on the outside seems very similar to `render-to-texture` in that it outputs an image either to the file system or the web page except displaying a grayscale render of the Mandelbrot Set. However, inside, the example dispatches a grid of compute workgroups, one for each pixel which calculates the pixel value and stores it to the corresponding pixel of the output storage texture. +- `repeated-compute` - Mostly for going into detail on subjects `hello-compute` did not. It, too, computes the Collatz conjecture but this time, it automatically loads large arrays of randomly generated numbers, prints them, runs them, and prints the result. It does this cycle 10 times. +- `hello-workgroups` - Teaches the user about the basics of compute workgroups; what they are and what they can do. +- `hello-synchronization` - Teaches the user about synchronization in WGSL, the ability to force all invocations in a workgroup to synchronize with each other before continuing via a sort of barrier. +- `storage-texture` - Demonstrates the use of storage textures as outputs to compute shaders. The example on the outside seems very similar to `render-to-texture` in that it outputs an image either to the file system or the web page except displaying a grayscale render of the Mandelbrot Set. However, inside, the example dispatches a grid of compute workgroups, one for each pixel which calculates the pixel value and stores it to the corresponding pixel of the output storage texture. #### Combined diff --git a/examples/src/boids/README.md b/examples/src/boids/README.md index 7c75ee9848..5cd6bc2024 100644 --- a/examples/src/boids/README.md +++ b/examples/src/boids/README.md @@ -5,7 +5,7 @@ Flocking boids example with gpu compute update pass ## To Run ``` -cargo run --bin boids +cargo run --bin wgpu-examples boids ``` ## Screenshots diff --git a/examples/src/bunnymark/README.md b/examples/src/bunnymark/README.md new file mode 100644 index 0000000000..95083cd19d --- /dev/null +++ b/examples/src/bunnymark/README.md @@ -0,0 +1,12 @@ +# bunnymark + + +## To Run + +``` +cargo run --bin wgpu-examples bunnymark +``` + +## Example output + +![Example output](./screenshot.png) diff --git a/examples/src/conservative_raster/README.md b/examples/src/conservative_raster/README.md index bf79a9a168..9100a8bae4 100644 --- a/examples/src/conservative_raster/README.md +++ b/examples/src/conservative_raster/README.md @@ -1,4 +1,4 @@ -# conservative-raster +# conservative_raster This example shows how to render with conservative rasterization (native extension with limited support). @@ -12,7 +12,7 @@ Pixels only drawn with conservative rasterization enabled are depicted red. ## To Run ``` -cargo run --bin conservative-raster +cargo run --bin wgpu-examples conservative_raster ``` ## Screenshots diff --git a/examples/src/cube/README.md b/examples/src/cube/README.md index 3c1324958d..39af75ae78 100644 --- a/examples/src/cube/README.md +++ b/examples/src/cube/README.md @@ -5,7 +5,7 @@ This example renders a textured cube. ## To Run ``` -cargo run --bin cube +cargo run --bin wgpu-examples cube ``` ## Screenshots diff --git a/examples/src/hello/README.md b/examples/src/hello/README.md index 170f53538b..1d51a6b83b 100644 --- a/examples/src/hello/README.md +++ b/examples/src/hello/README.md @@ -5,7 +5,7 @@ This example prints output describing the adapter in use. ## To Run ``` -cargo run --bin hello +cargo run --bin wgpu-examples hello ``` ## Example output diff --git a/examples/src/hello_compute/README.md b/examples/src/hello_compute/README.md index ee34a94838..8b3f3e111d 100644 --- a/examples/src/hello_compute/README.md +++ b/examples/src/hello_compute/README.md @@ -12,7 +12,7 @@ that it will take to finish and reach the number `1`. ``` # Pass in any 4 numbers as arguments -RUST_LOG=hello_compute cargo run --bin hello-compute 1 4 3 295 +RUST_LOG=hello_compute cargo run --bin wgpu-examples hello_compute 1 4 3 295 ``` ## Example Output diff --git a/examples/src/hello_compute/mod.rs b/examples/src/hello_compute/mod.rs index f957c6333d..d93d804ef1 100644 --- a/examples/src/hello_compute/mod.rs +++ b/examples/src/hello_compute/mod.rs @@ -12,7 +12,7 @@ async fn run() { default } else { std::env::args() - .skip(1) + .skip(2) .map(|s| u32::from_str(&s).expect("You must pass a list of positive integers!")) .collect() }; diff --git a/examples/src/hello_synchronization/README.md b/examples/src/hello_synchronization/README.md index 41c7d0d34a..5750801f14 100644 --- a/examples/src/hello_synchronization/README.md +++ b/examples/src/hello_synchronization/README.md @@ -1,9 +1,15 @@ -# hello-synchronization +# hello_synchronization This example is 1. A small demonstration of the importance of synchronization. 2. How basic synchronization you can understand from the CPU is preformed on the GPU. +## To Run + +``` +cargo run --bin wgpu-examples hello_synchronization +``` + ## A Primer on WGSL Synchronization Functions The official documentation is a little scattered and sparse. The meat of the subject is found [here](https://www.w3.org/TR/2023/WD-WGSL-20230629/#sync-builtin-functions) but there's also a bit on control barriers [here](https://www.w3.org/TR/2023/WD-WGSL-20230629/#control-barrier). The most important part comes from that first link though, where the spec says "the affected memory and atomic operations program-ordered before the synchronization function must be visible to all other threads in the workgroup before any affected memory or atomic operation program-ordered after the synchronization function is executed by a member of the workgroup." And at the second, we also get "a control barrier is executed by all invocations in the same workgroup as if it were executed concurrently." diff --git a/examples/src/hello_triangle/README.md b/examples/src/hello_triangle/README.md index 31425c0679..52daa8164e 100644 --- a/examples/src/hello_triangle/README.md +++ b/examples/src/hello_triangle/README.md @@ -1,11 +1,11 @@ -# hello-triangle +# hello_triangle This example renders a triangle to a window. ## To Run ``` -cargo run --bin hello-triangle +cargo run --bin wgpu-examples hello_triangle ``` ## Screenshots diff --git a/examples/src/hello_windows/README.md b/examples/src/hello_windows/README.md index c483b79acb..6e1abd5819 100644 --- a/examples/src/hello_windows/README.md +++ b/examples/src/hello_windows/README.md @@ -1,11 +1,11 @@ -# hello-windows +# hello_windows This example renders a set of 16 windows, with a differently colored background ## To Run ``` -cargo run --bin hello-windows +cargo run --bin wgpu-examples hello_windows ``` ## Screenshots diff --git a/examples/src/hello_workgroups/README.md b/examples/src/hello_workgroups/README.md index 5b913af06d..e7bcad2834 100644 --- a/examples/src/hello_workgroups/README.md +++ b/examples/src/hello_workgroups/README.md @@ -1,4 +1,4 @@ -# hello-workgroups +# hello_workgroups Now you finally know what that silly little `@workgroup_size(1)` means! @@ -6,6 +6,12 @@ This example is an extremely bare-bones and arguably somewhat unreasonable demon The example starts with two arrays of numbers. One where `a[i] = i` and the other where `b[i] = 2i`. Both are bound to the shader. The program dispatches a workgroup for each index, each workgroup representing both elements at that index in both arrays. Each invocation in each workgroup works on its respective array and adds 1 to the element there. +## To Run + +``` +cargo run --bin wgpu-examples hello_workgroups +``` + ## What are Workgroups? ### TLDR / Key Takeaways diff --git a/examples/src/mipmap/README.md b/examples/src/mipmap/README.md index 547df30c5d..d77009bc64 100644 --- a/examples/src/mipmap/README.md +++ b/examples/src/mipmap/README.md @@ -5,7 +5,7 @@ This example shows how to generate and make use of mipmaps. ## To Run ``` -cargo run --bin mipmap +cargo run --bin wgpu-examples mipmap ``` ## Screenshots diff --git a/examples/src/msaa_line/README.md b/examples/src/msaa_line/README.md index f0c63314f0..24aae95ee1 100644 --- a/examples/src/msaa_line/README.md +++ b/examples/src/msaa_line/README.md @@ -1,11 +1,11 @@ -# msaa-line +# msaa_line This example shows how to render lines using MSAA. ## To Run ``` -cargo run --bin msaa-line +cargo run --bin wgpu-examples msaa_line ``` ## Screenshots diff --git a/examples/src/render_to_texture/README.md b/examples/src/render_to_texture/README.md index dbc1943234..04bb3fff44 100644 --- a/examples/src/render_to_texture/README.md +++ b/examples/src/render_to_texture/README.md @@ -1,5 +1,11 @@ -# render-to-texture +# render_to_texture Similar to hello-triangle but instead of rendering to a window or canvas, renders to a texture that is then output as an image like the storage-texture example. -If all goes well, the end result should look familiarly like hello-triangle with its red triangle on a green background. \ No newline at end of file +If all goes well, the end result should look familiarly like hello-triangle with its red triangle on a green background. + +## To Run + +``` +cargo run --bin wgpu-examples render_to_texture +``` diff --git a/examples/src/repeated_compute/README.md b/examples/src/repeated_compute/README.md index 26e247c17e..874903760d 100644 --- a/examples/src/repeated_compute/README.md +++ b/examples/src/repeated_compute/README.md @@ -1,7 +1,13 @@ -# repeated-compute +# repeated_compute Repeatedly performs the Collatz calculation used in `hello-compute` on sets of random numbers. +## To Run + +``` +cargo run --bin wgpu-examples repeated_compute +``` + ## Sample Randomly generated input: diff --git a/examples/src/shadow/README.md b/examples/src/shadow/README.md index 3298975b8d..86435a7289 100644 --- a/examples/src/shadow/README.md +++ b/examples/src/shadow/README.md @@ -5,7 +5,7 @@ This animated example demonstrates shadow mapping. ## To Run ``` -cargo run --bin shadow +cargo run --bin wgpu-examples shadow ``` ## Screenshots diff --git a/examples/src/skybox/README.md b/examples/src/skybox/README.md index 7fe9de1df6..2e7e8d3174 100644 --- a/examples/src/skybox/README.md +++ b/examples/src/skybox/README.md @@ -6,7 +6,7 @@ It hooks up `winit` mouse controls for camera rotation around the model at the c ## To Run ``` -cargo run --bin skybox +cargo run --bin wgpu-examples skybox ``` ## Screenshots diff --git a/examples/src/srgb_blend/README.md b/examples/src/srgb_blend/README.md index abf8b23ebf..ebb3ee8150 100644 --- a/examples/src/srgb_blend/README.md +++ b/examples/src/srgb_blend/README.md @@ -1,23 +1,23 @@ -# cube +# srgb_blend This example shows blending in sRGB or linear space. ## To Run ``` -cargo run --bin cube -- linear +cargo run --bin wgpu-examples srgb_blend linear ``` ``` -cargo run --bin cube +cargo run --bin wgpu-examples srgb_blend ``` ## Screenshots Blending in linear space: -![sRGB blend example](./screenshot-srgb.png) +![sRGB blend example](./screenshot-linear.png) Blending in sRGB space: -![sRGB blend example](./screenshot-linear.png) +![sRGB blend example](./screenshot-srgb.png) diff --git a/examples/src/srgb_blend/mod.rs b/examples/src/srgb_blend/mod.rs index 803a43a1c2..d4021e6c5f 100644 --- a/examples/src/srgb_blend/mod.rs +++ b/examples/src/srgb_blend/mod.rs @@ -214,7 +214,7 @@ impl crate::framework::Example for Example { pub fn main() { let mut args = std::env::args(); args.next(); - if Some("linear") == args.next().as_deref() { + if Some("linear") == args.nth(1).as_deref() { crate::framework::run::>("srgb-blend-linear"); } else { crate::framework::run::>("srgb-blend-srg"); diff --git a/examples/src/stencil_triangles/README.md b/examples/src/stencil_triangles/README.md index 4b6842e091..e7c8c87a3d 100644 --- a/examples/src/stencil_triangles/README.md +++ b/examples/src/stencil_triangles/README.md @@ -1,4 +1,4 @@ -# hello-triangle +# stencil_triangles This example renders two different sized triangles to display three same sized triangles, by demonstrating the use of stencil buffers. @@ -10,7 +10,7 @@ Then, it draws a larger "outer" triangle which only touches pixels where the ste ## To Run ``` -cargo run --bin stencil-triangles +cargo run --bin wgpu-examples stencil_triangles ``` ## Screenshots diff --git a/examples/src/storage_texture/README.md b/examples/src/storage_texture/README.md index 51592c66a5..092fb69418 100644 --- a/examples/src/storage_texture/README.md +++ b/examples/src/storage_texture/README.md @@ -1,7 +1,14 @@ -# storage-texture +# storage_texture A simple example that uses a storage texture to compute an image of the Mandelbrot set (https://en.wikipedia.org/wiki/Mandelbrot_set) and either saves it as an image or presents it to the browser screen in such a way that it can be saved as an image. +## To Run + +``` +cargo run --bin wgpu-examples storage_texture +``` + + ## Example Output ![Example output](./example.png) \ No newline at end of file diff --git a/examples/src/texture_arrays/README.md b/examples/src/texture_arrays/README.md new file mode 100644 index 0000000000..ddc63a78b2 --- /dev/null +++ b/examples/src/texture_arrays/README.md @@ -0,0 +1,11 @@ +# texture_arrays + +## To Run + +``` +cargo run --bin wgpu-examples texture_arrays +``` + +## Example Output + +![Example output](./screenshot.png) \ No newline at end of file diff --git a/examples/src/timestamp_queries/README.md b/examples/src/timestamp_queries/README.md index 1c95ff9f11..18cf292538 100644 --- a/examples/src/timestamp_queries/README.md +++ b/examples/src/timestamp_queries/README.md @@ -1,9 +1,9 @@ -# timestamp-queries +# timestamp_queries This example shows various ways of querying time when supported. ## To Run ``` -cargo run --bin timestamp-queries +cargo run --bin wgpu-examples timestamp_queries ``` diff --git a/examples/src/uniform_values/README.md b/examples/src/uniform_values/README.md index 19514e1e6f..cbf34ae4df 100644 --- a/examples/src/uniform_values/README.md +++ b/examples/src/uniform_values/README.md @@ -1,7 +1,13 @@ -# uniform-values +# uniform_values Creates a window which displays a grayscale render of the [Mandelbrot set](https://en.wikipedia.org/wiki/Mandelbrot_set). Pressing the arrow keys will translate the set and scrolling the mouse wheel will zoom in and out. If the image appears too 'bright', it may be because you are using too few iterations or 'samples'. Use U and D to increase or decrease respectively the max number of iterations used. Make sure to play around with this too to get an optimally photogenic screen cap. The window can be resized and pressing ESC will close the window. Explore the Mandelbrot set using the power of uniform variables to transfer state from the main program to the shader! +## To Run + +``` +cargo run --bin wgpu-examples uniform_values +``` + ## Usage of Uniform Buffers / Variables Since the codebase of this example is so large (because why not demonstrate with a sort-of game) and the points of interest in terms of the actual point of the example so small, there is a module doc comment at the top of main.rs that points out the important points of the usage of uniform values. diff --git a/examples/src/water/README.md b/examples/src/water/README.md index 79934430a8..9ad0501f27 100644 --- a/examples/src/water/README.md +++ b/examples/src/water/README.md @@ -19,7 +19,7 @@ water ## To run ``` -cargo run --bin water +cargo run --bin wgpu-examples water ``` ## Screenshot