Add Metal external buffer-write interop

Author: jcwal1516

CHANGELOG.md

@@ -42,6 +42,12 @@ Bottom level categories:
 
 ## Unreleased
 
+### Added/New Features
+
+#### Metal
+
+- Add retained native device, queue, and buffer handles plus guarded external buffer-write initialization registration. By @jcwal1516 in [#9928](https://github.com/gfx-rs/wgpu/issues/9928).
+
 ## v29.0.4 (2026-07-01)
 
 ### New Features

Cargo.lock

@@ -92,6 +92,11 @@ parking_lot = { workspace = true, features = ["deadlock_detection"] }
 [target.'cfg(not(any(target_arch = "wasm32", miri)))'.dependencies]
 nv-flip.workspace = true
 
+[target.'cfg(target_vendor = "apple")'.dev-dependencies]
+objc2.workspace = true
+objc2-foundation.workspace = true
+objc2-metal.workspace = true
+
 # Webassembly
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 console_log.workspace = true

tests/Cargo.toml

@@ -38,6 +38,8 @@ mod instance;
 mod life_cycle;
 mod mem_leaks;
 mod mesh_shader;
+#[cfg(target_vendor = "apple")]
+mod metal_external_write;
 mod multiview;
 mod naga_capabilities;
 mod occlusion_query;
@@ -105,6 +107,8 @@ fn all_tests() -> Vec<wgpu_test::GpuTestInitializer> {
     image_atomics::all_tests(&mut tests);
     instance::all_tests(&mut tests);
     life_cycle::all_tests(&mut tests);
+    #[cfg(target_vendor = "apple")]
+    metal_external_write::all_tests(&mut tests);
     mem_leaks::all_tests(&mut tests);
     mesh_shader::all_tests(&mut tests);
     multiview::all_tests(&mut tests);

tests/tests/wgpu-gpu/main.rs

@@ -0,0 +1,101 @@
+use objc2::{rc::Retained, runtime::ProtocolObject};
+use objc2_foundation::NSRange;
+use objc2_metal::{
+    MTLBlitCommandEncoder, MTLBuffer, MTLCommandBuffer, MTLCommandEncoder, MTLCommandQueue,
+    MTLDevice,
+};
+use wgpu_test::{gpu_test, FailureCase, GpuTestConfiguration, GpuTestInitializer, TestParameters};
+
+pub fn all_tests(tests: &mut Vec<GpuTestInitializer>) {
+    tests.push(METAL_EXTERNAL_BUFFER_WRITE);
+}
+
+#[gpu_test]
+static METAL_EXTERNAL_BUFFER_WRITE: GpuTestConfiguration = GpuTestConfiguration::new()
+    .parameters(TestParameters::default().skip(FailureCase::backend(!wgpu::Backends::METAL)))
+    .run_sync(|ctx| {
+        const SIZE: u64 = 64;
+        const WRITTEN: core::ops::Range<usize> = 16..48;
+
+        let buffer = ctx.device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some("external Metal destination"),
+            size: SIZE,
+            usage: wgpu::BufferUsages::COPY_SRC | wgpu::BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        });
+        let readback = ctx.device.create_buffer(&wgpu::BufferDescriptor {
+            label: Some("external Metal readback"),
+            size: SIZE,
+            usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
+            mapped_at_creation: false,
+        });
+
+        let device_ptr = unsafe {
+            ctx.device
+                .as_hal::<wgpu_hal::api::Metal>()
+                .expect("Metal device")
+                .retained_raw_handle()
+        };
+        let queue_ptr = unsafe {
+            ctx.queue
+                .as_hal::<wgpu_hal::api::Metal>()
+                .expect("Metal queue")
+                .retained_raw_handle()
+        };
+        let buffer_ptr = unsafe {
+            buffer
+                .as_hal::<wgpu_hal::api::Metal>()
+                .expect("Metal buffer")
+                .retained_raw_handle()
+        };
+
+        let device = unsafe {
+            Retained::<ProtocolObject<dyn MTLDevice>>::from_raw(device_ptr.cast().as_ptr())
+                .expect("retained Metal device")
+        };
+        let queue = unsafe {
+            Retained::<ProtocolObject<dyn MTLCommandQueue>>::from_raw(queue_ptr.cast().as_ptr())
+                .expect("retained Metal queue")
+        };
+        let raw_buffer = unsafe {
+            Retained::<ProtocolObject<dyn MTLBuffer>>::from_raw(buffer_ptr.cast().as_ptr())
+                .expect("retained Metal buffer")
+        };
+        assert_eq!(queue.device(), device);
+
+        let command_buffer = queue.commandBuffer().expect("external command buffer");
+        let encoder = command_buffer.blitCommandEncoder().expect("blit encoder");
+        encoder.fillBuffer_range_value(
+            &raw_buffer,
+            NSRange::new(WRITTEN.start, WRITTEN.len()),
+            0xA5,
+        );
+        encoder.endEncoding();
+        command_buffer.commit();
+        command_buffer.waitUntilCompleted();
+
+        unsafe {
+            buffer
+                .mark_external_write_initialized(WRITTEN.start as u64..WRITTEN.end as u64)
+                .expect("register completed external write");
+        }
+
+        let mut command_encoder = ctx
+            .device
+            .create_command_encoder(&wgpu::CommandEncoderDescriptor::default());
+        command_encoder.copy_buffer_to_buffer(&buffer, 0, &readback, 0, SIZE);
+        ctx.queue.submit([command_encoder.finish()]);
+        readback
+            .slice(..)
+            .map_async(wgpu::MapMode::Read, Result::unwrap);
+        ctx.device
+            .poll(wgpu::PollType::wait_indefinitely())
+            .unwrap();
+
+        let mapped = readback.slice(..).get_mapped_range();
+        assert!(mapped[..WRITTEN.start].iter().all(|byte| *byte == 0));
+        assert!(mapped[WRITTEN.clone()].iter().all(|byte| *byte == 0xA5));
+        assert!(mapped[WRITTEN.end..].iter().all(|byte| *byte == 0));
+        drop(mapped);
+        readback.unmap();
+    });

