- 5.2) [Frame rate and performance metrics](#52-frame-rate-and-performance-metrics)

### 5.2) Frame rate and performance metrics

The Help menu in-game has a function to open the Frame rate window. This

window shows various real-time performance statistics, measuring what parts

of the game require the most processing power currently.

A summary of the statistics can also be retrieved from the console with the

`fps` command. This is especially useful on dedicated servers, where the

administrator might want to determine what's limiting performance in a slow

game.

The frame rate is given as two figures, the simulation rate and the graphics

frame rate. Usually these are identical, as the screen is rendered exactly

once per simulated tick, but in the future there might be support for graphics

and simulation running at different rates. When the game is paused, the

simulation rate drops to zero.

In addition to the simulation rate, a game speed factor is also calculated.

This is based on the target simulation speed, which is 30 milliseconds per

game tick. At that speed, the expected frame rate is 33.33 frames/second, and

the game speed factor is how close to that target the actual rate is. When

the game is in fast forward mode, the game speed factor shows how much

speed up is achieved.

The lower part of the window shows timing statistics for individual parts of

the game. The times shown are short-term and long-term averages of how long

it takes to process one tick of game time, all figures are in milliseconds.

Clicking a line in the lower part of the window opens a graph window, giving

detailed readings on each tick simulated by the game.

The following is an explanation of the different statistics:

- *Game loop* - Total processing time used per simulated "tick" in the game.

  This includes all pathfinding, world updates, and economy handling.

- *Cargo handling* - Time spent loading/unloading cargo at stations, and

  industries and towns sending/retrieving cargo from stations.

- *Train ticks*, *Road vehicle ticks*, *Ship ticks*, *Aircraft ticks* -

  Time spent on pathfinding and other processing for each player vehicle type.

- *World ticks* - Time spent on other world/landscape processing. This

  includes towns growing, building animations, updates of farmland and trees,

  and station rating updates.

- *Link graph delay* - Time overruns of the cargo distribution link graph

  update thread. Usually the link graph is updated in a background thread,

  but these updates need to synchronise with the main game loop occasionally,

  if the time spent on link graph updates is longer than the time taken to

  otherwise simulate the game while it was updating, these delays are counted

  in this figure.

- *Graphics rendering* - Total time spent rendering all graphics, including

  both GUI and world viewports. This typically spikes when panning the view

  around, and when more things are happening on screen at once.

- *World viewport rendering* - Isolated time spent rendering just world

  viewports. If this figure is significantly lower than the total graphics

  rendering time, most time is spent rendering GUI than rendering world.

- *Video output* - Speed of copying the rendered graphics to the display

  adapter. Usually this should be very fast (in the range of 0-3 ms), large

  values for this can indicate a graphics driver problem.

- *Sound mixing* - Speed of mixing active audio samples together. Usually

  this should be very fast (in the range of 0-3 ms), if it is slow, consider

  switching to the NoSound set.

If the frame rate window is shaded, the title bar will instead show just the

current simulation rate and the game speed factor.

    <ClInclude Include="..\src\framerate_type.h" />

    <ClCompile Include="..\src\framerate_gui.cpp" />

    <ClInclude Include="..\src\framerate_type.h">

      <Filter>Header Files</Filter>

    </ClInclude>

    <ClCompile Include="..\src\framerate_gui.cpp">

      <Filter>GUI Source Code</Filter>

    </ClCompile>

    <ClInclude Include="..\src\framerate_type.h" />

    <ClCompile Include="..\src\framerate_gui.cpp" />

    <ClInclude Include="..\src\framerate_type.h">

      <Filter>Header Files</Filter>

    </ClInclude>

    <ClCompile Include="..\src\framerate_gui.cpp">

      <Filter>GUI Source Code</Filter>

    </ClCompile>

    <ClInclude Include="..\src\framerate_type.h" />

    <ClCompile Include="..\src\framerate_gui.cpp" />

    <ClInclude Include="..\src\framerate_type.h">

      <Filter>Header Files</Filter>

    </ClInclude>

    <ClCompile Include="..\src\framerate_gui.cpp">

      <Filter>GUI Source Code</Filter>

    </ClCompile>

				RelativePath=".\..\src\framerate_type.h"

				>

			</File>

			<File

				RelativePath=".\..\src\framerate_gui.cpp"

				>

			</File>

			<File

				RelativePath=".\..\src\framerate_type.h"

				>

			</File>

			<File

				RelativePath=".\..\src\framerate_gui.cpp"

				>

			</File>

			<File

framerate_type.h

framerate_gui.cpp

#include "framerate_type.h"

	PerformanceAccumulator framerate(PFE_GL_AIRCRAFT);

#include "framerate_type.h"

	PerformanceAccumulator framerate(PFE_GL_LANDSCAPE);

DEF_CONSOLE_CMD(ConFramerate)

{

	extern void ConPrintFramerate(); // framerate_gui.cpp

	if (argc == 0) {

		IConsoleHelp("Show frame rate and game speed information");

		return true;

	}

	ConPrintFramerate();

	return true;

}

DEF_CONSOLE_CMD(ConFramerateWindow)

{

	extern void ShowFramerateWindow();

	if (argc == 0) {

		IConsoleHelp("Open the frame rate window");

		return true;

	}

	if (_network_dedicated) {

		IConsoleError("Can not open frame rate window on a dedicated server");

		return false;

	}

	ShowFramerateWindow();

	return true;

}

	IConsoleCmdRegister("fps",     ConFramerate);

	IConsoleCmdRegister("fps_wnd", ConFramerateWindow);

/* $Id$ */

/*

* This file is part of OpenTTD.

* 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.

* 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.

* 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/>.

*/

/** @file framerate_gui.cpp GUI for displaying framerate/game speed information. */

#include "framerate_type.h"

#include <chrono>

#include "gfx_func.h"

#include "window_gui.h"

#include "table/sprites.h"

#include "strings_func.h"

#include "debug.h"

#include "console_func.h"

#include "console_type.h"

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 */

	const TimingMeasurement TIMESTAMP_PRECISION = 1000000;

	struct PerformanceData {

		/** Duration value indicating the value is not valid should be considered a gap in measurements */

		static const TimingMeasurement INVALID_DURATION = UINT64_MAX;

		/** Time spent processing each cycle of the performance element, circular buffer */

		TimingMeasurement durations[NUM_FRAMERATE_POINTS];

		/** Start time of each cycle of the performance element, circular buffer */

		TimingMeasurement timestamps[NUM_FRAMERATE_POINTS];

		/** Expected number of cycles per second when the system is running without slowdowns */

		double expected_rate;

		/** Next index to write to in \c durations and \c timestamps */

		int next_index;

		/** Last index written to in \c durations and \c timestamps */

		int prev_index;

		/** Number of data points recorded, clamped to \c NUM_FRAMERATE_POINTS */

		int num_valid;

		/** Current accumulated duration */

		TimingMeasurement acc_duration;

		/** Start time for current accumulation cycle */

		TimingMeasurement acc_timestamp;

		explicit PerformanceData(double expected_rate) : expected_rate(expected_rate), next_index(0), prev_index(0), num_valid(0) { }

		void Add(TimingMeasurement start_time, TimingMeasurement end_time)

		{

			this->durations[this->next_index] = end_time - start_time;

			this->timestamps[this->next_index] = start_time;

			this->prev_index = this->next_index;

			this->next_index += 1;

			if (this->next_index >= NUM_FRAMERATE_POINTS) this->next_index = 0;

			this->num_valid = min(NUM_FRAMERATE_POINTS, this->num_valid + 1);

		}

		void BeginAccumulate(TimingMeasurement start_time)

		{

			this->timestamps[this->next_index] = this->acc_timestamp;

			this->durations[this->next_index] = this->acc_duration;

			this->prev_index = this->next_index;

			this->next_index += 1;

			if (this->next_index >= NUM_FRAMERATE_POINTS) this->next_index = 0;

			this->num_valid = min(NUM_FRAMERATE_POINTS, this->num_valid + 1);

			this->acc_duration = 0;

			this->acc_timestamp = start_time;

		}

		void AddAccumulate(TimingMeasurement duration)

		{

			this->acc_duration += duration;

		}

		void AddPause(TimingMeasurement start_time)

		{

			if (this->durations[this->prev_index] != INVALID_DURATION) {

				this->timestamps[this->next_index] = start_time;

				this->durations[this->next_index] = INVALID_DURATION;

				this->prev_index = this->next_index;

				this->next_index += 1;

				if (this->next_index >= NUM_FRAMERATE_POINTS) this->next_index = 0;

				this->num_valid += 1;

			}

		}

		/** Get average cycle processing time over a number of data points */

		double GetAverageDurationMilliseconds(int count)

		{

			count = min(count, this->num_valid);

			int first_point = this->prev_index - count;

			if (first_point < 0) first_point += NUM_FRAMERATE_POINTS;

			/* Sum durations, skipping invalid points */

			double sumtime = 0;

			for (int i = first_point; i < first_point + count; i++) {

				auto d = this->durations[i % NUM_FRAMERATE_POINTS];

				if (d != INVALID_DURATION) {

					sumtime += d;

				} else {

					/* Don't count the invalid durations */

					count--;

				}

			}

			if (count == 0) return 0; // avoid div by zero

			return sumtime * 1000 / count / TIMESTAMP_PRECISION;

		}

		/** Get current rate of a performance element, based on approximately the past one second of data */

		double GetRate()

		{

			/* Start at last recorded point, end at latest when reaching the earliest recorded point */

			int point = this->prev_index;

			int last_point = this->next_index - this->num_valid;

			if (last_point < 0) last_point += NUM_FRAMERATE_POINTS;

			/** Number of data points collected */

			int count = 0;

			/** Time of previous data point */

			TimingMeasurement last = this->timestamps[point];

			/** Total duration covered by collected points */

			TimingMeasurement total = 0;

			while (point != last_point) {

				/* Only record valid data points, but pretend the gaps in measurements aren't there */

				if (this->durations[point] != INVALID_DURATION) {

					total += last - this->timestamps[point];

					count++;

				}

				last = this->timestamps[point];

				if (total >= TIMESTAMP_PRECISION) break; // end after 1 second has been collected

				point--;

				if (point < 0) point = NUM_FRAMERATE_POINTS - 1;

			}

			if (total == 0 || count == 0) return 0;

			return (double)count * TIMESTAMP_PRECISION / total;

		}

	};

	/** Game loop rate, cycles per second */

	static const double GL_RATE = 1000.0 / MILLISECONDS_PER_TICK;

	PerformanceData _pf_data[PFE_MAX] = {

		PerformanceData(GL_RATE),               // PFE_GAMELOOP

		PerformanceData(1),                     // PFE_ACC_GL_ECONOMY

		PerformanceData(1),                     // PFE_ACC_GL_TRAINS

		PerformanceData(1),                     // PFE_ACC_GL_ROADVEHS

		PerformanceData(1),                     // PFE_ACC_GL_SHIPS

		PerformanceData(1),                     // PFE_ACC_GL_AIRCRAFT

		PerformanceData(1),                     // PFE_GL_LANDSCAPE

		PerformanceData(1),                     // PFE_GL_LINKGRAPH

		PerformanceData(GL_RATE),               // PFE_DRAWING

		PerformanceData(1),                     // PFE_ACC_DRAWWORLD

		PerformanceData(60.0),                  // PFE_VIDEO

		PerformanceData(1000.0 * 8192 / 44100), // PFE_SOUND

	};

}

