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

Command Setup

Setting Up a Command Structure

Discover how Metal executes commands on a GPU.

Devices and Commands

Demonstrates how to access and interact with the GPU.

protocol MTLCommandQueue

A queue that organizes command buffers to be executed by a GPU.

protocol MTLCommandBuffer

A container that stores encoded commands for the GPU to execute.

protocol MTLCommandEncoder

An encoder that writes GPU commands into a command buffer.

Advanced Command Setup

Organize your commands for maximum concurrency and minimal dependencies.