List all capturable processes. When Xcode 15 or higher is running on the system, it will also display capturable processes of any remote device visible to Xcode.

List all capturable boundaries for a given PID. A boundary is an API call that is used by gpucapture as a trigger to begin/end a GPU Trace. Available boundary types:

•

Device - begins as soon as the next MTLCommandBuffer (https://developer.apple.com/documentation/metal/mtlcommandbuffer) creation is traced. It ends once the created command buffer is scheduled.

•

Queue - begins as soon as the next MTLCommandBuffer (https://developer.apple.com/documentation/metal/mtlcommandbuffer) creation is traced on the target MTLCommandQueue (https://developer.apple.com/documentation/metal/mtlcommandqueue). It ends once the created command buffer is scheduled.

•

Layer - begins when we hit the next [CAMetalDrawable present] (https://developer.apple.com/documentation/metal/mtldrawable) (or derivative present APIs) on the target CAMetalLayer (https://developer.apple.com/documentation/quartzcore/cametallayer). It ends on the next present call in the target layer.

•

Scope - begins as soon as we trace [MTLCaptureScope beginScope] (https://developer.apple.com/documentation/metal/mtlcapturescope/2869571-beginscope). It ends once we hit [MTLCaptureScope endScope] (https://developer.apple.com/documentation/metal/mtlcapturescope/2869574-endscope) on the same scope.

Begins a GPU trace capture. If no arguments are provided this command will try a default behavior equivalent to gpucapture start --boundary DEFAULT_BOUNDARY_ID --count 1.

•

if there are more than 1 capturable processes, it will require --pid PID and/or --device ID for disambiguation.

•

DEFAULT_BOUNDARY_ID value will depend on the available boundaries in the target process. If there is a valid CAMetalLayer (https://developer.apple.com/documentation/quartzcore/cametallayer) it will attempt a Layer boundary capture unless there are multiple available layers. If multiple layers are available it will fail and ask for boundary disambiguation. If no layer is available, DEFAULT_BOUNDARY_ID will do a Device boundary capture.

•

a gpucapture will end and produce a GPU Trace if either the BOUNDARY_COUNT is reached, there is a gpucapture stop or if the process exits.

Produced GPU Trace is always stored in the local device filesystem.

Ends a GPU trace capture. Options are used to help decide the scope for applying the stop command.

Any gpucapture in progress can also be stopped at any point in time via Ctrl+C

Show contextual help

Capturable process PID for command to execute, if there are multiple PID available --device ID is required for disambiguation

Target device ID for command to execute at.

BOUNDARY_ID is the identifier of the trigger to use to begin/end a GPU Trace capture.

BOUNDARY_LABEL is used to identify a boundary API object instead of BOUNDARY_ID. If multiple objects share the same BOUNDARY_LABEL, gpucapture will be unable to define the target and will request the user to use --boundary BOUNDARY_ID instead. This option is especially useful for apps that do not have deterministic resource creation (random BOUNDARY_ID) but do label their objects. Only available for Queue, Layer or Scope.

BOUNDARY_COUNT is the amount of trigger ends that should be hit by the GPU trace capture before actually stopping it.

•

when applied to a Device or Queue this count is the number of complete MTLCommandBuffers (https://developer.apple.com/documentation/metal/mtlcommandbuffer) captured.

•

when applied to a Layer this count is equivalent to the number of frames.

•

when applied to a Scope this count is equivalent to the number of [MTLCaptureScope endScope] (https://developer.apple.com/documentation/metal/mtlcapturescope/2869574-endscope) seen after the begin trigger was reached.

This option is equivalent to --count UINT_MAX. Useful for capturing CLI workloads where the amount of CommandBuffers is not known as this allows the capture to progress until the process exits. Additionally, if you aim to control the gpucapture start of the process you should launch your target with MTLCAPTURE_WAIT_FOR_SIGNAL=1, this environment variable will halt the process on MTLDevice (https://developer.apple.com/documentation/metal/mtldevice) creation until a gpucapture start signal is registered.

FILEPATH on the host machine's file system, to where the recorded .gputrace will be stored.

•

must be a directory, or a filepath ending in .gputrace

•

if no --output is provided, gpucapture will default to saving the .gputrace archive in the current working directory it was launched in

Show tool version

List available devices and exit. Shows an ID column that can be passed to --device, along with the device name, model, and OS version.

$ gpucapture list

$ gpucapture boundary --pid 12345

$ gpucapture start

$ gpucapture start --pid 12345 --boundary 3 --count 5

$ gpucapture start --pid 12345 --count 100000

$ gpucapture stop --pid 12345

$ gpucapture stop --all