[WebGPU] Support binding GPUExternalTexture via importExternalTexture (#9936)

Co-authored-by: Connor Fitzgerald <connorwadefitzgerald@gmail.com>
This commit is contained in:
AdrianEddyandConnor Fitzgerald authored and GitHub committed 2026-08-28 19:24:32 +00:00
1 parent 4d749308e6
commit d5fde4291f
4 files changed
+115 -8

No files matched your search

+4
View File
@@ -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
+54 -1
View File
@@ -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<ExternalTexture, NotWebGpuBackendError> {
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 {
+55 -5
View File
@@ -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::<Vec<webgpu_sys::GpuBindGroupEntry>>();
@@ -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
}
}
+2 -2
View File
@@ -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)]