Add ExternalTexture BindingType behind new Feature flag

Adds a new feature flag, `EXTERNAL_TEXTURE`, indicating device support
for our implementation of WebGPU's `GPUExternalTexture` [1] which will
land in upcoming patches. Conceptually this would make more sense as a
downlevel flag, as it is a core part of the WebGPU spec which we do not
yet support. We do not want, however, to cause applications to reject
adapters because we have not finished implementing this, so for now we
are making it an opt-in feature.

As an initial step towards supporting this feature, this patch adds a
new `BindingType` corresponding to WebGPU's
`GPUExternalTextureBindingLayout` [2]. This binding type dictates that
when creating a bind group the corresponding entry must be either an
external texture or a texture view with certain additional requirements
[3].

As of yet wgpu has no concept of an external texture (that will follow
in later patches) but for now this patch ensures that texture views
corresponding to an external texture binding type are validated
correctly. Note that as the feature flag is not yet supported on any
real backends, bind group layout creation will fail before getting the
chance to attempt to create a bind group. But in the added tests using
the noop backend we can see this validation taking place.

[1] https://www.w3.org/TR/webgpu/#gpuexternaltexture
[1] https://www.w3.org/TR/webgpu/#dictdef-gpuexternaltexturebindinglayout
[2] https://gpuweb.github.io/gpuweb/#bind-group-creation

Author: jamienicol

tests/tests/wgpu-validation/api/external_texture.rs

