Protocol

MTLCaptureScope

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

Declaration

@protocol MTLCaptureScope

Overview

A capture scope works with Xcode's Metal frame capture by filtering 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 customize a frame capture by choosing which data Xcode should expose in the Metal frame debugger.

To tell Xcode exactly which Metal commands to record in a captured frame, you 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.

To use your capture scope, pass it to a MTLCaptureManager via startCaptureWithScope:, or set the capture scope's label so Xcode offers it to you by that name when you press and hold on the camera button on the debug bar.

For more information about frame capture, see Frame Capture Debugging Tools.

Create a Custom Capture Scope

You don't allocate a custom capture scope yourself. Instead, you call one of the MTLCaptureManager methods, newCaptureScopeWithDevice:, or newCaptureScopeWithCommandQueue:.

MTLCaptureManager *sharedCaptureManager = [MTLCaptureManager sharedCaptureManager];
id<MTLCaptureScope> myCaptureScope = [sharedCaptureManager newCaptureScopeWithDevice:_device];

Define Capture Boundaries

Call beginScope 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 endScope.

// Create _myCaptureScope outside of your rendering loop. 
[_myCaptureScope beginScope];
id<MTLCommandBuffer> commandBuffer = [_commandQueue commandBuffer];
// Do Metal work
[commandBuffer commit];
[_myCaptureScope endScope];

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.

Make a Custom Capture Scope the Default

When you capture a frame, Xcode uses the capture scope that's currently 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 presentDrawable: or present.

You can make a custom capture scope the default by creating a MTLCaptureScope and assigning it to the shared defaultCaptureScope property of MTLCaptureManager.

sharedCaptureManager.defaultCaptureScope = myCaptureScope;

Topics

Defining Capture Scope Boundaries

- beginScope

Marks the beginning boundary of a capture scope.

Required.

- endScope

Marks the ending boundary of a capture scope.

Required.

Identifying the Capture Scope

label

A string that identifies this object.

Required.

device

The device from which the capture scope was created.

Required.

commandQueue

The command queue from which the capture scope was created.

Required.

Relationships

Inherits From

See Also

Capturing a Frame Programmatically

Capturing a Frame Programmatically

Invoke the Metal frame debugger from your app under the specific runtime conditions you choose.

MTLCaptureManager

An object you use to capture customized frame data in your app.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software