Article

Enhancing Frame Capture by Using Labels

Assign meaningful labels to your Metal objects and commands so you can easily identify them in the call list of a captured frame.

Overview

Object and command labels are useful identifiers at runtime or when profiling and debugging your app using any Metal tool.

Label Objects

Many Metal objects provide a label property that you can assign a meaningful string to. These labels appear in the Metal tools, allowing you to easily identify specific objects.

Additionally, the addDebugMarker(_:range:) method allows you to easily mark and identify specific data ranges within a MTLBuffer.

Label Commands

Command buffers and command encoders provide the following methods that allow you to easily identify specific groups of Metal commands in your app:

Use these methods to simplify your app development process, particularly for tasks that use many Metal commands per buffer or encoder.

Debug groups are pushed and popped onto unique stacks that exist only within the lifetime of their associated MTLCommandBuffer or MTLCommandEncoder. You can nest debug groups by pushing multiple groups onto the stack before popping previous groups from the stack.

The following example demonstrates how to push and pop multiple debug groups.

guard let renderEncoder = commandBuffer.makeRenderCommandEncoder(descriptor: renderPassDescriptor) else { return }
renderEncoder.label = "My Render Encoder"
renderEncoder.pushDebugGroup("My Render Pass")

    renderEncoder.pushDebugGroup("Pipeline Setup")
    // Render pipeline commands
    renderEncoder.popDebugGroup() // Pops "Pipeline Setup"

    renderEncoder.pushDebugGroup("Vertex Setup")
    // Vertex function commands
    renderEncoder.popDebugGroup() // Pops "Vertex Setup"                      

    renderEncoder.pushDebugGroup("Fragment Setup")
    // Fragment function commands
    renderEncoder.popDebugGroup() // Pops "Fragment Setup"                      

    renderEncoder.pushDebugGroup("Draw Calls")
    // Drawing commands
    renderEncoder.popDebugGroup() // Pops "Draw Calls"                  

renderEncoder.popDebugGroup() // Pops "My Render Pass"
renderEncoder.endEncoding()

The following illustration shows how the debug groups appear in Xcode's debug navigator after you capture a frame.

An Xcode screenshot that shows debug groups in the Debug navigator.

See Also

Customizing Frame Capture

Capturing a Frame Using a Breakpoint

Capture a Metal frame at a breakpoint in your app by using Xcode's breakpoint actions.