Difference between revisions of "Profiling"

From OpenMW Wiki
Jump to navigation Jump to search
(Created page with "Applies to OpenMW 0.33 and later. == General notes == Make sure to profile with a '''save-game''', rather than a fresh game using --skip-menu. This is very important because...")
 
(rewrite)
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
Applies to OpenMW 0.33 and later.
This page describes the built in profiling tools and the best practices to using them. Profiling is helpful to get an idea of how the engine works and to troubleshoot performance issues with specific systems or mods.  


== General notes ==
If you have come to this page because you were asked to include profiling output in a bug report, the simple way is this: Press F3 three times and F4 once to show the most useful output, then take a screenshot.


Make sure to profile with a '''save-game''', rather than a fresh game using --skip-menu. This is very important because the number of actors in the scene depends on random factors - for example levelled creature spawns. Saving the game ensures that these parameters stay the same.
For the full explanation, read on below.


== Components ==
= OpenSceneGraph profiler =


The main bottlenecks are expected in the graphics, physics and script components. We can roughly measure their impact by enabling or disabling them.
The F3 key cycles between a combination of different profiling panels. These are, in order:


Neither of the following measurements are perfectly accurate and should be taken with a grain of salt. Use of an actual profiling application should be preferred, but real time instruments can give you a good first overview.
* FPS counter
* Profiler
* Camera statistics
* Scene statistics


=== Scripts ===
To display all panels up to the <i>n</i>-th one from the above list, press the key <i>n</i> times. To remove all output from the screen, press F3 until all panels are visible then press it once more.


Enable the main menu (Esc) to pause script executions. Enabling other menus (eg inventory) may also reduce the impact, because some scripts have an "if (menuMode) return" type statement, but this can not be relied on.
== FPS count ==


=== Graphics ===
FPS (Frames per second) count should be self explanatory. Some users prefer to play with the FPS counter enabled.


Use the ''toggleWorld'' script instruction to disable world rendering. This removes the bottleneck from number of batches and overdraw, but does not stop update of the scene graph.
== Profiler ==


=== Physics ===
The profiler shows how long in milliseconds the different components of the frame update have taken.


Use the F10 key to show the bullet physics profiler.
Let's start with the meaning of the colored phases:


Physics will be disabled while the game is paused (either via main menu, or any other active GUI window).
* <b><font color="green">Update</font></b>: Runs the update callback for each node in the scene graph. OpenMW uses these callbacks for animations, for example.
* <b><font color="cyan">Cull</font></b>: Culling refers to discarding off-screen objects then passing the actually visible ones on to the render queue. OpenMW additionally uses this phase for any tasks that need doing for each visible object, e.g. updating its animations and lights.
* <b><font color="yellow">Draw</font></b>: Submits the OpenGL calls collected by the Cull phase to your graphics driver. The Draw phase runs in a separate thread, so don't be surprised if its bar overlaps the other bars.
* <b><font color="orange">GPU</font></b>: This final stage represents the actual rendering as it happens on your graphics card. The process is mostly a black box, but thanks to inserting a timer we can see when it starts and ends.
 
The white bars on the other hand measure non-rendering, OpenMW-specific game logic:
 
* <b>Script</b> (MWScript): Executes scripts attached to game objects or global scripts.
* <b>Mechanics</b> (MWMechanics): Updates actor AI, spells and animations.
* <b>Physics</b> (MWWorld): Updates the world; the most costly portion of this is usually the collision detection for actor movements.
 
=== Conclusions ===
 
If one of these phases appears completely out of whack, that should give you an idea as to how to improve the performance. For example, excessive Physics calculations are often related to mods using overly complex collision geometry or poorly placed NPCs that intersect with their environment. You may want to use the 'disable' console command to find the offending object(s).
 
The profiler will also give you an idea if your game is CPU limited or GPU limited. If you notice the <b><font color="orange">GPU</font></b> thread is idle some or most of the time, that means your frame rate is limited by your CPU. For a game like Morrowind, this is normal, and nothing to worry about. If you feel like stressing your system more, you can turn up the resolution, enable anti-aliasing, per-pixel lighting, or install high-res textures. As long as you are still CPU limited overall, these features will not reduce your frame rate at all.
 
