mirror of
https://github.com/gfx-rs/wgpu.git
synced 2024-10-29 21:41:36 +00:00
Update Readme
This commit is contained in:
Connor Fitzgerald
parent
b8b93042c2
commit
e54289b08b
21
README.md
21
README.md
@ -6,7 +6,7 @@
|
||||
[](https://matrix.to/#/#wgpu:matrix.org)
|
||||
[](https://matrix.to/#/#wgpu-users:matrix.org)
|
||||
[](https://github.com/gfx-rs/wgpu/actions)
|
||||
[](https://codecov.io/gh/gfx-rs/wgpu)
|
||||
[](https://codecov.io/gh/gfx-rs/wgpu)
|
||||
|
||||
`wgpu` is a cross-platform, safe, pure-rust graphics api. It runs natively on Vulkan, Metal, D3D12, and OpenGL; and on top of WebGL2 and WebGPU on wasm.
|
||||
|
||||
@ -17,16 +17,18 @@ The api is based on the [WebGPU standard](https://gpuweb.github.io/gpuweb/). It
|
||||
The repository hosts the following libraries:
|
||||
|
||||
- [](https://crates.io/crates/wgpu) [](https://docs.rs/wgpu/) - User facing Rust API.
|
||||
- [](https://crates.io/crates/wgpu-core) [](https://docs.rs/wgpu-core/) - Internal WebGPU implementation.
|
||||
- [](https://crates.io/crates/wgpu-core) [](https://docs.rs/wgpu-core/) - Internal safe implementation.
|
||||
- [](https://crates.io/crates/wgpu-hal) [](https://docs.rs/wgpu-hal/) - Internal unsafe GPU API abstraction layer.
|
||||
- [](https://crates.io/crates/wgpu-types) [](https://docs.rs/wgpu-types/) - Rust types shared between all crates.
|
||||
- [](https://crates.io/crates/naga) [](https://docs.rs/naga/) - Stand-alone shader translation library.
|
||||
- [](https://crates.io/crates/deno_webgpu) - WebGPU implementation for the Deno JavaScript/TypeScript runtime
|
||||
|
||||
The following binaries:
|
||||
|
||||
- [](https://crates.io/crates/naga-cli) - Tool for translating shaders between different languages using naga.
|
||||
- [](https://crates.io/crates/wgpu-info) - Tool for getting information on GPUs in the system.
|
||||
- `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).
|
||||
|
||||
@ -34,7 +36,7 @@ For an overview of all the components in the gfx-rs ecosystem, see [the big pict
|
||||
|
||||
### Rust
|
||||
|
||||
Rust examples can be found at `wgpu/examples`. You can run the examples on native with `cargo run --bin <name>`. See the [list of examples](examples).
|
||||
Rust examples can be found at [wgpu/examples](examples). You can run the examples on native with `cargo run --bin <name>`. See the [list of examples](examples).
|
||||
|
||||
To run the examples on WebGPU on wasm, run `cargo xtask run-wasm --bin <name>`. Then connect to `http://localhost:8000` in your WebGPU enabled browser.
|
||||
|
||||
@ -60,8 +62,9 @@ If you want to use wgpu in other languages, there are many bindings to wgpu-nati
|
||||
|
||||
We have the Matrix space [](https://matrix.to/#/#Wgpu:matrix.org) with a few different rooms that form the wgpu community:
|
||||
|
||||
- [](https://matrix.to/#/#wgpu:matrix.org) - discussion of the library's development.
|
||||
- [](https://matrix.to/#/#wgpu-users:matrix.org) - discussion of using the library and the surrounding ecosystem.
|
||||
- [](https://matrix.to/#/#wgpu:matrix.org) - discussion of the wgpu's development.
|
||||
- [](https://matrix.to/#/#naga:matrix.org) - discussion of the naga's development.
|
||||
- [](https://matrix.to/#/#wgpu-users:matrix.org) - discussion of using the library and the surrounding ecosystem.
|
||||
- [](https://matrix.to/#/#wgpu-random:matrix.org) - discussion of everything else.
|
||||
|
||||
## Wiki
|
||||
@ -117,13 +120,13 @@ On Linux, you can point to them using `LD_LIBRARY_PATH` environment.
|
||||
### MSRV policy
|
||||
|
||||
Due to complex dependants, we have two MSRV policies:
|
||||
- `wgpu-core`, `wgpu-hal`, and `wgpu-types`'s MSRV is **1.65**.
|
||||
- `naga`, `wgpu-core`, `wgpu-hal`, and `wgpu-types`'s MSRV is **1.65**.
|
||||
- The rest of the workspace has the MSRV of **1.70**.
|
||||
|
||||
It is enforced on CI (in "/.github/workflows/ci.yml") with `CORE_MSRV` and `REPO_MSRV` variable.
|
||||
This version can only be upgraded in breaking releases, though we release a breaking version every 3 months.
|
||||
|
||||
The `wgpu-core`, `wgpu-hal`, and `wgpu-types` crates should never
|
||||
The `naga`, `wgpu-core`, `wgpu-hal`, and `wgpu-types` crates should never
|
||||
require an MSRV ahead of Firefox's MSRV for nightly builds, as
|
||||
determined by the value of `MINIMUM_RUST_VERSION` in
|
||||
[`python/mozboot/mozboot/util.py`][util].
|
||||
@ -195,7 +198,7 @@ To run a given set of tests:
|
||||
|
||||
```
|
||||
# Must be inside the cts folder we just checked out, else this will fail
|
||||
cargo run --manifest-path ../cts_runner/Cargo.toml -- ./tools/run_deno --verbose "<test string>"
|
||||
cargo run --manifest-path ../Cargo.toml --bin cts_runner -- ./tools/run_deno --verbose "<test string>"
|
||||
```
|
||||
|
||||
To find the full list of tests, go to the [online cts viewer](https://gpuweb.github.io/cts/standalone/?runnow=0&worker=0&debug=0&q=webgpu:*).
|
||||
|
||||
@ -1 +1,3 @@
|
||||
codecov:
|
||||
branch: trunk
|
||||
comment: false
|
||||
BIN
logo.png
BIN
logo.png
Binary file not shown.
|
Before Width: | Height: | Size: 50 KiB After Width: | Height: | Size: 182 KiB |
@ -8,9 +8,8 @@ homepage.workspace = true
|
||||
repository.workspace = true
|
||||
keywords.workspace = true
|
||||
license.workspace = true
|
||||
exclude = [
|
||||
"Cargo.lock",
|
||||
]
|
||||
readme = "../README.md"
|
||||
exclude = ["Cargo.lock"]
|
||||
|
||||
[package.metadata.docs.rs]
|
||||
all-features = true
|
||||
@ -41,7 +40,11 @@ webgl = ["hal", "wgc/gles"]
|
||||
vulkan-portability = ["wgc/vulkan"]
|
||||
expose-ids = []
|
||||
# Implement `Send` and `Sync` on Wasm.
|
||||
fragile-send-sync-non-atomic-wasm = ["hal/fragile-send-sync-non-atomic-wasm", "wgc/fragile-send-sync-non-atomic-wasm", "wgt/fragile-send-sync-non-atomic-wasm"]
|
||||
fragile-send-sync-non-atomic-wasm = [
|
||||
"hal/fragile-send-sync-non-atomic-wasm",
|
||||
"wgc/fragile-send-sync-non-atomic-wasm",
|
||||
"wgt/fragile-send-sync-non-atomic-wasm",
|
||||
]
|
||||
|
||||
# wgpu-core is always available as an optional dependency, "wgc".
|
||||
# Whenever wgpu-core is selected, we want raw window handle support.
|
||||
@ -87,7 +90,11 @@ hal = { workspace = true }
|
||||
hal = { workspace = true, features = ["renderdoc"] }
|
||||
|
||||
[target.'cfg(windows)'.dependencies]
|
||||
hal = { workspace = true, features = ["dxc_shader_compiler", "renderdoc", "windows_rs"] }
|
||||
hal = { workspace = true, features = [
|
||||
"dxc_shader_compiler",
|
||||
"renderdoc",
|
||||
"windows_rs",
|
||||
] }
|
||||
|
||||
[target.'cfg(target_arch = "wasm32")'.dependencies.hal]
|
||||
workspace = true
|
||||
@ -249,7 +256,7 @@ web-sys = { workspace = true, features = [
|
||||
"ImageBitmapRenderingContext",
|
||||
"Window",
|
||||
"WorkerGlobalScope",
|
||||
"WorkerNavigator"
|
||||
"WorkerNavigator",
|
||||
] }
|
||||
wasm-bindgen.workspace = true
|
||||
js-sys.workspace = true
|
||||
|
||||
@ -1,20 +0,0 @@
|
||||
# This Makefile generates SPIR-V shaders from GLSL shaders in the examples.
|
||||
|
||||
shader_compiler = glslangValidator
|
||||
|
||||
# All input shaders.
|
||||
glsls = $(wildcard examples/*/*.vert examples/*/*.frag examples/*/*.comp)
|
||||
|
||||
# All SPIR-V targets.
|
||||
spirvs = $(addsuffix .spv,$(glsls))
|
||||
|
||||
.PHONY: default
|
||||
default: $(spirvs)
|
||||
|
||||
# Rule for making a SPIR-V target.
|
||||
$(spirvs): %.spv: %
|
||||
$(shader_compiler) -V $< -o $@
|
||||
|
||||
.PHONY: clean
|
||||
clean:
|
||||
rm -f $(spirvs)
|
||||
@ -1,60 +0,0 @@
|
||||
<img align="right" width="25%" src="https://raw.githubusercontent.com/gfx-rs/wgpu/master/logo.png">
|
||||
|
||||
wgpu-rs is an idiomatic Rust wrapper over [wgpu-core](https://github.com/gfx-rs/wgpu). It's designed to be suitable for general purpose graphics and computation needs of Rust community.
|
||||
|
||||
wgpu-rs can target both the natively supported backends and Wasm directly.
|
||||
|
||||
See our [gallery](https://wgpu.rs/#showcase) and the [wiki page](https://github.com/gfx-rs/wgpu/wiki/Users) for the list of libraries and applications using `wgpu-rs`.
|
||||
|
||||
## Usage
|
||||
|
||||
### How to Run Examples
|
||||
|
||||
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 --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 --bin hello-compute 1 2 3 4
|
||||
```
|
||||
|
||||
The following environment variables can be used to configure how the framework examples run:
|
||||
|
||||
- `WGPU_BACKEND`
|
||||
|
||||
Options: `vulkan`, `metal`, `dx11`, `dx12`, `gl`, `webgpu`
|
||||
|
||||
If unset a default backend is chosen based on what is supported
|
||||
by your system.
|
||||
|
||||
- `WGPU_POWER_PREF`
|
||||
|
||||
Options: `low`, `high`, `none`
|
||||
|
||||
If unset power usage is not considered when choosing an adapter.
|
||||
|
||||
- `WGPU_ADAPTER_NAME`
|
||||
|
||||
Select a specific adapter by specifying a substring of the adapter name.
|
||||
|
||||
#### Run Examples on the Web (`wasm32-unknown-unknown`)
|
||||
|
||||
See [wiki article](https://github.com/gfx-rs/wgpu/wiki/Running-on-the-Web-with-WebGPU-and-WebGL).
|
||||
|
||||
## Shaders
|
||||
|
||||
[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>
|
||||
```
|
||||
|
||||
In addition, SPIR-V can be used by enabling the `spirv` feature and GLSL can be enabled by enabling the `glsl` feature at the cost of slightly increased build times.
|
||||
@ -3,7 +3,7 @@
|
||||
//! To start using the API, create an [`Instance`].
|
||||
|
||||
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
|
||||
#![doc(html_logo_url = "https://raw.githubusercontent.com/gfx-rs/wgpu/master/logo.png")]
|
||||
#![doc(html_logo_url = "https://raw.githubusercontent.com/gfx-rs/wgpu/trunk/logo.png")]
|
||||
#![warn(missing_docs, unsafe_op_in_unsafe_fn)]
|
||||
|
||||
mod backend;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user