@@ -0,0 +1,162 @@
+use wgpu::*;
+use wgpu_test::{fail, valid};
+
+/// Ensures a [`TextureView`] can be bound to a [`BindingType::ExternalTexture`]
+/// resource binding.
+#[test]
+fn external_texture_binding_texture_view() {
+    let (device, _queue) = wgpu::Device::noop(&DeviceDescriptor {
+        required_features: Features::EXTERNAL_TEXTURE,
+        ..Default::default()
+    });
+
+    let bgl = device.create_bind_group_layout(&BindGroupLayoutDescriptor {
+        label: None,
+        entries: &[BindGroupLayoutEntry {
+            binding: 0,
+            visibility: ShaderStages::FRAGMENT,
+            ty: BindingType::ExternalTexture,
+            count: None,
+        }],
+    });
+
+    let texture_descriptor = TextureDescriptor {
+        label: None,
+        size: Extent3d {
+            width: 256,
+            height: 256,
+            depth_or_array_layers: 1,
+        },
+        mip_level_count: 1,
+        sample_count: 1,
+        dimension: TextureDimension::D2,
+        format: TextureFormat::Rgba8Unorm,
+        usage: TextureUsages::TEXTURE_BINDING,
+        view_formats: &[],
+    };
+
+    let texture = device.create_texture(&texture_descriptor);
+    let view = texture.create_view(&TextureViewDescriptor::default());
+    valid(&device, || {
+        device.create_bind_group(&BindGroupDescriptor {
+            label: None,
+            layout: &bgl,
+            entries: &[BindGroupEntry {
+                binding: 0,
+                resource: BindingResource::TextureView(&view),
+            }],
+        })
+    });
+
+    // Invalid usages (must include TEXTURE_BINDING)
+    let texture = device.create_texture(&TextureDescriptor {
+        usage: TextureUsages::STORAGE_BINDING,
+        ..texture_descriptor
+    });
+    let view = texture.create_view(&TextureViewDescriptor::default());
+    fail(
+        &device,
+        || {
+            device.create_bind_group(&BindGroupDescriptor {
+                label: None,
+                layout: &bgl,
+                entries: &[BindGroupEntry {
+                    binding: 0,
+                    resource: BindingResource::TextureView(&view),
+                }],
+            })
+        },
+        Some("Usage flags TextureUsages(STORAGE_BINDING) of TextureView with '' label do not contain required usage flags TextureUsages(TEXTURE_BINDING"),
+    );
+
+    // Invalid dimension (must be D2)
+    let texture = device.create_texture(&TextureDescriptor {
+        dimension: TextureDimension::D3,
+        ..texture_descriptor
+    });
+    let view = texture.create_view(&TextureViewDescriptor::default());
+    fail(
+        &device,
+        || {
+            device.create_bind_group(&BindGroupDescriptor {
+                label: None,
+                layout: &bgl,
+                entries: &[BindGroupEntry {
+                    binding: 0,
+                    resource: BindingResource::TextureView(&view),
+                }],
+            })
+        },
+        Some("Texture binding 0 expects dimension = D2, but given a view with dimension = D3"),
+    );
+
+    // Invalid mip_level_count (must be 1)
+    let texture = device.create_texture(&TextureDescriptor {
+        mip_level_count: 2,
+        ..texture_descriptor
+    });
+    let view = texture.create_view(&TextureViewDescriptor::default());
+    fail(
+        &device,
+        || {
+
+            device.create_bind_group(&BindGroupDescriptor {
+                label: None,
+                layout: &bgl,
+                entries: &[
+                    BindGroupEntry {
+                        binding: 0,
+                        resource: BindingResource::TextureView(&view),
+                    },
+                ],
+            })
+        },
+        Some("External texture bindings must have a single mip level, but given a view with mip_level_count = 2 at binding 0")
+    );
+
+    // Invalid format (must be Rgba8Unorm, Bgra8Unorm, or Rgba16float)
+    let texture = device.create_texture(&TextureDescriptor {
+        format: TextureFormat::Rgba8Uint,
+        ..texture_descriptor
+    });
+    let view = texture.create_view(&TextureViewDescriptor::default());
+    fail(
+        &device,
+        || {
+
+            device.create_bind_group(&BindGroupDescriptor {
+                label: None,
+                layout: &bgl,
+                entries: &[
+                    BindGroupEntry {
+                        binding: 0,
+                        resource: BindingResource::TextureView(&view),
+                    },
+                ],
+            })
+        },
+        Some("External texture bindings must have a format of `rgba8unorm`, `bgra8unorm`, or `rgba16float, but given a view with format = Rgba8Uint at binding 0")
+    );
+
+    // Invalid sample count (must be 1)
+    let texture = device.create_texture(&TextureDescriptor {
+        sample_count: 4,
+        usage: TextureUsages::RENDER_ATTACHMENT | TextureUsages::TEXTURE_BINDING,
+        ..texture_descriptor
+    });
+    let view = texture.create_view(&TextureViewDescriptor::default());
+    fail(
+        &device,
+        || {
+            device.create_bind_group(&BindGroupDescriptor {
+                label: None,
+                layout: &bgl,
+                entries: &[BindGroupEntry {
+                    binding: 0,
+                    resource: BindingResource::TextureView(&view),
+                }],
+            })
+        },
+        Some("Texture binding 0 expects multisampled = false, but given a view with samples = 4"),
+    );
+}

tests/tests/wgpu-validation/api/mod.rs

@@ -1,5 +1,6 @@
 mod binding_arrays;
 mod buffer;
 mod buffer_slice;
+mod external_texture;
 mod instance;
 mod texture;

wgpu-core/src/binding_model.rs

@@ -173,6 +173,13 @@ pub enum CreateBindGroupError {
     },
     #[error("Storage texture bindings must have a single mip level, but given a view with mip_level_count = {mip_level_count:?} at binding {binding}")]
     InvalidStorageTextureMipLevelCount { binding: u32, mip_level_count: u32 },
