Inspecting acceleration structures

Overview

An acceleration structure is a data structure that Metal uses to accelerate ray intersection tests on the GPU. The Metal debugger allows you to inspect an acceleration structure with the Acceleration Structure viewer. After opening an acceleration structure, you can view it and its associated properties, along with various highlights.

Navigate your acceleration structure

You can navigate your acceleration structure using the two panes of the Acceleration Structure viewer — the structure outline on the left or the scene view on the right.

[Image]

The structure outline shows the components of your acceleration structure, along with their various properties. You can click any row in the structure outline to highlight the component of your acceleration structure in the scene view, or Control-click to jump to it.

The scene view shows a 3D representation of your acceleration structure. You can navigate around the scene or interact with your acceleration structure using the following controls:

Change the camera mode

If you’re using the Fly camera, dragging in the scene view rotates the camera. Alternatively, when using the Orbit camera, dragging orbits the camera around any primitive beneath the pointer, or around the scene center if there’s no primitive. You can click the Camera button in the control bar to switch between modes.

[Image]

Configure intersection functions

Xcode automatically picks an intersection function table to use when rendering the scene, depending on how you open your acceleration structure. For example, if you open your acceleration structure from the Bound Resources viewer, Xcode selects any bound intersection function tables with matching intersector tags. For more information, see Inspecting the bound resources for a command. If you open your acceleration structure from the All Resources viewer or the Memory viewer, Xcode automatically selects the last intersection function table, with matching intersector tags, in your workload. For more information, see Analyzing memory usage.

You can switch to the intersection function table outline to configure which intersection function table the Acceleration Structure viewer uses. If you select None, the Acceleration Structure viewer doesn’t use any intersection functions and relies solely on the geometry intersection. If you select an intersection function table, the system uses the intersection function corresponding to the intersection function table offset of each geometry to evaluate whether to accept an intersection. For more information, see intersectionFunctionTableOffset and accept_intersection in the Metal Shading Language Specification.

[Image]

Configure acceleration structure traversal behavior

You can override the default behavior of the acceleration structure traversal by clicking the arrow in the bottom right of the control bar. The popover options let you configure the same properties as the intersector to control traversal behavior (see Metal Shading Language Specification). Match the traversal behavior with your shader to ensure that the Acceleration Structure viewer is correct.

[Image]

View your acceleration structure with highlights

You can view your acceleration structure with different highlights to emphasize various properties. To enable and switch between modes, click the Highlight button in the control bar.

[Image]

Bounding Volume Traversals

You can use the Bounding Volume Traversals mode to highlight areas of your scene that are more expensive to traverse. Xcode color-codes the number of traversals it takes to intersect your acceleration structure on a scale from white (fewer traversals) to dark blue (more traversals). As you move the pointer around the viewport, the inspector (at the bottom left) updates several traversal statistics for the pixel under the pointer, along with the corresponding minimum and maximum values in the viewport.

[Image]

All Node Traversal

You can use the All Node Traversal mode to highlight the expensive parts of your scene that may be occluded. Xcode uses the same color-coding as the Bounding Volume Traversals highlight, but doesn’t stop traversing when it hits a surface. In the example below, you can see the eyes inside the ninja’s head:

[Image]

Acceleration Structures

This mode highlights different primitive acceleration structures. The inspector shows the primitive acceleration structure index as you move the pointer around the viewport.

[Image]

Geometries

This mode highlights different geometries within primitive acceleration structures. The inspector shows the geometry_id attribute as you move the pointer around the viewport. For more information, see Metal Shading Language Specification.

[Image]

Primitives

This mode highlights different primitives within primitive acceleration structures. The inspector shows the geometry_id and primitive_id attributes as you move the pointer around the viewport. For more information, see Metal Shading Language Specification.

[Image]

Instances

This mode highlights different instances of primitive acceleration structures. The inspector shows the instance_id attribute as you move the pointer around the viewport. For more information, see Metal Shading Language Specification.

[Image]

Intersection Functions

This mode highlights different intersection functions. The inspector shows the intersection function index as you move the pointer around the viewport.

[Image]

View per-primitive data

To view per-primitive data, first navigate to a primitive in the structure outline. Then, click the arrow next to the data property to open a Buffer viewer containing the per-primitive data.

[Image]

For information on configuring the Buffer viewer to better interpret the data, see Inspecting buffers.

View motion data

If your acceleration structure includes motion data, Xcode automatically shows additional motion data properties per-instance or per-geometry in the structure outline.

[Image]

Additional motion controls appear in the control bar. You can drag the motion timeline playhead to change the preview time. Alternatively, you can click the Play/Pause button and Xcode repeatedly bounces the current motion time between the minimum start time and the maximum end time.

[Image]

See Also

Metal resource inspection

• Inspecting buffers
• Inspecting pipeline states
• Inspecting sampler states
• Inspecting shaders
• Inspecting textures