tests/tests/wgpu-gpu/metal_external_write.rs

@@ -0,0 +1,86 @@
+use core::ops::Range;
+
+use crate::{
+    init_tracker::BufferInitTracker,
+    resource::{BufferAccessError, BufferAccessResult},
+};
+
+pub(super) fn mark_buffer_range_initialized(
+    buffer_size: wgt::BufferAddress,
+    initialization_status: &mut BufferInitTracker,
+    range: Range<wgt::BufferAddress>,
+) -> BufferAccessResult {
+    if range.start >= range.end {
+        return Err(BufferAccessError::InvalidRange {
+            start: range.start,
+            end: range.end,
+        });
+    }
+    if range.start > buffer_size {
+        return Err(BufferAccessError::OutOfBoundsStartOffsetOverrun {
+            index: range.start,
+            max: buffer_size,
+        });
+    }
+    if range.end > buffer_size {
+        return Err(BufferAccessError::OutOfBoundsEndOffsetOverrun {
+            index: range.start,
+            size: range.end - range.start,
+            max: buffer_size,
+        });
+    }
+
+    drop(initialization_status.drain(range));
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::mark_buffer_range_initialized;
+    use crate::init_tracker::BufferInitTracker;
+    use crate::resource::BufferAccessError;
+    use core::ops::Range;
+
+    fn rejected_range(range: Range<u64>) -> BufferAccessError {
+        let mut tracker = BufferInitTracker::new(64);
+        let error = mark_buffer_range_initialized(64, &mut tracker, range).unwrap_err();
+        assert_eq!(tracker.check(0..64), Some(0..64));
+        error
+    }
+
+    #[test]
+    fn marks_only_the_external_write_range_initialized() {
+        let mut tracker = BufferInitTracker::new(64);
+
+        mark_buffer_range_initialized(64, &mut tracker, 16..48).unwrap();
+
+        assert_eq!(tracker.check(0..16), Some(0..16));
+        assert_eq!(tracker.check(16..48), None);
+        assert_eq!(tracker.check(48..64), Some(48..64));
+    }
+
+    #[test]
+    fn rejects_empty_reversed_and_out_of_bounds_ranges() {
+        let reversed = Range { start: 32, end: 16 };
+        assert!(matches!(
+            rejected_range(16..16),
+            BufferAccessError::InvalidRange { start: 16, end: 16 }
+        ));
+        assert!(matches!(
+            rejected_range(reversed),
+            BufferAccessError::InvalidRange { start: 32, end: 16 }
+        ));
+        assert!(matches!(
+            rejected_range(65..66),
+            BufferAccessError::OutOfBoundsStartOffsetOverrun { index: 65, max: 64 }
+        ));
+        assert!(matches!(
+            rejected_range(48..65),
+            BufferAccessError::OutOfBoundsEndOffsetOverrun {
+                index: 48,
+                size: 17,
+                max: 64
+            }
+        ));
+    }
+}

