[hal metal] ray tracing acceleration structures #7660

Lichtso · 2025-05-02T22:41:04Z

Connections
Fixes: #7402

Description
Implements the missing ray tracing acceleration structures in the HAL metal backend.

Testing
The examples ray_scene, ray_shadows, ray_cube_compute, ray_cube_fragment and ray_traced_triangle all work.
That is if invoked via cargo run --bin wgpu-examples ray_traced_triangle, but not via cargo xtask test ray_traced_triangle. It seems this is caused by a race condition between the CPU uploading the scratch buffer and the GPU reading it to build the acceleration structure. Which indicates that the lack of barriers in the acceleration structure building is an issue.

Squash or Rebase?
Squash

Checklist

Run cargo fmt.
Run taplo format.
Run cargo clippy --tests
Run cargo xtask test to run tests.
If this contains user-facing changes, add a CHANGELOG.md entry.

Vecvec

Good job! Glad there didn't need to be any wgpu-core changes. Largely looks good, but I'm not extremely knowledgeable about metal. One question / comment, but haven't yet checked everything with spec.

Vecvec · 2025-05-03T02:30:23Z

wgpu-hal/src/metal/conv.rs

+                        descriptor.set_index_buffer(indices.buffer.map(|buffer| &*buffer.raw));
+                        descriptor.set_index_buffer_offset(indices.offset as u64);
+                        descriptor.set_index_type(map_index_format(indices.format).1);
+                        descriptor.set_triangle_count(indices.count as u64 / 3);


It feels like the triangle count shouldn't be set just if the index buffer is set, but I can't see other places where this is set. Is this correct?

I added a fallback to use the vertex count in the else branch if there are no indices.

Vecvec

Done checks against the Metal spec. It seems this requires MacOS 13.0+ not 11.0+ due to some more recent functions being used. Confusingly, the vertex buffer field suggests that the only format supported is f32x3 so I'm not sure what descriptor.set_vertex_format does.

Vecvec · 2025-05-03T05:31:32Z

wgpu-hal/src/metal/adapter.rs

