From 2e3818795447f9f0c87bf710da4eea9b95efec2d Mon Sep 17 00:00:00 2001 From: Connor Fitzgerald Date: Tue, 16 Jan 2024 14:21:51 -0500 Subject: [PATCH] Re-export public dependencies (#5063) --- CHANGELOG.md | 14 +++++++ wgpu-core/src/lib.rs | 1 + wgpu/Cargo.toml | 9 ++--- wgpu/build.rs | 5 ++- wgpu/src/backend/webgpu.rs | 6 +-- wgpu/src/backend/wgpu_core.rs | 4 +- wgpu/src/lib.rs | 75 +++++++++++++++++++++++++++-------- wgpu/src/util/init.rs | 8 ++-- 8 files changed, 90 insertions(+), 32 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7bdb11de2..96c289ce9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -39,6 +39,20 @@ Bottom level categories: ## Unreleased +### All Public Dependencies Are Re-Exported + +All of wgpu's public dependencies are now re-exported at the top level so that users don't need to take their own dependencies. +This includes: +- wgpu-core +- wgpu-hal +- naga +- raw_window_handle +- web_sys + +### `naga-ir` Shaders Have Dedicated Feature + +The `naga-ir` feature has been added to allow you to add naga module shaders without guessing about what other features needed to be enabled to get access to it. + ### Direct3D 11 backend removal This backend had no functionality, and with the recent support for GL on Desktop, which allows wgpu to run on older devices, there is no need to keep the backend. diff --git a/wgpu-core/src/lib.rs b/wgpu-core/src/lib.rs index 4fd284537..74c27bd96 100644 --- a/wgpu-core/src/lib.rs +++ b/wgpu-core/src/lib.rs @@ -105,6 +105,7 @@ mod track; pub mod validation; pub use hal::{api, MAX_BIND_GROUPS, MAX_COLOR_ATTACHMENTS, MAX_VERTEX_BUFFERS}; +pub use naga; use std::{borrow::Cow, os::raw::c_char}; diff --git a/wgpu/Cargo.toml b/wgpu/Cargo.toml index 8848371b9..813bc71f5 100644 --- a/wgpu/Cargo.toml +++ b/wgpu/Cargo.toml @@ -45,7 +45,7 @@ angle = ["wgc?/gles"] vulkan-portability = ["wgc?/vulkan"] ## Enables the WebGPU backend on Wasm. Disabled when targeting `emscripten`. -webgpu = [] +webgpu = ["naga?/wgsl-out"] ## Enables the GLES backend on Wasm ## @@ -64,6 +64,9 @@ glsl = ["naga/glsl-in"] ## Enable accepting WGSL shaders as input. wgsl = ["wgc?/wgsl"] +## Enable accepting naga IR shaders as input. +naga-ir = ["naga"] + #! ### Logging & Tracing # -------------------------------------------------------------------- #! The following features do not have any effect on the WebGPU backend. @@ -178,10 +181,6 @@ cfg_aliases.workspace = true workspace = true features = ["wgsl-in"] -[target.'cfg(target_arch = "wasm32")'.dependencies.naga] -workspace = true -features = ["wgsl-out"] - [target.'cfg(target_arch = "wasm32")'.dependencies] web-sys = { workspace = true, features = [ "Document", diff --git a/wgpu/build.rs b/wgpu/build.rs index 6f3d0f58a..1f07f7ebb 100644 --- a/wgpu/build.rs +++ b/wgpu/build.rs @@ -10,6 +10,9 @@ fn main() { all(feature = "fragile-send-sync-non-atomic-wasm", not(target_feature = "atomics")) ) }, dx12: { all(target_os = "windows", feature = "dx12") }, - metal: { all(any(target_os = "ios", target_os = "macos"), feature = "metal") } + metal: { all(any(target_os = "ios", target_os = "macos"), feature = "metal") }, + // This alias is _only_ if _we_ need naga in the wrapper. wgpu-core provides + // its own re-export of naga, which can be used in other situations + naga: { any(feature = "naga-ir", feature = "spirv", feature = "glsl") }, } } diff --git a/wgpu/src/backend/webgpu.rs b/wgpu/src/backend/webgpu.rs index f8a3380c9..91115c3e0 100644 --- a/wgpu/src/backend/webgpu.rs +++ b/wgpu/src/backend/webgpu.rs @@ -1400,7 +1400,7 @@ impl crate::context::Context for ContextWebGpu { feature = "spirv", feature = "glsl", feature = "wgsl", - feature = "naga" + feature = "naga-ir" )), allow(unreachable_code, unused_variables) )] @@ -1411,7 +1411,7 @@ impl crate::context::Context for ContextWebGpu { desc: crate::ShaderModuleDescriptor<'_>, _shader_bound_checks: wgt::ShaderBoundChecks, ) -> (Self::ShaderModuleId, Self::ShaderModuleData) { - let mut descriptor = match desc.source { + let mut descriptor: web_sys::GpuShaderModuleDescriptor = match desc.source { #[cfg(feature = "spirv")] crate::ShaderSource::SpirV(ref spv) => { use naga::{back, front, valid}; @@ -1465,7 +1465,7 @@ impl crate::context::Context for ContextWebGpu { } #[cfg(feature = "wgsl")] crate::ShaderSource::Wgsl(ref code) => web_sys::GpuShaderModuleDescriptor::new(code), - #[cfg(feature = "naga")] + #[cfg(feature = "naga-ir")] crate::ShaderSource::Naga(module) => { use naga::{back, valid}; diff --git a/wgpu/src/backend/wgpu_core.rs b/wgpu/src/backend/wgpu_core.rs index 3d5fd1d14..1d4139e73 100644 --- a/wgpu/src/backend/wgpu_core.rs +++ b/wgpu/src/backend/wgpu_core.rs @@ -820,7 +820,7 @@ impl crate::Context for ContextWgpuCore { feature = "spirv", feature = "glsl", feature = "wgsl", - feature = "naga" + feature = "naga-ir" )), allow(unreachable_code, unused_variables) )] @@ -866,7 +866,7 @@ impl crate::Context for ContextWgpuCore { } #[cfg(feature = "wgsl")] ShaderSource::Wgsl(ref code) => wgc::pipeline::ShaderModuleSource::Wgsl(Borrowed(code)), - #[cfg(feature = "naga")] + #[cfg(feature = "naga-ir")] ShaderSource::Naga(module) => wgc::pipeline::ShaderModuleSource::Naga(module), ShaderSource::Dummy(_) => panic!("found `ShaderSource::Dummy`"), }; diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs index 4120894b9..f12892dfb 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -7,25 +7,28 @@ //! //! ### 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 +//! ⚠️ 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. +//! - **`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. -//! - **`webgpu`** --- Enables the WebGPU backend on Wasm. Disabled when targeting `emscripten`. -//! - **`webgl`** --- Enables the GLES backend on Wasm -//! +//! - **`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. -//! - **`wgsl`** _(enabled by default)_ --- Enable accepting WGSL shaders as input. +//! - **`naga-ir`** --- Enable accepting Naga IR shaders as input. //! //! ### Logging & Tracing //! @@ -49,6 +52,14 @@ //! 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. //! +//! ### Feature Aliases +//! +//! These features aren't actually features on the crate itself, but a convenient shorthand for +//! complicated cases. +//! +//! - **`wgpu_core`** --- Enabled when there is any non-webgpu backend enabled on the platform. +//! - **`naga`** ---- Enabled when any non-wgsl shader input is enabled. +//! #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))] #![doc(html_logo_url = "https://raw.githubusercontent.com/gfx-rs/wgpu/trunk/logo.png")] @@ -100,15 +111,45 @@ pub use wgt::{ QUERY_SIZE, VERTEX_STRIDE_ALIGNMENT, }; -#[cfg(not(webgpu))] -#[doc(hidden)] -pub use ::hal; -#[cfg(feature = "naga")] -pub use ::naga; -#[cfg(not(webgpu))] -#[doc(hidden)] +/// Re-export of our `wgpu-core` dependency. +/// +#[cfg(wgpu_core)] +#[doc(inline)] pub use ::wgc as core; +/// Re-export of our `wgpu-hal` dependency. +/// +/// +#[cfg(wgpu_core)] +#[doc(inline)] +pub use ::hal; + +/// Re-export of our `naga` dependency. +/// +#[cfg(wgpu_core)] +#[cfg_attr(docsrs, doc(cfg(any(wgpu_core, naga))))] +#[doc(inline)] +// We re-export wgpu-core's re-export of naga, as we may not have direct access to it. +pub use ::wgc::naga; +/// Re-export of our `naga` dependency. +/// +#[cfg(all(not(wgpu_core), naga))] +#[cfg_attr(docsrs, doc(cfg(any(wgpu_core, naga))))] +#[doc(inline)] +// If that's not available, we re-export our own. +pub use naga; + +#[doc(inline)] +/// Re-export of our `raw-window-handle` dependency. +/// +pub use raw_window_handle as rwh; + +/// Re-export of our `web-sys` dependency. +/// +#[cfg(any(webgl, webgpu))] +#[doc(inline)] +pub use web_sys; + // wasm-only types, we try to keep as many types non-platform // specific, but these need to depend on web-sys. #[cfg(any(webgpu, webgl))] @@ -644,7 +685,7 @@ impl Drop for ShaderModule { /// /// This type is unique to the Rust API of `wgpu`. In the WebGPU specification, /// only WGSL source code strings are accepted. -#[cfg_attr(feature = "naga", allow(clippy::large_enum_variant))] +#[cfg_attr(feature = "naga-ir", allow(clippy::large_enum_variant))] #[derive(Clone, Debug)] #[non_exhaustive] pub enum ShaderSource<'a> { @@ -669,7 +710,7 @@ pub enum ShaderSource<'a> { #[cfg(feature = "wgsl")] Wgsl(Cow<'a, str>), /// Naga module. - #[cfg(feature = "naga")] + #[cfg(feature = "naga-ir")] Naga(Cow<'static, naga::Module>), /// Dummy variant because `Naga` doesn't have a lifetime and without enough active features it /// could be the last one active. diff --git a/wgpu/src/util/init.rs b/wgpu/src/util/init.rs index 016ce5f7f..55154242e 100644 --- a/wgpu/src/util/init.rs +++ b/wgpu/src/util/init.rs @@ -2,13 +2,13 @@ use wgt::{Backends, PowerPreference, RequestAdapterOptions}; use crate::{Adapter, Instance, Surface}; -#[cfg(not(webgpu))] +#[cfg(wgpu_core)] #[cfg_attr(docsrs, doc(cfg(all())))] pub use wgc::instance::parse_backends_from_comma_list; -/// Always returns WEBGPU on wasm over webgpu. -#[cfg(webgpu)] +/// Just return ALL, if wgpu_core is not enabled. +#[cfg(not(wgpu_core))] pub fn parse_backends_from_comma_list(_string: &str) -> Backends { - Backends::BROWSER_WEBGPU + Backends::all() } /// Get a set of backend bits from the environment variable WGPU_BACKEND.