From 78b4dfd0cb1ef5ed208fefe80ae2f855db3609bb Mon Sep 17 00:00:00 2001 From: Inner Daemons <85136135+inner-daemons@users.noreply.github.com> Date: Fri, 12 Jun 2026 16:09:42 -0500 Subject: [PATCH] Improve custom backend capabilities (#9605) --- CHANGELOG.md | 1 + wgpu/src/api/blas.rs | 7 +++ wgpu/src/api/device.rs | 19 +++++++ wgpu/src/api/external_texture.rs | 6 ++ wgpu/src/api/render_bundle_encoder.rs | 2 +- wgpu/src/api/tlas.rs | 8 ++- wgpu/src/backend/custom.rs | 80 ++++++++++++++++++++++++++- wgpu/src/backend/webgpu.rs | 8 +++ wgpu/src/backend/wgpu_core.rs | 8 +++ wgpu/src/dispatch.rs | 16 ++++++ 10 files changed, 152 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d089541ad..ed0469eb2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -131,6 +131,7 @@ By @beholdnec in [#8505](https://github.com/gfx-rs/wgpu/pull/8505). }; ``` By @AdrianEddy in [#9496](https://github.com/gfx-rs/wgpu/pull/9496). +- Add `as_custom` to many new API types, which increases the capabilities of custom backends. Also fixed render bundles on custom backends. By @inner-daemons in [#9605](https://github.com/gfx-rs/wgpu/pull/9605). - Extend `copy_texture_to_texture` to allow copying a single plane of a multi-planar source (NV12, P010) into a single-plane destination of the matching format (e.g. NV12 `Plane0` → `R8Unorm`, NV12 `Plane1` → `Rg8Unorm`). `copy_size` is interpreted in plane texels, not luma texels. By @AdrianEddy in [#9551](https://github.com/gfx-rs/wgpu/pull/9551). - Added `InstanceFlags::STRICT_WEBGPU_COMPLIANCE` flag, which restricts the available feature set to the one defined by the WebGPU specification. By @teoxoy in [#9586](https://github.com/gfx-rs/wgpu/pull/9586). diff --git a/wgpu/src/api/blas.rs b/wgpu/src/api/blas.rs index 358902b06..5433a37ce 100644 --- a/wgpu/src/api/blas.rs +++ b/wgpu/src/api/blas.rs @@ -95,6 +95,13 @@ impl TlasInstance { pub fn set_blas(&mut self, blas: &Blas) { self.blas = blas.inner.clone(); } + + /// Returns custom implementation of the BLAS referenced by this instance + /// (if the custom backend is active and the BLAS is internally of type T). + #[cfg(custom)] + pub fn blas_as_custom(&self) -> Option<&T> { + self.blas.as_custom() + } } #[derive(Debug)] diff --git a/wgpu/src/api/device.rs b/wgpu/src/api/device.rs index 5afd2d70d..57e6d512b 100644 --- a/wgpu/src/api/device.rs +++ b/wgpu/src/api/device.rs @@ -718,6 +718,17 @@ impl Device { pub struct RequestDeviceError { pub(crate) inner: RequestDeviceErrorKind, } + +impl RequestDeviceError { + /// Construct an error from a custom backend message. This is mainly useful for custom backends. + #[cfg(custom)] + pub fn from_message(message: String) -> Self { + RequestDeviceError { + inner: RequestDeviceErrorKind::Custom(message), + } + } +} + #[derive(Clone, Debug)] pub(crate) enum RequestDeviceErrorKind { /// Error from [`wgpu_core`]. @@ -730,6 +741,10 @@ pub(crate) enum RequestDeviceErrorKind { /// (This is currently never used by the webgl backend, but it could be.) #[cfg(webgpu)] WebGpu(String), + + /// Error from a custom backend. + #[cfg(custom)] + Custom(String), } static_assertions::assert_impl_all!(RequestDeviceError: Send, Sync); @@ -743,6 +758,8 @@ impl fmt::Display for RequestDeviceError { RequestDeviceErrorKind::WebGpu(error) => { write!(_f, "{error}") } + #[cfg(custom)] + RequestDeviceErrorKind::Custom(msg) => write!(_f, "{msg}"), #[cfg(not(any(webgpu, wgpu_core)))] _ => unimplemented!("unknown `RequestDeviceErrorKind`"), } @@ -756,6 +773,8 @@ impl error::Error for RequestDeviceError { RequestDeviceErrorKind::Core(error) => error.source(), #[cfg(webgpu)] RequestDeviceErrorKind::WebGpu(_) => None, + #[cfg(custom)] + RequestDeviceErrorKind::Custom(_) => None, #[cfg(not(any(webgpu, wgpu_core)))] _ => unimplemented!("unknown `RequestDeviceErrorKind`"), } diff --git a/wgpu/src/api/external_texture.rs b/wgpu/src/api/external_texture.rs index d41f41c56..f08798101 100644 --- a/wgpu/src/api/external_texture.rs +++ b/wgpu/src/api/external_texture.rs @@ -19,6 +19,12 @@ impl ExternalTexture { pub fn destroy(&self) { self.inner.destroy(); } + + /// Returns custom implementation of ExternalTexture (if custom backend and is internally T) + #[cfg(custom)] + pub fn as_custom(&self) -> Option<&T> { + self.inner.as_custom() + } } /// Describes an [`ExternalTexture`]. diff --git a/wgpu/src/api/render_bundle_encoder.rs b/wgpu/src/api/render_bundle_encoder.rs index 041b67cac..30dd1b2dd 100644 --- a/wgpu/src/api/render_bundle_encoder.rs +++ b/wgpu/src/api/render_bundle_encoder.rs @@ -58,7 +58,7 @@ impl<'a> RenderBundleEncoder<'a> { #[cfg(webgpu)] dispatch::DispatchRenderBundleEncoder::WebGPU(b) => b.finish(desc), #[cfg(custom)] - dispatch::DispatchRenderBundleEncoder::Custom(_) => unimplemented!(), + dispatch::DispatchRenderBundleEncoder::Custom(b) => b.finish_boxed(desc), }; RenderBundle { inner: bundle } diff --git a/wgpu/src/api/tlas.rs b/wgpu/src/api/tlas.rs index b897824d5..d71918c77 100644 --- a/wgpu/src/api/tlas.rs +++ b/wgpu/src/api/tlas.rs @@ -75,11 +75,17 @@ impl Tlas { unsafe { tlas.context.tlas_as_hal::(tlas) } } - #[cfg(custom)] /// Returns custom implementation of Tlas (if custom backend and is internally T) + #[cfg(custom)] pub fn as_custom(&self) -> Option<&T> { self.inner.as_custom() } + /// Returns the index of the first instance that has not been modified since the last build. + /// Custom backends use this to perform partial TLAS updates. + #[cfg(custom)] + pub fn lowest_unmodified(&self) -> u32 { + self.lowest_unmodified + } /// Get a reference to all instances. pub fn get(&self) -> &[Option] { diff --git a/wgpu/src/backend/custom.rs b/wgpu/src/backend/custom.rs index 4d205e001..3160ca785 100644 --- a/wgpu/src/backend/custom.rs +++ b/wgpu/src/backend/custom.rs @@ -4,7 +4,10 @@ pub use crate::dispatch::*; +use crate::cmp::AtomicU64; +use alloc::boxed::Box; use alloc::sync::Arc; +use core::sync::atomic::Ordering; macro_rules! dyn_type { // cloning of arc forbidden @@ -91,7 +94,82 @@ dyn_type!(pub mut struct DynCommandEncoder(dyn CommandEncoderInterface)); dyn_type!(pub mut struct DynComputePass(dyn ComputePassInterface)); dyn_type!(pub mut struct DynRenderPass(dyn RenderPassInterface)); dyn_type!(pub mut struct DynCommandBuffer(dyn CommandBufferInterface)); -dyn_type!(pub mut struct DynRenderBundleEncoder(dyn RenderBundleEncoderInterface)); + +static NEXT_RENDER_BUNDLE_ENCODER_ID: AtomicU64 = AtomicU64::new(0); + +// DynRenderBundleEncoder uses Box instead of Arc so that finish_boxed(self: Box) +// can be dispatched through the trait object (consuming the encoder). +#[derive(Debug)] +pub(crate) struct DynRenderBundleEncoder { + // Unique identity for Eq/Ord/Hash. The data pointer of the boxed trait object is + // not safe to use for identity because ZST impls share the same dangling address. + id: u64, + inner: Box, +} + +impl DynRenderBundleEncoder { + pub(crate) fn new(t: T) -> Self { + Self { + id: NEXT_RENDER_BUNDLE_ENCODER_ID.fetch_add(1, Ordering::Relaxed), + inner: Box::new(t), + } + } + + pub(crate) fn downcast(&self) -> Option<&T> { + self.inner.as_ref().as_any().downcast_ref() + } + + pub(crate) fn finish_boxed( + self, + desc: &crate::RenderBundleDescriptor<'_>, + ) -> crate::dispatch::DispatchRenderBundle { + self.inner.finish_boxed(desc) + } +} + +impl core::ops::Deref for DynRenderBundleEncoder { + type Target = dyn RenderBundleEncoderInterface; + #[inline] + fn deref(&self) -> &Self::Target { + self.inner.as_ref() + } +} + +impl core::ops::DerefMut for DynRenderBundleEncoder { + #[inline] + fn deref_mut(&mut self) -> &mut Self::Target { + self.inner.as_mut() + } +} + +// Eq/Ord/Hash for DynRenderBundleEncoder are based on a unique id assigned at construction. +// +// These impls are not semantically meaningful (we never sort or deduplicate encoders by +// "value") but are required to satisfy bounds imposed by the dispatch enum machinery. +impl PartialEq for DynRenderBundleEncoder { + fn eq(&self, other: &Self) -> bool { + self.id == other.id + } +} +impl Eq for DynRenderBundleEncoder {} + +impl PartialOrd for DynRenderBundleEncoder { + fn partial_cmp(&self, other: &Self) -> Option { + Some(self.cmp(other)) + } +} +impl Ord for DynRenderBundleEncoder { + fn cmp(&self, other: &Self) -> core::cmp::Ordering { + self.id.cmp(&other.id) + } +} + +impl core::hash::Hash for DynRenderBundleEncoder { + fn hash(&self, state: &mut H) { + self.id.hash(state); + } +} + dyn_type!(pub ref struct DynRenderBundle(dyn RenderBundleInterface)); dyn_type!(pub ref struct DynSurface(dyn SurfaceInterface)); dyn_type!(pub ref struct DynSurfaceOutputDetail(dyn SurfaceOutputDetailInterface)); diff --git a/wgpu/src/backend/webgpu.rs b/wgpu/src/backend/webgpu.rs index 9121d3599..ce2803952 100644 --- a/wgpu/src/backend/webgpu.rs +++ b/wgpu/src/backend/webgpu.rs @@ -3892,6 +3892,14 @@ impl dispatch::RenderBundleEncoderInterface for WebRenderBundleEncoder { } .into() } + + #[cfg(custom)] + fn finish_boxed( + self: Box, + desc: &crate::RenderBundleDescriptor<'_>, + ) -> dispatch::DispatchRenderBundle { + (*self).finish(desc) + } } impl Drop for WebRenderBundleEncoder { fn drop(&mut self) { diff --git a/wgpu/src/backend/wgpu_core.rs b/wgpu/src/backend/wgpu_core.rs index fce2ee5c9..738c847b5 100644 --- a/wgpu/src/backend/wgpu_core.rs +++ b/wgpu/src/backend/wgpu_core.rs @@ -3913,6 +3913,14 @@ impl dispatch::RenderBundleEncoderInterface for CoreRenderBundleEncoder { } .into() } + + #[cfg(custom)] + fn finish_boxed( + self: Box, + desc: &crate::RenderBundleDescriptor<'_>, + ) -> dispatch::DispatchRenderBundle { + (*self).finish(desc) + } } impl dispatch::RenderBundleInterface for CoreRenderBundle {} diff --git a/wgpu/src/dispatch.rs b/wgpu/src/dispatch.rs index 57c0511c8..2f07d3622 100644 --- a/wgpu/src/dispatch.rs +++ b/wgpu/src/dispatch.rs @@ -571,6 +571,22 @@ pub trait RenderBundleEncoderInterface: CommonTraits { fn finish(self, desc: &crate::RenderBundleDescriptor<'_>) -> DispatchRenderBundle where Self: Sized; + + /// Object-safe version of `finish` for dyn dispatch through `Box`. + /// + /// A default implementation cannot be provided here: a default that calls `finish` would + /// require `Self: Sized` (to move out of the box), which would remove the method from the + /// vtable and break object safety. Every concrete backend must implement this as: + /// ```ignore + /// fn finish_boxed(self: Box, desc: &RenderBundleDescriptor<'_>) -> DispatchRenderBundle { + /// (*self).finish(desc) + /// } + /// ``` + #[cfg(custom)] + fn finish_boxed( + self: Box, + desc: &crate::RenderBundleDescriptor<'_>, + ) -> DispatchRenderBundle; } pub trait CommandBufferInterface: CommonTraits {}