wgpu-core/src/device/external_write.rs

@@ -1,5 +1,5 @@
 use alloc::{borrow::Cow, boxed::Box, string::String, sync::Arc, vec::Vec};
-use core::{ptr::NonNull, sync::atomic::Ordering};
+use core::{ops::Range, ptr::NonNull, sync::atomic::Ordering};
 
 #[cfg(feature = "trace")]
 use crate::device::trace::{self, IntoTrace};
@@ -11,7 +11,10 @@ use crate::{
     },
     command::{self, CommandEncoder},
     conv,
-    device::{life::WaitIdleError, DeviceError, DeviceLostClosure},
+    device::{
+        external_write::mark_buffer_range_initialized, life::WaitIdleError, DeviceError,
+        DeviceLostClosure,
+    },
     global::Global,
     id::{self, AdapterId, DeviceId, QueueId, SurfaceId},
     instance::{self, Adapter, Surface},
@@ -34,6 +37,32 @@ use wgt::{BufferAddress, TextureFormat};
 use super::UserClosures;
 
 impl Global {
+    /// Record that a completed external GPU producer fully initialized a buffer range.
+    ///
+    /// # Safety
+    ///
+    /// The caller must own the range exclusively, resolve every prior wgpu use, and prevent
+    /// later wgpu access until the external write completes or an equivalent GPU dependency is
+    /// installed. Every semantically accessible byte in `range` must have been written.
+    #[doc(hidden)]
+    pub unsafe fn buffer_mark_external_write_initialized(
+        &self,
+        buffer_id: id::BufferId,
+        range: Range<BufferAddress>,
+    ) -> BufferAccessResult {
+        let buffer = self.hub.buffers.get(buffer_id).get()?;
+        let snatch_guard = buffer.device.snatchable_lock.read();
+        buffer.check_destroyed(&snatch_guard)?;
+        drop(snatch_guard);
+        buffer.device.check_is_valid()?;
+
+        let result = {
+            let mut initialization_status = buffer.initialization_status.write();
+            mark_buffer_range_initialized(buffer.size, &mut initialization_status, range)
+        };
+        result
+    }
+
     pub fn adapter_is_surface_supported(
         &self,
         adapter_id: AdapterId,

wgpu-core/src/device/global.rs

@@ -21,6 +21,7 @@ use wgt::{
 };
 
 pub(crate) mod bgl;
+mod external_write;
 pub mod global;
 mod life;
 pub mod queue;

wgpu-core/src/device/mod.rs

@@ -300,6 +300,11 @@ pub enum BufferAccessError {
         size: wgt::BufferAddress,
         max: wgt::BufferAddress,
     },
+    #[error("Buffer access range {start}..{end} must be non-empty and ordered")]
+    InvalidRange {
+        start: wgt::BufferAddress,
+        end: wgt::BufferAddress,
+    },
     #[error("Buffer map aborted")]
     MapAborted,
     #[error(transparent)]
@@ -340,6 +345,7 @@ impl WebGpuError for BufferAccessError {
             | Self::OutOfBoundsStartOffsetUnderrun { .. }
             | Self::OutOfBoundsStartOffsetOverrun { .. }
             | Self::OutOfBoundsEndOffsetOverrun { .. }
+            | Self::InvalidRange { .. }
             | Self::MapAborted
             | Self::MapStartOffsetOverrun { .. }
             | Self::MapEndOffsetOverrun { .. } => ErrorType::Validation,