[wgpu-core] Add ExternalTexture type to wgpu-core

`ExternalTexture` will form the basis of wgpu's implementation of
WebGPU's `GPUExternalTexture`. [1]

The application will be responsible for creating `Texture`(s) and
`TextureView`(s) from the external texture source and managing their
lifecycle. It may have a single RGBA texture, or it may have multiple
textures for separate Y and Cb/Cr planes. It can then create an external
texture by calling `create_external_texture()`, providing the texture
views and a descriptor. The descriptor provides the following required
information:

  * Whether the texture data is RGBA, or multiplanar or interleaved
    YCbCr.
  * The purpoted size of the external texture, which may not match the
    actual size of the underlying textures.
  * A matrix for converting from YCbCr to RGBA, if required.
  * A transform to apply to texture sample coordinates, allowing for
    rotation and crop rects.

The external texture stores a reference to the provided texture views,
and additionally owns a `Buffer`. This buffer holds data of the type
`ExternalTextureParams`, and will be provided as a uniform buffer to
shaders containing external textures. This contains information that
will be required by the shaders to handle external textures correctly.

Note that attempting to create an external texture will fail unless the
`Feature::EXTERNAL_TEXTURE` feature is enabled, which as of yet is not
supported by any HAL backends.

Additionally add the relevant API to wgpu, implemented for the
wgpu-core backend. The web and custom backends are unimplemented.

[1] https://www.w3.org/TR/webgpu/#gpuexternaltexture

Author: jamienicol

examples/standalone/custom_backend/src/custom.rs

@@ -184,6 +184,14 @@ impl DeviceInterface for CustomDevice {
         unimplemented!()
     }
 
