Heads Up Display (HUD)

The default view of the HUD looks like the image below:

Components of the HUD

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.

• Frame time: to the right of the draw indicator, is the frame time. This is the sum, in milliseconds, of the update, draw and swap times. If the frame time is higher than 16.6, the app would have a reduced FPS. The displayed value is color coded: green means the frame time is good, yellow means it’s a bit too high, and red means the frame time is too high.

• 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.

• Update, Draw, Swap times: follow after the miss count. All three are displayed in milliseconds, and should be kept under 16.6 ms.
• JS value: next to swap time. This value is only displayed for React apps. It displays the amount of time spent executing JavaScript, in milliseconds. This value is already included in the Update time.

• 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.

  Note

  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 You.i Platform was built. After this, the optional app version is displayed. You can set this by calling CYIApp::SetVersion. 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 UserInit() function. 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.

Viewing HUD Profiles

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.

Default Profile

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.

Resources Profile

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 Proc:.

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:

• Tizen only supports showing the system CPU usage and memory usage (the process CPU usage and memory usage is not available).
• PS4 does not support displaying anything (well except the estimated GPU usage).
• Android devices starting at Android O do not support showing the system CPU and memory usage (though process CPU usage and memory usage is available).

Text Profile

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.

Legacy Profile

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.

Customizing the HUD

Changing the Visibility of Content

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 UserInit function:

GetHUD().SetSectionEnabled(CYIHud::PROCESS_MEMORY, true); Other constants to enable or disable other sections can be viewed in the debug/YiHud.h header.

Adding Custom Data

To display custom data on the HUD, the following code can be used:

CYIHud::SetUserText("Hello World!");

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.

Adding New Sections

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 CYIApp::GetHUD()). New HUD bars can also be added to the HUD, and aligned to any of the screen’s corners.