/**

 * Return a timestamp with \c TIMESTAMP_PRECISION ticks per second precision.

 * The basis of the timestamp is implementation defined, but the value should be steady,

 * so differences can be taken to reliably measure intervals.

 */

static TimingMeasurement GetPerformanceTimer()

{

	using namespace std::chrono;

	return (TimingMeasurement)time_point_cast<microseconds>(high_resolution_clock::now()).time_since_epoch().count();

}

/** Begin a cycle of a measured element. */

PerformanceMeasurer::PerformanceMeasurer(PerformanceElement elem)

{

	assert(elem < PFE_MAX);

	this->elem = elem;

	this->start_time = GetPerformanceTimer();

}

/** Finish a cycle of a measured element and store the measurement taken. */

PerformanceMeasurer::~PerformanceMeasurer()

{

	_pf_data[this->elem].Add(this->start_time, GetPerformanceTimer());

}

/** Set the rate of expected cycles per second of a performance element. */

void PerformanceMeasurer::SetExpectedRate(double rate)

{

	_pf_data[this->elem].expected_rate = rate;

}

/** Indicate that a cycle of "pause" where no processing occurs. */

void PerformanceMeasurer::Paused(PerformanceElement elem)

{

	_pf_data[elem].AddPause(GetPerformanceTimer());

}