+    #[error("External texture bindings must have a single mip level, but given a view with mip_level_count = {mip_level_count:?} at binding {binding}")]
+    InvalidExternalTextureMipLevelCount { binding: u32, mip_level_count: u32 },
+    #[error("External texture bindings must have a format of `rgba8unorm`, `bgra8unorm`, or `rgba16float, but given a view with format = {format:?} at binding {binding}")]
+    InvalidExternalTextureFormat {
+        binding: u32,
+        format: wgt::TextureFormat,
+    },
     #[error("Sampler binding {binding} expects comparison = {layout_cmp}, but given a sampler with comparison = {sampler_cmp}")]
     WrongSamplerComparison {
         binding: u32,
@@ -382,6 +389,19 @@ impl BindingTypeMaxCountValidator {
                 wgt::BindingType::AccelerationStructure { .. } => {
                     self.acceleration_structures.add(binding.visibility, count);
                 }
+                wgt::BindingType::ExternalTexture => {
+                    // https://www.w3.org/TR/webgpu/#gpuexternaltexture
+                    // In order to account for many possible representations,
+                    // the binding conservatively uses the following, for each
+                    // external texture:
+                    // * Three sampled textures for up to 3 planes
+                    // * One additional sampled texture for a 3D LUT
+                    // * One sampler to sample the LUT
+                    // * One uniform buffer for metadata
+                    self.sampled_textures.add(binding.visibility, count * 4);
+                    self.samplers.add(binding.visibility, count);
+                    self.uniform_buffers.add(binding.visibility, count);
+                }
             }
         }
     }

wgpu-core/src/device/resource.rs

@@ -2010,6 +2010,14 @@ impl Device {
                     )
                 }
                 Bt::AccelerationStructure { .. } => (None, WritableStorage::No),
+                Bt::ExternalTexture => {
+                    self.require_features(wgt::Features::EXTERNAL_TEXTURE)
+                        .map_err(|e| binding_model::CreateBindGroupLayoutError::Entry {
+                            binding: entry.binding,
+                            error: e.into(),
+                        })?;
+                    (None, WritableStorage::No)
+                }
             };
 
             // Validate the count parameter
@@ -2760,6 +2768,41 @@ impl Device {
                 view.check_usage(wgt::TextureUsages::STORAGE_BINDING)?;
                 Ok(internal_use)
             }
+            wgt::BindingType::ExternalTexture => {
+                if view.desc.dimension != TextureViewDimension::D2 {
+                    return Err(Error::InvalidTextureDimension {
+                        binding,
+                        layout_dimension: TextureViewDimension::D2,
+                        view_dimension: view.desc.dimension,
+                    });
+                }
+                let mip_level_count = view.selector.mips.end - view.selector.mips.start;
+                if mip_level_count != 1 {
+                    return Err(Error::InvalidExternalTextureMipLevelCount {
+                        binding,
+                        mip_level_count,
+                    });
+                }
+                if view.desc.format != TextureFormat::Rgba8Unorm
+                    && view.desc.format != TextureFormat::Bgra8Unorm
+                    && view.desc.format != TextureFormat::Rgba16Float
+                {
+                    return Err(Error::InvalidExternalTextureFormat {
+                        binding,
+                        format: view.desc.format,
+                    });
+                }
+                if view.samples != 1 {
+                    return Err(Error::InvalidTextureMultisample {
+                        binding,
+                        layout_multisampled: false,
+                        view_samples: view.samples,
+                    });
+                }
+
+                view.check_usage(wgt::TextureUsages::TEXTURE_BINDING)?;
+                Ok(wgt::TextureUses::RESOURCE)
+            }
             _ => Err(Error::WrongBindingType {
                 binding,
                 actual: decl.ty,

wgpu-core/src/validation.rs

@@ -36,6 +36,7 @@ pub enum BindingTypeName {
     Texture,
     Sampler,
     AccelerationStructure,
+    ExternalTexture,
 }
 
 impl From<&ResourceType> for BindingTypeName {
@@ -57,6 +58,7 @@ impl From<&BindingType> for BindingTypeName {
             BindingType::StorageTexture { .. } => BindingTypeName::Texture,
             BindingType::Sampler { .. } => BindingTypeName::Sampler,
             BindingType::AccelerationStructure { .. } => BindingTypeName::AccelerationStructure,
+            BindingType::ExternalTexture => BindingTypeName::ExternalTexture,
         }
     }
 }
@@ -466,6 +468,7 @@ impl Resource {
                 let view_dimension = match entry.ty {
                     BindingType::Texture { view_dimension, .. }
                     | BindingType::StorageTexture { view_dimension, .. } => view_dimension,
+                    BindingType::ExternalTexture => wgt::TextureViewDimension::D2,
                     _ => {
                         return Err(BindingError::WrongTextureViewDimension {
                             dim,
@@ -1147,6 +1150,9 @@ impl Interface {
                 );
                 let texture_sample_type = match texture_layout.ty {
                     BindingType::Texture { sample_type, .. } => sample_type,
+                    BindingType::ExternalTexture => {
+                        wgt::TextureSampleType::Float { filterable: true }
+                    }
                     _ => unreachable!(),
                 };
 

wgpu-hal/src/dx12/conv.rs

@@ -135,6 +135,7 @@ pub fn map_binding_type(ty: &wgt::BindingType) -> Direct3D12::D3D12_DESCRIPTOR_R
         }
         | Bt::StorageTexture { .. } => Direct3D12::D3D12_DESCRIPTOR_RANGE_TYPE_UAV,
         Bt::AccelerationStructure { .. } => Direct3D12::D3D12_DESCRIPTOR_RANGE_TYPE_SRV,
+        Bt::ExternalTexture => unimplemented!(),
     }
 }
 

wgpu-hal/src/dx12/device.rs

@@ -761,6 +761,7 @@ impl crate::Device for super::Device {
                 | wgt::BindingType::StorageTexture { .. }
                 | wgt::BindingType::AccelerationStructure { .. } => num_views += count,
                 wgt::BindingType::Sampler { .. } => has_sampler_in_group = true,
+                wgt::BindingType::ExternalTexture => unimplemented!(),
             }
         }
 
@@ -1526,6 +1527,7 @@ impl crate::Device for super::Device {
                         inner.stage.push(handle);
                     }
                 }
+                wgt::BindingType::ExternalTexture => unimplemented!(),
             }
         }
 

