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.


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

Assign Labels to 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.

Assign Labels to 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.

id<MTLRenderCommandEncoder> renderEncoder = [commandBuffer renderCommandEncoderWithDescriptor:renderPassDescriptor];
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.