Document wgpu & wgpu-core features (#4886)

2024-11-29 02:03:35 +00:00 · 2023-12-17 23:10:38 +01:00 · 2023-12-17 23:10:38 +01:00 · ba56dd2901
commit ba56dd2901
parent 10dd5844ac
7 changed files with 150 additions and 52 deletions
--- 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).
--- 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",
--- 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"
@ -128,15 +128,15 @@ 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"
--- 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:
+## <https://renderdoc.org/>
 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"
--- 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(
--- 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
--- 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")]