/** Begin measuring one block of the accumulating value. */

PerformanceAccumulator::PerformanceAccumulator(PerformanceElement elem)

{

	assert(elem < PFE_MAX);

	this->elem = elem;

	this->start_time = GetPerformanceTimer();

}

/** Finish and add one block of the accumulating value. */

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. */

void PerformanceAccumulator::Reset(PerformanceElement elem)

{

	_pf_data[elem].BeginAccumulate(GetPerformanceTimer());

}

void ShowFrametimeGraphWindow(PerformanceElement elem);

enum FramerateWindowWidgets {

	WID_FRW_CAPTION,

	WID_FRW_RATE_GAMELOOP,

	WID_FRW_RATE_DRAWING,

	WID_FRW_RATE_FACTOR,

	WID_FRW_INFO_DATA_POINTS,

	WID_FRW_TIMES_NAMES,

	WID_FRW_TIMES_CURRENT,

	WID_FRW_TIMES_AVERAGE,

};

static const NWidgetPart _framerate_window_widgets[] = {

	NWidget(NWID_HORIZONTAL),

		NWidget(WWT_CLOSEBOX, COLOUR_GREY),

		NWidget(WWT_CAPTION, COLOUR_GREY, WID_FRW_CAPTION), SetDataTip(STR_FRAMERATE_CAPTION, STR_TOOLTIP_WINDOW_TITLE_DRAG_THIS),

		NWidget(WWT_SHADEBOX, COLOUR_GREY),

		NWidget(WWT_STICKYBOX, COLOUR_GREY),

	EndContainer(),

	NWidget(WWT_PANEL, COLOUR_GREY),

		NWidget(NWID_VERTICAL), SetPadding(6), SetPIP(0, 3, 0),

			NWidget(WWT_TEXT, COLOUR_GREY, WID_FRW_RATE_GAMELOOP), SetDataTip(STR_FRAMERATE_RATE_GAMELOOP, STR_FRAMERATE_RATE_GAMELOOP_TOOLTIP),

			NWidget(WWT_TEXT, COLOUR_GREY, WID_FRW_RATE_DRAWING),  SetDataTip(STR_FRAMERATE_RATE_BLITTER,  STR_FRAMERATE_RATE_BLITTER_TOOLTIP),

			NWidget(WWT_TEXT, COLOUR_GREY, WID_FRW_RATE_FACTOR),   SetDataTip(STR_FRAMERATE_SPEED_FACTOR,  STR_FRAMERATE_SPEED_FACTOR_TOOLTIP),

		EndContainer(),

	EndContainer(),

	NWidget(WWT_PANEL, COLOUR_GREY),

		NWidget(NWID_VERTICAL), SetPadding(6), SetPIP(0, 3, 0),

			NWidget(NWID_HORIZONTAL), SetPIP(0, 6, 0),

				NWidget(WWT_EMPTY, COLOUR_GREY, WID_FRW_TIMES_NAMES),

				NWidget(WWT_EMPTY, COLOUR_GREY, WID_FRW_TIMES_CURRENT),

				NWidget(WWT_EMPTY, COLOUR_GREY, WID_FRW_TIMES_AVERAGE),

			EndContainer(),

			NWidget(WWT_TEXT, COLOUR_GREY, WID_FRW_INFO_DATA_POINTS), SetDataTip(STR_FRAMERATE_DATA_POINTS, 0x0),

		EndContainer(),

	EndContainer(),

};

