Document wgpu & wgpu-core features

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).

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"

wgpu-core/Cargo.toml

@@ -29,54 +29,80 @@ 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.
-resource_log_info = []
 
-# Backends, passed through to wgpu-hal
-metal = ["hal/metal"]
-vulkan = ["hal/vulkan"]
-gles = ["hal/gles"]
-dx12 = ["hal/dx12"]
+## Log resource lifecycle management at info instead of trace level.
+resource_log_info = []
 
-# 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 enforce `Send` and `Sync`
+## anyways to make it easier to write cross-platform code.
+## This is technically *very* unsafe, but as long as objects can not be shared
+## with another thread it's fine, thus the restriction on having atomics disabled.
 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"

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(

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 Windows & 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 the WebGPU feature. See [#2804](https://github.com/gfx-rs/wgpu/issues/3514).
+webgl = ["hal", "wgc/gles"]
+
+#! ### Shading language support
+# --------------------------------------------------------------------
+#! The following features do not have any effect on the WebGPU backend.
+
+## 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 enforce `Send` and `Sync`
+## anyways to make it easier to write cross-platform code.
+## This is technically *very* unsafe, but as long as objects can not be shared
+## with another thread it's fine, thus the restriction on having atomics disabled.
 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

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")]