The default view of the HUD looks like the image below:
Within the default viewing profile of the HUD are some of its main components. Follow the components in the image below as they appear from left to right across the top of the HUD:
Draw indicator: located at the top left corner. Each time a frame is drawn, the indicator ‘spins’. When not animating, the indicator will normally spin slowly as the HUD itself in drawn, as in this animation:
If something is causing each frame to re-render, the indicator will instead look like this animation:
When the draw indicator spins this fast, and no animations are running, it indicates a problem that may be impacting battery life on mobile devices. If the draw indicator does not spin at all, the app may be frozen.
Miss count: next to the frame time is the miss count. This tracks the number of frames whose frame time was longer than 16.6 milliseconds since the app was started. Missed frames result in a poor user experience, so this number should be kept low as possible.
Frames Per Second (FPS): at the far right of the HUD. This is calculated from the beginning of one frame to the beginning of the next. Typically, this value would be capped at 60.
The frame, update, draw, swap and FPS values represent the worst value gathered from the previous three seconds, rather than being an average value. This helps ensure that any issues with playback aren’t missed.
The sum of the update, draw and swap values may not add up to the reported frame time, as each value is the maximum over three seconds, and each value may have been taken at a different time within that three second window.
The HUD also includes a bottom bar:
This portion of the HUD displays the version of You.i Platform that the app was built with.
This also includes the git commit from which the Engine was built.
After this, the optional app version is displayed.
You can set this by calling
If no version is set, this field does not appear.
The last marker displayed is a DEBug/RELease indicator.
This shows whether an app was built in debug or in release mode.
Typically, the HUD isn’t displayed in release builds, but it can be enabled through user code by calling
SetHUDVisibility(true); in the app’s
You.i TV recommends that you use release builds when doing performance profiling or measurements as there can be significant performance differences between debug and release builds.
The HUD has built-in support for more metrics than what can be displayed by default. Through the Dev Panel, you can turn different items on and off. To access the Dev Panel HUD sub-menu, use the small ? button on to the right of the Toggle HUD button.
Because the list of items that can be toggled is extensive, the Dev Panel provides HUD profiles. The profiles can be cycled through by clicking the Preset button in the Dev Panel.
This profile is the one selected by the Dev Panel and includes the components previously mentioned.
Detailed Profile: The Detailed profile shows the same information as the Default profile, but with more details. Specifically, the minimum and average values for each metric are displayed along with the maximum value; all of these values are calculated over a three-second window. This provides a more complete picture of your app’s performance. This extra information is withheld from the Default profile, as it can make the panel appear too busy.
The Resources profile shows the same information as the Default profile, but also shows CPU, memory and GPU information. Values are calculated over a one-second window.
The first added value in the display is the system CPU usage. The displayed value is normalized so that 100% represents one CPU core being fully utilized, 200% represents two CPU cores being fully utilized, and so on. To the right of the system CPU usage is a set of graphs displaying the CPU usage for each CPU core. On some platforms, the per-CPU usage is not available, and one large graph is shown instead:
To the right of the system CPU usage is the Process CPU usage. This shows the amount of CPU time used by the app. As with the system CPU usage, a value of 100% indicates that one core is fully utilized. To the right of the Process CPU usage is the GPU utilization. This is a value between 0% and 100% indicating how much ‘work’ the GPU is doing. As this metric is only available on macOS, it is hidden on other platforms.
The next value displayed are the memory usage metrics. First is the system memory utilization, both used and total.
To the right is displayed the process memory usage.
This value generally excludes the memory used by shared libraries.
On Android, this value also includes the memory used by the Java heap.
On some platforms, this value includes the memory used by the GPU.
If that’s the case, the label will say
Proc^: instead of
Finally we have the GPU memory usage. On all platforms, this is an approximated value based on the assets loaded in the asset manager (as indicated by the ~ in the label). Some platforms support showing the total amount of available GPU memory; apps generally won’t use the full amount, as the system that the app is running on will typically require a portion of the GPU memory to run itself.
Most of these resource values are available on all platforms, with a few exceptions:
Fetching memory, CPU usage, and GPU usage can be computationally-intensive, and can affect the app’s performance.
The Text profile, as the name suggests, displays text-related information. Like the Resources profile, it shows the same data as the Default profile, but with extra fields.
This profile shows percentage utilization for the ‘regular’ text atlas, and for the SDF text atlas. If either of those atlases have not been initialized, N/A is displayed.
The Legacy profile shows the data from the previous FPS bar. This can be useful when looking to compare performance metrics across releases.
In the Legacy profile, the values are averages calculated over the last 10 frames. This can result in overstated performance values when scenes do not require a redraw.
The HUD content can be changed by selecting a different profile in the Dev Panel, or by toggling a specific section in the HUD Dev Panel widget.
The HUD can also be configured programmatically.
For example, while profiling an app’s memory usage, a user might want to enable displaying the process memory.
This can be done like this from the app’s
Other constants to enable or disable other sections can be viewed in the
To display custom data on the HUD, the following code can be used:
That function is static, so no reference to the HUD is required (though an
#include "debug/YiHud.h” may be needed).
This is useful if you need to quickly show debugging information on the screen.
More adventurous users can write custom HUD sections to add new content.
Simply subclass from
CYIHud::Section, and add a section instance to the HUD (accessible using
New HUD bars can also be added to the HUD, and aligned to any of the screen’s corners.