struct FramerateWindow : Window {

	bool small;

	uint32 next_update;

	struct CachedDecimal {

		StringID strid;

		uint32 value;

		inline void SetRate(double value, double target)

		{

			const double threshold_good = target * 0.95;

			const double threshold_bad = target * 2 / 3;

			value = min(9999.99, value);

			this->value = (uint32)(value * 100);

			this->strid = (value > threshold_good) ? STR_FRAMERATE_FPS_GOOD : (value < threshold_bad) ? STR_FRAMERATE_FPS_BAD : STR_FRAMERATE_FPS_WARN;

		}

		inline void SetTime(double value, double target)

		{

			const double threshold_good = target / 3;

			const double threshold_bad = target;

			value = min(9999.99, value);

			this->value = (uint32)(value * 100);

			this->strid = (value < threshold_good) ? STR_FRAMERATE_MS_GOOD : (value > threshold_bad) ? STR_FRAMERATE_MS_BAD : STR_FRAMERATE_MS_WARN;

		}

		inline void InsertDParams(uint n) const

		{

			SetDParam(n, this->value);

			SetDParam(n + 1, 2);

		}

	};

	CachedDecimal rate_gameloop;            ///< cached game loop tick rate

	CachedDecimal rate_drawing;             ///< cached drawing frame rate

