src/framerate_type.h

   1 /*
   2 * This file is part of OpenTTD.
   3 * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   4 * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   5 * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   6 */
   7
   8 /** @file framerate_type.h
   9  * Types for recording game performance data.
  10  *
  11  * @par Adding new measurements
  12  * Adding a new measurement requires multiple steps, which are outlined here.
  13  * The first thing to do is add a new member of the #PerformanceElement enum.
  14  * It must be added before \c PFE_MAX and should be added in a logical place.
  15  * For example, an element of the game loop would be added next to the other game loop elements, and a rendering element next to the other rendering elements.
  16  *
  17  * @par
  18  * Second is adding a member to the \link anonymous_namespace{framerate_gui.cpp}::_pf_data _pf_data \endlink array, in the same position as the new #PerformanceElement member.
  19  *
  20  * @par
  21  * Third is adding strings for the new element. There is an array in #ConPrintFramerate with strings used for the console command.
  22  * Additionally, there are two sets of strings in \c english.txt for two GUI uses, also in the #PerformanceElement order.
  23  * Search for \c STR_FRAMERATE_GAMELOOP and \c STR_FRAMETIME_CAPTION_GAMELOOP in \c english.txt to find those.
  24  *
  25  * @par
  26  * Last is actually adding the measurements. There are two ways to measure, either one-shot (a single function/block handling all processing),
  27  * or as an accumulated element (multiple functions/blocks that need to be summed across each frame/tick).
  28  * Use either the PerformanceMeasurer or the PerformanceAccumulator class respectively for the two cases.
  29  * Either class is used by instantiating an object of it at the beginning of the block to be measured, so it auto-destructs at the end of the block.
  30  * For PerformanceAccumulator, make sure to also call PerformanceAccumulator::Reset once at the beginning of a new frame. Usually the StateGameLoop function is appropriate for this.
  31  *
  32  * @see framerate_gui.cpp for implementation
  33  */
  34
  35 #ifndef FRAMERATE_TYPE_H
  36 #define FRAMERATE_TYPE_H
  37
  38 #include "stdafx.h"
  39 #include "core/enum_type.hpp"
  40
  41 /**
  42  * Elements of game performance that can be measured.
  43  *
  44  * @note When adding new elements here, make sure to also update all other locations depending on the length and order of this enum.
  45  * See <em>Adding new measurements</em> above.
  46  */
  47 enum PerformanceElement {
  48         PFE_FIRST = 0,
  49         PFE_GAMELOOP = 0,  ///< Speed of gameloop processing.
  50         PFE_GL_ECONOMY,    ///< Time spent processing cargo movement
  51         PFE_GL_TRAINS,     ///< Time spent processing trains
  52         PFE_GL_ROADVEHS,   ///< Time spend processing road vehicles
  53         PFE_GL_SHIPS,      ///< Time spent processing ships
  54         PFE_GL_AIRCRAFT,   ///< Time spent processing aircraft
  55         PFE_GL_LANDSCAPE,  ///< Time spent processing other world features
  56         PFE_GL_LINKGRAPH,  ///< Time spent waiting for link graph background jobs
  57         PFE_DRAWING,       ///< Speed of drawing world and GUI.
  58         PFE_DRAWWORLD,     ///< Time spent drawing world viewports in GUI
  59         PFE_VIDEO,         ///< Speed of painting drawn video buffer.
  60         PFE_SOUND,         ///< Speed of mixing audio samples
  61         PFE_ALLSCRIPTS,    ///< Sum of all GS/AI scripts
  62         PFE_GAMESCRIPT,    ///< Game script execution
  63         PFE_AI0,           ///< AI execution for player slot 1
  64         PFE_AI1,           ///< AI execution for player slot 2
  65         PFE_AI2,           ///< AI execution for player slot 3
  66         PFE_AI3,           ///< AI execution for player slot 4
  67         PFE_AI4,           ///< AI execution for player slot 5
  68         PFE_AI5,           ///< AI execution for player slot 6
  69         PFE_AI6,           ///< AI execution for player slot 7
  70         PFE_AI7,           ///< AI execution for player slot 8
  71         PFE_AI8,           ///< AI execution for player slot 9
  72         PFE_AI9,           ///< AI execution for player slot 10
  73         PFE_AI10,          ///< AI execution for player slot 11
  74         PFE_AI11,          ///< AI execution for player slot 12
  75         PFE_AI12,          ///< AI execution for player slot 13
  76         PFE_AI13,          ///< AI execution for player slot 14
  77         PFE_AI14,          ///< AI execution for player slot 15
  78         PFE_MAX,           ///< End of enum, must be last.
  79 };
  80 DECLARE_POSTFIX_INCREMENT(PerformanceElement)
  81
  82 /** Type used to hold a performance timing measurement */
  83 typedef uint64 TimingMeasurement;
  84
  85 /**
  86  * RAII class for measuring simple elements of performance.
  87  * Construct an object with the appropriate element parameter when processing begins,
  88  * time is automatically taken when the object goes out of scope again.
  89  *
  90  * Call Paused at the start of a frame if the processing of this element is paused.
  91  */
  92 class PerformanceMeasurer {
  93         PerformanceElement elem;
  94         TimingMeasurement start_time;
  95 public:
  96         PerformanceMeasurer(PerformanceElement elem);
  97         ~PerformanceMeasurer();
  98         void SetExpectedRate(double rate);
  99         static void SetInactive(PerformanceElement elem);
 100         static void Paused(PerformanceElement elem);
 101 };
 102
 103 /**
 104  * RAII class for measuring multi-step elements of performance.
 105  * At the beginning of a frame, call Reset on the element, then construct an object in the scope where
 106  * each processing cycle happens. The measurements are summed between resets.
 107  *
 108  * Usually StateGameLoop is an appropriate function to place Reset calls in, but for elements with
 109  * more isolated scopes it can also be appropriate to Reset somewhere else.
 110  * An example is the CallVehicleTicks function where all the vehicle type elements are reset.
 111  *
 112  * The PerformanceMeasurer::Paused function can also be used with elements otherwise measured with this class.
 113  */
 114 class PerformanceAccumulator {
 115         PerformanceElement elem;
 116         TimingMeasurement start_time;
 117 public:
 118         PerformanceAccumulator(PerformanceElement elem);
 119         ~PerformanceAccumulator();
 120         static void Reset(PerformanceElement elem);
 121 };
 122
 123 void ShowFramerateWindow();
 124
 125 #endif /* FRAMERATE_TYPE_H */