From ba56dd29016964bcf5e51653a5cbf98a4573157b Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Sun, 17 Dec 2023 23:10:38 +0100 Subject: [PATCH] Document wgpu & wgpu-core features (#4886) --- CHANGELOG.md | 1 + Cargo.lock | 17 ++++++++++ Cargo.toml | 22 ++++++------ wgpu-core/Cargo.toml | 67 ++++++++++++++++++++++++++----------- wgpu-core/src/lib.rs | 11 +++--- wgpu/Cargo.toml | 80 ++++++++++++++++++++++++++++++++++---------- wgpu/src/lib.rs | 4 +++ 7 files changed, 150 insertions(+), 52 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 39ad54048..f3b731daf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -65,6 +65,7 @@ Wgpu now exposes backend feature for the Direct3D 12 (`dx12`) and Metal (`metal` - Added `DownlevelFlags::VERTEX_AND_INSTANCE_INDEX_RESPECTS_RESPECTIVE_FIRST_VALUE_IN_INDIRECT_DRAW` to know if `@builtin(vertex_index)` and `@builtin(instance_index)` will respect the `first_vertex` / `first_instance` in indirect calls. If this is not present, both will always start counting from 0. Currently enabled on all backends except DX12. By @cwfitzgerald in [#4722](https://github.com/gfx-rs/wgpu/pull/4722) - No longer validate surfaces against their allowed extent range on configure. This caused warnings that were almost impossible to avoid. As before, the resulting behavior depends on the compositor. By @wumpf in [#4796](https://github.com/gfx-rs/wgpu/pull/4796) - Added support for the float32-filterable feature. By @almarklein in [#4759](https://github.com/gfx-rs/wgpu/pull/4759) +- wgpu and wgpu-core features are now documented on docs.rs. By @wumpf in [#4886](https://github.com/gfx-rs/wgpu/pull/4886) #### OpenGL - `@builtin(instance_index)` now properly reflects the range provided in the draw call instead of always counting from 0. By @cwfitzgerald in [#4722](https://github.com/gfx-rs/wgpu/pull/4722). diff --git a/Cargo.lock b/Cargo.lock index b73155a32..dc5eddbb9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1100,6 +1100,15 @@ dependencies = [ "libloading 0.8.1", ] +[[package]] +name = "document-features" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e493c573fce17f00dcab13b6ac057994f3ce17d1af4dc39bfd482b83c6eb6157" +dependencies = [ + "litrs", +] + [[package]] name = "downcast-rs" version = "1.2.0" @@ -1939,6 +1948,12 @@ version = "0.4.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "969488b55f8ac402214f3f5fd243ebb7206cf82de60d3172994707a4bcc2b829" +[[package]] +name = "litrs" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f9275e0933cf8bb20f008924c0cb07a0692fe54d8064996520bf998de9eb79aa" + [[package]] name = "lock_api" version = "0.4.11" @@ -3994,6 +4009,7 @@ version = "0.18.0" dependencies = [ "arrayvec 0.7.4", "cfg-if", + "document-features", "js-sys", "log", "naga", @@ -4019,6 +4035,7 @@ dependencies = [ "bit-vec", "bitflags 2.4.1", "codespan-reporting", + "document-features", "log", "naga", "parking_lot", diff --git a/Cargo.toml b/Cargo.toml index 06f7d9127..5de02c191 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -70,38 +70,37 @@ version = "0.14.0" [workspace.dependencies] anyhow = "1.0" arrayvec = "0.7" -bitflags = "2" bit-vec = "0.6" +bitflags = "2" bytemuck = { version = "1.14", features = ["derive"] } cfg_aliases = "0.1" cfg-if = "1" codespan-reporting = "0.11" ctor = "0.2" +document-features = "0.2" encase = "0.6" env_logger = "0.10" fern = "0.6" flume = "0.11" futures-lite = "2" -rustc-hash = "1.1.0" getrandom = "0.2" glam = "0.24.2" heck = "0.4.0" image = { version = "0.24", default-features = false, features = ["png"] } ktx2 = "0.3" +libc = "0.2" # libloading 0.8 switches from `winapi` to `windows-sys`; permit either libloading = ">=0.7, <0.9" -libc = "0.2" libtest-mimic = "0.6" log = "0.4" nanorand = { version = "0.7", default-features = false, features = ["wyrand"] } -nv-flip = "0.1" -num-traits = { version = "0.2" } # https://github.com/Razaekel/noise-rs/issues/335 (Updated dependencies) noise = { version = "0.8", git = "https://github.com/Razaekel/noise-rs.git", rev = "c6942d4fb70af26db4441edcf41f90fa115333f2" } +num-traits = { version = "0.2" } +nv-flip = "0.1" obj = "0.10" once_cell = "1" -# parking_lot 0.12 switches from `winapi` to `windows`; permit either -parking_lot = ">=0.11,<0.13" +parking_lot = ">=0.11,<0.13" # parking_lot 0.12 switches from `winapi` to `windows`; permit either pico-args = { version = "0.5.0", features = [ "eq-separator", "short-space-opt", @@ -113,6 +112,7 @@ profiling = { version = "1", default-features = false } raw-window-handle = "0.6" renderdoc-sys = "1.0.0" ron = "0.8" +rustc-hash = "1.1.0" serde = "1" serde_json = "1.0.108" smallvec = "1" @@ -124,19 +124,19 @@ wgpu-example = { version = "0.18.0", path = "./examples/common" } wgpu-macros = { version = "0.18.0", path = "./wgpu-macros" } wgpu-test = { version = "0.18.0", path = "./tests" } wgpu-types = { version = "0.18.0", path = "./wgpu-types" } -winit = { version = "0.29", features = [ "android-native-activity" ] } +winit = { version = "0.29", features = ["android-native-activity"] } # Metal dependencies block = "0.1" +core-graphics-types = "0.1" metal = "0.27.0" objc = "0.2.5" -core-graphics-types = "0.1" # Vulkan dependencies +android_system_properties = "0.1.1" ash = "0.37.3" gpu-alloc = "0.6" gpu-descriptor = "0.2" -android_system_properties = "0.1.1" # DX dependencies bit-set = "0.5" @@ -161,8 +161,8 @@ js-sys = "0.3.66" wasm-bindgen = "0.2.87" wasm-bindgen-futures = "0.4.39" wasm-bindgen-test = "0.3" -web-time = "0.2.3" web-sys = "0.3.66" +web-time = "0.2.3" # deno dependencies deno_console = "0.125.0" diff --git a/wgpu-core/Cargo.toml b/wgpu-core/Cargo.toml index ee908124b..d7eceb3df 100644 --- a/wgpu-core/Cargo.toml +++ b/wgpu-core/Cargo.toml @@ -29,54 +29,81 @@ targets = [ [features] default = ["link"] -# Log all API entry points at info instead of trace level. + +## Log all API entry points at info instead of trace level. api_log_info = [] -# Log resource lifecycle management at info instead of trace level. + +## Log resource lifecycle management at info instead of trace level. resource_log_info = [] -# Backends, passed through to wgpu-hal -metal = ["hal/metal"] -vulkan = ["hal/vulkan"] -gles = ["hal/gles"] -dx12 = ["hal/dx12"] - -# Use static linking for libraries. Disale to manually link. Enabled by default. +## Use static linking for libraries. Disale to manually link. Enabled by default. link = ["hal/link"] -# Support the Renderdoc graphics debugger: -# https://renderdoc.org/ +## Support the Renderdoc graphics debugger: +## renderdoc = ["hal/renderdoc"] -# Apply run-time checks, even in release builds. These are in addition -# to the validation carried out at public APIs in all builds. +## Apply run-time checks, even in release builds. These are in addition +## to the validation carried out at public APIs in all builds. strict_asserts = ["wgt/strict_asserts"] -# Enable API tracing + +## Enable API tracing. trace = ["ron", "serde", "wgt/trace", "arrayvec/serde", "naga/serialize"] -# Enable API replaying + +## Enable API replaying replay = ["serde", "wgt/replay", "arrayvec/serde", "naga/deserialize"] -# Enable serializable compute/render passes, and bundle encoders. + +## Enable serializable compute/render passes, and bundle encoders. serial-pass = ["serde", "wgt/serde", "arrayvec/serde"] + id32 = [] -# Enable `ShaderModuleSource::Wgsl` + +## Enable `ShaderModuleSource::Wgsl` wgsl = ["naga/wgsl-in"] -# Implement `Send` and `Sync` on Wasm. + +## Implement `Send` and `Sync` on Wasm, but only if atomics are not enabled. +## +## WebGL/WebGPU objects can not be shared between threads. +## However, it can be useful to artificially mark them as `Send` and `Sync` +## anyways to make it easier to write cross-platform code. +## This is technically *very* unsafe in a multithreaded environment, +## but on a wasm binary compiled without atomics we know we are definitely +## not in a multithreaded environment. fragile-send-sync-non-atomic-wasm = [ "hal/fragile-send-sync-non-atomic-wasm", "wgt/fragile-send-sync-non-atomic-wasm", ] +#! ### Backends, passed through to wgpu-hal +# -------------------------------------------------------------------- + +## Enable the `metal` backend. +metal = ["hal/metal"] + +## Enable the `vulkan` backend. +vulkan = ["hal/vulkan"] + +## Enable the `GLES` backend. +## +## This is used for all of GLES, OpenGL, and WebGL. +gles = ["hal/gles"] + +## Enable the `dx12` backend. +dx12 = ["hal/dx12"] + [dependencies] arrayvec = "0.7" -bitflags = "2" bit-vec = "0.6" +bitflags = "2" codespan-reporting = "0.11" -rustc-hash = "1.1" +document-features.workspace = true log = "0.4" # parking_lot 0.12 switches from `winapi` to `windows`; permit either parking_lot = ">=0.11,<0.13" profiling = { version = "1", default-features = false } raw-window-handle = { version = "0.6", optional = true } ron = { version = "0.8", optional = true } +rustc-hash = "1.1" serde = { version = "1", features = ["serde_derive"], optional = true } smallvec = "1" thiserror = "1" diff --git a/wgpu-core/src/lib.rs b/wgpu-core/src/lib.rs index 78fdcbf6c..3355c0155 100644 --- a/wgpu-core/src/lib.rs +++ b/wgpu-core/src/lib.rs @@ -1,7 +1,10 @@ -/*! This library safely implements WebGPU on native platforms. - * It is designed for integration into browsers, as well as wrapping - * into other language-specific user-friendly libraries. - */ +//! This library safely implements WebGPU on native platforms. +//! It is designed for integration into browsers, as well as wrapping +//! into other language-specific user-friendly libraries. +//! +//! ## Feature flags +#![doc = document_features::document_features!()] +//! // When we have no backends, we end up with a lot of dead or otherwise unreachable code. #![cfg_attr( diff --git a/wgpu/Cargo.toml b/wgpu/Cargo.toml index 12466d89d..ef199068e 100644 --- a/wgpu/Cargo.toml +++ b/wgpu/Cargo.toml @@ -25,33 +25,78 @@ targets = [ [features] default = ["wgsl", "dx12", "metal"] -# Apply run-time checks, even in release builds. These are in addition -# to the validation carried out at public APIs in all builds. -strict_asserts = ["wgc?/strict_asserts", "wgt/strict_asserts"] + +#! ### Backends +# -------------------------------------------------------------------- +#! ⚠️ WIP: Not all backends can be manually configured today. +#! On Windows & Linux the Vulkan & GLES backends are always enabled. +#! See [#3514](https://github.com/gfx-rs/wgpu/issues/3514) for more details. + +## Enables the DX12 backend on Windows. +dx12 = ["wgc?/dx12"] + +## Enables the Metal backend on macOS & iOS. +metal = ["wgc?/metal"] + +## Enables the GLES backend via [ANGLE](https://github.com/google/angle) on macOS using. +angle = ["wgc?/gles"] + +## Enables the Vulkan backend on macOS & iOS. +vulkan-portability = ["wgc?/vulkan"] + +## Enables the GLES backend on Wasm +## +## * ⚠️ WIP: Currently will also enable GLES dependencies on any other targets. +## * ⚠️ WIP: This automatically disables use of WebGPU. See [#2804](https://github.com/gfx-rs/wgpu/issues/3514). +webgl = ["hal", "wgc/gles"] + +#! ### Shading language support +# -------------------------------------------------------------------- + +## Enable accepting SPIR-V shaders as input. spirv = ["naga/spv-in"] + +## Enable accepting GLSL shaders as input. glsl = ["naga/glsl-in"] + +## Enable accepting WGSL shaders as input. wgsl = ["wgc?/wgsl"] + +#! ### Logging & Tracing +# -------------------------------------------------------------------- +#! The following features do not have any effect on the WebGPU backend. + +## Apply run-time checks, even in release builds. These are in addition +## to the validation carried out at public APIs in all builds. +strict_asserts = ["wgc?/strict_asserts", "wgt/strict_asserts"] + +## Log all API entry points at info instead of trace level. +api_log_info = ["wgc/api_log_info"] + +## Allow writing of trace capture files. +## See [`Adapter::request_device`]. trace = ["serde", "wgc/trace"] + +## Allow deserializing of trace capture files that were written with the `trace` feature. +## To replay a trace file use the [wgpu player](https://github.com/gfx-rs/wgpu/tree/trunk/player). replay = ["serde", "wgc/replay"] -# Implement `Send` and `Sync` on Wasm. + +#! ### Other +# -------------------------------------------------------------------- + +## Implement `Send` and `Sync` on Wasm, but only if atomics are not enabled. +## +## WebGL/WebGPU objects can not be shared between threads. +## However, it can be useful to artificially mark them as `Send` and `Sync` +## anyways to make it easier to write cross-platform code. +## This is technically *very* unsafe in a multithreaded environment, +## but on a wasm binary compiled without atomics we know we are definitely +## not in a multithreaded environment. 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", ] -# Log all API entry points at info instead of trace level. -api_log_info = ["wgc/api_log_info"] -# Backends -# Enables the DX12 backend on Windows -dx12 = ["wgc?/dx12"] -# Enables the Metal backend on macOS & iOS -metal = ["wgc?/metal"] -# Enables the GLES backend on Windows & macOS -angle = ["wgc?/gles"] -# Enables the Vulkan backend on macOS & iOS -vulkan-portability = ["wgc?/vulkan"] -# Enables the GLES backend on Wasm (currently will also enable GLES dependencies on any other target) -webgl = ["hal", "wgc/gles"] # wgpu-core is always available as an optional dependency, "wgc". # Whenever wgpu-core is selected, we want raw window handle support. @@ -110,6 +155,7 @@ optional = true [dependencies] arrayvec.workspace = true cfg-if.workspace = true +document-features.workspace = true log.workspace = true parking_lot.workspace = true profiling.workspace = true diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs index b3c665c3f..b02434e47 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -1,6 +1,10 @@ //! A cross-platform graphics and compute library based on [WebGPU](https://gpuweb.github.io/gpuweb/). //! //! To start using the API, create an [`Instance`]. +//! +//! ## Feature flags +#![doc = document_features::document_features!()] +//! #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))] #![doc(html_logo_url = "https://raw.githubusercontent.com/gfx-rs/wgpu/trunk/logo.png")]