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:
- [![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-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/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/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-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/deno_webgpu.svg?label=deno_webgpu)](https://crates.io/crates/deno_webgpu) - WebGPU implementation for the Deno JavaScript/TypeScript runtime
The following binaries:
- `cts_runner` - WebGPU Conformance Test Suite runner using `deno_webgpu`.
- `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.
- `cts_runner` - WebGPU Conformance Test Suite runner using `deno_webgpu`.
- `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).
@ -42,7 +43,7 @@ determined by the value of `MINIMUM_RUST_VERSION` in
vendor` to extract only those crates it actually uses, so the
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
removes any features Firefox's MSRV couldn't handle. For example,
`wgpu` can use manifest key inheritance, added in Rust 1.64, even
@ -56,9 +57,10 @@ files, producing 1.63-compatible files.
### 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:
- https://sotrh.github.io/learn-wgpu/
### 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).
If you are looking for a wgpu C++ tutorial, look at the following:
- https://eliemichel.github.io/LearnWebGPU/
### Others
@ -74,8 +77,8 @@ If you want to use wgpu in other languages, there are many bindings to wgpu-nati
## 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.
- [![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.
@ -86,14 +89,14 @@ We have a [wiki](https://github.com/gfx-rs/wgpu/wiki) that serves as a knowledge
## Supported Platforms
API | Windows | Linux & Android | macOS & iOS |
----- | ------------------------------ | ------------------------- | ------------------- |
Vulkan | :white_check_mark: | :white_check_mark: | :ok: (vulkan-portability) |
Metal | | | :white_check_mark: |
DX12 | :white_check_mark: (W10+ only) | | |
DX11 | :hammer_and_wrench: | | |
GLES3 | | :ok: | |
Angle | :ok: | :ok: | :ok: (macOS only) |
| API | Windows | Linux & Android | macOS & iOS |
| ------ | ------------------------------ | ------------------ | ------------------------- |
| Vulkan | :white_check_mark: | :white_check_mark: | :ok: (vulkan-portability) |
| Metal | | | :white_check_mark: |
| DX12 | :white_check_mark: (W10+ only) | | |
| DX11 | :hammer_and_wrench: | | |
| GLES3 | | :ok: | |
| Angle | :ok: | :ok: | :ok: (macOS only) |
: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:
| Backend/Platform | Tests | CTS | Notes |
| ---------------- | -------------------|---------------------|-------------------------------------- |
| DX12/Windows 10 | :heavy_check_mark: | :heavy_check_mark: | using WARP |
| DX11/Windows 10 | :construction: | — | using WARP |
| Metal/MacOS | — | — | metal requires GPU |
| Vulkan/Linux | :heavy_check_mark: | :x: | using lavapipe, [cts hangs][cts-hang] |
| GLES/Linux | :heavy_check_mark: | — | using llvmpipe |
| Backend/Platform | Tests | CTS | Notes |
| ---------------- | ------------------ | ------------------ | ------------------------------------- |
| DX12/Windows 10 | :heavy_check_mark: | :heavy_check_mark: | using WARP |
| DX11/Windows 10 | :construction: | — | using WARP |
| Metal/MacOS | — | — | metal requires GPU |
| Vulkan/Linux | :heavy_check_mark: | :x: | using lavapipe, [cts hangs][cts-hang] |
| GLES/Linux | :heavy_check_mark: | — | using llvmpipe |
[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:
Render | Texture
-------|--------
![render_coordinates](./etc/render_coordinates.png) | ![texture_coordinates](./etc/texture_coordinates.png)
| Render | Texture |
| --------------------------------------------------- | ----------------------------------------------------- |
| ![render_coordinates](./etc/render_coordinates.png) | ![texture_coordinates](./etc/texture_coordinates.png) |

17
examples/README.md
View File

@ -1,9 +1,10 @@
## 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
- `hello` for printing adapter information
- `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.
@ -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.
## Feature matrix
| 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: | | |
| instancing | :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: | | |
| compute passes | :star: | | | | | | | | | | |
| error scopes | | | :star: | | | | | | | | |
| *optional extensions* | | | | | | | | :star: | | | |
| _optional extensions_ | | | | | | | | :star: | | | |
| - SPIR-V shaders | | | | | | | | | | | |
| - binding array | | | | | | | | :star: | | | |
| - push constants | | | | | | | | | | | |
@ -43,7 +45,7 @@ All framework-based examples render to the window and are reftested against the
| - polygon mode | | | :star: | | | | | | | | |
| - queries | | | | :star: | | | | | | | |
| - conservative rasterization | | | | | | | | | | :star: | |
| *integrations* | | | | | | | | | | | |
| _integrations_ | | | | | | | | | | | |
| - staging belt | | | | | | | :star: | | | | |
| - typed arena | | | | | | | | | | | |
| - obj loading | | | | | | | :star: | | | | |
@ -51,6 +53,7 @@ All framework-based examples render to the window and are reftested against the
## Hacking
You can record an API trace any of the framework-based examples by starting them as:
```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
```
cargo run --example boids
cargo run --bin boids
```
## Screenshots

2
examples/capture/README.md
View File

@ -9,7 +9,7 @@ require a window to be created.
## To Run
```
cargo run --example capture
cargo run --bin capture
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
```
cargo run --example conservative-raster
cargo run --bin conservative-raster
```
## Screenshots

2
examples/cube/README.md
View File

@ -5,7 +5,7 @@ This example renders a textured cube.
## To Run
```
cargo run --example cube
cargo run --bin cube
```
## 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
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

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

@ -5,7 +5,7 @@ This example renders a triangle to a window.
## To Run
```
cargo run --example hello-triangle
cargo run --bin hello-triangle
```
## 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
```
cargo run --example hello-windows
cargo run --bin hello-windows
```
## Screenshots

2
examples/hello/README.md
View File

@ -5,7 +5,7 @@ This example prints output describing the adapter in use.
## To Run
```
cargo run --example hello
cargo run --bin hello
```
## 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
```
cargo run --example mipmap
cargo run --bin mipmap
```
## Screenshots

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

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

2
examples/shadow/README.md
View File

@ -5,7 +5,7 @@ This animated example demonstrates shadow mapping.
## To Run
```
cargo run --example shadow
cargo run --bin shadow
```
## 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
```
cargo run --example skybox
cargo run --bin skybox
```
## 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.
## To Run
```
cargo run --example stencil-triangles
cargo run --bin stencil-triangles
```
## 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.
## Files:
```
water
├── main.rs ------------------ Main program
@ -16,9 +17,11 @@ water
```
## To run
```
cargo run --example water
cargo run --bin water
```
## Screenshot
![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:
```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:
```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:
@ -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.
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
cargo run -- <input.spv> <output.wgsl>
```