archive-gh-me/wgpu
1
0
Fork 0
mirror of https://github.com/gfx-rs/wgpu.git synced 2025-12-08 21:26:17 +00:00
Code Issues Projects Releases Wiki Activity

Formatting and example command fixes (#3872)

Browse Source
This commit is contained in:
Connor Fitzgerald 2023-06-15 16:05:26 -04:00 committed by GitHub
parent e6be20f72e
commit db39b5423e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 62 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
README.md
View File

@ -16,16 +16,17 @@ The api is based on the [WebGPU standard](https://gpuweb.github.io/gpuweb/). It
The repository hosts the following libraries: The repository hosts the following libraries:
- [![Crates.io](https://img.shields.io/crates/v/wgpu.svg?label=wgpu)](https://crates.io/crates/wgpu) [![docs.rs](https://docs.rs/wgpu/badge.svg)](https://docs.rs/wgpu/) - User facing Rust API. - [![Crates.io](https://img.shields.io/crates/v/wgpu.svg?label=wgpu)](https://crates.io/crates/wgpu) [![docs.rs](https://docs.rs/wgpu/badge.svg)](https://docs.rs/wgpu/) - User facing Rust API.
- [![Crates.io](https://img.shields.io/crates/v/wgpu-core.svg?label=wgpu-core)](https://crates.io/crates/wgpu-core) [![docs.rs](https://docs.rs/wgpu-core/badge.svg)](https://docs.rs/wgpu-core/) - Internal WebGPU implementation. - [![Crates.io](https://img.shields.io/crates/v/wgpu-core.svg?label=wgpu-core)](https://crates.io/crates/wgpu-core) [![docs.rs](https://docs.rs/wgpu-core/badge.svg)](https://docs.rs/wgpu-core/) - Internal WebGPU implementation.
- [![Crates.io](https://img.shields.io/crates/v/wgpu-hal.svg?label=wgpu-hal)](https://crates.io/crates/wgpu-hal) [![docs.rs](https://docs.rs/wgpu-hal/badge.svg)](https://docs.rs/wgpu-hal/) - Internal unsafe GPU API abstraction layer. - [![Crates.io](https://img.shields.io/crates/v/wgpu-hal.svg?label=wgpu-hal)](https://crates.io/crates/wgpu-hal) [![docs.rs](https://docs.rs/wgpu-hal/badge.svg)](https://docs.rs/wgpu-hal/) - Internal unsafe GPU API abstraction layer.
- [![Crates.io](https://img.shields.io/crates/v/wgpu-types.svg?label=wgpu-types)](https://crates.io/crates/wgpu-types) [![docs.rs](https://docs.rs/wgpu-types/badge.svg)](https://docs.rs/wgpu-types/) - Rust types shared between all crates. - [![Crates.io](https://img.shields.io/crates/v/wgpu-types.svg?label=wgpu-types)](https://crates.io/crates/wgpu-types) [![docs.rs](https://docs.rs/wgpu-types/badge.svg)](https://docs.rs/wgpu-types/) - Rust types shared between all crates.
- [![Crates.io](https://img.shields.io/crates/v/deno_webgpu.svg?label=deno_webgpu)](https://crates.io/crates/deno_webgpu) - WebGPU implementation for the Deno JavaScript/TypeScript runtime - [![Crates.io](https://img.shields.io/crates/v/deno_webgpu.svg?label=deno_webgpu)](https://crates.io/crates/deno_webgpu) - WebGPU implementation for the Deno JavaScript/TypeScript runtime
The following binaries: The following binaries:
- `cts_runner` - WebGPU Conformance Test Suite runner using `deno_webgpu`.
- `player` - standalone application for replaying the API traces. - `cts_runner` - WebGPU Conformance Test Suite runner using `deno_webgpu`.
- `wgpu-info` - program that prints out information about all the adapters on the system or invokes a command for every adapter. - `player` - standalone application for replaying the API traces.
- `wgpu-info` - program that prints out information about all the adapters on the system or invokes a command for every adapter.
For an overview of all the components in the gfx-rs ecosystem, see [the big picture](./etc/big-picture.png). For an overview of all the components in the gfx-rs ecosystem, see [the big picture](./etc/big-picture.png).
@ -42,7 +43,7 @@ determined by the value of `MINIMUM_RUST_VERSION` in
vendor` to extract only those crates it actually uses, so the vendor` to extract only those crates it actually uses, so the
workspace's other crates can have more recent MSRVs. workspace's other crates can have more recent MSRVs.
*Note for Rust 1.64*: The workspace itself can even use a newer MSRV _Note for Rust 1.64_: The workspace itself can even use a newer MSRV
than Firefox, as long as the vendoring step's `Cargo.toml` rewriting than Firefox, as long as the vendoring step's `Cargo.toml` rewriting
removes any features Firefox's MSRV couldn't handle. For example, removes any features Firefox's MSRV couldn't handle. For example,
`wgpu` can use manifest key inheritance, added in Rust 1.64, even `wgpu` can use manifest key inheritance, added in Rust 1.64, even
@ -56,9 +57,10 @@ files, producing 1.63-compatible files.
### Rust ### Rust
Rust examples can be found at `wgpu/examples`. You can run the examples with `cargo run --example name`. See the [list of examples](wgpu/examples). For detailed instructions, look at [Running the examples](https://github.com/gfx-rs/wgpu/wiki/Running-the-examples) on the wiki. Rust examples can be found at `wgpu/examples`. You can run the examples with `cargo run --bin name`. See the [list of examples](wgpu/examples). For detailed instructions, look at [Running the examples](https://github.com/gfx-rs/wgpu/wiki/Running-the-examples) on the wiki.
If you are looking for a wgpu tutorial, look at the following: If you are looking for a wgpu tutorial, look at the following:
- https://sotrh.github.io/learn-wgpu/ - https://sotrh.github.io/learn-wgpu/
### C/C++ ### C/C++
@ -66,6 +68,7 @@ If you are looking for a wgpu tutorial, look at the following:
To use wgpu in C/C++, you need [wgpu-native](https://github.com/gfx-rs/wgpu-native). To use wgpu in C/C++, you need [wgpu-native](https://github.com/gfx-rs/wgpu-native).
If you are looking for a wgpu C++ tutorial, look at the following: If you are looking for a wgpu C++ tutorial, look at the following:
- https://eliemichel.github.io/LearnWebGPU/ - https://eliemichel.github.io/LearnWebGPU/
### Others ### Others
@ -74,8 +77,8 @@ If you want to use wgpu in other languages, there are many bindings to wgpu-nati
## Community ## Community
We have the Matrix space [![Matrix Space](https://img.shields.io/static/v1?label=Space&message=%23Wgpu&color=blue&logo=matrix)](https://matrix.to/#/#Wgpu:matrix.org) with a few different rooms that form the wgpu community: We have the Matrix space [![Matrix Space](https://img.shields.io/static/v1?label=Space&message=%23Wgpu&color=blue&logo=matrix)](https://matrix.to/#/#Wgpu:matrix.org) with a few different rooms that form the wgpu community:
- [![Dev Matrix](https://img.shields.io/static/v1?label=devs&message=%23wgpu&color=blueviolet&logo=matrix)](https://matrix.to/#/#wgpu:matrix.org) - discussion of the library's development. - [![Dev Matrix](https://img.shields.io/static/v1?label=devs&message=%23wgpu&color=blueviolet&logo=matrix)](https://matrix.to/#/#wgpu:matrix.org) - discussion of the library's development.
- [![User Matrix](https://img.shields.io/static/v1?label=users&message=%23wgpu-users&color=blueviolet&logo=matrix)](https://matrix.to/#/#wgpu-users:matrix.org) - discussion of using the library and the surrounding ecosystem. - [![User Matrix](https://img.shields.io/static/v1?label=users&message=%23wgpu-users&color=blueviolet&logo=matrix)](https://matrix.to/#/#wgpu-users:matrix.org) - discussion of using the library and the surrounding ecosystem.
- [![Random Matrix](https://img.shields.io/static/v1?label=random&message=%23wgpu-random&color=blueviolet&logo=matrix)](https://matrix.to/#/#wgpu-random:matrix.org) - discussion of everything else. - [![Random Matrix](https://img.shields.io/static/v1?label=random&message=%23wgpu-random&color=blueviolet&logo=matrix)](https://matrix.to/#/#wgpu-random:matrix.org) - discussion of everything else.
@ -86,14 +89,14 @@ We have a [wiki](https://github.com/gfx-rs/wgpu/wiki) that serves as a knowledge
## Supported Platforms ## Supported Platforms
API | Windows | Linux & Android | macOS & iOS | | API | Windows | Linux & Android | macOS & iOS |
----- | ------------------------------ | ------------------------- | ------------------- | | ------ | ------------------------------ | ------------------ | ------------------------- |
Vulkan | :white_check_mark: | :white_check_mark: | :ok: (vulkan-portability) | | Vulkan | :white_check_mark: | :white_check_mark: | :ok: (vulkan-portability) |
Metal | | | :white_check_mark: | | Metal | | | :white_check_mark: |
DX12 | :white_check_mark: (W10+ only) | | | | DX12 | :white_check_mark: (W10+ only) | | |
DX11 | :hammer_and_wrench: | | | | DX11 | :hammer_and_wrench: | | |
GLES3 | | :ok: | | | GLES3 | | :ok: | |
Angle | :ok: | :ok: | :ok: (macOS only) | | Angle | :ok: | :ok: | :ok: (macOS only) |
:white_check_mark: = First Class Support — :ok: = Best Effort Support — :hammer_and_wrench: = Unsupported, but support in progress :white_check_mark: = First Class Support — :ok: = Best Effort Support — :hammer_and_wrench: = Unsupported, but support in progress
@ -141,13 +144,13 @@ When running the CTS, use the variables `DENO_WEBGPU_ADAPTER_NAME`, `DENO_WEBGPU
We have multiple methods of testing, each of which tests different qualities about wgpu. We automatically run our tests on CI if possible. The current state of CI testing: We have multiple methods of testing, each of which tests different qualities about wgpu. We automatically run our tests on CI if possible. The current state of CI testing:
| Backend/Platform | Tests | CTS | Notes | | Backend/Platform | Tests | CTS | Notes |
| ---------------- | -------------------|---------------------|-------------------------------------- | | ---------------- | ------------------ | ------------------ | ------------------------------------- |
| DX12/Windows 10 | :heavy_check_mark: | :heavy_check_mark: | using WARP | | DX12/Windows 10 | :heavy_check_mark: | :heavy_check_mark: | using WARP |
| DX11/Windows 10 | :construction: | — | using WARP | | DX11/Windows 10 | :construction: | — | using WARP |
| Metal/MacOS | — | — | metal requires GPU | | Metal/MacOS | — | — | metal requires GPU |
| Vulkan/Linux | :heavy_check_mark: | :x: | using lavapipe, [cts hangs][cts-hang] | | Vulkan/Linux | :heavy_check_mark: | :x: | using lavapipe, [cts hangs][cts-hang] |
| GLES/Linux | :heavy_check_mark: | — | using llvmpipe | | GLES/Linux | :heavy_check_mark: | — | using llvmpipe |
[cts-hang]: https://github.com/gfx-rs/wgpu/issues/1974 [cts-hang]: https://github.com/gfx-rs/wgpu/issues/1974
@ -245,6 +248,6 @@ Exactly which WGSL features `wgpu` supports depends on how you are using it:
wgpu uses the coordinate systems of D3D and Metal: wgpu uses the coordinate systems of D3D and Metal:
Render | Texture | Render | Texture |
-------|-------- | --------------------------------------------------- | ----------------------------------------------------- |
![render_coordinates](./etc/render_coordinates.png) | ![texture_coordinates](./etc/texture_coordinates.png) | ![render_coordinates](./etc/render_coordinates.png) | ![texture_coordinates](./etc/texture_coordinates.png) |

17
examples/README.md
View File

@ -1,9 +1,10 @@
## Structure ## Structure
For the simplest examples without using any helping code (see `framework.rs` here), check out: 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` for printing adapter information
- `hello-compute` for pure computing - `hello-triangle` for graphics and presentation
- `hello-compute` for pure computing
Notably, `capture` example shows rendering without a surface/window. It reads back the contents and saves them to a file. Notably, `capture` example shows rendering without a surface/window. It reads back the contents and saves them to a file.
@ -12,8 +13,9 @@ All the examples use [WGSL](https://gpuweb.github.io/gpuweb/wgsl.html) shaders u
All framework-based examples render to the window and are reftested against the screenshot in the directory. All framework-based examples render to the window and are reftested against the screenshot in the directory.
## Feature matrix ## Feature matrix
| Feature | boids | bunnymark | cube | mipmap | msaa-line | shadow | skybox | texture-arrays | water | conservative-raster | stencil-triangles | | Feature | boids | bunnymark | cube | mipmap | msaa-line | shadow | skybox | texture-arrays | water | conservative-raster | stencil-triangles |
|------------------------------| ------ | --------- | ------ | ------ | --------- | ------ | ------ | -------------- | ------ | ------------------- |-------------------| | ---------------------------- | ------ | --------- | ------ | ------ | --------- | ------ | ------ | -------------- | ------ | ------------------- | ----------------- |
| vertex attributes | :star: | | :star: | | :star: | :star: | :star: | :star: | :star: | | | | vertex attributes | :star: | | :star: | | :star: | :star: | :star: | :star: | :star: | | |
| instancing | :star: | | | | | | | | | | | | instancing | :star: | | | | | | | | | | |
| lines and points | | | | | :star: | | | | | :star: | | | lines and points | | | | | :star: | | | | | :star: | |
@ -34,7 +36,7 @@ All framework-based examples render to the window and are reftested against the
| render bundles | | | | | :star: | | | | :star: | | | | render bundles | | | | | :star: | | | | :star: | | |
| compute passes | :star: | | | | | | | | | | | | compute passes | :star: | | | | | | | | | | |
| error scopes | | | :star: | | | | | | | | | | error scopes | | | :star: | | | | | | | | |
| *optional extensions* | | | | | | | | :star: | | | | | _optional extensions_ | | | | | | | | :star: | | | |
| - SPIR-V shaders | | | | | | | | | | | | | - SPIR-V shaders | | | | | | | | | | | |
| - binding array | | | | | | | | :star: | | | | | - binding array | | | | | | | | :star: | | | |
| - push constants | | | | | | | | | | | | | - push constants | | | | | | | | | | | |
@ -43,7 +45,7 @@ All framework-based examples render to the window and are reftested against the
| - polygon mode | | | :star: | | | | | | | | | | - polygon mode | | | :star: | | | | | | | | |
| - queries | | | | :star: | | | | | | | | | - queries | | | | :star: | | | | | | | |
| - conservative rasterization | | | | | | | | | | :star: | | | - conservative rasterization | | | | | | | | | | :star: | |
| *integrations* | | | | | | | | | | | | | _integrations_ | | | | | | | | | | | |
| - staging belt | | | | | | | :star: | | | | | | - staging belt | | | | | | | :star: | | | | |
| - typed arena | | | | | | | | | | | | | - typed arena | | | | | | | | | | | |
| - obj loading | | | | | | | :star: | | | | | | - obj loading | | | | | | | :star: | | | | |
@ -51,6 +53,7 @@ All framework-based examples render to the window and are reftested against the
## Hacking ## Hacking
You can record an API trace any of the framework-based examples by starting them as: You can record an API trace any of the framework-based examples by starting them as:
```sh ```sh
mkdir -p trace && WGPU_TRACE=trace cargo run --features trace --example <example-name> mkdir -p trace && WGPU_TRACE=trace cargo run --features trace --bin <example-name>
``` ```

2
examples/boids/README.md
View File

@ -5,7 +5,7 @@ Flocking boids example with gpu compute update pass
## To Run ## To Run
``` ```
cargo run --example boids cargo run --bin boids
``` ```
## Screenshots ## Screenshots

2
examples/capture/README.md
View File

@ -9,7 +9,7 @@ require a window to be created.
## To Run ## To Run
``` ```
cargo run --example capture cargo run --bin capture
open examples/capture/red.png open examples/capture/red.png
``` ```

2
examples/conservative-raster/README.md
View File

@ -12,7 +12,7 @@ Pixels only drawn with conservative rasterization enabled are depicted red.
## To Run ## To Run
``` ```
cargo run --example conservative-raster cargo run --bin conservative-raster
``` ```
## Screenshots ## Screenshots

2
examples/cube/README.md
View File

@ -5,7 +5,7 @@ This example renders a textured cube.
## To Run ## To Run
``` ```
cargo run --example cube cargo run --bin cube
``` ```
## Screenshots ## Screenshots

2
examples/hello-compute/README.md
View File

@ -12,7 +12,7 @@ that it will take to finish and reach the number `1`.
``` ```
# Pass in any 4 numbers as arguments # Pass in any 4 numbers as arguments
RUST_LOG=hello_compute cargo run --example hello-compute 1 4 3 295 RUST_LOG=hello_compute cargo run --bin hello-compute 1 4 3 295
``` ```
## Example Output ## Example Output

2
examples/hello-triangle/README.md
View File

@ -5,7 +5,7 @@ This example renders a triangle to a window.
## To Run ## To Run
``` ```
cargo run --example hello-triangle cargo run --bin hello-triangle
``` ```
## Screenshots ## Screenshots

2
examples/hello-windows/README.md
View File

@ -5,7 +5,7 @@ This example renders a set of 16 windows, with a differently colored background
## To Run ## To Run
``` ```
cargo run --example hello-windows cargo run --bin hello-windows
``` ```
## Screenshots ## Screenshots

2
examples/hello/README.md
View File

@ -5,7 +5,7 @@ This example prints output describing the adapter in use.
## To Run ## To Run
``` ```
cargo run --example hello cargo run --bin hello
``` ```
## Example output ## Example output

2
examples/mipmap/README.md
View File

@ -5,7 +5,7 @@ This example shows how to generate and make use of mipmaps.
## To Run ## To Run
``` ```
cargo run --example mipmap cargo run --bin mipmap
``` ```
## Screenshots ## Screenshots

2
examples/msaa-line/README.md
View File

@ -5,7 +5,7 @@ This example shows how to render lines using MSAA.
## To Run ## To Run
``` ```
cargo run --example msaa-line cargo run --bin msaa-line
``` ```
## Screenshots ## Screenshots

2
examples/shadow/README.md
View File

@ -5,7 +5,7 @@ This animated example demonstrates shadow mapping.
## To Run ## To Run
``` ```
cargo run --example shadow cargo run --bin shadow
``` ```
## Screenshots ## Screenshots

2
examples/skybox/README.md
View File

@ -6,7 +6,7 @@ It hooks up `winit` mouse controls for camera rotation around the model at the c
## To Run ## To Run
``` ```
cargo run --example skybox cargo run --bin skybox
``` ```
## Screenshots ## Screenshots

3
examples/stencil-triangles/README.md
View File

@ -7,11 +7,10 @@ First it draws a small "mask" triangle, which sets the stencil buffer at every p
Then, it draws a larger "outer" triangle which only touches pixels where the stencil buffer is less than 1. Then, it draws a larger "outer" triangle which only touches pixels where the stencil buffer is less than 1.
## To Run ## To Run
``` ```
cargo run --example stencil-triangles cargo run --bin stencil-triangles
``` ```
## Screenshots ## Screenshots

5
examples/water/README.md
View File

@ -5,6 +5,7 @@ This example renders animated water.
It demonstrates Read only Depth/Stencil (abbreviated RODS), where a depth/stencil buffer is used as an attachment which is read-only. In this case it's used in the shaders to calculate reflections and depth. It demonstrates Read only Depth/Stencil (abbreviated RODS), where a depth/stencil buffer is used as an attachment which is read-only. In this case it's used in the shaders to calculate reflections and depth.
## Files: ## Files:
``` ```
water water
├── main.rs ------------------ Main program ├── main.rs ------------------ Main program
@ -16,9 +17,11 @@ water
``` ```
## To run ## To run
``` ```
cargo run --example water cargo run --bin water
``` ```
## Screenshot ## Screenshot
![Water example](./screenshot.png) ![Water example](./screenshot.png)

5
wgpu/README.md
View File

@ -15,13 +15,13 @@ All examples are located under the [examples](examples) directory.
These examples use the default syntax for running examples, as found in the [Cargo](https://doc.rust-lang.org/cargo/reference/manifest.html#examples) documentation. For example, to run the `cube` example: These examples use the default syntax for running examples, as found in the [Cargo](https://doc.rust-lang.org/cargo/reference/manifest.html#examples) documentation. For example, to run the `cube` example:
```bash ```bash
cargo run --example cube cargo run --bin cube
``` ```
The `hello*` examples show bare-bones setup without any helper code. For `hello-compute`, pass 4 numbers separated by spaces as arguments: The `hello*` examples show bare-bones setup without any helper code. For `hello-compute`, pass 4 numbers separated by spaces as arguments:
```bash ```bash
cargo run --example hello-compute 1 2 3 4 cargo run --bin hello-compute 1 2 3 4
``` ```
The following environment variables can be used to configure how the framework examples run: The following environment variables can be used to configure how the framework examples run:
@ -52,6 +52,7 @@ See [wiki article](https://github.com/gfx-rs/wgpu/wiki/Running-on-the-Web-with-W
[WGSL](https://gpuweb.github.io/gpuweb/wgsl/) is the main shading language of WebGPU. [WGSL](https://gpuweb.github.io/gpuweb/wgsl/) is the main shading language of WebGPU.
Users can run the [naga](https://github.com/gfx-rs/naga) binary in the following way to convert their SPIR-V shaders to WGSL: Users can run the [naga](https://github.com/gfx-rs/naga) binary in the following way to convert their SPIR-V shaders to WGSL:
```bash ```bash
cargo run -- <input.spv> <output.wgsl> cargo run -- <input.spv> <output.wgsl>
``` ```