Time, frames and ticks - Revision history

Stgatilov: rendering time?

2020-08-02T10:10:08Z

rendering time?

← Older revision		Revision as of 10:10, 2 August 2020
Line 45:		Line 45:

	'''tr.frameCount''' is number of <tt>idRenderSystemLocal::BeginFrame</tt> calls. This is the number of frames rendered, this it has little relation to game time or astronomical time. Used inside renderer for various "last updated" properties and etc. Should not be used outside renderer.		'''tr.frameCount''' is number of <tt>idRenderSystemLocal::BeginFrame</tt> calls. This is the number of frames rendered, this it has little relation to game time or astronomical time. Used inside renderer for various "last updated" properties and etc. Should not be used outside renderer.

			'''backEnd.viewDef->floatTime''' and '''tr.viewDef->floatTime''' are some sort of rendering time. They are passed to materials as <tt>time</tt> variables, also used in cinematics.

	'''std::time()''', '''Sys_GetTimeMicroseconds()''' both return astronomical time since year 1970. Obviously, they never stop.		'''std::time()''', '''Sys_GetTimeMicroseconds()''' both return astronomical time since year 1970. Obviously, they never stop.
Line 68:		Line 70:

	'''com_frameTime''' is some sort of overall runtime. Looks astronomical, but with the a strict discrete nature of updates. It is often used for GUI modeling. For instance, game console is modeled based on this time, so slowing down game time via cvars does not reduce console usability. Note that it never stops or changes speed, unlike game time.		'''com_frameTime''' is some sort of overall runtime. Looks astronomical, but with the a strict discrete nature of updates. It is often used for GUI modeling. For instance, game console is modeled based on this time, so slowing down game time via cvars does not reduce console usability. Note that it never stops or changes speed, unlike game time.


	=== Important cvars ===		=== Important cvars ===

Stgatilov: /* Modeling */

2020-07-25T11:21:07Z

Modeling

