diff --git a/CHANGELOG.md b/CHANGELOG.md index 294f22071..4b4e0b4f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -96,6 +96,10 @@ By @sagudev in [#10115](https://github.com/gfx-rs/wgpu/pull/10115). - Add ANGLE as an opt-in OpenGL backend on Windows via `cfg(windows_angle)`, while keeping the `angle` feature for ANGLE on macOS/iOS. By @csmoe in [#9422](https://github.com/gfx-rs/wgpu/pull/9422). +#### WebGPU + +- Add `Device::import_external_texture` to bind a `GPUExternalTexture` sampled from an `HTMLVideoElement` or WebCodecs `VideoFrame`, without a copy. By @AdrianEddy in [#9936](https://github.com/gfx-rs/wgpu/pull/9936). + ### Changes #### General diff --git a/wgpu/src/api/device.rs b/wgpu/src/api/device.rs index caa038c21..63584798a 100644 --- a/wgpu/src/api/device.rs +++ b/wgpu/src/api/device.rs @@ -415,7 +415,17 @@ impl Device { self.inner.as_webgpu_opt().map(|wd| &wd.inner) } - /// Creates a new [`ExternalTexture`]. + /// Creates a new [`ExternalTexture`] from plane textures the caller + /// already has. + /// + /// The planes and the [`ExternalTextureDescriptor`]'s conversion + /// parameters (YCbCr matrix, gamut and transfer functions) are supplied by + /// the caller, and wgpu performs the conversion when the texture is + /// sampled. Works on every backend. + /// + /// Use this when the video data already lives in wgpu textures, e.g. + /// frames you decoded yourself. To bind a web media source directly on the + /// WebGPU backend, use `Device::import_external_texture` instead. #[must_use] pub fn create_external_texture( &self, @@ -429,6 +439,33 @@ impl Device { } } + /// Imports a video source as an [`ExternalTexture`] on the WebGPU backend, + /// without a copy. + /// + /// Unlike [`Self::create_external_texture`] — where the caller supplies + /// plane textures and conversion parameters — this hands `source` to the + /// browser's `importExternalTexture`, which performs the color conversion + /// internally. Use it whenever the frames come from a web media source + /// rather than from data you decoded yourself. + /// + /// The result is valid only while `source` is: a `VideoFrame` until it is + /// closed, an `HTMLVideoElement` for the current task. + /// [`ExternalTexture::destroy`] is a no-op. + /// + /// Returns an error if this device is not on the WebGPU backend. + #[cfg(webgpu)] + pub fn import_external_texture( + &self, + source: &webgpu::ExternalTextureSource, + ) -> Result { + let inner = self + .inner + .as_webgpu_opt() + .ok_or(NotWebGpuBackendError)? + .import_external_texture(source); + Ok(ExternalTexture { inner }) + } + /// Creates a [`Buffer`] from a wgpu-hal Buffer. /// /// # Types @@ -767,6 +804,22 @@ impl Device { } } +/// The [`Device`] is not on the WebGPU backend. +#[cfg(webgpu)] +#[derive(Clone, Debug)] +#[non_exhaustive] +pub struct NotWebGpuBackendError; + +#[cfg(webgpu)] +impl fmt::Display for NotWebGpuBackendError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "this device is not using the WebGPU backend") + } +} + +#[cfg(webgpu)] +impl error::Error for NotWebGpuBackendError {} + /// Requesting a device from an [`Adapter`] failed. #[derive(Clone, Debug)] pub struct RequestDeviceError { diff --git a/wgpu/src/backend/webgpu.rs b/wgpu/src/backend/webgpu.rs index 3f1874b71..d292aeb1f 100644 --- a/wgpu/src/backend/webgpu.rs +++ b/wgpu/src/backend/webgpu.rs @@ -1409,8 +1409,22 @@ pub struct WebTexture { desc: crate::TextureDescriptor<'static>, } +/// A video source for [`Device::import_external_texture`]. +/// +/// This is the `source` of a WebGPU `GPUExternalTextureDescriptor`. +/// +/// [`Device::import_external_texture`]: crate::Device::import_external_texture +#[derive(Debug, Clone)] +pub enum ExternalTextureSource { + /// An `HTMLVideoElement`. + HtmlVideoElement(web_sys::HtmlVideoElement), + /// A WebCodecs `VideoFrame`. + VideoFrame(web_sys::VideoFrame), +} + #[derive(Debug, Clone)] pub struct WebExternalTexture { + pub(crate) inner: webgpu_sys::GpuExternalTexture, /// Unique identifier for this ExternalTexture. ident: crate::cmp::Identifier, } @@ -1911,6 +1925,34 @@ impl WebDevice { } .into() } + + /// Import a video source as a `GPUExternalTexture`, without a copy. + /// + /// The browser performs the YCbCr-to-RGB conversion internally. The result is + /// valid only while the source is: a `VideoFrame` until it is closed, an + /// `HTMLVideoElement` for the current task. + pub(crate) fn import_external_texture( + &self, + source: &ExternalTextureSource, + ) -> dispatch::DispatchExternalTexture { + let descriptor = match source { + ExternalTextureSource::HtmlVideoElement(v) => { + webgpu_sys::GpuExternalTextureDescriptor::new(v) + } + ExternalTextureSource::VideoFrame(f) => { + webgpu_sys::GpuExternalTextureDescriptor::new_with_video_frame(f) + } + }; + let inner = self + .inner + .import_external_texture(&descriptor) + .expect("importExternalTexture failed"); + WebExternalTexture { + inner, + ident: crate::cmp::Identifier::create(), + } + .into() + } } impl dispatch::DeviceInterface for WebDevice { @@ -2272,8 +2314,12 @@ impl dispatch::DeviceInterface for WebDevice { crate::BindingResource::AccelerationStructureArray(_) => { unimplemented!("Raytracing not implemented for web") } - crate::BindingResource::ExternalTexture(_) => { - unimplemented!("ExternalTexture not implemented for web") + crate::BindingResource::ExternalTexture(external_texture) => { + let external_texture = &external_texture.inner.as_webgpu().inner; + webgpu_sys::GpuBindGroupEntry::new_with_gpu_external_texture( + binding.binding, + external_texture, + ) } }) .collect::>(); @@ -2534,7 +2580,11 @@ impl dispatch::DeviceInterface for WebDevice { _desc: &crate::ExternalTextureDescriptor<'_>, _planes: &[&crate::TextureView], ) -> dispatch::DispatchExternalTexture { - unimplemented!("ExternalTexture not implemented for web"); + // The browser builds external textures from a video source, not from + // plane textures. Use `Device::import_external_texture` on this backend. + unimplemented!( + "plane-based external textures are unsupported on WebGPU; use Device::import_external_texture" + ); } fn create_blas( @@ -3103,12 +3153,12 @@ impl Drop for WebTexture { impl dispatch::ExternalTextureInterface for WebExternalTexture { fn destroy(&self) { - unimplemented!("ExternalTexture not implemented for web"); + // A `GPUExternalTexture` has no `destroy()`; it expires automatically. } } impl Drop for WebExternalTexture { fn drop(&mut self) { - unimplemented!("ExternalTexture not implemented for web"); + // no-op } } diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs index d0df7ef65..9e855a43b 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -346,9 +346,9 @@ pub use web_sys; #[cfg(webgpu)] pub mod webgpu { pub use crate::backend::webgpu::webgpu_sys::{ - GpuBuffer, GpuDevice, GpuQueue, GpuTexture, GpuTextureView, + GpuBuffer, GpuDevice, GpuExternalTexture, GpuQueue, GpuTexture, GpuTextureView, }; - pub use crate::backend::webgpu::DropCallback; + pub use crate::backend::webgpu::{DropCallback, ExternalTextureSource}; } #[doc(hidden)]