diff --git a/Cargo.lock b/Cargo.lock index 31e69e12a7..0d1769b4e0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1108,6 +1108,15 @@ dependencies = [ "libloading 0.8.1", ] +[[package]] +name = "document-features" +version = "0.2.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef5282ad69563b5fc40319526ba27e0e7363d552a896f0297d54f767717f9b95" +dependencies = [ + "litrs", +] + [[package]] name = "downcast-rs" version = "1.2.0" @@ -1946,6 +1955,12 @@ version = "0.4.13" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "01cda141df6706de531b6c46c3a33ecca755538219bd484262fa09410c13539c" +[[package]] +name = "litrs" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b4ce301924b7887e9d637144fdade93f9dfff9b60981d4ac161db09720d39aa5" + [[package]] name = "lock_api" version = "0.4.11" @@ -3967,6 +3982,7 @@ dependencies = [ "arrayvec 0.7.4", "cfg-if", "cfg_aliases", + "document-features", "js-sys", "log", "naga", @@ -3994,6 +4010,7 @@ dependencies = [ "bytemuck", "cfg_aliases", "codespan-reporting", + "document-features", "indexmap", "log", "naga", diff --git a/Cargo.toml b/Cargo.toml index bde4e8451a..3dc6dfb6f3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -77,6 +77,7 @@ cfg_aliases = "0.1" cfg-if = "1" codespan-reporting = "0.11" ctor = "0.2" +document-features = "0.2.8" encase = "0.7" env_logger = "0.10" fern = "0.6" diff --git a/wgpu-core/Cargo.toml b/wgpu-core/Cargo.toml index 9c2ca87b0e..890120ac08 100644 --- a/wgpu-core/Cargo.toml +++ b/wgpu-core/Cargo.toml @@ -101,6 +101,7 @@ bit-vec = "0.6" bitflags = "2" bytemuck = { version = "1.14", optional = true } codespan-reporting = "0.11" +document-features.workspace = true indexmap = "2" log = "0.4" once_cell = "1" diff --git a/wgpu-core/src/lib.rs b/wgpu-core/src/lib.rs index 9f6526fc11..5454f0d682 100644 --- a/wgpu-core/src/lib.rs +++ b/wgpu-core/src/lib.rs @@ -3,36 +3,8 @@ //! into other language-specific user-friendly libraries. //! //! ## Feature flags -// NOTE: feature docs. below should be kept in sync. with `Cargo.toml`! +#![doc = document_features::document_features!()] //! -//! - **`api_log_info`** --- Log all API entry points at info instead of trace level. -//! - **`resource_log_info`** --- Log resource lifecycle management at info instead of trace level. -//! - **`link`** _(enabled by default)_ --- Use static linking for libraries. Disable to manually -//! link. Enabled by default. -//! - **`renderdoc`** --- Support the Renderdoc graphics debugger: -//! [https://renderdoc.org/](https://renderdoc.org/) -//! - **`strict_asserts`** --- Apply run-time checks, even in release builds. These are in addition -//! to the validation carried out at public APIs in all builds. -//! - **`serde`** --- Enables serialization via `serde` on common wgpu types. -//! - **`trace`** --- Enable API tracing. -//! - **`replay`** --- Enable API replaying -//! - **`wgsl`** --- Enable `ShaderModuleSource::Wgsl` -//! - **`fragile-send-sync-non-atomic-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. -//! -//! ### Backends, passed through to wgpu-hal -//! -//! - **`metal`** --- Enable the `metal` backend. -//! - **`vulkan`** --- Enable the `vulkan` backend. -//! - **`gles`** --- Enable the `GLES` backend. -//! -//! This is used for all of GLES, OpenGL, and WebGL. -//! - **`dx12`** --- Enable the `dx12` backend. // 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 2c2b8af2e0..e4d4795cb1 100644 --- a/wgpu/Cargo.toml +++ b/wgpu/Cargo.toml @@ -38,20 +38,24 @@ dx12 = ["wgc?/dx12"] ## Enables the Metal backend on macOS & iOS. metal = ["wgc?/metal"] +## Enables the WebGPU backend on Wasm. Disabled when targeting `emscripten`. +webgpu = ["naga?/wgsl-out"] + ## 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 WebGPU backend on Wasm. Disabled when targeting `emscripten`. -webgpu = ["naga?/wgsl-out"] - ## Enables the GLES backend on Wasm ## ## * ⚠️ WIP: Currently will also enable GLES dependencies on any other targets. webgl = ["hal", "wgc/gles"] +#! **Note:** In the documentation, if you see that an item depends on a backend, +#! it means that the item is only available when that backend is enabled _and_ the backend +#! is supported on the current platform. + #! ### Shading language support # -------------------------------------------------------------------- @@ -81,8 +85,7 @@ api_log_info = ["wgc/api_log_info"] ## Enables serialization via `serde` on common wgpu types. serde = ["dep:serde", "wgc/serde"] -## Allow writing of trace capture files. -## See [`Adapter::request_device`]. +## 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. @@ -163,6 +166,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 cf39652c47..983c7d5a2b 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -3,55 +3,7 @@ //! To start using the API, create an [`Instance`]. //! //! ## Feature flags -// NOTE: feature docs. below should be kept in sync. with `Cargo.toml`! -//! -//! ### 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. -//! -//! - **`dx12`** _(enabled by default)_ --- Enables the DX12 backend on Windows. -//! - **`metal`** _(enabled by default)_ --- Enables the Metal backend on macOS & iOS. -//! - **`webgpu`** _(enabled by default)_ --- Enables the WebGPU backend on Wasm. Disabled when targeting `emscripten`. -//! - **`angle`** --- Enables the GLES backend via [ANGLE](https://github.com/google/angle) on macOS. -//! - **`vulkan-portability`** --- Enables the Vulkan backend on macOS & iOS. -//! - **`webgl`** --- Enables the GLES backend on Wasm. -//! - ⚠️ WIP: Currently will also enable GLES dependencies on any other targets. -//! -//! **Note:** In the documentation, if you see that an item depends on a backend, -//! it means that the item is only available when that backend is enabled _and_ the backend -//! is supported on the current platform. -//! -//! ### Shading language support -//! -//! - **`wgsl`** _(enabled by default)_ --- Enable accepting WGSL shaders as input. -//! - **`spirv`** --- Enable accepting SPIR-V shaders as input. -//! - **`glsl`** --- Enable accepting GLSL shaders as input. -//! - **`naga-ir`** --- Enable accepting Naga IR shaders as input. -//! -//! ### Logging & Tracing -//! -//! The following features do not have any effect on the WebGPU backend. -//! -//! - **`strict_asserts`** --- Apply run-time checks, even in release builds. These are in addition -//! to the validation carried out at public APIs in all builds. -//! - **`api_log_info`** --- Log all API entry points at info instead of trace level. -//! - **`serde`** --- Enables serialization via `serde` on common wgpu types. -//! - **`trace`** --- Allow writing of trace capture files. See [`Adapter::request_device`]. -//! - **`replay`** --- 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). -//! -//! ### Other -//! -//! - **`fragile-send-sync-non-atomic-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. +#![doc = document_features::document_features!()] //! //! ### Feature Aliases //!