wgpu-hal/src/gles/device.rs

@@ -1192,6 +1192,7 @@ impl crate::Device for super::Device {
                         ..
                     } => &mut num_storage_buffers,
                     wgt::BindingType::AccelerationStructure { .. } => unimplemented!(),
+                    wgt::BindingType::ExternalTexture => unimplemented!(),
                 };
 
                 binding_to_slot[entry.binding as usize] = *counter;
@@ -1302,6 +1303,7 @@ impl crate::Device for super::Device {
                     })
                 }
                 wgt::BindingType::AccelerationStructure { .. } => unimplemented!(),
+                wgt::BindingType::ExternalTexture => unimplemented!(),
             };
             contents.push(binding);
         }

wgpu-hal/src/metal/device.rs

@@ -746,6 +746,7 @@ impl crate::Device for super::Device {
                                 };
                             }
                             wgt::BindingType::AccelerationStructure { .. } => unimplemented!(),
+                            wgt::BindingType::ExternalTexture => unimplemented!(),
                         }
                     }
 
@@ -978,6 +979,7 @@ impl crate::Device for super::Device {
                                 counter.textures += 1;
                             }
                             wgt::BindingType::AccelerationStructure { .. } => unimplemented!(),
+                            wgt::BindingType::ExternalTexture => unimplemented!(),
                         }
                     }
                 }

wgpu-hal/src/vulkan/conv.rs

@@ -764,6 +764,7 @@ pub fn map_binding_type(ty: wgt::BindingType) -> vk::DescriptorType {
         wgt::BindingType::AccelerationStructure { .. } => {
             vk::DescriptorType::ACCELERATION_STRUCTURE_KHR
         }
+        wgt::BindingType::ExternalTexture => unimplemented!(),
     }
 }
 

wgpu-hal/src/vulkan/device.rs

@@ -1482,6 +1482,7 @@ impl crate::Device for super::Device {
                 wgt::BindingType::AccelerationStructure { .. } => {
                     desc_count.acceleration_structure += count;
                 }
+                wgt::BindingType::ExternalTexture => unimplemented!(),
             }
         }