mirror of
https://github.com/gfx-rs/wgpu.git
synced 2024-11-22 06:44:14 +00:00
79a6f2cd31
* fix more compile errors * fix err * fix all compile errors * fix clippy errors * fix issues in ray-traced-triangle example * fix clippy warnings * fix wasm not compiling * fix test * fix clippy (again) * fix some rustfmt issues * fix more rustfmt issues * fix even more rustfmt issues * fix yet more rustfmt issues * add #[allow(dead_code)] to some structs to fix clippy on web assembly * more format fixes * even more format fixes * close to final format fixes * final format fixes (hopefully) * actual final format fixes (hopefully) * move ray_cube_cube example and fix bugs * move other examples * fix crash when dropping * fix test * apply clippy and rustfmt changes * fix some memory leaks * fix incompatibility with new wgpu trunk changes * fix clippy & fmt * fix clippy errors on github * update to trunk * remove a line that printed log "Created blas ..." in device create tlas * fix merge issues * fix merge * fix fmt * restored example ray scene functionality * WIP fix rebase * Fix compile issues * More fixes * Fix rebase * Add wgls backend write_value_type AccelerationStructure * Add back xtask Cargo.lock * Revert serde path * Doc typos * Add -diff * Revert more serde * Revert serde again? * Fix doc typo * add test * clippy & fmt * fix error "blas does not exist" * fix various things * fix unused acceleration structures causing invalid SPIR-V * fix merge * fix use after free in a different way (now moved tlas instances to wgpu_core) * refactor & fmt * remove accidentally created file * remove accidentally created file (actually) * merge & fix * Fix problems * fix validation error * fix validation * fix merge * fmt * fix merge * use staging buffer trackers in creating the ray-tracing staging buffers (not the tlas_s) * change one missed staging buffer's tracker * wip: example * finished shadow! * fix merge * clippy * remove some uses of blas ids * fmt * fix merge * deduplicate code shared between command_encoder_build_acceleration_structures and command_encoder_build_acceleration_structures_unsafe_tlas * clippy * fix merge * fix warnings * clippy & fmt * re-add matching to get_raw_tlas_instance_size and tlas_instance_into_bytes * fmt * fix command * wip: fix merge * fix merge * fmt & docs * fix wasm clippy * fix issues with tests * fix issues with tests * fmt & clippy (wasm) * wip ray-traced-triangle (non hal) * unify camera location in ray_shadows * fix tests * add readme to ray_traced_triangle * note that vertex format must be f32x3 (not yet validated) * changelog * require VertexFormat::Float32x3 * fix compile error * when creating and building acceleration structures require Features::RAY_TRACING_ACCELERATION_STRUCTURE is enabled * remove duplicate workaround * fix most feedback * remove all changes from .gitattributes * fix compile error in test * more changes along same lines * format * apply feedback to more places * fix `cargo clippy` not just `cargo clippy --all-features` * cache max instances from tlas creation * fix clippy * fix examples * fix tests * remove now useless docs * add more docs * yet more docs * still more docs * Documentation. * Running out of unique commit messages to say writing docs. * Add more references to docs. * Get BindGroup in scope * Remove unintentional changes * Remove #[allow(dead_code)] * Remove old comments * Add device.poll * make ray_scene start right way up * fmt * move scratch buffer to its own module * actually remove intentional changes (turns out wgt is inconsistent) * use better names in ray_scene/shader.wgsl * fmt * remove more unintentional changes. * work on ray_tracing use after free * spelling Co-authored-by: Connor Fitzgerald <connorwadefitzgerald@gmail.com> * grammar Co-authored-by: Connor Fitzgerald <connorwadefitzgerald@gmail.com> * move things into struct (should be all vectors with 3 item types or more) * remove long-standing locks. * fmt * move not using index buffer to test * impl index & index mut for tlas package * impl index & index mut for tlas package * fix errors * fix test errors * move everything out of ray_tracing.rs * more index_mut * fmt * fix docs links * move to separate impl block * fix older request review * fmt * remove missed deref * fix wasm clippy * change to suggestions * fmt * add a note as to why `command_encoder_build_acceleration_structures_unsafe_tlas` and `command_encoder_build_acceleration_structures` are currently separate * add a todo to reconsider soon `command_encoder_build_acceleration_structures_unsafe_tlas` * switch to mat4 in ray-tracing examples * Combine RT Tests Under Single Submodule * Add More Raytracing Tests and Re-Organize * Documentation and Formatting Fixes * Remove Forced Alignment in wgpu-hal * work on out_of_order_as_build and add out_of_order_as_build_use * fmt * update test label naming * fix one validation error * fix clippy & fmt * add acceleration structure creation tests * make mis-matched index test use the correct function * move validation into validate_command_buffer * fix tests * add blas and tlas to pending writes to remove (now unneeded) `device.poll()`s * remove commented out code from examples and properly use the constants in ray_shadow * add examples to examples\README.md * rename ray tracing to ray queries in readme * remove unneeded usage from scratch buffer creation * use snatchables for raw acceleration structures * format * add EXPERIMENTAL_ to features * fix missed comment --------- Co-authored-by: Daniel Keitel <daniel.mg.keitel@fau.de> Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com> Co-authored-by: atlas dostal <rodol@rivalrebels.com> Co-authored-by: vero <email@atlasdostal.com> Co-authored-by: Connor Fitzgerald <connorwadefitzgerald@gmail.com>
112 lines
22 KiB
Markdown
112 lines
22 KiB
Markdown
## Structure
|
|
|
|
For the simplest examples without using any helping code (see `framework.rs` here), check out:
|
|
|
|
- `hello` for printing adapter information
|
|
- `hello_triangle` for graphics and presentation
|
|
- `hello_compute` for pure computing
|
|
|
|
### Summary of examples
|
|
|
|
A summary of the basic examples as split along the graphics and compute "pathways" laid out roughly in order of building on each other. Those further indented, and thus more roughly dependent on more other examples, tend to be more complicated as well as those further down. It should be noted, though, that computing examples, even though they are mentioned further down (because rendering to a window is by far the most common use case), tend to be less complex as they require less surrounding context to create and manage a window to render to.
|
|
|
|
The rest of the examples are for demonstrating specific features that you can come back for later when you know what those features are.
|
|
|
|
#### General
|
|
|
|
- `hello` - Demonstrates the basics of the WGPU library by getting a default Adapter and debugging it to the screen
|
|
|
|
#### 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 is performing 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 states.
|
|
- `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 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 also 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 wgpu-examples -- render_to_texture "test.png"`) or adds an `img` element containing the image to the page in WASM.
|
|
- `ray_cube_fragment` - Demonstrates using ray queries with a fragment shader.
|
|
- `ray_scene` - Demonstrates using ray queries and model loading
|
|
- `ray_shadows` - Demonstrates a simple use of ray queries - high quality shadows - uses a light set with push constants to raytrace through an untransformed scene and detect whether there is something obstructing the light.
|
|
|
|
#### 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 performs 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. This example either outputs an image file of your naming (pass command line arguments after specifying a `--` like `cargo run --bin wgpu-examples -- storage_texture "test.png"`) or adds an `img` element containing the image to the page in WASM.
|
|
|
|
#### Combined
|
|
|
|
- `boids` - Demonstrates how to combine compute and render workflows by performing a [boid](https://en.wikipedia.org/wiki/Boids) simulation and rendering the boids to the screen as little triangles.
|
|
- `ray_cube_compute` - Demonstrates using ray queries with a compute shader.
|
|
- `ray_traced_triangle` - A simpler example demonstrating using ray queries with a compute shader
|
|
|
|
## Feature matrix
|
|
|
|
| Feature | boids | bunnymark | conservative_raster | cube | hello_synchronization | hello_workgroups | mipmap | msaa_line | render_to_texture | repeated_compute | shadow | skybox | stencil_triangles | storage_texture | texture_arrays | uniform_values | water | ray_cube_compute | ray_cube_fragment | ray_scene | ray_shadows | ray_traced_triangle |
|
|
|------------------------------| ------ | --------- | ------------------- | ------ | --------------------- | ---------------- | ------ | --------- | ----------------- | ---------------- | ------ | ------ | ----------------- | --------------- | -------------- | -------------- | ------ |------------------|-------------------|-----------|-------------|---------------------|
|
|
| vertex attributes | :star: | | | :star: | | | | :star: | | | :star: | :star: | | | :star: | | :star: | | | | | |
|
|
| instancing | :star: | | | | | | | | | | | | | | | | | | | | | |
|
|
| lines and points | | | :star: | | | | | :star: | | | | | | | | | | | | | | |
|
|
| dynamic buffer offsets | | :star: | | | | | | | | | :star: | | | | | | | | | | | |
|
|
| implicit layout | | | | | | | :star: | | | | | | | | | | | | | | | |
|
|
| sampled color textures | :star: | :star: | :star: | :star: | | | :star: | | | | | :star: | | | :star: | | :star: | | | | | |
|
|
| storage textures | :star: | | | | | | | | | | | | | :star: | | | | :star: | | | | :star: |
|
|
| comparison samplers | | | | | | | | | | | :star: | | | | | | | | | | | |
|
|
| subresource views | | | | | | | :star: | | | | :star: | | | | | | | | | | | |
|
|
| cubemaps | | | | | | | | | | | | :star: | | | | | | | | | | |
|
|
| multisampling | | | | | | | | :star: | | | | | | | | | | | | | | |
|
|
| off-screen rendering | | | :star: | | | | | | :star: | | :star: | | | | | | :star: | | | | | |
|
|
| stencil testing | | | | | | | | | | | | | :star: | | | | | | | | | |
|
|
| depth testing | | | | | | | | | | | :star: | :star: | | | | | :star: | | | | | |
|
|
| depth biasing | | | | | | | | | | | :star: | | | | | | | | | | | |
|
|
| read-only depth | | | | | | | | | | | | | | | | | :star: | | | | | |
|
|
| blending | | :star: | | :star: | | | | | | | | | | | | | :star: | | | | | |
|
|
| render bundles | | | | | | | | :star: | | | | | | | | | :star: | | | | | |
|
|
| uniform buffers | | | | | | | | | | | | | | | | :star: | | | | | | |
|
|
| compute passes | :star: | | | | :star: | :star: | | | | :star: | | | | :star: | | | | | | | | |
|
|
| buffer mapping | | | | | :star: | :star: | | | | :star: | | | | :star: | | | | | | | | |
|
|
| error scopes | | | | :star: | | | | | | | | | | | | | | | | | | |
|
|
| compute workgroups | | | | | :star: | :star: | | | | | | | | | | | | | | | | |
|
|
| compute synchronization | | | | | :star: | | | | | | | | | | | | | | | | | |
|
|
| _optional extensions_ | | | | | | | | | | | | | | | :star: | | | | | | | |
|
|
| - SPIR-V shaders | | | | | | | | | | | | | | | | | | | | | | |
|
|
| - binding array | | | | | | | | | | | | | | | :star: | | | | | | | |
|
|
| - push constants | | | | | | | | | | | | | | | | | | | | | :star: | |
|
|
| - depth clamping | | | | | | | | | | | :star: | | | | | | | | | | | |
|
|
| - compressed textures | | | | | | | | | | | | :star: | | | | | | | | | | |
|
|
| - polygon mode | | | | :star: | | | | | | | | | | | | | | | | | | |
|
|
| - queries | | | | | | | :star: | | | | | | | | | | | | | | | |
|
|
| - conservative rasterization | | | :star: | | | | | | | | | | | | | | | | | | | |
|
|
| - ray queries | | | | | | | | | | | | | | | | | | :star: | :star: | :star: | :star: | :star: |
|
|
| _integrations_ | | | | | | | | | | | | | | | | | | | | | | |
|
|
| - staging belt | | | | | | | | | | | | :star: | | | | | | | | | | |
|
|
| - typed arena | | | | | | | | | | | | | | | | | | | | | | |
|
|
| - obj loading | | | | | | | | | | | | :star: | | | | | | | | :star: | | |
|
|
|
|
## Running on the Web
|
|
|
|
To run the examples in a browser, run `cargo xtask run-wasm`.
|
|
Then open `http://localhost:8000` in your browser, and you can choose an example to run.
|
|
Naturally, in order to display any of the WebGPU based examples, you need to make sure your browser supports it.
|
|
|
|
Note that many cannot be downleveled to WebGL as WebGL does (among other things) not support storage texture, storage buffers and compute shaders. Running any example using these feature in a browser will require that browser to support WebGPU.
|
|
|
|
## Additional notes
|
|
|
|
Note that the examples regarding computing build off of each other; repeated_compute extends hello_compute, hello_workgroups assumes you know the basic workflow of GPU computation, and hello_synchronization assumes you know what a workgroup is.
|
|
|
|
All the examples use [WGSL](https://gpuweb.github.io/gpuweb/wgsl.html) shaders unless specified otherwise.
|
|
|
|
All framework-based examples render to the window and are reftested against the screenshot in the directory.
|
|
|
|
## Hacking
|
|
|
|
You can record an API trace for any of the framework-based examples by starting them as:
|
|
|
|
```sh
|
|
mkdir -p trace && WGPU_TRACE=trace cargo run --features trace --bin wgpu-examples <example-name>
|
|
```
|