An object that defines custom boundaries for a GPU frame capture.
- iOS 11.0+
- macOS 10.13+
- UIKit for Mac 13.0+Beta
- tvOS 11.0+
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
end around the Metal calls you want the capture to include. In the case of a rendering loop, your calls to
end can capture a small part of a frame, or capture data across multiple frames.
To use your capture scope, pass it to a
start, 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
Define Capture Boundaries
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
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
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.
Make a Custom Capture Scope the Default
When you capture a frame, Xcode uses the capture scope that's currently assigned to the
default property of
MTLCapture. 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