--- title: Customizing the Metal Performance HUD framework: xcode role: article role_heading: Article path: xcode/customizing-metal-performance-hud --- # Customizing the Metal Performance HUD Modify the appearance of your Metal heads-up display to monitor your graphics performance. ## Overview Overview You can customize the appearance of the Metal Performance HUD in a variety of ways, including its size and opacity, or change the metrics that appear in the overlay. In macOS, you can export the HUD settings and apply them to your app at launch. Customize the Metal Performance HUD on macOS When you enable the Metal Performance HUD in your app, the HUD adds a new Metal HUD menu to the menu bar. The Metal HUD menu provides a quick way to configure the HUD, create performance reports (see Generating performance reports with the Metal Performance HUD), and access the configuration panel. note: You can also open the configuration panel by triple-clicking the HUD overlay. The configuration panel is where you can fully customize the HUD. You can enable or disable various features in the HUD panel, such as encoder GPU time tracking (see Monitoring your Metal app’s graphics performance), or adjust the overlay’s opacity, scale, and position. In the Metrics panel, you can see the list of available metrics in the overlay. To learn more about these metrics, see Understanding the Metal Performance HUD metrics. In the Insights panel, enable the performance insights feature to help you find potential performance issues. This feature tracks the usage of the Metal API and highlights potential bottlenecks. To learn more, see Gaining performance insights with the Metal Performance HUD. Customize the Metal Performance HUD on a device You can customize the Metal Performance HUD and logging on an iOS or iPadOS device in the Developer settings by following these steps: Open the Settings app. Select Developer. Under Graphics HUD, click Graphics HUD to access the settings. The following screenshot shows the options in iOS: important: These settings apply to all apps that enable the Metal Performance HUD. You can use environment variables to override the settings when debugging from Xcode. Customize the Metal Performance HUD programmatically You can customize the Metal Performance HUD programmatically by configuring the CAMetalLayer instance’s developerHUDProperties dictionary with the following: myMetalLayer.developerHUDProperties = [ "mode": "default", "logging": "default", "positionX": 0, "positionY": 0, // ... ] | | | | | | | | | | Additionally, you can add various effects by setting environment variables that the HUD supports in the dictionary, including: Save and load the Metal Performance HUD configuration You can save your custom Metal Performance HUD configuration by clicking the Export HUD Configuration button in the configuration panel. The configuration file is a property list file containing key-value pairs of environment variables, and you can pass it into the HUD by setting the MTL_HUD_CONFIG_FILE environment variable. export MTL_HUD_CONFIG_FILE= Alternatively, you can use the Copy HUD Configuration option in the Metal HUD menu, which exports the current state of the HUD with a list of environment variables that you can pass to your app at launch. ## See Also ### Runtime diagnostics - [Inspecting live resources at runtime](xcode/inspecting-live-resources-at-runtime.md) - [Validating your app’s Metal API usage](xcode/validating-your-apps-metal-api-usage.md) - [Validating your app’s Metal shader usage](xcode/validating-your-apps-metal-shader-usage.md) - [Monitoring your Metal app’s graphics performance](xcode/monitoring-your-metal-apps-graphics-performance.md) - [Understanding the Metal Performance HUD metrics](xcode/understanding-metal-performance-hud-metrics.md) - [Gaining performance insights with the Metal Performance HUD](xcode/gaining-performance-insights-with-metal-performance-hud.md) - [Generating performance reports with the Metal Performance HUD](xcode/generating-performance-reports-with-metal-performance-hud.md)