fix up the docs

wgpu-core/src/device/queue.rs

@@ -999,7 +999,7 @@ impl<G: GlobalIdentityHandlerFactory> Global<G> {
                             .initialize_texture_memory(&mut *trackers, &mut *texture_guard, device)
                             .map_err(|err| QueueSubmitError::DestroyedTexture(err.0))?;
 
-                        // Insert synthetic barriers to insert EXTERNAL barriers for any used external textures.
+                        // Insert synthetic barriers to for external textures used in the command submission.
                         {
                             let mut used_external_textures = TextureUsageScope::new();
                             let mut visited_ids = HashSet::new();
@@ -1024,13 +1024,15 @@ impl<G: GlobalIdentityHandlerFactory> Global<G> {
                                         .unwrap_or(false)
                                 })
                                 .filter(|transition| {
-                                    // Insert returns false if the element was already added.
+                                    // HashSet::insert returns false if the element was already added.
                                     visited_ids.insert(&transition.id)
                                 });
 
                             external_textures.for_each(|transition| {
-                                // Create and record a synthetic transition state to EXTERNAL based on the last usage.
+                                // Create and record a synthetic transition state to EXTERNAL AND the last usage.
                                 unsafe {
+                                    // SAFETY: The texture must be known by the tracker if it was used during
+                                    // command submission or is pending.
                                     let id = texture_guard
                                         .get_valid_unchecked(transition.id, A::VARIANT);
                                     let ref_count = baked.trackers.textures.get_ref_count(id);

wgpu-hal/Cargo.toml

@@ -35,6 +35,7 @@ dx11 = ["naga/hlsl-out", "native", "libloading", "winapi/d3d11", "winapi/d3d11_1
 dx12 = ["naga/hlsl-out", "native", "bit-set", "range-alloc", "winapi/d3d12", "winapi/d3d12shader", "winapi/d3d12sdklayers", "winapi/dxgi1_6"]
 renderdoc = ["libloading", "renderdoc-sys"]
 emscripten = ["gles"]
+strict_asserts = []
 
 [[example]]
 name = "halmark"

wgpu-hal/src/assertions.rs

@@ -0,0 +1,50 @@
+//! This module defines assertion macros that respect `wgpu-hal`'s
+//! `"strict_asserts"` feature.
+
+#[cfg(feature = "strict_asserts")]
+#[macro_export]
+macro_rules! strict_assert {
+    ( $( $arg:tt )* ) => {
+        assert!( $( $arg )* )
+    }
+}
+
+#[cfg(feature = "strict_asserts")]
+#[macro_export]
+macro_rules! strict_assert_eq {
+    ( $( $arg:tt )* ) => {
+        assert_eq!( $( $arg )* )
+    }
+}
+
+#[cfg(feature = "strict_asserts")]
+#[macro_export]
+macro_rules! strict_assert_ne {
+    ( $( $arg:tt )* ) => {
+        assert_ne!( $( $arg )* )
+    }
+}
+
+#[cfg(not(feature = "strict_asserts"))]
+#[macro_export]
+macro_rules! strict_assert {
+    ( $( $arg:tt )* ) => {
+        debug_assert!( $( $arg )* )
+    };
+}
+
+#[cfg(not(feature = "strict_asserts"))]
+#[macro_export]
+macro_rules! strict_assert_eq {
+    ( $( $arg:tt )* ) => {
+        debug_assert_eq!( $( $arg )* )
+    };
+}
+
+#[cfg(not(feature = "strict_asserts"))]
+#[macro_export]
+macro_rules! strict_assert_ne {
+    ( $( $arg:tt )* ) => {
+        debug_assert_ne!( $( $arg )* )
+    };
+}

wgpu-hal/src/lib.rs

@@ -54,6 +54,9 @@ compile_error!("Metal API enabled on non-Apple OS. If your project is not using
 #[cfg(all(feature = "dx12", not(windows)))]
 compile_error!("DX12 API enabled on non-Windows OS. If your project is not using resolver=\"2\" in Cargo.toml, it should.");
 
+#[macro_use]
+mod assertions;
+
 #[cfg(all(feature = "dx11", windows))]
 mod dx11;
 #[cfg(all(feature = "dx12", windows))]

wgpu-hal/src/vulkan/device.rs

@@ -605,19 +605,31 @@ impl super::Device {
         })
     }
 
+    /// Creates a hal texture from a Vulkan [`Image`].
+    ///
+    /// The `external_queue_family_index` specifies what queue family the image must be transferred from when the image
+    /// is used during command execution. This parameter is essential for using an [`Image`] that has been imported from
+    /// a platform's external memory handle using extensions such as [VK_EXT_external_memory_dma_buf] and
+    /// [VK_ANDROID_external_memory_android_hardware_buffer].
+    ///
     /// # Safety
     ///
-    /// - `vk_image` must be created respecting `desc`
+    /// - `vk_image` must be created respecting `desc`. In particular this means that the format of the
+    ///   `vk_image` must have a valid wgpu equivalent format.
     /// - If [`TextureUses::EXTERNAL`](crate::TextureUses::EXTERNAL) is set, then `external_queue_family_index` must be set.
     /// - If `drop_guard` is `Some`, the application must manually destroy the image handle. This
     ///   can be done inside the `Drop` impl of `drop_guard`.
+    ///
+    /// [`Image`]: vk::Image
+    /// [VK_EXT_external_memory_dma_buf]: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_external_memory_dma_buf.html
+    /// [VK_ANDROID_external_memory_android_hardware_buffer]: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_ANDROID_external_memory_android_hardware_buffer.html
     pub unsafe fn texture_from_raw(
         vk_image: vk::Image,
         desc: &crate::TextureDescriptor,
         external_queue_family_index: Option<u32>,
         drop_guard: Option<crate::DropGuard>,
     ) -> super::Texture {
-        #[cfg(debug_assertions)]
+        #[cfg(feature = "strict_asserts")]
         {
             if desc.usage.contains(crate::TextureUses::EXTERNAL) {
                 assert!(external_queue_family_index.is_some(), "Texture has TextureUse::EXTERNAL, but does not specify the owning queue family");