	CachedDecimal speed_gameloop;           ///< cached game loop speed factor

	CachedDecimal times_shortterm[PFE_MAX]; ///< cached short term average times

	CachedDecimal times_longterm[PFE_MAX];  ///< cached long term average times

	static const int VSPACING = 3; ///< space between column heading and values

	FramerateWindow(WindowDesc *desc, WindowNumber number) : Window(desc)

	{

		this->InitNested(number);

		this->small = this->IsShaded();

		this->UpdateData();

	}

	virtual void OnTick()

	{

		/* Check if the shaded state has changed, switch caption text if it has */

		if (this->small != this->IsShaded()) {

			this->small = this->IsShaded();

			this->GetWidget<NWidgetLeaf>(WID_FRW_CAPTION)->SetDataTip(this->small ? STR_FRAMERATE_CAPTION_SMALL : STR_FRAMERATE_CAPTION, STR_TOOLTIP_WINDOW_TITLE_DRAG_THIS);

			this->next_update = 0;

		}

		if (_realtime_tick >= this->next_update) {

			this->UpdateData();

			this->SetDirty();

			this->next_update = _realtime_tick + 100;

		}

	}

	void UpdateData()

	{

		double gl_rate = _pf_data[PFE_GAMELOOP].GetRate();

		this->rate_gameloop.SetRate(gl_rate, _pf_data[PFE_GAMELOOP].expected_rate);

		this->speed_gameloop.SetRate(gl_rate / _pf_data[PFE_GAMELOOP].expected_rate, 1.0);

		if (this->small) return; // in small mode, this is everything needed

		this->rate_drawing.SetRate(_pf_data[PFE_DRAWING].GetRate(), _pf_data[PFE_DRAWING].expected_rate);

		for (PerformanceElement e = PFE_FIRST; e < PFE_MAX; e++) {

			this->times_shortterm[e].SetTime(_pf_data[e].GetAverageDurationMilliseconds(8), MILLISECONDS_PER_TICK);

			this->times_longterm[e].SetTime(_pf_data[e].GetAverageDurationMilliseconds(NUM_FRAMERATE_POINTS), MILLISECONDS_PER_TICK);

		}

	}

	virtual void SetStringParameters(int widget) const

	{

		switch (widget) {

			case WID_FRW_CAPTION:

				/* When the window is shaded, the caption shows game loop rate and speed factor */

				if (!this->small) break;

				SetDParam(0, this->rate_gameloop.strid);

				this->rate_gameloop.InsertDParams(1);

				this->speed_gameloop.InsertDParams(3);

				break;

			case WID_FRW_RATE_GAMELOOP:

				SetDParam(0, this->rate_gameloop.strid);

				this->rate_gameloop.InsertDParams(1);

				break;

			case WID_FRW_RATE_DRAWING:

				SetDParam(0, this->rate_drawing.strid);

				this->rate_drawing.InsertDParams(1);

				break;

			case WID_FRW_RATE_FACTOR:

				this->speed_gameloop.InsertDParams(0);

				break;

			case WID_FRW_INFO_DATA_POINTS:

				SetDParam(0, NUM_FRAMERATE_POINTS);

				break;

		}

	}

	virtual void UpdateWidgetSize(int widget, Dimension *size, const Dimension &padding, Dimension *fill, Dimension *resize)

	{

		switch (widget) {

			case WID_FRW_RATE_GAMELOOP:

				SetDParam(0, STR_FRAMERATE_FPS_GOOD);

				SetDParam(1, 999999);

				SetDParam(2, 2);

				*size = GetStringBoundingBox(STR_FRAMERATE_RATE_GAMELOOP);

				break;

			case WID_FRW_RATE_DRAWING:

				SetDParam(0, STR_FRAMERATE_FPS_GOOD);

				SetDParam(1, 999999);

				SetDParam(2, 2);

				*size = GetStringBoundingBox(STR_FRAMERATE_RATE_BLITTER);

				break;

			case WID_FRW_RATE_FACTOR: