diff options
| -rw-r--r-- | src/framerate_gui.cpp | 54 | ||||
| -rw-r--r-- | src/framerate_type.h | 37 |
2 files changed, 82 insertions, 9 deletions
diff --git a/src/framerate_gui.cpp b/src/framerate_gui.cpp index 021958d32..4f1c0e2e1 100644 --- a/src/framerate_gui.cpp +++ b/src/framerate_gui.cpp @@ -22,11 +22,14 @@ #include "widgets/framerate_widget.h" +/** + * Private declarations for performance measurement implementation + */ namespace { /** Number of data points to keep in buffer for each performance measurement */ const int NUM_FRAMERATE_POINTS = 512; - /** Units a second is divided into in performance measurements */ + /** %Units a second is divided into in performance measurements */ const TimingMeasurement TIMESTAMP_PRECISION = 1000000; struct PerformanceData { @@ -51,8 +54,15 @@ namespace { /** Start time for current accumulation cycle */ TimingMeasurement acc_timestamp; + /** + * Initialize a data element with an expected collection rate + * @param expected_rate + * Expected number of cycles per second of the performance element. Use 1 if unknown or not relevant. + * The rate is used for highlighting slow-running elements in the GUI. + */ explicit PerformanceData(double expected_rate) : expected_rate(expected_rate), next_index(0), prev_index(0), num_valid(0) { } + /** Collect a complete measurement, given start and ending times for a processing block */ void Add(TimingMeasurement start_time, TimingMeasurement end_time) { this->durations[this->next_index] = end_time - start_time; @@ -63,6 +73,7 @@ namespace { this->num_valid = min(NUM_FRAMERATE_POINTS, this->num_valid + 1); } + /** Begin an accumulation of multiple measurements into a single value, from a given start time */ void BeginAccumulate(TimingMeasurement start_time) { this->timestamps[this->next_index] = this->acc_timestamp; @@ -76,11 +87,13 @@ namespace { this->acc_timestamp = start_time; } + /** Accumulate a period onto the current measurement */ void AddAccumulate(TimingMeasurement duration) { this->acc_duration += duration; } + /** Indicate a pause/expected discontinuity in processing the element */ void AddPause(TimingMeasurement start_time) { if (this->durations[this->prev_index] != INVALID_DURATION) { @@ -125,11 +138,11 @@ namespace { int last_point = this->next_index - this->num_valid; if (last_point < 0) last_point += NUM_FRAMERATE_POINTS; - /** Number of data points collected */ + /* Number of data points collected */ int count = 0; - /** Time of previous data point */ + /* Time of previous data point */ TimingMeasurement last = this->timestamps[point]; - /** Total duration covered by collected points */ + /* Total duration covered by collected points */ TimingMeasurement total = 0; while (point != last_point) { @@ -149,9 +162,14 @@ namespace { } }; - /** Game loop rate, cycles per second */ + /** %Game loop rate, cycles per second */ static const double GL_RATE = 1000.0 / MILLISECONDS_PER_TICK; + /** + * Storage for all performance element measurements. + * Elements are initialized with the expected rate in recorded values per second. + * @hideinitializer + */ PerformanceData _pf_data[PFE_MAX] = { PerformanceData(GL_RATE), // PFE_GAMELOOP PerformanceData(1), // PFE_ACC_GL_ECONOMY @@ -182,7 +200,10 @@ static TimingMeasurement GetPerformanceTimer() } -/** Begin a cycle of a measured element. */ +/** + * Begin a cycle of a measured element. + * @param elem The element to be measured + */ PerformanceMeasurer::PerformanceMeasurer(PerformanceElement elem) { assert(elem < PFE_MAX); @@ -203,14 +224,20 @@ void PerformanceMeasurer::SetExpectedRate(double rate) _pf_data[this->elem].expected_rate = rate; } -/** Indicate that a cycle of "pause" where no processing occurs. */ +/** + * Indicate that a cycle of "pause" where no processing occurs. + * @param elem The element not currently being processed + */ void PerformanceMeasurer::Paused(PerformanceElement elem) { _pf_data[elem].AddPause(GetPerformanceTimer()); } -/** Begin measuring one block of the accumulating value. */ +/** + * Begin measuring one block of the accumulating value. + * @param elem The element to be measured + */ PerformanceAccumulator::PerformanceAccumulator(PerformanceElement elem) { assert(elem < PFE_MAX); @@ -225,7 +252,11 @@ PerformanceAccumulator::~PerformanceAccumulator() _pf_data[this->elem].AddAccumulate(GetPerformanceTimer() - this->start_time); } -/** Store the previous accumulator value and reset for a new cycle of accumulating measurements. */ +/** + * Store the previous accumulator value and reset for a new cycle of accumulating measurements. + * @note This function must be called once per frame, otherwise measurements are not collected. + * @param elem The element to begin a new measurement cycle of + */ void PerformanceAccumulator::Reset(PerformanceElement elem) { _pf_data[elem].BeginAccumulate(GetPerformanceTimer()); @@ -235,6 +266,7 @@ void PerformanceAccumulator::Reset(PerformanceElement elem) void ShowFrametimeGraphWindow(PerformanceElement elem); +/** @hideinitializer */ static const NWidgetPart _framerate_window_widgets[] = { NWidget(NWID_HORIZONTAL), NWidget(WWT_CLOSEBOX, COLOUR_GREY), @@ -478,6 +510,7 @@ static WindowDesc _framerate_display_desc( ); +/** @hideinitializer */ static const NWidgetPart _frametime_graph_window_widgets[] = { NWidget(NWID_HORIZONTAL), NWidget(WWT_CLOSEBOX, COLOUR_GREY), @@ -758,17 +791,20 @@ static WindowDesc _frametime_graph_window_desc( +/** Open the general framerate window */ void ShowFramerateWindow() { AllocateWindowDescFront<FramerateWindow>(&_framerate_display_desc, 0); } +/** Open a graph window for a performance element */ void ShowFrametimeGraphWindow(PerformanceElement elem) { if (elem < PFE_FIRST || elem >= PFE_MAX) return; // maybe warn? AllocateWindowDescFront<FrametimeGraphWindow>(&_frametime_graph_window_desc, elem, true); } +/** Print performance statistics to game console */ void ConPrintFramerate() { const int count1 = NUM_FRAMERATE_POINTS / 8; diff --git a/src/framerate_type.h b/src/framerate_type.h index 13e7ee690..8df9a279a 100644 --- a/src/framerate_type.h +++ b/src/framerate_type.h @@ -9,6 +9,28 @@ /** @file framerate_type.h * Types for recording game performance data. + * + * @par Adding new measurements + * Adding a new measurement requires multiple steps, which are outlined here. + * The first thing to do is add a new member of the #PerformanceElement enum. + * It must be added before \c PFE_MAX and should be added in a logical place. + * 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. + * + * @par + * 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. + * + * @par + * Third is adding strings for the new element. There is an array in #ConPrintFramerate with strings used for the console command. + * Additionally, there are two sets of strings in \c english.txt for two GUI uses, also in the #PerformanceElement order. + * Search for \c STR_FRAMERATE_GAMELOOP and \c STR_FRAMETIME_CAPTION_GAMELOOP in \c english.txt to find those. + * + * @par + * Last is actually adding the measurements. There are two ways to measure, either one-shot (a single function/block handling all processing), + * or as an accumulated element (multiple functions/blocks that need to be summed across each frame/tick). + * Use either the PerformanceMeasurer or the PerformanceAccumulator class respectively for the two cases. + * 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. + * 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. + * * @see framerate_gui.cpp for implementation */ @@ -18,6 +40,12 @@ #include "stdafx.h" #include "core/enum_type.hpp" +/** + * Elements of game performance that can be measured. + * + * @note When adding new elements here, make sure to also update all other locations depending on the length and order of this enum. + * See <em>Adding new measurements</em> above. + */ enum PerformanceElement { PFE_FIRST = 0, PFE_GAMELOOP = 0, ///< Speed of gameloop processing. @@ -36,12 +64,15 @@ enum PerformanceElement { }; DECLARE_POSTFIX_INCREMENT(PerformanceElement) +/** Type used to hold a performance timing measurement */ typedef uint64 TimingMeasurement; /** * RAII class for measuring simple elements of performance. * Construct an object with the appropriate element parameter when processing begins, * time is automatically taken when the object goes out of scope again. + * + * Call Paused at the start of a frame if the processing of this element is paused. */ class PerformanceMeasurer { PerformanceElement elem; @@ -57,6 +88,12 @@ public: * RAII class for measuring multi-step elements of performance. * At the beginning of a frame, call Reset on the element, then construct an object in the scope where * each processing cycle happens. The measurements are summed between resets. + * + * Usually StateGameLoop is an appropriate function to place Reset calls in, but for elements with + * more isolated scopes it can also be appropriate to Reset somewhere else. + * An example is the CallVehicleTicks function where all the vehicle type elements are reset. + * + * The PerformanceMeasurer::Paused function can also be used with elements otherwise measured with this class. */ class PerformanceAccumulator { PerformanceElement elem; |