← Older revision		Revision as of 11:21, 25 July 2020
Line 86:		Line 86:
	The outermost loop is located in <tt>WinMain</tt> in <tt>win_main.cpp</tt>. It simply runs <tt>idCommonLocal::Frame</tt> every iteration.		The outermost loop is located in <tt>WinMain</tt> in <tt>win_main.cpp</tt>. It simply runs <tt>idCommonLocal::Frame</tt> every iteration.

	Before main loop starts, a separate thread is started in <tt>Sys_StartAsyncThread</tt>, calling <tt>Sys_AsyncThread</tt> function every 3 ms (as of 2.08) by OS timer ([https://docs.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-setwaitabletimer SetWaitableTimer]). This separate thread generates async tics. The function calls <tt>idCommonLocal::Async</tt>, which looks at astronomical time and decides how many async tics to generate (targeting ~~exact~~ 60 Hz frequency). The async ticks are done in <tt>idCommonLocal::SingleAsyncTic</tt>, which increments <tt>com_ticNumber</tt> and pushes some more data to sound output.		Before main loop starts, a separate thread is started in <tt>Sys_StartAsyncThread</tt>, calling <tt>Sys_AsyncThread</tt> function every 3 ms (as of 2.08) by OS timer ([https://docs.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-setwaitabletimer SetWaitableTimer]). This separate thread generates async tics. The function calls <tt>idCommonLocal::Async</tt>, which looks at astronomical time and decides how many async tics to generate (targeting average 60 Hz frequency). The async ticks are done in <tt>idCommonLocal::SingleAsyncTic</tt>, which increments <tt>com_ticNumber</tt> and pushes some more data to sound output.

	The iteration of main loop on main thread <tt>idCommonLocal::Frame</tt> calls:		The iteration of main loop on main thread <tt>idCommonLocal::Frame</tt> calls:

Stgatilov: Added link to #4696

2020-07-25T09:08:49Z

Added link to #4696

← Older revision		Revision as of 09:08, 25 July 2020
Line 114:		Line 114:
	In original Doom 3, async tics happened every 16 ms, which caused a regular micro-stutter. This was fixed as part of [https://bugs.thedarkmod.com/view.php?id=4514 #4614] (linked forum threads are interesting to read). But since most of the game code stores time in integer number of milliseconds, the timestep had to remain 16 ms.		In original Doom 3, async tics happened every 16 ms, which caused a regular micro-stutter. This was fixed as part of [https://bugs.thedarkmod.com/view.php?id=4514 #4614] (linked forum threads are interesting to read). But since most of the game code stores time in integer number of milliseconds, the timestep had to remain 16 ms.
	This leads to a strange effect that when uncapped FPS is off, game runs slower by 4% =)		This leads to a strange effect that when uncapped FPS is off, game runs slower by 4% =)

			If you like to review discussions and issues related to this topic, "uncapped" is a good word to search for, both on forums and on bugtracker.
			Also, issue [https://bugs.thedarkmod.com/view.php?id=4696 #4696] serves as a good hub of issues caused by uncapped FPS mode.

	[[Category: Coding]]		[[Category: Coding]]

Stgatilov: /* Important cvars */

2020-07-25T09:06:23Z

Important cvars

← Older revision		Revision as of 09:06, 25 July 2020
Line 74:		Line 74:
	'''com_fixedTic''': enables "Uncapped FPS" mode. When value is 0, old 60-FPS mode runs, and every game modeling step is fixed to 16 ms. When value is 0, FPS can go higher than 60, but game modeling timesteps vary.		'''com_fixedTic''': enables "Uncapped FPS" mode. When value is 0, old 60-FPS mode runs, and every game modeling step is fixed to 16 ms. When value is 0, FPS can go higher than 60, but game modeling timesteps vary.

	'''com_maxTicTimestep''', '''com_maxTicsPerFrame''', '''com_maxFPS''': additional parameters for uncapped FPS mode. They are used to cap timesteps in game modeling in order to make physics stable. See rope physics issue [https://bugs.thedarkmod.com/view.php?id=4924 #4924] and [https://bugs.thedarkmod.com/view.php?id=4696 ~~Missing footsteps issue~~ #4696] for rationale behind limits.		'''com_maxTicTimestep''', '''com_maxTicsPerFrame''', '''com_maxFPS''': additional parameters for uncapped FPS mode. They are used to cap timesteps in game modeling in order to make physics stable. See rope physics issue [https://bugs.thedarkmod.com/view.php?id=4924 #4924] and Missing footsteps issue [https://bugs.thedarkmod.com/view.php?id=4696 #4696] for rationale behind limits.

	'''timescale''': accelerates async ticks, making them happen faster. The intended effect is that game ticks (which are more of less tied to async ticks) will also happen faster, so the whole game will accelerate. I think it should only work without uncapped FPS. Unlike effect of <tt>g_timeModifier</tt>, timesteps remain the same, but ticks happen more frequently than 60 times per second.		'''timescale''': accelerates async ticks, making them happen faster. The intended effect is that game ticks (which are more of less tied to async ticks) will also happen faster, so the whole game will accelerate. I think it should only work without uncapped FPS. Unlike effect of <tt>g_timeModifier</tt>, timesteps remain the same, but ticks happen more frequently than 60 times per second.
Line 81:		Line 81:

	'''g_stopTime''': stops game time from running completely. Game ticks don't happen, game time does not increase. The only exception is that <tt>idPlayer::Think</tt> is called in place of game ticks, so player can move around. Sometimes it's very useful to enable it straight in debugger, in order to teleport to the place where some event has happened.		'''g_stopTime''': stops game time from running completely. Game ticks don't happen, game time does not increase. The only exception is that <tt>idPlayer::Think</tt> is called in place of game ticks, so player can move around. Sometimes it's very useful to enable it straight in debugger, in order to teleport to the place where some event has happened.


	=== Modeling ===		=== Modeling ===

Stgatilov: com_maxFPS mentioned

2020-07-25T09:06:00Z

com_maxFPS mentioned

← Older revision		Revision as of 09:06, 25 July 2020
Line 74:		Line 74:
	'''com_fixedTic''': enables "Uncapped FPS" mode. When value is 0, old 60-FPS mode runs, and every game modeling step is fixed to 16 ms. When value is 0, FPS can go higher than 60, but game modeling timesteps vary.		'''com_fixedTic''': enables "Uncapped FPS" mode. When value is 0, old 60-FPS mode runs, and every game modeling step is fixed to 16 ms. When value is 0, FPS can go higher than 60, but game modeling timesteps vary.

	'''com_maxTicTimestep''', '''com_maxTicsPerFrame''': additional parameters for uncapped FPS mode. They are used to cap timesteps in game modeling in order to make physics stable. See rope physics issue [https://bugs.thedarkmod.com/view.php?id=4924 #4924] for rationale behind it.		'''com_maxTicTimestep''', '''com_maxTicsPerFrame''', '''com_maxFPS''': additional parameters for uncapped FPS mode. They are used to cap timesteps in game modeling in order to make physics stable. See rope physics issue [https://bugs.thedarkmod.com/view.php?id=4924 #4924] and [https://bugs.thedarkmod.com/view.php?id=4696 Missing footsteps issue #4696] for rationale behind limits.

	'''timescale''': accelerates async ticks, making them happen faster. The intended effect is that game ticks (which are more of less tied to async ticks) will also happen faster, so the whole game will accelerate. I think it should only work without uncapped FPS. Unlike effect of <tt>g_timeModifier</tt>, timesteps remain the same, but ticks happen more frequently than 60 times per second.		'''timescale''': accelerates async ticks, making them happen faster. The intended effect is that game ticks (which are more of less tied to async ticks) will also happen faster, so the whole game will accelerate. I think it should only work without uncapped FPS. Unlike effect of <tt>g_timeModifier</tt>, timesteps remain the same, but ticks happen more frequently than 60 times per second.

Stgatilov: Initial version

2020-07-25T09:02:58Z

Initial version

New page

TDM engine has:
* many variables storing current "time"
* some clocks, tics, and timers
* some cvars causing wildly different behavior of time
* some time-modifying cvars

It is often necessary to understand the differences between various notions of time.
The purpose of this article is to help coders with it.

Preliminary note: the original Doom 3 engine works under 60 FPS limit, with fixed game modeling timestep of 16 ms. It is also the default mode of TDM (as of 2.08). The new '''Uncapped FPS''' mode was added specifically in TDM: it can run with higher FPS, but models game with varying timestep. It can be enabled either as <tt>com_fixedTic 1</tt> and by checkbox in graphics menu. The cvar was hijacked: it meant something completely different in original Doom 3 engine.

=== Times ===

The main types of time are:

* '''astronomical time'''. This time goes exactly as the physical time outside of your computer does.
* '''game time'''. This is the time going in-game in terms of gameplay. Mainly, all the physics are simulated based on this time.

Of course, even if you choose one of these types, the exact value depends also on things like (not counting obvious beginning of era and measurement units):

# Is the time paused or accelerated under some conditions? (e.g. some astronomical time can exclude time spent in main menu)
# Is the time save-game persistent, i.e. written to savefile and restored on load? (e.g. gameplay time shown to player at the end)

Some additional timelike quantities include:

* '''frame number''' (<tt>tr.frameCount</tt>). This often serves as time in renderer. Some time ago similar notions were also used as time in game code, but it is completely wrong in "uncapped FPS" mode.
* '''async tick number''' (<tt>com_ticNumber</tt>). This is a counter incremented in separate thread every with 60 FPS speed. It approximately controls game time in default mode (uncapped FPS disabled). See modeling section for details.

=== Notable values ===

'''gameLocal.time''' represents game time in milliseconds.
It starts from zero when game/map is started.
It is persistent on save/load.
While it is kept roughly in sync with astronomical time, it can drift away due to accidental missed ticks and such.
Also, it is paused when player is in main menu, when <tt>g_stopTime</tt> is enabled, and at "press attack to start" screen.
As seen in <tt>idGameLocal::RunFrame</tt>, its speed is multiplied by <tt>g_timeModifier</tt>, which is often used for debugging purposes.
This is the main time used everywhere: it controls physics, AI, animation, etc.

'''gameLocal.framenum''' is the number of game ticks modeled during current game.
Unlike what words say, it has nothing to do with rendering frames.
Game tick is one call of <tt>idGameLocal::RunFrame</tt>. Every such call, game time is incremented by the passed timestep. Obviously, timestep varies due to various factors (uncapped FPS, <tt>g_timeModifier</tt>), so number of game ticks and game time can't be obtained one from the other.
This value is persistent on save/load, paused by same things as <tt>gameLocal.time</tt>.

'''tr.frameCount''' is number of <tt>idRenderSystemLocal::BeginFrame</tt> calls. This is the number of frames rendered, this it has little relation to game time or astronomical time. Used inside renderer for various "last updated" properties and etc. Should not be used outside renderer.

'''std::time()''', '''Sys_GetTimeMicroseconds()''' both return astronomical time since year 1970. Obviously, they never stop.
The latter function was added in TDM, and unless one second resolution is enough, better prefer it.
'''Sys_Milliseconds()''' returns astronomical time since the moment executable was started.
These values should not be used in general. Exceptions include: high-level time/game modeling code (to sync game time to astronomical),
reporting gameplay time to user (use <tt>m_GamePlayTimer</tt> for this).

'''Sys_GetClockTicks()''' relies on RDTSC counter, and returns number of CPU clocks passed since some moment.
God knows how it interacts with sleeping, variable CPU frequency, multicore coherency, etc., so it cannot be called exactly astronomical.
It can only be used for high-precision low-duration benchmarking on single core (e.g. SIMD code benchmarks), and never for anything important.

'''gameLocal.m_GamePlayTimer''' (both <tt>_timePassed</tt> and <tt>_msecPassed</tt>) reflects how much '''astronomical''' time player has spent in action during current playthrough.
It's sole purpose is to report "played for 45 minutes 13 seconds" to player when he finished mission. Never use it for anything related to gameplay/physics/rendering!
While it runs with the speed of astronomical time, it is 1) saved/restored in savegames, and 2) paused when player is at main menu or at "press attack to start" screen.

'''com_ticNumber''' is the number of async ticks happened since async thread was started (most likely since executable was started)
Async ticks are the calls of function <tt>idCommonLocal::SingleAsyncTic</tt>, happening on a separate thread with help of OS timer.
It plays important role when uncapped FPS is off, since game ticks are more or less synchronized to async tics (although some drifts are possible as usual).
Unless you decide to change high-level game modeling code, better not mess with this value.

'''com_frameNumber''' is number of times <tt>idCommonLocal::Frame</tt> was called. This is the upper-most function called in infinite loop. It is the number reported as "frame" by </tt>com_speeds</tt>. Not much else can be said here: just keep away from it.

'''com_frameTime''' is some sort of overall runtime. Looks astronomical, but with the a strict discrete nature of updates. It is often used for GUI modeling. For instance, game console is modeled based on this time, so slowing down game time via cvars does not reduce console usability. Note that it never stops or changes speed, unlike game time.

=== Important cvars ===

'''com_fixedTic''': enables "Uncapped FPS" mode. When value is 0, old 60-FPS mode runs, and every game modeling step is fixed to 16 ms. When value is 0, FPS can go higher than 60, but game modeling timesteps vary.

'''com_maxTicTimestep''', '''com_maxTicsPerFrame''': additional parameters for uncapped FPS mode. They are used to cap timesteps in game modeling in order to make physics stable. See rope physics issue [https://bugs.thedarkmod.com/view.php?id=4924 #4924] for rationale behind it.

'''timescale''': accelerates async ticks, making them happen faster. The intended effect is that game ticks (which are more of less tied to async ticks) will also happen faster, so the whole game will accelerate. I think it should only work without uncapped FPS. Unlike effect of <tt>g_timeModifier</tt>, timesteps remain the same, but ticks happen more frequently than 60 times per second.

'''g_timeModifier''': accelerates game time by this multiplier. Note that it is applied directly to timestep in <tt>idGameLocal::RunFrame</tt>, it does not change the number of modeled game ticks, but makes every timestep longer. So it affects physics stability: setting high values can easily break things.

'''g_stopTime''': stops game time from running completely. Game ticks don't happen, game time does not increase. The only exception is that <tt>idPlayer::Think</tt> is called in place of game ticks, so player can move around. Sometimes it's very useful to enable it straight in debugger, in order to teleport to the place where some event has happened.

=== Modeling ===

The outermost loop is located in <tt>WinMain</tt> in <tt>win_main.cpp</tt>. It simply runs <tt>idCommonLocal::Frame</tt> every iteration.

Before main loop starts, a separate thread is started in <tt>Sys_StartAsyncThread</tt>, calling <tt>Sys_AsyncThread</tt> function every 3 ms (as of 2.08) by OS timer ([https://docs.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-setwaitabletimer SetWaitableTimer]). This separate thread generates async tics. The function calls <tt>idCommonLocal::Async</tt>, which looks at astronomical time and decides how many async tics to generate (targeting exact 60 Hz frequency). The async ticks are done in <tt>idCommonLocal::SingleAsyncTic</tt>, which increments <tt>com_ticNumber</tt> and pushes some more data to sound output.

The iteration of main loop on main thread <tt>idCommonLocal::Frame</tt> calls:
# <tt>idSession::Frame</tt> --- responsible for game modeling and possible waiting if working too fast.
# <tt>idSession::UpdateScreen</tt> --- backend renders new frame to display, waiting for VSync if <tt>r_swapInterval</tt> is enabled.

<tt>idSessionLocal::Frame</tt> is the most interesting place because it explains how rendering frames, async tics and game ticks are all tied together. While this function is called once per rendering frame, it does not necessarily performs one game tick per frame. The way it works depends on whether Uncapped FPS is enabled or not:

* Disabled (default): Looks at async ticks number <tt>com_ticNumber</tt>, let's says it has increased by K since last time. If K == 0, then waits (nothing to do yet). Otherwise, models K game ticks, with timestep = 16 ms each.
* Enabled: Looks at how much astronomical time has passed since last time, let's say it is dT ms. Unless this dT is too large, models one game tick with timestamp = dT. In order to cap timestep and stabilize game physics, timesteps longer than 17 ms are broken into several game ticks of equal duration. If dT is too small, then the function spinlocks a bit (limits FPS from above).

Both code paths have a limit of doing 10 game ticks per call. If it is exceeded, then deltatime is lowered, allowing game time to lag behind astronomical time. Also, in both cases game ticks are not modeled immediately due because of <tt>com_smp</tt>, only some variables are set.

In fact, both approaches are trying to synchronize game time with astronomical time, but the old approach does this with intermediate layer of async tics generates by separate thread, while uncapped FPS mode is tied to astronomical time directly. The former is more deterministic in terms of game modeling, while the latter is more flexible to adapt timestep at higher FPS.

<tt>idSessionLocal::ActivateFrontend</tt> is the function which calls:
# <tt>idSessionLocal::RunGameTics</tt> --- performs game ticks modeling.
# <tt>idSessionLocal::DrawFrame</tt> --- runs renderer frontend.
It is called on separate thread if <tt>com_smp</tt> is enabled, and directly from <tt>idSessionLocal::UpdateScreen</tt> if it is not.

<tt>idSessionLocal::RunGameTics</tt> calls <tt>idGameLocal::RunFrame</tt> with timestep computed by <tt>idSessionLocal::Frame</tt>, as many times as required. The latter function actually does the game modeling, increasing game tick number <tt>gameLocal.framenum</tt> and game time <tt>gameLocal.time</tt>.

=== Misc ===

An attentive reader might have noticed that async tics are generated at frequency 60 Hz, game modeling timestep is 16 ms, and these two numbers don't match.
As you know, VSync on standard monitors happens 60 times per second with good precision. In order to avoid micro-stutters, game ticks should happen with same frequency.
In original Doom 3, async tics happened every 16 ms, which caused a regular micro-stutter. This was fixed as part of [https://bugs.thedarkmod.com/view.php?id=4514 #4614] (linked forum threads are interesting to read). But since most of the game code stores time in integer number of milliseconds, the timestep had to remain 16 ms.
This leads to a strange effect that when uncapped FPS is off, game runs slower by 4% =)

[[Category: Coding]]