Skip to content

Commit 3d5bec6

Browse files
ErichDonGublerErichDonGubler
committed
docs: inline document-features usage, remove dep.
Re-implements #4886 (CC @Wumpf) without the `document-features` crate, which has issues integrating into Firefox builds after being `cargo vendor`ed into its repository. This issue is being tracked against slint-ui/document-features#20. Once resolved, I expect that we will want to revert this PR in its entirety, since `document-features` is still a good addition to `wgpu`'s documentation story. Internally, consensus has already been achieved for this change. Firefox's ability to build unfortunately take priority over this particular convenience. Hopefully, we won't have to compromise shortly! I tested this by ensuring that the HTML output of our existing `document_features::document_features!(…)` usage was exactly the same. There should be exactly zero regressions in the current state of documentation for users. For maintainers, I have added a disclaimer that one needs to keep changes in sync. with the relevant `Cargo.toml` manifests.
1 parent c97b351 commit 3d5bec6

File tree

6 files changed

+75
-22
lines changed

6 files changed

+75
-22
lines changed

‎Cargo.lock

-17
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml

-1
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,6 @@ cfg_aliases = "0.1"
7777
cfg-if = "1"
7878
codespan-reporting = "0.11"
7979
ctor = "0.2"
80-
document-features = "0.2"
8180
encase = "0.6"
8281
env_logger = "0.10"
8382
fern = "0.6"

‎wgpu-core/Cargo.toml

-1
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,6 @@ arrayvec = "0.7"
9494
bit-vec = "0.6"
9595
bitflags = "2"
9696
codespan-reporting = "0.11"
97-
document-features.workspace = true
9897
log = "0.4"
9998
# parking_lot 0.12 switches from `winapi` to `windows`; permit either
10099
parking_lot = ">=0.11,<0.13"

‎wgpu-core/src/lib.rs

+29-1
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,36 @@
33
//! into other language-specific user-friendly libraries.
44
//!
55
//! ## Feature flags
6-
#![doc = document_features::document_features!()]
6+
// NOTE: the above should be kept in sync. with `Cargo.toml`!
77
//!
8+
//! - **`api_log_info`** --- Log all API entry points at info instead of trace level.
9+
//! - **`resource_log_info`** --- Log resource lifecycle management at info instead of trace level.
10+
//! - **`link`** _(enabled by default)_ --- Use static linking for libraries. Disale to manually
11+
//! link. Enabled by default.
12+
//! - **`renderdoc`** --- Support the Renderdoc graphics debugger:
13+
//! [https://renderdoc.org/](https://renderdoc.org/)
14+
//! - **`strict_asserts`** --- Apply run-time checks, even in release builds. These are in addition
15+
//! to the validation carried out at public APIs in all builds.
16+
//! - **`trace`** --- Enable API tracing.
17+
//! - **`replay`** --- Enable API replaying
18+
//! - **`serial-pass`** --- Enable serializable compute/render passes, and bundle encoders.
19+
//! - **`wgsl`** --- Enable `ShaderModuleSource::Wgsl`
20+
//! - **`fragile-send-sync-non-atomic-wasm`** --- Implement `Send` and `Sync` on Wasm, but only if
21+
//! atomics are not enabled.
22+
//!
23+
//! WebGL/WebGPU objects can not be shared between threads. However, it can be useful to
24+
//! artificially mark them as `Send` and `Sync` anyways to make it easier to write cross-platform
25+
//! code. This is technically _very_ unsafe in a multithreaded environment, but on a wasm binary
26+
//! compiled without atomics we know we are definitely not in a multithreaded environment.
27+
//!
28+
//! ### Backends, passed through to wgpu-hal
29+
//!
30+
//! - **`metal`** --- Enable the `metal` backend.
31+
//! - **`vulkan`** --- Enable the `vulkan` backend.
32+
//! - **`gles`** --- Enable the `GLES` backend.
33+
//!
34+
//! This is used for all of GLES, OpenGL, and WebGL.
35+
//! - **`dx12`** --- Enable the `dx12` backend.
836
937
// When we have no backends, we end up with a lot of dead or otherwise unreachable code.
1038
#![cfg_attr(

‎wgpu/Cargo.toml

-1
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,6 @@ optional = true
155155
[dependencies]
156156
arrayvec.workspace = true
157157
cfg-if.workspace = true
158-
document-features.workspace = true
159158
log.workspace = true
160159
parking_lot.workspace = true
161160
profiling.workspace = true

‎wgpu/src/lib.rs

+46-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,52 @@
33
//! To start using the API, create an [`Instance`].
44
//!
55
//! ## Feature flags
6-
#![doc = document_features::document_features!()]
6+
// NOTE: the above should be kept in sync. with `Cargo.toml`!
7+
//!
8+
//! ### Backends
9+
//!
10+
//! ⚠️ WIP: Not all backends can be manually configured today. On Windows & Linux the Vulkan & GLES
11+
//! backends are always enabled. See [#3514](https://github.com/gfx-rs/wgpu/issues/3514) for more
12+
//! details.
13+
//!
14+
//! - **`dx12`** _(enabled by default)_ --- Enables the DX12 backend on Windows.
15+
//! - **`metal`** _(enabled by default)_ --- Enables the Metal backend on macOS & iOS.
16+
//! - **`angle`** --- Enables the GLES backend via [ANGLE](https://github.com/google/angle) on macOS
17+
//! using.
18+
//! - **`vulkan-portability`** --- Enables the Vulkan backend on macOS & iOS.
19+
//! - **`webgl`** --- Enables the GLES backend on Wasm
20+
//!
21+
//! - ⚠️ WIP: Currently will also enable GLES dependencies on any other targets.
22+
//! - ⚠️ WIP: This automatically disables use of WebGPU. See
23+
//! [#2804](https://github.com/gfx-rs/wgpu/issues/3514).
24+
//!
25+
//! ### Shading language support
26+
//!
27+
//! - **`spirv`** --- Enable accepting SPIR-V shaders as input.
28+
//! - **`glsl`** --- Enable accepting GLSL shaders as input.
29+
//! - **`wgsl`** _(enabled by default)_ --- Enable accepting WGSL shaders as input.
30+
//!
31+
//! ### Logging & Tracing
32+
//!
33+
//! The following features do not have any effect on the WebGPU backend.
34+
//!
35+
//! - **`strict_asserts`** --- Apply run-time checks, even in release builds. These are in addition
36+
//! to the validation carried out at public APIs in all builds.
37+
//! - **`api_log_info`** --- Log all API entry points at info instead of trace level.
38+
//! - **`trace`** --- Allow writing of trace capture files. See [`Adapter::request_device`].
39+
//! - **`replay`** --- Allow deserializing of trace capture files that were written with the `trace`
40+
//! feature. To replay a trace file use the [wgpu
41+
//! player](https://github.com/gfx-rs/wgpu/tree/trunk/player).
42+
//!
43+
//! ### Other
44+
//!
45+
//! - **`fragile-send-sync-non-atomic-wasm`** --- Implement `Send` and `Sync` on Wasm, but only if
46+
//! atomics are not enabled.
47+
//!
48+
//! WebGL/WebGPU objects can not be shared between threads. However, it can be useful to
49+
//! artificially mark them as `Send` and `Sync` anyways to make it easier to write cross-platform
50+
//! code. This is technically _very_ unsafe in a multithreaded environment, but on a wasm binary
51+
//! compiled without atomics we know we are definitely not in a multithreaded environment.
752
//!
853
954
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]

0 commit comments

Comments
 (0)