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 begin() and end() around the Metal calls you want the capture to include. In the case of a rendering loop, your calls to begin() and end() 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

func begin()

Tells Metal to begin recording command information.


func end()

Tells Metal to stop recording command information.


Identifying the Capture Scope

var label: String?

A string that identifies the capture scope.


var device: MTLDevice

The device object from which you created the capture scope.


var commandQueue: MTLCommandQueue?

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.

class MTLCaptureManager

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

class MTLCaptureDescriptor

A configuration for a Metal capture session.

enum MTLCaptureDestination

The kinds of destinations for captured command data.

let MTLCaptureErrorDomain: String

The error domain for capture errors.

enum MTLCaptureError

Errors returned by capture sessions.