@@ -890,6 +890,11 @@ impl super::PrivateCapabilities {
                && (device.supports_family(MTLGPUFamily::Apple7)
                    || device.supports_family(MTLGPUFamily::Mac2)),
            supports_shared_event: version.at_least((10, 14), (12, 0), os_is_mac),
+            supports_raytracing: if version.at_least((11, 0), (14, 0), os_is_mac) {
+                device.supports_raytracing()


I think raytracing support needs supportsRaytracingFromRender due to support of ray queries in fragment shaders (Requires MacOS 12.0+).

That function is not exposed in the Rust metal crate. But I did bump the min required versions to macOS 13 and iOS 16.

If the metal crate is still taking PRs (Idk what state of deprecated they are in) it would probably be a good idea to add this (and the other later ones).

Vecvec · 2025-05-03T05:49:09Z

wgpu-hal/src/metal/conv.rs

+                    descriptor.set_vertex_format(unsafe {
+                        core::mem::transmute::<MTLVertexFormat, MTLAttributeFormat>(
+                            map_vertex_format(triangles.vertex_format),
+                        )
+                    });
+                    if let Some(transform) = triangles.transform.as_ref() {
+                        descriptor.set_transformation_matrix_buffer(Some(&*transform.buffer.raw));
+                        descriptor.set_transformation_matrix_buffer_offset(transform.offset as u64);
+                    }


On the spec these are listed as being MacOS 13.0+ while what is being checked is MacOS 11.0+, so it may be worth requiring MacOS 13.0+.

Vecvec · 2025-05-03T05:57:12Z

wgpu-hal/src/metal/command.rs

    ) {
-        unimplemented!()
+        let command_encoder = self.enter_acceleration_structure_builder();
+        command_encoder.write_compacted_acceleration_structure_size_with_type(


This requires MacOS 12.0+. https://developer.apple.com/documentation/metal/mtlaccelerationstructurecommandencoder/writecompactedsize(accelerationstructure:buffer:offset:sizedatatype:)

Lichtso · 2025-05-03T08:37:43Z

wgpu-hal/src/metal/device.rs

    }

    unsafe fn destroy_acceleration_structure(
        &self,
        _acceleration_structure: super::AccelerationStructure,
    ) {
-        unimplemented!()
+        // self.counters.acceleration_structures.sub(1);


I there a reason not to have HalCounters::acceleration_structures?

Looking back at the history I couldn't find a reason, but it's possible it's buried somewhere.

Lichtso · 2025-05-03T08:42:19Z

wgpu-hal/src/metal/command.rs

+        for descriptor in descriptors {
+            let acceleration_structure_descriptor =
+                conv::map_acceleration_structure_descriptor(descriptor.entries);
+            /* The Rust metal crate does not expose metal::MTLAccelerationStructureUsage yet


Again, not exposed in the Rust metal crate.

Lichtso · 2025-05-03T08:47:01Z

examples/features/src/ray_shadows/shader.wgsl

@@ -35,6 +35,7 @@ var acc_struct: acceleration_structure;

 struct PushConstants {
    light: vec3<f32>,
+    padding: f32,


It seems that metal always sends at least 16 bytes for push constants, even if we only pass in 12 bytes. And then the shader validation complains that the receiver here only expects 12 bytes.

…n_structure().

Lichtso · 2025-05-03T11:26:05Z

Glad there didn't need to be any wgpu-core changes

Almost, had to remove the Option<> around the buffers and always pass the dummy zero buffer when computing the size of the acceleration structures and their scratch buffers because Metal does not like nil.

I can split those first four commits into a separate PR if that helps with the review.

Lichtso requested a review from a team as a code owner May 2, 2025 22:41

Lichtso force-pushed the metal/ray_tracing_acceleration_structures branch 2 times, most recently from e30b663 to f3830cb Compare May 2, 2025 22:52

Vecvec approved these changes May 3, 2025

View reviewed changes

Vecvec suggested changes May 3, 2025

View reviewed changes

Lichtso force-pushed the metal/ray_tracing_acceleration_structures branch from f3830cb to 234e75b Compare May 3, 2025 08:33

Lichtso commented May 3, 2025

View reviewed changes

Removes Option<> around AccelerationStructureTriangleIndices::buffer.

b90a6b3

Lichtso force-pushed the metal/ray_tracing_acceleration_structures branch from 234e75b to 5f1c464 Compare May 3, 2025 11:01

Lichtso added 19 commits May 3, 2025 13:05

Removes Option<> around AccelerationStructureTriangles::vertex_buffer.

78ae78d

Removes Option<> around AccelerationStructureAABBs::buffer.

5e9563d

Removes Option<> around AccelerationStructureInstances::buffer.

6385fc9

Fixes index_buffer label in ray_traced_triangle example.

80d22d4

Fixes min_push_constant_size in ray_shadows example.

b23c93f

Updates CHANGELOG.

cb42a10

Adds feature detection.

f8041bb

Sets raw_tlas_instance_size.

20b68d7

Sets ray_tracing_scratch_buffer_alignment.

d189d0e

Adds conv::map_index_format().

714b1d8

Adds conv::map_acceleration_structure_descriptor().

b5ae113

Adds AccelerationStructurePtr.

8f1e05c

Implements AccelerationStructure.

d7589bb

Adds CommandState::acceleration_structure_builder.

64ff0b9

Implements CommandEncoder::copy_acceleration_structure_to_acceleratio…

38b6491

…n_structure().

Implements CommandEncoder::build_acceleration_structures().

254ad06

Implements CommandEncoder::place_acceleration_structure_barrier().

a0f38b6

Implements CommandEncoder::read_acceleration_structure_compact_size().

61012e3

Implements Device::get_acceleration_structure_build_sizes().

be18980

Lichtso added 5 commits May 3, 2025 13:12

Implements Device::get_acceleration_structure_device_address().

565054b

Implements Device::create_acceleration_structure().

b2a695d

Implements Device::destroy_acceleration_structure().

45dbf28

Implements Device::tlas_instance_to_bytes().

e50cecf

Implements resource binding.

2a6d9b6

Lichtso force-pushed the metal/ray_tracing_acceleration_structures branch from 5f1c464 to 2a6d9b6 Compare May 3, 2025 11:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[hal metal] ray tracing acceleration structures #7660

[hal metal] ray tracing acceleration structures #7660

Lichtso commented May 2, 2025 •

edited

Loading

Vecvec left a comment •

edited

Loading

Vecvec May 3, 2025 •

edited

Loading

Lichtso May 3, 2025

Vecvec left a comment

Vecvec May 3, 2025

Lichtso May 3, 2025

Vecvec May 3, 2025

Vecvec May 3, 2025

Vecvec May 3, 2025

Lichtso May 3, 2025

Vecvec May 3, 2025

Lichtso May 3, 2025

Lichtso May 3, 2025 •

edited

Loading

Lichtso commented May 3, 2025

[hal metal] ray tracing acceleration structures #7660

Are you sure you want to change the base?

[hal metal] ray tracing acceleration structures #7660

Conversation

Lichtso commented May 2, 2025 • edited Loading

Vecvec left a comment • edited Loading

Choose a reason for hiding this comment

Vecvec May 3, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Vecvec left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Lichtso May 3, 2025 • edited Loading

Choose a reason for hiding this comment

Lichtso commented May 3, 2025

Lichtso commented May 2, 2025 •

edited

Loading

Vecvec left a comment •

edited

Loading

Vecvec May 3, 2025 •

edited

Loading

Lichtso May 3, 2025 •

edited

Loading