Frame Capture Debugging Tools

Analyze and optimize your app performance at runtime.

Overview

Xcode provides a suite of tools that enable you to halt the execution of your Metal app and inspect its commands and data buffers. You take a snapshot of your app's Metal commands and data using a mechanism called GPU frame capture, then use the debugging and performance tools to operate on the data you collect.

When you're ready to capture a frame, click the camera button in Xcode's debug bar. Alternatively, you can invoke a frame capture using a breakpoint, or programmatically with the capture API during the runtime conditions you choose.

Topics

Essentials

Enabling Frame Capture

Configure your project to work with the Metal frame debugger.

Capturing a Frame Programmatically

Choose the commands you want to analyze, and define the runtime conditions to present them in the Metal frame debugger.

Capturing GPU Command Data Programmatically

Invoke Metal’s frame capture from your app under the specific runtime conditions you choose.

Capturing Metal Commands Programmatically

Invoke Metal’s frame capture from your app, then save the resulting GPU trace to a file or view it in Xcode.

Creating a Custom Capture Scope

Use custom capture scopes to control which commands get captured.

MTLCaptureManager

An object you use to capture Metal command data in your app.

MTLCaptureScope

An object that defines custom boundaries for a GPU frame capture.

MTLCaptureDescriptor

A configuration for a Metal capture session.

MTLCaptureDestination

The kinds of destinations for captured command data.

MTLCaptureErrorDomain

The error domain for capture errors.

MTLCaptureError

Errors returned by capture sessions.

Customizing Frame Capture

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.

Capturing a Frame Using a Breakpoint

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

Developing Your Shaders

Developing and Debugging Metal Shaders

Step through your app's shaders to inspect their variables during execution, and use a live preview to enhance development.

Debugging Your App

Viewing Your Frame Graph

View your render passes as a flow chart to inspect resource dependencies and understand which commands wait on others to complete.

Viewing Your Meshes with the Geometry Viewer

Find problems in your app's vertex function by pausing your app at any time, and viewing the current geometry from an angle you choose.

Optimizing Your App

Optimizing Performance with GPU Counters

Examine granular metrics for your rendering or compute calls, and tune your app as needed.

Optimizing Performance with the Shader Profiler

Discover which lines of shader code take the longest to complete, identify their primary GPU activities, and tune your shaders accordingly.

Optimizing Performance with Pipeline Statistics

Decide how to tune your encoder performance by identifying your app's longest-running encoders and their primary GPU activity.