Assortment of Docs and Understandability Improvements

docs/release-checklist.md

@@ -50,6 +50,7 @@ Day of Release:
 - Create a new tag called `vX.Y.Z` and push it to the repo.
 - Create a new release on the `wgpu` repo with the changelog from this version, targeting that tag
 - Create a branch with the with the new version `vX` and push it to the repo.
+  - On this branch, remove the [!NOTE] at the top of [wgpu/examples/README.md].
 - Complete the release's milestone on GitHub.
 - Create a new milestone for the next release, in 12 weeks time.
 - Update the release checklist with any needed changes.

wgpu-core/src/as_hal.rs

@@ -6,7 +6,6 @@ use hal::DynResource;
 use crate::{
     device::Device,
     global::Global,
-    hal_api::HalApi,
     id::{
         AdapterId, BlasId, BufferId, CommandEncoderId, DeviceId, QueueId, SurfaceId, TextureId,
         TextureViewId, TlasId,
@@ -226,7 +225,7 @@ impl Global {
     /// # Safety
     ///
     /// - The raw buffer handle must not be manually destroyed
-    pub unsafe fn buffer_as_hal<A: HalApi>(
+    pub unsafe fn buffer_as_hal<A: hal::Api>(
         &self,
         id: BufferId,
     ) -> Option<impl Deref<Target = A::Buffer>> {
@@ -242,7 +241,7 @@ impl Global {
     /// # Safety
     ///
     /// - The raw texture handle must not be manually destroyed
-    pub unsafe fn texture_as_hal<A: HalApi>(
+    pub unsafe fn texture_as_hal<A: hal::Api>(
         &self,
         id: TextureId,
     ) -> Option<impl Deref<Target = A::Texture>> {
@@ -258,7 +257,7 @@ impl Global {
     /// # Safety
     ///
     /// - The raw texture view handle must not be manually destroyed
-    pub unsafe fn texture_view_as_hal<A: HalApi>(
+    pub unsafe fn texture_view_as_hal<A: hal::Api>(
         &self,
         id: TextureViewId,
     ) -> Option<impl Deref<Target = A::TextureView>> {
@@ -274,7 +273,7 @@ impl Global {
     /// # Safety
     ///
     /// - The raw adapter handle must not be manually destroyed
-    pub unsafe fn adapter_as_hal<A: HalApi>(
+    pub unsafe fn adapter_as_hal<A: hal::Api>(
         &self,
         id: AdapterId,
     ) -> Option<impl Deref<Target = A::Adapter>> {
@@ -291,7 +290,7 @@ impl Global {
     /// # Safety
     ///
     /// - The raw device handle must not be manually destroyed
-    pub unsafe fn device_as_hal<A: HalApi>(
+    pub unsafe fn device_as_hal<A: hal::Api>(
         &self,
         id: DeviceId,
     ) -> Option<impl Deref<Target = A::Device>> {
@@ -305,7 +304,7 @@ impl Global {
     /// # Safety
     ///
     /// - The raw fence handle must not be manually destroyed
-    pub unsafe fn device_fence_as_hal<A: HalApi>(
+    pub unsafe fn device_fence_as_hal<A: hal::Api>(
         &self,
         id: DeviceId,
     ) -> Option<impl Deref<Target = A::Fence>> {
@@ -318,7 +317,7 @@ impl Global {
 
     /// # Safety
     /// - The raw surface handle must not be manually destroyed
-    pub unsafe fn surface_as_hal<A: HalApi>(
+    pub unsafe fn surface_as_hal<A: hal::Api>(
         &self,
         id: SurfaceId,
     ) -> Option<impl Deref<Target = A::Surface>> {
@@ -335,7 +334,7 @@ impl Global {
     ///
     /// - The raw command encoder handle must not be manually destroyed
     pub unsafe fn command_encoder_as_hal_mut<
-        A: HalApi,
+        A: hal::Api,
         F: FnOnce(Option<&mut A::CommandEncoder>) -> R,
         R,
     >(
@@ -363,7 +362,7 @@ impl Global {
     /// # Safety
     ///
     /// - The raw queue handle must not be manually destroyed
-    pub unsafe fn queue_as_hal<A: HalApi>(
+    pub unsafe fn queue_as_hal<A: hal::Api>(
         &self,
         id: QueueId,
     ) -> Option<impl Deref<Target = A::Queue>> {
@@ -377,7 +376,7 @@ impl Global {
     /// # Safety
     ///
     /// - The raw blas handle must not be manually destroyed
-    pub unsafe fn blas_as_hal<A: HalApi>(
+    pub unsafe fn blas_as_hal<A: hal::Api>(
         &self,
         id: BlasId,
     ) -> Option<impl Deref<Target = A::AccelerationStructure>> {
@@ -393,7 +392,7 @@ impl Global {
     /// # Safety
     ///
     /// - The raw tlas handle must not be manually destroyed
-    pub unsafe fn tlas_as_hal<A: HalApi>(
+    pub unsafe fn tlas_as_hal<A: hal::Api>(
         &self,
         id: TlasId,
     ) -> Option<impl Deref<Target = A::AccelerationStructure>> {

wgpu-core/src/device/global.rs

@@ -13,7 +13,6 @@ use crate::{
     conv,
     device::{bgl, life::WaitIdleError, DeviceError, DeviceLostClosure},
     global::Global,
-    hal_api::HalApi,
     id::{self, AdapterId, DeviceId, QueueId, SurfaceId},
     instance::{self, Adapter, Surface},
     pipeline::{
@@ -386,7 +385,7 @@ impl Global {
     /// - `hal_buffer` must be created respecting `desc`
     /// - `hal_buffer` must be initialized
     /// - `hal_buffer` must not have zero size.
-    pub unsafe fn create_buffer_from_hal<A: HalApi>(
+    pub unsafe fn create_buffer_from_hal<A: hal::Api>(
         &self,
         hal_buffer: A::Buffer,
         device_id: DeviceId,

wgpu-core/src/global.rs

@@ -2,7 +2,6 @@ use alloc::{borrow::ToOwned as _, sync::Arc};
 use core::fmt;
 
 use crate::{
-    hal_api::HalApi,
     hub::{Hub, HubReport},
     instance::{Instance, Surface},
     registry::{Registry, RegistryReport},
@@ -44,7 +43,7 @@ impl Global {
     /// # Safety
     ///
     /// Refer to the creation of wgpu-hal Instance for every backend.
-    pub unsafe fn from_hal_instance<A: HalApi>(name: &str, hal_instance: A::Instance) -> Self {
+    pub unsafe fn from_hal_instance<A: hal::Api>(name: &str, hal_instance: A::Instance) -> Self {
         profiling::scope!("Global::new");
 
         Self {
@@ -57,7 +56,7 @@ impl Global {
     /// # Safety
     ///
     /// - The raw instance handle returned must not be manually destroyed.
-    pub unsafe fn instance_as_hal<A: HalApi>(&self) -> Option<&A::Instance> {
+    pub unsafe fn instance_as_hal<A: hal::Api>(&self) -> Option<&A::Instance> {
         unsafe { self.instance.as_hal::<A>() }
     }
 

wgpu-core/src/instance.rs

@@ -15,7 +15,6 @@ use crate::{
     api_log, api_log_debug,
     device::{queue::Queue, resource::Device, DeviceDescriptor, DeviceError},
     global::Global,
-    hal_api::HalApi,
     id::{markers, AdapterId, DeviceId, QueueId, SurfaceId},
     lock::{rank, Mutex},
     present::Presentation,
@@ -117,7 +116,7 @@ impl Instance {
     }
 
     /// Helper for `Instance::new()`; attempts to add a single `wgpu-hal` backend to this instance.
-    fn try_add_hal<A: HalApi>(&mut self, _: A, instance_desc: &wgt::InstanceDescriptor) {
+    fn try_add_hal<A: hal::Api>(&mut self, _: A, instance_desc: &wgt::InstanceDescriptor) {
         // Whether or not the backend was requested, and whether or not it succeeds,
         // note that we *could* try it.
         self.supported_backends |= A::VARIANT.into();
@@ -151,7 +150,7 @@ impl Instance {
         }
     }
 
-    pub(crate) fn from_hal_instance<A: HalApi>(
+    pub(crate) fn from_hal_instance<A: hal::Api>(
         name: String,
         hal_instance: <A as hal::Api>::Instance,
     ) -> Self {
@@ -175,7 +174,7 @@ impl Instance {
     /// # Safety
     ///
     /// - The raw instance handle returned must not be manually destroyed.
-    pub unsafe fn as_hal<A: HalApi>(&self) -> Option<&A::Instance> {
+    pub unsafe fn as_hal<A: hal::Api>(&self) -> Option<&A::Instance> {
         self.raw(A::VARIANT).map(|instance| {
             instance
                 .as_any()

wgpu-core/src/lib.rs

@@ -72,7 +72,6 @@ mod conv;
 pub mod device;
 pub mod error;
 pub mod global;
-pub mod hal_api;
 mod hash_utils;
 pub mod hub;
 pub mod id;

wgpu-hal/src/dx12/mod.rs

@@ -397,6 +397,8 @@ impl D3DBlob {
 pub struct Api;
 
 impl crate::Api for Api {
+    const VARIANT: wgt::Backend = wgt::Backend::Dx12;
+
     type Instance = Instance;
     type Surface = Surface;
     type Adapter = Adapter;

wgpu-hal/src/gles/mod.rs

@@ -101,17 +101,17 @@ pub use fence::Fence;
 #[cfg(not(any(windows, webgl)))]
 pub use self::egl::{AdapterContext, AdapterContextLock};
 #[cfg(not(any(windows, webgl)))]
-use self::egl::{Instance, Surface};
+pub use self::egl::{Instance, Surface};
 
 #[cfg(webgl)]
 pub use self::web::AdapterContext;
 #[cfg(webgl)]
-use self::web::{Instance, Surface};
+pub use self::web::{Instance, Surface};
 
 #[cfg(windows)]
 use self::wgl::AdapterContext;
 #[cfg(windows)]
-use self::wgl::{Instance, Surface};
+pub use self::wgl::{Instance, Surface};
 
 use alloc::{boxed::Box, string::String, string::ToString as _, sync::Arc, vec::Vec};
 use core::{
@@ -141,6 +141,8 @@ const MAX_PUSH_CONSTANTS: usize = 64;
 const MAX_PUSH_CONSTANT_COMMANDS: usize = MAX_PUSH_CONSTANTS * crate::MAX_CONCURRENT_SHADER_STAGES;
 
 impl crate::Api for Api {
+    const VARIANT: wgt::Backend = wgt::Backend::Gl;
+
     type Instance = Instance;
     type Surface = Surface;
     type Adapter = Adapter;

wgpu-hal/src/lib.rs

@@ -472,7 +472,16 @@ impl InstanceError {
     }
 }
 
-pub trait Api: Clone + fmt::Debug + Sized {
+/// All the types and methods that make up a implementation on top of a backend.
+///
+/// Only the types that have non-dyn trait bounds have methods on them. Most methods
+/// are either on [`CommandEncoder`] or [`Device`].
+///
+/// The api can either be used through generics (through use of this trait and associated
+/// types) or dynamically through using the `Dyn*` traits.
+pub trait Api: Clone + fmt::Debug + Sized + WasmNotSendSync + 'static {
+    const VARIANT: wgt::Backend;
+
     type Instance: DynInstance + Instance<A = Self>;
     type Surface: DynSurface + Surface<A = Self>;
     type Adapter: DynAdapter + Adapter<A = Self>;
@@ -1804,6 +1813,10 @@ pub struct Capabilities {
     pub downlevel: wgt::DownlevelCapabilities,
 }
 
+/// An adapter with all the information needed to reason about its capabilities.
+///
+/// These are either made by [`Instance::enumerate_adapters`] or by backend specific
+/// methods on the backend [`Instance`] or [`Adapter`].
 #[derive(Debug)]
 pub struct ExposedAdapter<A: Api> {
     pub adapter: A::Adapter,
@@ -1858,6 +1871,10 @@ pub struct AcquiredSurfaceTexture<A: Api> {
     pub suboptimal: bool,
 }
 
+/// An open connection to a device and a queue.
+///
+/// This can be created from [`Adapter::open`] or backend
+/// specific methods on the backend's [`Instance`] or [`Adapter`].
 #[derive(Debug)]
 pub struct OpenDevice<A: Api> {
     pub device: A::Device,

wgpu-hal/src/metal/mod.rs

@@ -47,6 +47,8 @@ pub struct Api;
 type ResourceIndex = u32;
 
 impl crate::Api for Api {
+    const VARIANT: wgt::Backend = wgt::Backend::Metal;
+
     type Instance = Instance;
     type Surface = Surface;
     type Adapter = Adapter;

wgpu-hal/src/noop/mod.rs

@@ -31,6 +31,8 @@ pub struct Fence {
 type DeviceResult<T> = Result<T, crate::DeviceError>;
 
 impl crate::Api for Api {
+    const VARIANT: wgt::Backend = wgt::Backend::Noop;
+
     type Instance = Context;
     type Surface = Context;
     type Adapter = Context;

wgpu-hal/src/vulkan/mod.rs

@@ -56,6 +56,8 @@ const MAX_TOTAL_ATTACHMENTS: usize = crate::MAX_COLOR_ATTACHMENTS * 2 + 1;
 pub struct Api;
 
 impl crate::Api for Api {
+    const VARIANT: wgt::Backend = wgt::Backend::Vulkan;
+
     type Instance = Instance;
     type Surface = Surface;
     type Adapter = Adapter;

wgpu-types/src/instance.rs

@@ -8,15 +8,34 @@ use crate::Backends;
 use crate::{Backend, DownlevelFlags};
 
 /// Options for creating an instance.
+///
+/// If you want to allow control of instance settings via environment variables, call either
+/// [`InstanceDescriptor::from_env_or_default()`] or [`InstanceDescriptor::with_env()`]. Each type
+/// within this descriptor has its own equivalent methods, so you can select which options you want
+/// to expose to influence from the environment.
 #[derive(Clone, Debug)]
 pub struct InstanceDescriptor {
-    /// Which `Backends` to enable.
+    /// Which [`Backends`] to enable.
+    ///
+    /// [`Backends::BROWSER_WEBGPU`] has an additional effect:
+    /// If it is set and a [`navigator.gpu`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/gpu)
+    /// object is present, this instance will *only* be able to create WebGPU adapters.
+    ///
+    /// ⚠️ On some browsers this check is insufficient to determine whether WebGPU is supported,
+    /// as the browser may define the `navigator.gpu` object, but be unable to create any WebGPU adapters.
+    /// For targeting _both_ WebGPU & WebGL, it is recommended to use [`crate::util::new_instance_with_webgpu_detection`](../wgpu/util/fn.new_instance_with_webgpu_detection.html).
+    ///
+    /// If you instead want to force use of WebGL, either disable the `webgpu` compile-time feature
+    /// or don't include the [`Backends::BROWSER_WEBGPU`] flag in this field.
+    /// If it is set and WebGPU support is *not* detected, the instance will use `wgpu-core`
+    /// to create adapters, meaning that if the `webgl` feature is enabled, it is able to create
+    /// a WebGL adapter.
     pub backends: Backends,
     /// Flags to tune the behavior of the instance.
     pub flags: InstanceFlags,
     /// Memory budget thresholds used by some backends.
     pub memory_budget_thresholds: MemoryBudgetThresholds,
-    /// Options the control the behavior of various backends.
+    /// Options the control the behavior of specific backends.
     pub backend_options: BackendOptions,
 }