[[TOC]]

= Graphics profiling =

This page aims to give an overview of the various tools available for profiling graphics part of the game (i.e. measuring speed and resource usage), and some details on how to use them.

== Frame profiling ==

=== apitrace ===

1. Install apitrace from https://apitrace.github.io/#download (analyzing scripts require Python 3)
2. Capture a trace. Currently apitrace can't capture an interval, it starts capturing from the beginning. So it makes sense to repeat the needed frame as fast as possible using a window size as small as possible (a minute capture might use few GBs).
{{{
path/to/apitrace trace --api gl --output 0ad.trace path/to/pyrogenesis [pyrogenesis arguments...]
}}}

3. Analyze the capture.
{{{
path/to/apitrace replay --headless --pframe-times --pgpu --pcpu --ppd 0ad.trace > 0ad.trace.profiling.txt
}}}
  * {{{--pframe-times}}} record frames times, waiting for presentation to finish before starting next frame.
  * {{{--pgpu}}} record GPU times for frames and draw calls.
  * {{{--pcpu}}} record CPU times for frames and draw calls.
  * {{{--ppd}}} record pixels drawn for each draw call.
  * {{{--headless}}} don't show windows.


== Graphics profiling and debugging tools ==

A list of tested tools that work or partly work for Pyrogenesis (A24).

* '''apitrace''' - a free MIT licensed stand-alone graphics debugger for OpenGL, GLES and Direct3D and the most of platforms (https://apitrace.github.io/). It supports GL >= 1.0 and GLES >= 1.0 (v9.0).
* '''RenderDoc''' - a free MIT licensed stand-alone graphics debugger for the most of graphics APIs and platforms (https://renderdoc.org/). It supports GL >= 3.2 and GLES >= 2.0 (v1.11).
* '''NVIDIA® NSight™''' - a free proprietary standalone developer tool that enables you to debug, profile, and export frames built with Direct3D, Vulkan, OpenGL and so on (https://developer.nvidia.com/nsight-graphics, https://developer.nvidia.com/nsight-visual-studio-edition). Old versions (<2020) work fine, the latest (2020.6) doesn't work: the engine crashes somewhere on a draw call in a driver.

Other lists of graphics tools (not tested or tested a long time ago):

* https://www.khronos.org/opengl/wiki/Debugging_Tools
* https://apitrace.github.io/#links