nordic-dev.net/wgpu
nordic-dev.net/wgpu
2
0
Fork 0
mirror of https://github.com/gfx-rs/wgpu.git synced 2024-11-22 06:44:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: inline document-features usage, remove dep.

Browse Source 
Re-implements https://github.com/gfx-rs/wgpu/pull/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
https://github.com/slint-ui/document-features/issues/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.
This commit is contained in:
Erich Gubler 2023-12-21 20:33:35 -05:00
parent c97b351b83
commit e1baa5a56e
6 changed files with 75 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
Cargo.lock generated
View File

@ -1100,15 +1100,6 @@ 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"
@ -1948,12 +1939,6 @@ 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"
@ -4009,7 +3994,6 @@ version = "0.18.0"
dependencies = [
"arrayvec 0.7.4",
"cfg-if",
"document-features",
"js-sys",
"log",
"naga",
@ -4035,7 +4019,6 @@ dependencies = [
"bit-vec",
"bitflags 2.4.1",
"codespan-reporting",
"document-features",
"log",
"naga",
"parking_lot",

1
Cargo.toml
View File

@ -77,7 +77,6 @@ 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"

1
wgpu-core/Cargo.toml
View File

@ -94,7 +94,6 @@ arrayvec = "0.7"
bit-vec = "0.6"
bitflags = "2"
codespan-reporting = "0.11"
document-features.workspace = true
log = "0.4"
# parking_lot 0.12 switches from `winapi` to `windows`; permit either
parking_lot = ">=0.11,<0.13"

30
wgpu-core/src/lib.rs
View File

@ -3,8 +3,36 @@
//! into other language-specific user-friendly libraries.
//!
//! ## Feature flags
#![doc = document_features::document_features!()]
// NOTE: feature docs. below should be kept in sync. with `Cargo.toml`!
//!
//! - **`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. Disale 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.
//! - **`trace`** --- Enable API tracing.
//! - **`replay`** --- Enable API replaying
//! - **`serial-pass`** --- Enable serializable compute/render passes, and bundle encoders.
//! - **`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(

1
wgpu/Cargo.toml
View File

@ -155,7 +155,6 @@ optional = true
[dependencies]
arrayvec.workspace = true
cfg-if.workspace = true
document-features.workspace = true
log.workspace = true
parking_lot.workspace = true
profiling.workspace = true

47
wgpu/src/lib.rs
View File

@ -3,7 +3,52 @@
//! To start using the API, create an [`Instance`].
//!
//! ## Feature flags
#![doc = document_features::document_features!()]
// 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.
//! - **`angle`** --- Enables the GLES backend via [ANGLE](https://github.com/google/angle) on macOS
//! using.
//! - **`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.
//! - ⚠️ WIP: This automatically disables use of WebGPU. See
//! [#2804](https://github.com/gfx-rs/wgpu/issues/3514).
//!
//! ### Shading language support
//!
//! - **`spirv`** --- Enable accepting SPIR-V shaders as input.
//! - **`glsl`** --- Enable accepting GLSL shaders as input.
//! - **`wgsl`** _(enabled by default)_ --- Enable accepting WGSL 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.
//! - **`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.
//!
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]