Discover Metal Performance HUD

Hi, my name is Nat Brown, and I manage a team of engineers working on game technologies at Apple.

Today I'd like to tell you about the heads-up display for watching and collecting key real-time graphic statistics in your applications and games.

Let's take a look at the Metal Performance HUD.

When enabled, it will appear as an overlay in the upper right-hand corner of your application.

Its purpose is to help you and your testers easily spot potential performance problems and to log some basic information for later analysis.

The HUD is a complement to and not a replacement for your existing debugging and performance analysis tools, one that helps you get useful information from quality assurance teams and customers with just screenshots and logs helping you more quickly reproduce, analyze, and fix hard-to-reproduce performance problems and graphics glitches.

Let's take a look at what data the HUD shows and can collect.

The top line of the HUD shows you information about the GPU and the display, the device being used, the resolution being targeted, and the scaling state of the display.

The HUD shows you whether you are in the direct or composited path of the display.

The direct path has the least buffering and the fewest number of refresh intervals between when you present your drawable and when it appears on the screen.

When you are composited, there may be some additional buffering and display latency due to system UI elements or your own additional layers overlapping the screen.

You're also going to see the maximum refresh rate of the physical display being used.

For variable refresh rate displays, you will also see the minimum refresh rate of the display, so you'll see the possible refresh rate ranges that are available.

Next, the first column of the real-time data shows the instantaneous frame rate in Hertz or frames per second, then the pretime, or the time between your presents, also known as the frame time or frame interval in milliseconds.

And finally, the amount of GPU work that was completed in the frame interval also measured in milliseconds.

The second column shows you a bit more information about the lowest values of frame rate, frame interval, and GPU time spent in the frame over the last one and a half seconds.

The HUD highlights in red when this low value has deviated significantly from the average.

The last column of numerical data in the HUD shows you the highest instantaneous frame rate in the last one and a half seconds, the largest single frame time in the last one and a half seconds, and the highest GPU cost in milliseconds of work done in the last one and a half seconds of frame intervals.

Unusually high frame intervals and GPU time compared to the average are once again highlighted here in red.

The final section at the bottom of the HUD shows you process and GPU memory consumption information to help you spot potential leaks over time and also a dual-line graph of the present intervals and GPU time spent.

The purpose of this information is to help you and your testers spot transient frame drops which you might otherwise miss and to help you isolate your deeper testing, debugging, and performance tuning using more advanced Xcode and Instruments tools.

So how do you turn on the Metal Performance HUD? Well you might be surprised to learn that there are a lot of different ways to do it because we know there are a lot of ways developers want to interact with and automate this form of data collection.

The first is right from Xcode 14 while you're developing for iOS, macOS, or tvOS.

In your Run scheme under the Diagnostics tab, you'll see the option to turn the HUD on by choosing Show Graphics Overview and to enable logging data to the system log by choosing Log Graphics Overview.

On iOS and tvOS, if you have connected the device to Xcode and enabled it for development, you can turn on the HUD and logging using the Developer Settings.

Just go to Settings > Developer Settings, scroll down and enable the HUD and optionally logging.

On iOS and tvOS, the HUD will only show up and perform logging for your own applications; that is, applications you have installed via Xcode or using TestFlight.

On macOS, you can enable the HUD outside of Xcode through environment variables.

Set the MTL_HUD_ENABLED environment variable to one to show the HUD and set the MTL_HUD_LOGGING_ENABLED environment variable to one to trigger logging.

Another option you might find useful is using your application's user defaults.

On macOS, iOS, and tvOS, you can set the MetalForceHudEnabled key to true in your standard user defaults and the HUD will display and logging will occur for subsequent launches of your applications.

On macOS, you can set a global value to have the HUD show for all Metal-based applications.

Finally, you can add the MetalHUDEnabled key to your Info.plist to always enable the HUD.

Now if the HUD is enabled, you can use the CAMetalLayer developerHUDProperties dictionary to show and hide the HUD and to enable and disable logging.

Setting the mode key to default will show the HUD.

Clearing the key will hide the HUD.

Setting the logging key to default will enable logging.

Clearing this key will disable logging.

You might add the Info.plist key and use this API if you want to provide your testers with a UI toggle in internal builds to show and hide the HUD.

Now let's take a look at what the Metal Performance HUD logs.

About once per second the Metal Performance HUD writes data to the system log summarizing the data it is collecting so you can analyze it in your own way.

Just launch the console application and filter the output with the string metal-HUD.

Each resulting line will start with the string metal-HUD.

Next comes the first frame number, then the number of estimated frame misses.

In this case, none were missed.

Next, the process memory usage.

Here it's 56.05 megabytes.

After that are each frame's present interval and GPU time in milliseconds.

You might find all of this data useful to analyze offline or to correlate with a video you capture of gameplay to give you an even more accurate insight into where to focus additional debugging and optimization.

I hope you enjoyed learning about the Metal Performance HUD today.

Use the HUD to visualize your game's performance.

It will help you spot subtle performance issues and help you choose where to use more advanced tools like Instruments.

It's easy to enable on all Apple platforms, and you can also capture the data it logs for your own custom analysis.

I really hope you find it useful for optimizing your games and graphics applications.

If you have any feedback, be sure to send it through feedbackassistant.apple.com.

Thanks for joining me.