summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNiels Martin Hansen <nielsm@indvikleren.dk>2018-10-27 18:04:40 +0200
committerNiels Martin Hansen <nielsm@indvikleren.dk>2018-11-25 00:49:33 +0100
commitcb1fcc4765bae30e818f8c3c25e33c6e51273d8c (patch)
tree75d5354e0b798c6608c285585c6bccc401d17e6c
parent1ee20fac9a73e72c07b42fcab87a6b7eb7d9113b (diff)
downloadopenttd-cb1fcc4765bae30e818f8c3c25e33c6e51273d8c.tar.xz
Doc: More notes for developers adding new PerformanceElements
-rw-r--r--src/framerate_gui.cpp54
-rw-r--r--src/framerate_type.h37
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;