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


@protocol MTLCaptureScope


A capture scope works with Metal’s frame capture feature to filter a captured frame to include the specific commands that you choose. By contrast, when you capture a frame with the default capture scope by clicking the camera button on Xcode’s debug bar, the resulting capture includes all the data from a single frame. You create your own capture scope when you want to choose which data Metal should record.

To determine exactly which Metal commands to record in a captured frame, call beginScope and endScope around the Metal calls you want the capture to include. In the case of a rendering loop, your calls to beginScope and endScope can capture a small part of a frame, or capture data across multiple frames.

You can use capture scopes in a few different ways:

  • You can change Xcode’s default capturing behavior.

  • In Xcode, you can add additional capture scopes that appear when you click and hold the camera button on the debug bar.

  • You can programmatically trigger a capture session using a specific scope.

For more information about frame capture, see Frame Capture Debugging Tools. For more information on creating custom capture scopes, see Creating a Custom Capture Scope.


Defining Capture Scope Boundaries

- beginScope

Tells Metal to begin recording command information.


- endScope

Tells Metal to stop recording command information.


Identifying the Capture Scope


A string that identifies the capture scope.



The device object from which you created the capture scope.



The command queue that this capture scope uses to limit which commands are recorded.



Inherits From

See Also

Capturing a Frame Programmatically

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.


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


A configuration for a Metal capture session.


The kinds of destinations for captured command data.


The error domain for capture errors.


Errors returned by capture sessions.