Invoke Metal’s frame capture from your app under the specific runtime conditions you choose.
MTLCapture to programmatically capture information about commands sent to a specific device object. Depending on the runtime conditions you choose to stop the capture, it enables you to capture a specific frame, just a part of a frame, implement a custom UI to trigger a capture, or programmatically trigger capture when certain conditions occur.
To start a capture, create a
MTLCapture object that defines which commands you want to record and what should happen after the capture is complete. By default, when you stop capturing data, Xcode halts your app and presents its results in the Metal frame debugger.
Capture a Device or Command Queue
To start capturing commands for a specific
MTLCommand, set the capture descriptor's
capture property to point at the specific object to track, and call the
start method. To stop capturing commands, call the
The capture manager captures commands only within
MTLCommand objects that are created after the capture starts and are committed before the capture stops.
Capture a Custom Scope
To capture commands using a custom scope, create a
MTLCapture object and set the capture descriptor's
capture property to point to it. To define boundaries for the scoped capture, call the
end() methods just before and after the commands that you want to capture. The capture stops when your app reaches the corresponding
end() method of the given capture scope.
The capture scope only captures commands within
MTLCommand objects that are created after the scope begins and are committed before the scope ends.
Capture Multiple Frames
When you capture a frame programmatically, you can capture Metal commands that span multiple frames by using a custom capture scope. For example, by calling
begin() at the start of frame 1 and
end() after frame 3, the trace will contain command data from all the buffers that were committed in the three frames.
Capture GPU Command Data to a File
Instead of launching the Xcode frame debugger, you can also save GPU command information to a file for later analysis. Test to make sure the feature is available before attempting to record a trace file. Then, set the capture descriptor's
destination property to
MTLCapture and specify the file's destination. The file must have a file extension of
When you stop capturing data, Metal writes the trace to the file, and then continues executing your app. Open a trace file at a later time to launch Xcode and replay the trace.
You can record multiple traces in a single launch of your app, although not at the same time.