Code review:

- Remove Cow from wgpu-hal API surface. You graze on in our hearts.
- Rename feature flag to SPIRV_SHADER_PASSTHROUGH in anticipation
  of crate feature `spirv` to reduce confusion.
- Add some more documentation about behaviour and intended avenues of
  use to the feature.

wgpu-core/src/device/mod.rs

@@ -939,9 +939,9 @@ impl<A: HalApi> Device<A> {
         &self,
         self_id: id::DeviceId,
         desc: &pipeline::ShaderModuleDescriptor<'a>,
-        source: Cow<'a, [u32]>,
+        source: &'a [u32],
     ) -> Result<pipeline::ShaderModule<A>, pipeline::CreateShaderModuleError> {
-        self.require_features(wgt::Features::SPIRV_SHADER_MODULES)?;
+        self.require_features(wgt::Features::SPIRV_SHADER_PASSTHROUGH)?;
         let hal_desc = hal::ShaderModuleDescriptor {
             label: desc.label.borrow_option(),
         };
@@ -3546,7 +3546,7 @@ impl<G: GlobalIdentityHandlerFactory> Global<G> {
                 });
             };
 
-            let shader = match device.create_shader_module_spirv(device_id, desc, source) {
+            let shader = match device.create_shader_module_spirv(device_id, desc, &source) {
                 Ok(shader) => shader,
                 Err(e) => break e,
             };

wgpu-hal/src/lib.rs

@@ -64,7 +64,7 @@ pub mod api {
 }
 
 use std::{
-    borrow::{Borrow, Cow},
+    borrow::Borrow,
     fmt,
     num::NonZeroU8,
     ops::{Range, RangeInclusive},
@@ -842,7 +842,7 @@ pub struct NagaShader {
 /// Shader input.
 pub enum ShaderInput<'a> {
     Naga(NagaShader),
-    SpirV(Cow<'a, [u32]>),
+    SpirV(&'a [u32]),
 }
 
 pub struct ShaderModuleDescriptor<'a> {

wgpu-hal/src/metal/device.rs

@@ -635,7 +635,7 @@ impl crate::Device<super::Api> for super::Device {
         match shader {
             crate::ShaderInput::Naga(raw) => Ok(super::ShaderModule { raw }),
             crate::ShaderInput::SpirV(_) => {
-                unreachable!("SPIRV_SHADER_MODULES is not enabled for this backend")
+                unreachable!("SPIRV_SHADER_PASSTHROUGH is not enabled for this backend")
             }
         }
     }

wgpu-hal/src/vulkan/adapter.rs

@@ -203,7 +203,7 @@ impl PhysicalDeviceFeatures {
     fn to_wgpu(&self, caps: &PhysicalDeviceCapabilities) -> (wgt::Features, wgt::DownlevelFlags) {
         use wgt::{DownlevelFlags as Df, Features as F};
         let mut features = F::empty()
-            | F::SPIRV_SHADER_MODULES
+            | F::SPIRV_SHADER_PASSTHROUGH
             | F::MAPPABLE_PRIMARY_BUFFERS
             | F::PUSH_CONSTANTS
             | F::ADDRESS_MODE_CLAMP_TO_BORDER

wgpu-hal/src/vulkan/device.rs

@@ -1070,7 +1070,7 @@ impl crate::Device<super::Api> for super::Device {
                 )
                 .map_err(|e| crate::ShaderError::Compilation(format!("{}", e)))?,
             ),
-            crate::ShaderInput::SpirV(spv) => spv,
+            crate::ShaderInput::SpirV(spv) => Cow::Borrowed(spv),
         };
 
         let vk_info = vk::ShaderModuleCreateInfo::builder()

wgpu-types/src/lib.rs

@@ -596,12 +596,16 @@ bitflags::bitflags! {
         const CLEAR_COMMANDS = 0x0000_0200_0000_0000;
         /// Enables creating shader modules from SPIR-V binary data (unsafe).
         ///
+        /// SPIR-V data is not parsed or interpreted in any way; you can use
+        /// [`wgpu::make_spirv_raw!`] to check for alignment and magic number when converting from
+        /// raw bytes.
+        ///
         /// Supported platforms:
         /// - Vulkan, in case shader's requested capabilities and extensions agree with
         /// Vulkan implementation.
         ///
         /// This is a native only feature.
-        const SPIRV_SHADER_MODULES = 0x0000_0400_0000_0000;
+        const SPIRV_SHADER_PASSTHROUGH = 0x0000_0400_0000_0000;
 
         /// Features which are part of the upstream WebGPU standard.
         const ALL_WEBGPU = 0x0000_0000_0000_FFFF;

wgpu/examples/texture-arrays/main.rs

@@ -77,7 +77,7 @@ impl framework::Example for Example {
             | wgpu::Features::PUSH_CONSTANTS
     }
     fn required_features() -> wgpu::Features {
-        wgpu::Features::SAMPLED_TEXTURE_BINDING_ARRAY | wgpu::Features::SPIRV_SHADER_MODULES
+        wgpu::Features::SAMPLED_TEXTURE_BINDING_ARRAY | wgpu::Features::SPIRV_SHADER_PASSTHROUGH
     }
     fn required_limits() -> wgpu::Limits {
         wgpu::Limits {

wgpu/src/lib.rs

@@ -1569,8 +1569,10 @@ impl Device {
     ///
     /// # Safety
     ///
-    /// This function passes SPIR-V binary to the backend as-is and can potentially result in a
-    /// driver crash.
+    /// This function passes binary data to the backend as-is and can potentially result in a
+    /// driver crash or bogus behaviour. No attempt is made to ensure that data is valid SPIR-V.
+    ///
+    /// See also [`crate::include_spirv_raw!`] and [`crate::make_spirv_raw`].
     pub unsafe fn create_shader_module_spirv(
         &self,
         desc: &ShaderModuleDescriptorSpirV,

wgpu/src/macros.rs

@@ -57,7 +57,7 @@ macro_rules! include_spirv {
     };
 }
 
-/// Macro to load raw SPIR-V data statically, for use with [`wgpu::Features::SPIRV_SHADER_MODULES`].
+/// Macro to load raw SPIR-V data statically, for use with [`wgpu::Features::SPIRV_SHADER_PASSTHROUGH`].
 ///
 /// It ensures the word alignment as well as the magic number.
 #[macro_export]