Creating a Custom Capture Scope

Use custom capture scopes to control which commands get captured.


Don’t allocate a custom capture scope yourself. Instead, call one of the MTLCaptureManager methods, makeCaptureScope(device:), or makeCaptureScope(commandQueue:).

let sharedCaptureManager = MTLCaptureManager.shared()
let myCaptureScope = sharedCaptureManager.makeCaptureScope(device: device)

Define Capture Boundaries

Call begin() on your capture scope to instruct the Metal frame debugger to record your app’s subsequent Metal activity. To stop recording a frame captured with this scope and to present the Metal frame debugger, call end().

// Create myCaptureScope outside of your rendering loop. 
let commandBuffer = commandQueue.makeCommandBuffer()!
// Do Metal work

Label Your Capture Scope for Use in the Debug Bar

To capture your custom scope from Xcode’s debug bar, set your capture scope’s label property.

myCaptureScope.label = "My Capture Scope"

When you’re ready to capture a frame, press and hold the camera button on the debug bar. Xcode presents a selection menu from which you choose the scope with your label.

An Xcode screenshot that shows the Capture Scope contextual menu in the debug bar.

Keep a strong reference to the capture scope for as long as you want the option to be visible in Xcode.

Make a Custom Capture Scope the Default

When you capture a frame, Xcode uses the capture scope that’s assigned to the defaultCaptureScope property of MTLCaptureManager. If the value of this property is nil, Xcode defines the default capture scope using drawable presentation boundaries; for example, using your calls to the methods present(_:) or present().

To change the default scope, create a MTLCaptureScope and assign it to the defaultCaptureScope property of the shared MTLCaptureManager.

sharedCaptureManager.defaultCaptureScope = myCaptureScope

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.

class MTLCaptureManager

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

protocol MTLCaptureScope

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

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.