+    fn create_external_texture(
+        &self,
+        _desc: &wgpu::ExternalTextureDescriptor<'_>,
+        _planes: &[&wgpu::TextureView],
+    ) -> wgpu::custom::DispatchExternalTexture {
+        unimplemented!()
+    }
+
     fn create_blas(
         &self,
         _desc: &wgpu::CreateBlasDescriptor<'_>,

player/src/lib.rs

@@ -244,6 +244,19 @@ impl GlobalPlay for wgc::global::Global {
             Action::DestroyTextureView(id) => {
                 self.texture_view_drop(id).unwrap();
             }
+            Action::CreateExternalTexture { id, desc, planes } => {
+                let (_, error) =
+                    self.device_create_external_texture(device, &desc, &planes, Some(id));
+                if let Some(e) = error {
+                    panic!("{e}");
+                }
+            }
+            Action::FreeExternalTexture(id) => {
+                self.external_texture_destroy(id);
+            }
+            Action::DestroyExternalTexture(id) => {
+                self.external_texture_drop(id);
+            }
             Action::CreateSampler(id, desc) => {
                 let (_, error) = self.device_create_sampler(device, &desc, Some(id));
                 if let Some(e) = error {

wgpu-core/Cargo.toml

@@ -72,14 +72,7 @@ observe_locks = ["std", "dep:ron", "serde/serde_derive"]
 serde = ["dep:serde", "wgpu-types/serde", "arrayvec/serde", "hashbrown/serde"]
 
 ## Enable API tracing.
-trace = [
-    "serde",
-    "std",
-    "dep:ron",
-    "naga/serialize",
-    "wgpu-types/trace",
-    "dep:bytemuck",
-]
+trace = ["serde", "std", "dep:ron", "naga/serialize", "wgpu-types/trace"]
 
 ## Enable API replaying
 replay = ["serde", "naga/deserialize"]
@@ -100,7 +93,7 @@ wgsl = ["naga/wgsl-in"]
 glsl = ["naga/glsl-in"]
 
 ## Enable `ShaderModuleSource::SpirV`
-spirv = ["naga/spv-in", "dep:bytemuck"]
+spirv = ["naga/spv-in"]
 
 #! ### Other
 # --------------------------------------------------------------------
@@ -180,7 +173,7 @@ arrayvec.workspace = true
 bit-vec.workspace = true
 bit-set.workspace = true
 bitflags.workspace = true
-bytemuck = { workspace = true, optional = true }
+bytemuck.workspace = true
 document-features.workspace = true
 hashbrown.workspace = true
 indexmap.workspace = true

wgpu-core/src/device/global.rs

@@ -178,6 +178,9 @@ impl Global {
         fid.assign(Fallible::Invalid(Arc::new(desc.label.to_string())));
     }
 
+    /// Assign `id_in` an error with the given `label`.
+    ///
+    /// See [`Self::create_buffer_error`] for more context and explanation.
     pub fn create_render_bundle_error(
         &self,
         id_in: Option<id::RenderBundleId>,
@@ -189,7 +192,7 @@ impl Global {
 
     /// Assign `id_in` an error with the given `label`.
     ///
-    /// See `create_buffer_error` for more context and explanation.
+    /// See [`Self::create_buffer_error`] for more context and explanation.
     pub fn create_texture_error(
         &self,
         id_in: Option<id::TextureId>,
@@ -199,6 +202,18 @@ impl Global {
         fid.assign(Fallible::Invalid(Arc::new(desc.label.to_string())));
     }
 
+    /// Assign `id_in` an error with the given `label`.
+    ///
+    /// See [`Self::create_buffer_error`] for more context and explanation.
+    pub fn create_external_texture_error(
+        &self,
+        id_in: Option<id::ExternalTextureId>,
+        desc: &resource::ExternalTextureDescriptor,
+    ) {
+        let fid = self.hub.external_textures.prepare(id_in);
+        fid.assign(Fallible::Invalid(Arc::new(desc.label.to_string())));
+    }
+
     #[cfg(feature = "replay")]
     pub fn device_set_buffer_data(
         &self,
@@ -512,6 +527,94 @@ impl Global {
         Ok(())
     }
 
+    pub fn device_create_external_texture(
+        &self,
+        device_id: DeviceId,
+        desc: &resource::ExternalTextureDescriptor,
+        planes: &[id::TextureViewId],
+        id_in: Option<id::ExternalTextureId>,
+    ) -> (
+        id::ExternalTextureId,
+        Option<resource::CreateExternalTextureError>,
+    ) {
+        profiling::scope!("Device::create_external_texture");
+
+        let hub = &self.hub;
+
+        let fid = hub.external_textures.prepare(id_in);
+
+        let error = 'error: {
+            let device = self.hub.devices.get(device_id);
+
+            #[cfg(feature = "trace")]
+            if let Some(ref mut trace) = *device.trace.lock() {
+                let planes = Box::from(planes);
+                trace.add(trace::Action::CreateExternalTexture {
+                    id: fid.id(),
+                    desc: desc.clone(),
+                    planes,
+                });
+            }
+
+            let planes = planes
+                .iter()
+                .map(|plane_id| self.hub.texture_views.get(*plane_id).get())
+                .collect::<Result<Vec<_>, _>>();
+            let planes = match planes {
+                Ok(planes) => planes,
+                Err(error) => break 'error error.into(),
+            };
+
+            let external_texture = match device.create_external_texture(desc, &planes) {
+                Ok(external_texture) => external_texture,
+                Err(error) => break 'error error,
+            };
+
+            let id = fid.assign(Fallible::Valid(external_texture));
+            api_log!("Device::create_external_texture({desc:?}) -> {id:?}");
+
+            return (id, None);
+        };
+
+        let id = fid.assign(Fallible::Invalid(Arc::new(desc.label.to_string())));
+        (id, Some(error))
+    }
+
+    pub fn external_texture_destroy(&self, external_texture_id: id::ExternalTextureId) {
+        profiling::scope!("ExternalTexture::destroy");
+        api_log!("ExternalTexture::destroy {external_texture_id:?}");
+
+        let hub = &self.hub;
+
+        let Ok(external_texture) = hub.external_textures.get(external_texture_id).get() else {
+            // If the external texture is already invalid, there's nothing to do.
+            return;
+        };
+
+        #[cfg(feature = "trace")]
+        if let Some(trace) = external_texture.device.trace.lock().as_mut() {
+            trace.add(trace::Action::FreeExternalTexture(external_texture_id));
+        }
+
+        external_texture.destroy();
+    }
+
+    pub fn external_texture_drop(&self, external_texture_id: id::ExternalTextureId) {
+        profiling::scope!("ExternalTexture::drop");
+        api_log!("ExternalTexture::drop {external_texture_id:?}");
+
+        let hub = &self.hub;
+
+        let _external_texture = hub.external_textures.remove(external_texture_id);
+
+        #[cfg(feature = "trace")]
+        if let Ok(external_texture) = _external_texture.get() {
+            if let Some(t) = external_texture.device.trace.lock().as_mut() {
+                t.add(trace::Action::DestroyExternalTexture(external_texture_id));
+            }
+        }
+    }
+
     pub fn device_create_sampler(
         &self,
         device_id: DeviceId,

wgpu-core/src/device/resource.rs

@@ -41,8 +41,9 @@ use crate::{
     pipeline,
     pool::ResourcePool,
     resource::{
-        self, Buffer, Fallible, Labeled, ParentDevice, QuerySet, RawResourceAccess, Sampler,
-        StagingBuffer, Texture, TextureView, TextureViewNotRenderableReason, Tlas, TrackingData,
+        self, Buffer, ExternalTexture, Fallible, Labeled, ParentDevice, QuerySet,
+        RawResourceAccess, Sampler, StagingBuffer, Texture, TextureView,
+        TextureViewNotRenderableReason, Tlas, TrackingData,
     },
     resource_log,
     snatch::{SnatchGuard, SnatchLock, Snatchable},
@@ -75,6 +76,42 @@ pub(crate) struct CommandIndices {
     pub(crate) next_acceleration_structure_build_command_index: u64,
 }
 
+/// Parameters provided to shaders via a uniform buffer, describing an
+/// ExternalTexture resource binding.
+#[repr(C)]
+#[derive(Copy, Clone, bytemuck::Zeroable, bytemuck::Pod)]
+pub struct ExternalTextureParams {
+    /// 4x4 column-major matrix with which to convert sampled YCbCr values
+    /// to RGBA.
+    /// This is ignored when `num_planes` is 1.
+    pub yuv_conversion_matrix: [f32; 16],
+    /// 3x2 column-major matrix with which to multiply texture coordinates
+    /// prior to sampling from the external texture.
+    pub sample_transform: [f32; 6],
+    pub load_transform: [f32; 6],
+    /// Size of the external texture. This value should be returned by size
+    /// queries in shader code. Note that this may not match the dimensions of
+    /// the underlying texture(s). A value of [0, 0] indicates that the actual
+    /// size of plane 0 should be used.
+    pub size: [u32; 2],
+    /// Number of planes. 1 indicates a single RGBA plane. 2 indicates a Y
+    /// plane and an interleaved CbCr plane. 3 indicates separate Y, Cb, and Cr
+    /// planes.
+    pub num_planes: u32,
+}
+
+impl ExternalTextureParams {
+    pub fn from_desc<L>(desc: &wgt::ExternalTextureDescriptor<L>) -> Self {
+        Self {
+            yuv_conversion_matrix: desc.yuv_conversion_matrix,
+            size: [desc.width, desc.height],
+            sample_transform: desc.sample_transform,
+            load_transform: desc.load_transform,
+            num_planes: desc.num_planes() as u32,
+        }
+    }
+}
+
 /// Structure describing a logical device. Some members are internally mutable,
 /// stored behind mutexes.
 pub struct Device {
@@ -1550,6 +1587,101 @@ impl Device {
         Ok(view)
     }
 
+    pub(crate) fn create_external_texture(
+        self: &Arc<Self>,
+        desc: &resource::ExternalTextureDescriptor,
+        planes: &[Arc<TextureView>],
+    ) -> Result<Arc<ExternalTexture>, resource::CreateExternalTextureError> {
+        use resource::CreateExternalTextureError;
+        self.require_features(wgt::Features::EXTERNAL_TEXTURE)?;
+        self.check_is_valid()?;
+
+        if desc.num_planes() != planes.len() {
+            return Err(CreateExternalTextureError::IncorrectPlaneCount {
+                format: desc.format,
+                expected: desc.num_planes(),
+                provided: planes.len(),
+            });
+        }
+
+        let planes = planes
+            .iter()
+            .enumerate()
+            .map(|(i, plane)| {
+                if plane.samples != 1 {
+                    return Err(CreateExternalTextureError::InvalidPlaneMultisample(
+                        plane.samples,
+                    ));
+                }
+
+                let sample_type = plane
+                    .desc
+                    .format
+                    .sample_type(Some(plane.desc.range.aspect), Some(self.features))
+                    .unwrap();
+                if !matches!(sample_type, TextureSampleType::Float { filterable: true }) {
+                    return Err(CreateExternalTextureError::InvalidPlaneSampleType {
+                        format: plane.desc.format,
+                        sample_type,
+                    });
+                }
+
+                if plane.desc.dimension != TextureViewDimension::D2 {
+                    return Err(CreateExternalTextureError::InvalidPlaneDimension(
+                        plane.desc.dimension,
+                    ));
+                }
+
+                let expected_components = match desc.format {
+                    wgt::ExternalTextureFormat::Rgba => 4,
+                    wgt::ExternalTextureFormat::Nv12 => match i {
+                        0 => 1,
+                        1 => 2,
+                        _ => unreachable!(),
+                    },
+                    wgt::ExternalTextureFormat::Yu12 => 1,
+                };
+                if plane.desc.format.components() != expected_components {
+                    return Err(CreateExternalTextureError::InvalidPlaneFormat {
+                        format: desc.format,
+                        plane: i,
+                        expected: expected_components,
+                        provided: plane.desc.format,
+                    });
+                }
+
+                plane.check_usage(wgt::TextureUsages::TEXTURE_BINDING)?;
+                Ok(plane.clone())
+            })
+            .collect::<Result<_, _>>()?;
+
+        let params_data = ExternalTextureParams::from_desc(desc);
+        let label = desc.label.as_ref().map(|l| alloc::format!("{l} params"));
+        let params_desc = resource::BufferDescriptor {
+            label: label.map(Cow::Owned),
+            size: size_of_val(&params_data) as wgt::BufferAddress,
+            usage: wgt::BufferUsages::UNIFORM | wgt::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        };
+        let params = self.create_buffer(&params_desc)?;
+        self.get_queue().unwrap().write_buffer(
+            Fallible::Valid(params.clone()),
+            0,
+            bytemuck::bytes_of(&params_data),
+        )?;
+
+        let external_texture = ExternalTexture {
+            device: self.clone(),
+            planes,
+            params,
+            label: desc.label.to_string(),
+            tracking_data: TrackingData::new(self.tracker_indices.external_textures.clone()),
+        };
+        let external_texture = Arc::new(external_texture);
+
+        Ok(external_texture)
+    }
+
     pub(crate) fn create_sampler(
         self: &Arc<Self>,
         desc: &resource::SamplerDescriptor,

wgpu-core/src/device/trace.rs

@@ -58,6 +58,13 @@ pub enum Action<'a> {
         desc: crate::resource::TextureViewDescriptor<'a>,
     },
     DestroyTextureView(id::TextureViewId),
+    CreateExternalTexture {
+        id: id::ExternalTextureId,
+        desc: crate::resource::ExternalTextureDescriptor<'a>,
+        planes: alloc::boxed::Box<[id::TextureViewId]>,
+    },
+    FreeExternalTexture(id::ExternalTextureId),
+    DestroyExternalTexture(id::ExternalTextureId),
     CreateSampler(id::SamplerId, crate::resource::SamplerDescriptor<'a>),
     DestroySampler(id::SamplerId),
     GetSurfaceTexture {