Article

Enabling Frame Capture

Configure your project to work with the Metal frame debugger.

Overview

If your target links to the Metal framework (or any other framework that uses the Metal API), Xcode automatically enables GPU Frame Capture and Metal API Validation. Enable these options in your app’s scheme to use the host of tools Xcode provides with Metal Frame Capture, and to test for correct API usage with Metal API Validation. You only disable these options when you want to test your app’s maximum performance level.

Navigate to the Metal Scheme Settings

  1. In the toolbar, choose Edit Scheme from the scheme menu. (Alternatively, choose Product > Scheme > Edit Scheme.)

  2. In the scheme action panel, select Run.

  3. In the action setting tab, select Options.

An Xcode screenshot that shows the scheme menu.
An Xcode screenshot that shows the scheme editor, scheme actions, scheme options, and Metal tools.

Choose a GPU Frame Capture Option

Choose the option that best suits your debugging needs:

  • Automatically Enabled: Captures Metal or OpenGL ES API usage in your app. If your target doesn’t link to the Metal or OpenGL ES framework, the Capture GPU Frame icon isn’t shown in the debug bar. If your app uses both the Metal and OpenGL ES API, you can click and hold the Capture GPU Frame icon to choose which API usage to capture.

  • Metal: Captures only Metal API usage in your app. If your app doesn’t use Metal API, Xcode disables the Capture GPU Frame icon in the debug bar.

  • Disabled: Doesn’t capture Metal usage in your app.

You can also choose whether Xcode profiles the trace data once capture is complete.

Choose a Metal API Validation Option

Choose the option that best suits your validation and performance needs:

  • Enabled: Metal performs runtime validation and assertion for Metal API calls.

  • Disabled: Metal doesn’t perform runtime validation and assertion for Metal API calls.

Capture GPU Traces Without Xcode

Sometimes, you might want to capture a GPU trace when Xcode isn’t running. For example, you might want testers to be able to save a GPU trace when they discover a problem. To add this capability to your app, first add the MetalCaptureEnabled key to your Info.plist file, with a value of YES. In Xcode’s property list editor, this key appears as Metal Capture Enabled. After enabling this key, add code to your app to programmatically capture trace information and save it to a file for later analysis. For more information, see Capture GPU Command Data to a File.