== Camera statistics ==
 
This panel shows the count of different types of scene graph objects contained in the current view. These counters can be a good indication of how [[Rendering_Architecture#Optimizer|optimized]] your visual assets are because you want to keep the number of Drawables and State Graphs as low as possible. Consider reusing textures and materials so that meshes can be combined together for more efficient rendering. The original game with its massive number of different textures is unfortunately not a very good example of this, but there is a promising [https://www.nexusmods.com/morrowind/mods/45384 mod] in development that improves its performance. Using too many lights in a scene can also prevent state sharing and hence reduce performance. Tip: select an object in the console and type 'showSceneGraph' to see what the optimizer made of it.
 
== Scene statistics ==
 
Similar to the Camera statistics, but for the whole scene, including off-screen objects.
 
<b>This panel causes a big performance hit while enabled, so do not leave it on if you are investigating the frame rate!</b>
 
= Resource statistics =
 
This OpenMW-specific panel, toggled with the F4 key, can be useful to see the effects of different [https://openmw.readthedocs.io/en/stable/reference/modding/settings/cells.html#preload-enabled preloading settings] or to investigate why you might be experiencing stutters, hickups or whatever else you want to call a momentary reduction in frame rate.
 
The <i>WorkThread</i> counter will flip to 1 while preloading is happening, and the other numbers show how many of each type of resource are currently (pre)loaded.
 
The <i>Composite</i> counter is only active if [https://openmw.readthedocs.io/en/stable/reference/modding/settings/terrain.html#distant-terrain Distant Terrain] is enabled, and refers to distant terrain textures that have yet to be rendered. Depending on your system, you might notice stuttering if you abruptly turn the camera while this counter is not down to 0 yet. If this bothers you, try reducing the [https://openmw.readthedocs.io/en/master/reference/modding/settings/cells.html#target-framerate target framerate] (to be added in OpenMW 0.44).
 
= Physics profiler =
 
If you determined that Physics are a bottleneck, you may want to press the F10 key to bring up the Bullet Physics profiler. The output will probably not make any sense if you're not familiar with Bullet, so it will not be explained here.
 
= Log / config files =
 
Although not technically a profiling tool, the [[Paths|openmw.log]] file should be mentioned here because it is often overlooked and any errors displayed therein may be connected to performance problems. This especially applies to errors that continuously print every frame because the error printing itself can be costly.
 
Likewise, if you have manually tweaked your settings.cfg, then try to revert it to the default to see if that helps because many of its advanced options can easily wreck the frame rate if used improperly.
 
= Reproducibility =
 
Once you have located a performance issue, you will probably want to make some changes and see how much of a difference those changes make.
 
In the interest of accuracy, there are a few things you could do to ensure comparable results on subsequent runs.
 
For example, you might want to profile with a saved game instead of a fresh game from --skip-menu. This is because the number of actors in the scene depends on random creature spawns, and starting a new game would randomize those anew.
 
You can also use the ToggleAi console command to stop actors from randomly wandering around. Walking actors are more costly to process than idle ones, so disabling this alleviates randomness from the profiling results.

Latest revision as of 00:04, 10 March 2018

This page describes the built in profiling tools and the best practices to using them. Profiling is helpful to get an idea of how the engine works and to troubleshoot performance issues with specific systems or mods.

If you have come to this page because you were asked to include profiling output in a bug report, the simple way is this: Press F3 three times and F4 once to show the most useful output, then take a screenshot.

For the full explanation, read on below.

OpenSceneGraph profiler[edit]

The F3 key cycles between a combination of different profiling panels. These are, in order:

  • FPS counter
  • Profiler
  • Camera statistics
  • Scene statistics

To display all panels up to the n-th one from the above list, press the key n times. To remove all output from the screen, press F3 until all panels are visible then press it once more.

FPS count[edit]

FPS (Frames per second) count should be self explanatory. Some users prefer to play with the FPS counter enabled.

Profiler[edit]

The profiler shows how long in milliseconds the different components of the frame update have taken.

Let's start with the meaning of the colored phases:

  • Update: Runs the update callback for each node in the scene graph. OpenMW uses these callbacks for animations, for example.
  • Cull: Culling refers to discarding off-screen objects then passing the actually visible ones on to the render queue. OpenMW additionally uses this phase for any tasks that need doing for each visible object, e.g. updating its animations and lights.
  • Draw: Submits the OpenGL calls collected by the Cull phase to your graphics driver. The Draw phase runs in a separate thread, so don't be surprised if its bar overlaps the other bars.
  • GPU: This final stage represents the actual rendering as it happens on your graphics card. The process is mostly a black box, but thanks to inserting a timer we can see when it starts and ends.

The white bars on the other hand measure non-rendering, OpenMW-specific game logic:

  • Script (MWScript): Executes scripts attached to game objects or global scripts.
  • Mechanics (MWMechanics): Updates actor AI, spells and animations.
  • Physics (MWWorld): Updates the world; the most costly portion of this is usually the collision detection for actor movements.

Conclusions[edit]

If one of these phases appears completely out of whack, that should give you an idea as to how to improve the performance. For example, excessive Physics calculations are often related to mods using overly complex collision geometry or poorly placed NPCs that intersect with their environment. You may want to use the 'disable' console command to find the offending object(s).

The profiler will also give you an idea if your game is CPU limited or GPU limited. If you notice the GPU thread is idle some or most of the time, that means your frame rate is limited by your CPU. For a game like Morrowind, this is normal, and nothing to worry about. If you feel like stressing your system more, you can turn up the resolution, enable anti-aliasing, per-pixel lighting, or install high-res textures. As long as you are still CPU limited overall, these features will not reduce your frame rate at all.

Camera statistics[edit]

This panel shows the count of different types of scene graph objects contained in the current view. These counters can be a good indication of how optimized your visual assets are because you want to keep the number of Drawables and State Graphs as low as possible. Consider reusing textures and materials so that meshes can be combined together for more efficient rendering. The original game with its massive number of different textures is unfortunately not a very good example of this, but there is a promising mod in development that improves its performance. Using too many lights in a scene can also prevent state sharing and hence reduce performance. Tip: select an object in the console and type 'showSceneGraph' to see what the optimizer made of it.

Scene statistics[edit]

Similar to the Camera statistics, but for the whole scene, including off-screen objects.

This panel causes a big performance hit while enabled, so do not leave it on if you are investigating the frame rate!

Resource statistics[edit]

This OpenMW-specific panel, toggled with the F4 key, can be useful to see the effects of different preloading settings or to investigate why you might be experiencing stutters, hickups or whatever else you want to call a momentary reduction in frame rate.

The WorkThread counter will flip to 1 while preloading is happening, and the other numbers show how many of each type of resource are currently (pre)loaded.

The Composite counter is only active if Distant Terrain is enabled, and refers to distant terrain textures that have yet to be rendered. Depending on your system, you might notice stuttering if you abruptly turn the camera while this counter is not down to 0 yet. If this bothers you, try reducing the target framerate (to be added in OpenMW 0.44).

Physics profiler[edit]

If you determined that Physics are a bottleneck, you may want to press the F10 key to bring up the Bullet Physics profiler. The output will probably not make any sense if you're not familiar with Bullet, so it will not be explained here.

Log / config files[edit]

Although not technically a profiling tool, the openmw.log file should be mentioned here because it is often overlooked and any errors displayed therein may be connected to performance problems. This especially applies to errors that continuously print every frame because the error printing itself can be costly.

Likewise, if you have manually tweaked your settings.cfg, then try to revert it to the default to see if that helps because many of its advanced options can easily wreck the frame rate if used improperly.

Reproducibility[edit]

Once you have located a performance issue, you will probably want to make some changes and see how much of a difference those changes make.

In the interest of accuracy, there are a few things you could do to ensure comparable results on subsequent runs.

For example, you might want to profile with a saved game instead of a fresh game from --skip-menu. This is because the number of actors in the scene depends on random creature spawns, and starting a new game would randomize those anew.

You can also use the ToggleAi console command to stop actors from randomly wandering around. Walking actors are more costly to process than idle ones, so disabling this alleviates randomness from the profiling results.