Converting a GPU’s counter data into a readable format

Inspect and use the data within a GPU’s counter sample buffer by resolving it into a standard format.

Overview

To use the data a GPU driver stores in an MTLCounterSampleBuffer instance (see Sampling GPU data into counter sample buffers), your app needs to resolve it. Resolving the data converts the counter data from the GPU’s internal data structure into a common format that Metal defines.

You can resolve the data in a counter sample buffer by creating a blit pass that converts the data as it copies it to an MTLBuffer. If the CPU can access a counter sample buffer, you can also resolve the data after the GPU finishes running a command buffer. See Creating a counter sample buffer to store a GPU’s counter data during a pass for information about making a CPU-accessible counter sample buffer.

Resolve the counter sample buffer with the CPU

For an MTLCounterSampleBuffer instance that you create with shared memory (see storageMode and MTLStorageMode.shared), you can resolve the data by calling its resolveCounterRange(_:) method.

You can resolve a sample counter buffer with the CPU at any time after the GPU finishes running the pass that retrieves the counter’s data. To access the data as soon as possible (with the CPU), add a completion handler to the pass’s command buffer by calling its addCompletedHandler(_:) method.

Resolve the counter sample buffer with a blit pass on the GPU

You can also resolve an MTLCounterSampleBuffer instance’s data into an MTLBuffer by running a blit pass on the GPU. For some GPUs, this technique is the only way to resolve a counter sample buffer that uses private storage (see storageMode and MTLStorageMode.private).

To resolve a sample counter buffer in a blit pass, create an MTLBlitCommandEncoder instance and call its resolveCounters(_:range:destinationBuffer:destinationOffset:) method.

Cast the counter sample’s data to a result type

Your app can inspect and use the resolved data by casting it to the result type that corresponds to the counter set.

Counter set names	Counter result types
Timestamp	Mtlcounterresulttimestamp
Stageutilization	Mtlcounterresultstageutilization
Statistic	Mtlcounterresultstatistic

For example, your app can cast the data it resolves from a timestamp counter set as an MTLCounterResultTimestamp array.

The code example above also checks whether the result type array has the correct number of elements of the counter set for the app.

Inspect the information and check for error values

You can also use the result type instances to check whether the GPU stores any error values. The following code example determines whether any of the timestamp samples are equal to 0 or a sentinel error value:

Any time the GPU encounters a runtime error while sampling a counter, it sets the counter datum to the sentinel value MTLCounterErrorValue.