[WebGPU] Add the ability to interop with external textures (#9530)

Co-authored-by: Kevin Reid <kpreid@switchb.org>
This commit is contained in:
AdrianEddyandKevin Reid authored and GitHub committed 2026-06-30 03:18:58 +00:00
1 parent 378124a2bd
commit bd4d9a99b6
8 files changed
+219 -9

No files matched your search

+5
View File
@@ -305,6 +305,11 @@ By @stuartparmenter in [#9658](https://github.com/gfx-rs/wgpu/pull/9658).
- Fixed structure field names incorrectly ignoring reserved keywords in the Metal (MSL) backend. By @39ali [#9379](https://github.com/gfx-rs/wgpu/pull/9379).
- Restore the `Queue::as_raw` method, which was removed without good reason in v29. It now returns `&ProtocolObject<dyn MTLCommandQueue>`. By @andyleiserson in [#9560](https://github.com/gfx-rs/wgpu/pull/9560).
#### WebGPU
- Expose the underlying JS handles of WebGPU-backed resources via new `as_webgpu` accessors on `Texture`, `TextureView`, `Buffer`, `Queue`, and `Device`, returning `Option<&wgpu::webgpu::Gpu*>`. This is the WebGPU counterpart of `as_hal` (which returns `None` on the WebGPU backend, since WebGPU is not a `wgpu_hal` API). The vendored handle types are re-exported under the new `wgpu::webgpu` module. By @AdrianEddy in [#9530](https://github.com/gfx-rs/wgpu/pull/9530)
- Add `Device::create_texture_from_webgpu_handle(texture, desc, drop_callback)` for wrapping a foreign `webgpu::GpuTexture` (e.g. a canvas `getCurrentTexture()` result) as a `wgpu::Texture` without copy. Use the `drop_callback` to decide if you want to call `GpuTexture.destroy()` when wgpu is done with the texture. By @AdrianEddy in [#9530](https://github.com/gfx-rs/wgpu/pull/9530)
### Dependency Updates
#### WebGPU
+10 -1
View File
@@ -273,7 +273,9 @@ impl Buffer {
///
/// This method will return None if:
/// - The buffer is not from the backend specified by `A`.
/// - The buffer is from the `webgpu` or `custom` backend.
/// - The buffer is from [`Backend::BrowserWebGpu`].
/// (Use `Buffer::as_webgpu()` instead.)
/// - The buffer is from a custom backend.
/// - The buffer has had [`Self::destroy()`] called on it.
///
/// # Safety
@@ -455,6 +457,13 @@ impl Buffer {
pub fn as_custom<T: custom::BufferInterface>(&self) -> Option<&T> {
self.inner.as_custom()
}
/// Returns the underlying [`webgpu::GpuBuffer`] handle if this `Buffer`
/// is on the WebGPU backend, otherwise `None`.
#[cfg(webgpu)]
pub fn as_webgpu(&self) -> Option<&webgpu::GpuBuffer> {
self.inner.as_webgpu_opt().map(|wb| &wb.inner)
}
}
/// A slice of a [`Buffer`], to be mapped, used for vertex or index data, or the like.
+68
View File
@@ -315,6 +315,8 @@ impl Device {
#[doc = crate::macros::hal_type_dx12!("Texture")]
#[doc = crate::macros::hal_type_gles!("Texture")]
///
/// On [`Backend::BrowserWebGpu`], use `Device::create_texture_from_webgpu_handle()` instead.
///
/// # `initial_state`
///
/// If the resource has already been initialized, `initial_state` should be
@@ -361,6 +363,70 @@ impl Device {
}
}
/// Wraps a foreign [`webgpu::GpuTexture`] (e.g. a canvas `getCurrentTexture()` result)
/// as a [`Texture`] without any copy.
///
/// The wrapped texture is *external*: dropping the returned `Texture` (or
/// calling [`Texture::destroy`] on it) does **not** call `GpuTexture.destroy()`
/// on the underlying handle - its lifetime is the caller's responsibility.
///
/// If `drop_callback` is `Some`, it fires when wgpu releases its last
/// reference to the wrapped handle. wgpu never calls `GpuTexture.destroy()`
/// itself on a wrapped texture; to hand the handle's lifetime to wgpu,
/// supply a callback that calls `GpuTexture.destroy()`. The callback can
/// also be used to free a pool slot or notify dependent code that wgpu is
/// done with the handle. Pass `None` if the caller manages the handle's
/// lifetime entirely on their own.
///
/// This is the WebGPU counterpart of [`Self::create_texture_from_hal`].
/// A `Some` `drop_callback` plays the same role as `wgpu_hal::DropCallback`
/// does on the Vulkan backend. The `None` case differs: here the texture is
/// always external and wgpu never destroys it, whereas on Vulkan a `None`
/// callback means wgpu takes ownership of the image and destroys it.
///
/// The caller must guarantee:
///
/// 1. `texture` was produced by the same underlying `GpuDevice` that this `Device` wraps.
/// 2. `desc.format`, `desc.size`, `desc.usage`, `desc.dimension`,
/// `desc.mip_level_count`, and `desc.sample_count` match the actual
/// `GPUTexture`'s reflected values. wgpu stores these verbatim and
/// returns them from [`Texture::size`], [`Texture::format`], etc.
/// without re-checking the handle; a mismatch yields silently incorrect
/// metadata and, downstream, `GPUValidationError`s rather than memory
/// unsafety (the browser bounds every access).
/// 3. The underlying `GpuTexture` must remain alive for as long as wgpu
/// may use it (e.g. until any submitted command buffer that references
/// it has finished executing). If `drop_callback` is `Some`, it is
/// sufficient to keep the handle alive until the callback fires.
#[cfg(webgpu)]
#[must_use]
pub fn create_texture_from_webgpu_handle(
&self,
texture: webgpu::GpuTexture,
desc: &TextureDescriptor<'_>,
drop_callback: Option<webgpu::DropCallback>,
) -> Texture {
let inner = self
.inner
.as_webgpu()
.wrap_external_texture(texture, drop_callback);
Texture {
inner,
descriptor: TextureDescriptor {
label: None,
view_formats: &[],
..desc.clone()
},
}
}
/// Returns the underlying [`webgpu::GpuDevice`] handle if this `Device`
/// is on the WebGPU backend, otherwise `None`.
#[cfg(webgpu)]
pub fn as_webgpu(&self) -> Option<&webgpu::GpuDevice> {
self.inner.as_webgpu_opt().map(|wd| &wd.inner)
}
/// Creates a new [`ExternalTexture`].
#[must_use]
pub fn create_external_texture(
@@ -588,6 +654,8 @@ impl Device {
/// - The device is not from the backend specified by `A`.
/// - The device is from the `webgpu` or `custom` backend.
///
/// On the `webgpu` backend, use `as_webgpu` instead.
///
/// # Safety
///
/// - The returned resource must not be destroyed unless the guard
+11
View File
@@ -34,6 +34,15 @@ impl Queue {
inner: dispatch::DispatchQueue::custom(queue),
}
}
/// Returns the underlying [`webgpu::GpuQueue`] handle if this `Queue`
/// is on the WebGPU backend, otherwise `None`.
///
/// [`webgpu::GpuQueue`]: crate::webgpu::GpuQueue
#[cfg(webgpu)]
pub fn as_webgpu(&self) -> Option<&webgpu::GpuQueue> {
self.inner.as_webgpu_opt().map(|wq| &wq.inner)
}
}
/// Identifier for a particular call to [`Queue::submit`]. Can be used
@@ -337,6 +346,8 @@ impl Queue {
/// - The queue is not from the backend specified by `A`.
/// - The queue is from the `webgpu` or `custom` backend.
///
/// On the `webgpu` backend, use `as_webgpu` instead.
///
/// # Safety
///
/// - The returned resource must not be destroyed unless the guard
+16 -2
View File
@@ -46,8 +46,9 @@ impl Texture {
///
/// This method will return None if:
/// - The texture is not from the backend specified by `A`.
/// - The texture is from the `webgpu` or `custom` backend.
/// - The texture has had [`Self::destroy()`] called on it.
/// - The texture is from [`Backend::BrowserWebGpu`].
/// (Use `Texture::as_webgpu()` instead.)
/// - The texture is from a custom backend.
///
/// # Safety
///
@@ -63,6 +64,19 @@ impl Texture {
unsafe { texture.context.texture_as_hal::<A>(texture) }
}
/// Returns the underlying [`webgpu::GpuTexture`] handle if this `Texture`
/// is on the WebGPU backend.
///
/// Use this on the WebGPU backend instead of [`Self::as_hal`].
///
/// The returned handle is the same JS object wgpu uses internally; it can
/// be passed to other WebGPU-aware JS APIs, used for identity comparison,
/// or fed back into [`Device::create_texture_from_webgpu_handle`].
#[cfg(webgpu)]
pub fn as_webgpu(&self) -> Option<&webgpu::GpuTexture> {
self.inner.as_webgpu_opt().map(|wt| &wt.inner)
}
#[cfg(custom)]
/// Returns custom implementation of Texture (if custom backend and is internally T)
pub fn as_custom<T: custom::TextureInterface>(&self) -> Option<&T> {
+12 -2
View File
@@ -58,8 +58,9 @@ impl TextureView {
///
/// This method will return None if:
/// - The texture view is not from the backend specified by `A`.
/// - The texture view is from the `webgpu` or `custom` backend.
/// - The texture this view points to has had [`Texture::destroy()`] called on it.
/// - The texture view is from [`Backend::BrowserWebGpu`].
/// (Use `TextureView::as_webgpu()` instead.)
/// - The texture view is from a custom backend.
///
/// # Safety
///
@@ -75,6 +76,15 @@ impl TextureView {
unsafe { view.context.texture_view_as_hal::<A>(view) }
}
/// Returns the underlying [`webgpu::GpuTextureView`] handle if this view
/// is on the WebGPU backend, otherwise `None`.
///
/// [`webgpu::GpuTextureView`]: crate::webgpu::GpuTextureView
#[cfg(webgpu)]
pub fn as_webgpu(&self) -> Option<&webgpu::GpuTextureView> {
self.inner.as_webgpu_opt().map(|wv| &wv.inner)
}
#[cfg(custom)]
/// Returns custom implementation of TextureView (if custom backend and is internally T)
pub fn as_custom<T: custom::TextureViewInterface>(&self) -> Option<&T> {
+79 -4
View File
@@ -3,7 +3,7 @@
mod defined_non_null_js_value;
mod ext_bindings;
#[allow(clippy::allow_attributes)]
mod webgpu_sys;
pub(crate) mod webgpu_sys;
use alloc::{
boxed::Box,
@@ -87,6 +87,37 @@ impl crate::Error {
}
}
/// A callback invoked when wgpu releases its reference to an externally
/// owned WebGPU resource (e.g. a `GpuTexture` passed to
/// [`crate::Device::create_texture_from_webgpu_handle`]).
///
/// This is the WebGPU counterpart of [`wgpu_hal::DropCallback`].
pub type DropCallback = Box<dyn FnOnce() + 'static>;
pub(crate) struct DropGuard {
callback: Option<DropCallback>,
}
impl DropGuard {
fn new(callback: Option<DropCallback>) -> Self {
Self { callback }
}
}
impl Drop for DropGuard {
fn drop(&mut self) {
if let Some(cb) = self.callback.take() {
cb();
}
}
}
impl fmt::Debug for DropGuard {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("DropGuard").finish()
}
}
#[derive(Debug, Clone)]
pub struct WebShaderModule {
module: webgpu_sys::GpuShaderModule,
@@ -1293,7 +1324,7 @@ struct WebBufferMapState {
#[derive(Debug, Clone)]
pub struct WebBuffer {
/// The associated GPU buffer.
inner: webgpu_sys::GpuBuffer,
pub(crate) inner: webgpu_sys::GpuBuffer,
/// The mapped array buffer and mapped range.
mapping: Rc<RefCell<WebBufferMapState>>,
/// Unique identifier for this Buffer.
@@ -1347,6 +1378,17 @@ impl WebBuffer {
#[derive(Debug, Clone)]
pub struct WebTexture {
pub(crate) inner: webgpu_sys::GpuTexture,
/// Lifetime management for the underlying `GpuTexture`.
///
/// - `None` means wgpu owns the handle: [`Self::destroy`] forwards to
/// `GpuTexture.destroy()`. (This is the case for textures created via
/// `device.createTexture` or `surface.getCurrentTexture`.)
/// - `Some(_)` means the handle is externally owned (wrapped via
/// [`WebDevice::wrap_external_texture`]). `destroy()` is a no-op, and
/// the wrapped [`DropCallback`], if any, fires when the last clone of
/// this `WebTexture` is dropped, signalling that wgpu is done with the
/// handle.
drop_guard: Option<Rc<DropGuard>>,
/// Unique identifier for this Texture.
ident: crate::cmp::Identifier,
}
@@ -1810,6 +1852,34 @@ impl Drop for WebAdapter {
}
}
impl WebDevice {
/// Wrap a foreign `webgpu_sys::GpuTexture` (e.g. from a canvas `getCurrentTexture()`) as a
/// dispatch-level `WebTexture` without calling `device.createTexture(...)`.
///
/// The resulting texture is *external*: its `destroy()` is a no-op, since
/// the JS handle's lifetime is the caller's responsibility.
///
/// If `drop_callback` is `Some`, it fires when the last clone of the
/// returned `WebTexture` is dropped, signalling that wgpu is done with
/// the handle (e.g. so the caller can call `GpuTexture.destroy()`
/// themselves, release a pool slot, etc.).
///
/// The caller is responsible for asserting that `texture` was produced by
/// the same underlying `GpuDevice` as `self`.
pub(crate) fn wrap_external_texture(
&self,
texture: webgpu_sys::GpuTexture,
drop_callback: Option<DropCallback>,
) -> dispatch::DispatchTexture {
WebTexture {
inner: texture,
drop_guard: Some(Rc::new(DropGuard::new(drop_callback))),
ident: crate::cmp::Identifier::create(),
}
.into()
}
}
impl dispatch::DeviceInterface for WebDevice {
fn features(&self) -> crate::Features {
map_wgt_features(self.inner.features())
@@ -2415,6 +2485,7 @@ impl dispatch::DeviceInterface for WebDevice {
let texture = self.inner.create_texture(&mapped_desc).unwrap();
WebTexture {
inner: texture,
drop_guard: None,
ident: crate::cmp::Identifier::create(),
}
.into()
@@ -2943,12 +3014,15 @@ impl dispatch::TextureInterface for WebTexture {
}
fn destroy(&self) {
self.inner.destroy();
if self.drop_guard.is_none() {
self.inner.destroy();
}
}
}
impl Drop for WebTexture {
fn drop(&mut self) {
// no-op
// The drop callback for external textures is fired by `DropGuard`'s
// own `Drop` impl when the last `Rc<DropGuard>` clone is released.
}
}
@@ -4282,6 +4356,7 @@ impl dispatch::SurfaceInterface for WebSurface {
let web_surface_texture = WebTexture {
inner: surface_texture,
drop_guard: None,
ident: crate::cmp::Identifier::create(),
};
+18
View File
@@ -333,5 +333,23 @@ pub use raw_window_handle as rwh;
#[cfg(web)]
pub use web_sys;
/// Vendored WebGPU JS-handle types used by the WebGPU backend.
///
/// They are exposed publicly so that interop crates can read the JS handle
/// behind a [`Texture`] / [`Buffer`] / etc. (via [`Texture::as_webgpu`] and
/// siblings), and pass a foreign handle in (via
/// [`Device::create_texture_from_webgpu_handle`]).
///
/// A `web_sys::GpuTexture` from a consumer's own `web-sys` dependency wraps
/// the same JS object as a `wgpu::webgpu::GpuTexture`; convert between them
/// with [`wasm_bindgen::JsCast::unchecked_into`].
#[cfg(webgpu)]
pub mod webgpu {
pub use crate::backend::webgpu::webgpu_sys::{
GpuBuffer, GpuDevice, GpuQueue, GpuTexture, GpuTextureView,
};
pub use crate::backend::webgpu::DropCallback;
}
#[doc(hidden)]
pub use macros::helpers as __macro_helpers;