cpp/openttd-patchpack/source Changeset - r23060:230e0b87f745

Changeset - r23060:230e0b87f745

Parent rev.

Child rev.

[Not reviewed]

master

0 2 0

Niels Martin Hansen - 6 years ago 2018-10-27 16:04:40
nielsm@indvikleren.dk

Doc: More notes for developers adding new PerformanceElements

2 files changed with 82 insertions and 9 deletions:

src/framerate_gui.cpp

src/framerate_type.h

0 comments (0 inline, 0 general)

src/framerate_gui.cpp

➞

Show inline comments

@@ @@ -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 GetPerformanceT @@
+}
 /** 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::SetExpectedRat @@
 	_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::~PerformanceAccu @@
 	_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(Perfo @@
 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_des @@
 );
 /** @hideinitializer */
 static const NWidgetPart _frametime_graph_window_widgets[] = {
 	NWidget(NWID_HORIZONTAL),
 		NWidget(WWT_CLOSEBOX, COLOUR_GREY),
@@ @@ -758,17 +791,20 @@ static WindowDesc _frametime_graph_windo @@
 /** 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;

src/framerate_type.h

➞

Show inline comments

@@ @@ -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;

0 comments (0 inline, 0 general)