Microprofile

Microprofile is performance-consuming, that's why we recommend you to enable it only when you work with it and keep disabled otherwise.

One way to disable Microprofile is to untick the corresponding option before running UnigineEditor or the application:

Another way is to use the microprofile_enabled console command.

Microprofile allows saving the performance data to an HTML file and then analyzing it offline.

To output the performance data to the HTML file, perform the following:

1. In the console, set the the number of frames to be profiled via the microprofile_dump_frames console command. You can skip this step: by default, 500 frames will be profiled.
2. Run the microprofile_dump_html console command.

The performance data will be saved to the specified HTML file.

Using profiling dumps simplifies capturing performance "spikes": the engine continues rendering the application in the background even when it is out of focus, so the frame where the spike has occurred can be overwritten in case of using the Web server for performance data visualization. Also it can be used to estimate the optimization results: you can dump frames before and after optimization and compare them.

To visualize the performance data using the local web server, perform the following:

1. In the console, set the the number of frames to be profiled via the microprofile_webserver_frames console command. You can skip this step: by default, 200 frames will be profiled.

2. On the Menu Bar of UnigineEditor, choose Tools -> Microprofile.

   

The performance data will be displayed in your Web browser.

For example, if you specify localhost:1337/100, only the first 100 frames will be displayed.

In the Main group of the performance data, the call stack of the operations (e.g., update, rendering, etc.) performed by the engine on CPU is displayed.

In the GPU group of the performance data, the call stack of the operations performed by the engine on GPU is displayed. In addition to the main performance data, for each function (e.g. environment rendering, post materials rendering and so on), the number of DIP calls and rendered triangles is shown. Also there can be the number of surfaces, lights, shadows rendered by this function, the number of materials and shaders used; the information on the node or material for which the function is called (identifier, name, etc.).

When the region that corresponds to the certain function is pointed, the Microprofile displays when this function is called on CPU and how much time is spent on its performing.

OpenGL or DirectX commands can be combined into GPU Debug groups that are created automatically when defining a profiling scope. All graphic resources loaded from external files, such as textures, shaders, static or skinned meshes, as well as the Engine's internal resources, have their own debug names to simplify identification. This information can be useful when using Graphics API debuggers, such as NVIDIA Nsight or RenderDoc.

The performance data on the engine threads is visualized in the CPUThread, SoundThread, AsyncQueueThread, WorldSpawnMeshClutterThread, WorldSpawnGrassThread groups.

To create several nested counters, you should use the beginMicro() and endMicro() functions. beginMicro() returns an identifier that should be passed to endMicro(). This enables to create nested and intersecting profiler counters.

In the following example, combination of begin()/end() and beginMicro()/endMicro() is used. So, profiling of the AppWorldLogic::update() function will be available in both the Profiler and the Microprofile.

int AppWorldLogic::update()
{

	// start profiling
	Profiler::begin("AppWorldLogic::update");

	float time = Game::getTime();
	float angle_0 = time * 1.0f;
	float angle_1 = time * 1.5f;
	float angle_2 = time * 2.0f;

	// start profiling of the first light source (available in the Microprofile only)
	int id_0 = Profiler::beginMicro("1st Light Update");

	light_0->setWorldTransform(translate(Unigine::Math::Vec3(sinf(angle_0), cosf(angle_0), 1.0f) * 20.0f));

	// stop profiling of the first light source
	Profiler::endMicro(id_0);

	// start profiling of the second light source (available in the Microprofile only)
	int id_1 = Profiler::beginMicro("2nd Light Update");

	light_1->setWorldTransform(translate(Unigine::Math::Vec3(sinf(angle_1), cosf(angle_1), 1.0f) * 20.0f));

	// stop profiling of the second light source
	Profiler::endMicro(id_1);

	light_2->setWorldTransform(translate(Unigine::Math::Vec3(sinf(angle_2), cosf(angle_2), 1.0f) * 20.0f));

	// stop profiling
	Profiler::end();

	return 1;
}

There are special macros to mark fragments of your code that should be inspected. They can be used instead of the beginMicro() and endMicro() functions:

• UNIGINE_PROFILER_FUNCTION to inspect performance of the function.

  Using Macro	Using Functions
  Source code (C++) void myFunction() { UNIGINE_PROFILER_FUNCTION; // your function code }	Source code (C++) void myFunction() { int id = Profiler::beginMicro(__FUNCTION__); // your function code Profiler::endMicro(id); }

• UNIGINE_PROFILER_SCOPED to inspect only a certain part of the code.

  Using Macro	Using Functions
  Source code (C++) void myFunction() { // your function code { UNIGINE_PROFILER_SCOPED("Scope name"); // your function code } }	Source code (C++) void myFunction() { // your function code { int id = Profiler::beginMicro("Scope name"); // your function code Profiler::endMicro(id); } }