diff --git a/README.md b/README.md index d2cf6131b..348713c31 100644 --- a/README.md +++ b/README.md @@ -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) | diff --git a/examples/README.md b/examples/README.md index ef427e735..bf7c9b82a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -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 +mkdir -p trace && WGPU_TRACE=trace cargo run --features trace --bin ``` diff --git a/examples/boids/README.md b/examples/boids/README.md index 28c7c88bb..7c75ee984 100644 --- a/examples/boids/README.md +++ b/examples/boids/README.md @@ -5,7 +5,7 @@ Flocking boids example with gpu compute update pass ## To Run ``` -cargo run --example boids +cargo run --bin boids ``` ## Screenshots diff --git a/examples/capture/README.md b/examples/capture/README.md index b9c0ee22b..2baea436d 100644 --- a/examples/capture/README.md +++ b/examples/capture/README.md @@ -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 ``` diff --git a/examples/conservative-raster/README.md b/examples/conservative-raster/README.md index bd157319b..bf79a9a16 100644 --- a/examples/conservative-raster/README.md +++ b/examples/conservative-raster/README.md @@ -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 diff --git a/examples/cube/README.md b/examples/cube/README.md index 8b3f32872..3c1324958 100644 --- a/examples/cube/README.md +++ b/examples/cube/README.md @@ -5,7 +5,7 @@ This example renders a textured cube. ## To Run ``` -cargo run --example cube +cargo run --bin cube ``` ## Screenshots diff --git a/examples/hello-compute/README.md b/examples/hello-compute/README.md index f33845624..ee34a9483 100644 --- a/examples/hello-compute/README.md +++ b/examples/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 --example hello-compute 1 4 3 295 +RUST_LOG=hello_compute cargo run --bin hello-compute 1 4 3 295 ``` ## Example Output diff --git a/examples/hello-triangle/README.md b/examples/hello-triangle/README.md index f53af111a..31425c067 100644 --- a/examples/hello-triangle/README.md +++ b/examples/hello-triangle/README.md @@ -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 diff --git a/examples/hello-windows/README.md b/examples/hello-windows/README.md index e45071333..c483b79ac 100644 --- a/examples/hello-windows/README.md +++ b/examples/hello-windows/README.md @@ -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 diff --git a/examples/hello/README.md b/examples/hello/README.md index 2fbd36778..170f53538 100644 --- a/examples/hello/README.md +++ b/examples/hello/README.md @@ -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 diff --git a/examples/mipmap/README.md b/examples/mipmap/README.md index a50b0ecbf..547df30c5 100644 --- a/examples/mipmap/README.md +++ b/examples/mipmap/README.md @@ -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 diff --git a/examples/msaa-line/README.md b/examples/msaa-line/README.md index 031236f9d..f0c63314f 100644 --- a/examples/msaa-line/README.md +++ b/examples/msaa-line/README.md @@ -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 diff --git a/examples/shadow/README.md b/examples/shadow/README.md index 62bc83eed..3298975b8 100644 --- a/examples/shadow/README.md +++ b/examples/shadow/README.md @@ -5,7 +5,7 @@ This animated example demonstrates shadow mapping. ## To Run ``` -cargo run --example shadow +cargo run --bin shadow ``` ## Screenshots diff --git a/examples/skybox/README.md b/examples/skybox/README.md index 51dce9d36..7fe9de1df 100644 --- a/examples/skybox/README.md +++ b/examples/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 --example skybox +cargo run --bin skybox ``` ## Screenshots diff --git a/examples/stencil-triangles/README.md b/examples/stencil-triangles/README.md index f55c27b77..4b6842e09 100644 --- a/examples/stencil-triangles/README.md +++ b/examples/stencil-triangles/README.md @@ -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 diff --git a/examples/water/README.md b/examples/water/README.md index 0c316700c..79934430a 100644 --- a/examples/water/README.md +++ b/examples/water/README.md @@ -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) diff --git a/wgpu/README.md b/wgpu/README.md index 2de2ec07d..44a6f05c0 100644 --- a/wgpu/README.md +++ b/wgpu/README.md @@ -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 -- ```