DebugHud and Profiling

Profiling is a form of dynamic program analysis that measures, for example, the space (memory) or time complexity of a program, the usage of particular instructions, or the frequency and duration of function calls.
https://en.wikipedia.org/wiki/Profiling_%28computer_programming%29

Urho3D features DebugHud, an inbuilt utility for profiling, measuring and displaying scene, memory or other runtime statistics. To see DebugHud in action use F2 and F3 on Urho3D’s samples.

DebugHud is split into three different sections:

1. Scene Statistics (STATS): Displays information related to the loaded scene such as triangles, viewports, lights, etc.
2. Render Statistics (MODE): Displays information related to the renderer’s settings, such as Texture quality, Shadow Map quality, Backend Graphics API, etc.
3. The Profiler (PROFILER or MEMORY): Depending on the mode, it will show either function statistics or memory consumption statistics. When in function mode, functions will be displayed hierarchically.

Using DebugHud

Initializing DebugHud

In order to use DebugHud, we must first initialize it.

#include <Urho3D/Engine/DebugHud.h>
void Start() {
  ...
  // Get default style
  ResourceCache* cache = GetSubsystem<ResourceCache>();
  XMLFile* xmlFile = cache->GetResource<XMLFile ("UI/DefaultStyle.xml");

  // Create debug HUD.
  DebugHud* debugHud = engine_->CreateDebugHud();
  debugHud->SetDefaultStyle(xmlFile);
  ...
}

Setting DebugHud’s mode

DebugHud’s sections can be toggled by using its SetMode(uint Mode) function.

The available modes are defined in Urho3D/Engine/DebugHud.h as:

static const unsigned DEBUGHUD_SHOW_NONE = 0x0;
static const unsigned DEBUGHUD_SHOW_STATS = 0x1;
static const unsigned DEBUGHUD_SHOW_MODE = 0x2;
static const unsigned DEBUGHUD_SHOW_PROFILER = 0x4;
static const unsigned DEBUGHUD_SHOW_MEMORY = 0x8;
static const unsigned DEBUGHUD_SHOW_ALL = 0x7;
static const unsigned DEBUGHUD_SHOW_ALL_MEMORY = 0xB;

As the numbering suggests, these modes can be combined. For example, DEBUGHUD_SHOW_ALL displays STATS, MODE and PROFILER. Using 0x3 would just display STATS and MODE.

We then can then toggle DebugHud as follows:

void HandleKeyDebug(StringHash /*eventType*/, VariantMap& eventData)
{
  DebugHud* debugHud = GetSubsystem<DebugHud>();
  if (debugHud->GetMode() != DEBUGHUD_SHOW_ALL)  // if not in SHOW_ALL mode
      debugHud->SetMode(DEBUGHUD_SHOW_ALL);      // set it to DEBUGHUD_SHOW_ALL
  else
      debugHud->SetMode(DEBUGHUD_SHOW_NONE);     // else hide the DebugHud
}

Using DebugHud's profiler

We can add a function into the profiler using the URHO3D_PROFILE() macro.

#include <Urho3D/Core/Profiler.h>
...
URHO3D_PROFILE(myFunction);

DebugHud's modes

DEBUGHUD_SHOW_STATS

DEBUGHUD_SHOW_MODE

DEBUGHUD_SHOW_PROFILER

DEBUGHUD_SHOW_MEMORY

DEBUGHUD_SHOW_ALL

DEBUGHUD_SHOW_ALL_MEMORY