Expand the sections regarding Jitter, Stutter and Latency

[darksylinc]

This guide has basically two parts:

1. The result of thorough examination of all the problems found that were not caused by Godot (but were attributed to it). This adds an in-depth guide on how to locate and fix such issues.
2. A guide to the new code introduced by PR Improve pacing, latency, and add tweakable options godot#106221 which still needs to be merged.

This is my first PR to godot-docs so please point out if I made a mistake and I apologize any mistake that could've been solved with a RTFM (I did read it, but I probably missed something).

[Calinou]

Suggested change

	Troubleshooting Guide
	----------------------
	After an extensive evaluation of reported tickets and thorough testing of Godot on different HW,
	we found that Godot is blamed for many stutter, jitter or input lag that is not caused by Godot,
	but rather by 3rd Party Software or malfunctioning Hardware.
	This guide will help you find the root cause of these issues.
	**Please read it carefully and exhaust all options before reporting a ticket on Godot.**
	Troubleshooting guide
	---------------------
	After an extensive evaluation of reported tickets and thorough testing of Godot on different hardware,
	we found that Godot is blamed for many stutter, jitter or input lag that is not caused by Godot,
	but rather by third-party software or malfunctioning hardware.
	This guide will help you find the root cause of these issues.
	**Please read it carefully and exhaust all options before reporting a ticket on Godot.**

[Calinou]

Suggested change

	A broken cable may appear to function properly, but cause signal synchronization
	issues that go apparently unnoticed. However these issues can manifest when V-Sync
	is on and apps (including, but not limited, to Godot) running in exclusive fullscreen
	constantly have FPS jitter or slowdowns even in the most basic of scenes.
	If you see simple demo apps struggle to reach 60 fps (e.g. it reaches 60 fps then
	every 2 seconds slows down to 55 or 40 FPS and then goes back up) you may have a bad cable.
	A broken cable may appear to function properly, but cause signal synchronization
	issues that go apparently unnoticed. However, these issues can manifest when V-Sync
	is enabled and apps (including but not limited to Godot) running in exclusive fullscreen
	constantly have FPS jitter or slowdowns, even in the most basic of scenes.
	If you see simple demo apps struggle to reach 60 FPS (e.g. it reaches 60 FPS, then
	every 2 seconds slows down to 55 or 40 FPS and then goes back up), you may have a bad cable.

[Calinou]

Suggested change

	Broken Monitor Firmware
	~~~~~~~~~~~~~~~~~~~~~~~
	Broken monitor firmware
	~~~~~~~~~~~~~~~~~~~~~~~

[Calinou]

Mention updatable firmware (it's common on most monitors released in the last 5 years):

Suggested change

	Unfortunately the simple answer is to replace the monitor. You might have luck contacting
	your Monitor manufacturer (e.g. LG, Samsung, Viewsonic, etc) and/or your GPU vendor
	(e.g. NVIDIA, AMD, Intel) and ask them for a solution or workaround.
	Some monitors (typically the more recent/high-end ones) allow you to update their firmware. In this case, download the latest firmware and apply it.
	For many other monitors, this is not an option. Unfortunately, in this case,
	the simple answer is to replace the monitor. You might have luck contacting
	your monitor manufacturer (e.g. LG, Samsung, ViewSonic, etc) and/or your GPU vendor
	(e.g. NVIDIA, AMD, Intel) and ask them for a solution or workaround.

[Calinou]

Suggested change

	**Solution:** Replace the monitor, or ask the manufacturer for a firmware/driver update.
	**Solution:** Update firmware if possible, replace the monitor, or ask the manufacturer for a firmware/driver update.

[Calinou]

Suggested change

	Multiple Monitors
	~~~~~~~~~~~~~~~~~
	Multiple monitors
	~~~~~~~~~~~~~~~~~

[Calinou]

Suggested change

	If they're not, change their settings until they match.
	If problems persist, try disabling all but one of the monitors.
	If they're not, change their settings until they match. If problems persist, try disabling all but one of the monitors.

[Calinou]

Mention some examples of temperature monitors:

Suggested change

	Jitter or stutter may be caused by an overheating CPU and/or GPU that throttles itself down.
	You can use temperature monitor software to see if this is the case.
	Jitter or stutter may be caused by an overheating CPU and/or GPU that throttles itself down.
	You can use temperature monitor software such as
	`Libre Hardware Monitor <https://github.com/LibreHardwareMonitor/LibreHardwareMonitor>`__ on Windows or
	`lm-sensors <https://wiki.archlinux.org/title/Lm_sensors>`__ on Linux
	to see if this is the case.

[Calinou]

Suggested change

	Inconsistent Power Saving
	~~~~~~~~~~~~~~~~~~~~~~~~~
	Inconsistent power saving
	~~~~~~~~~~~~~~~~~~~~~~~~~

[Calinou]

Suggested change

	In some cases the OS or driver keeps switching the CPU and/or GPU frequencies up and
	down; causing an uneven experience.
	In some cases, the OS or driver keeps switching the CPU and/or GPU frequencies up and
	down. This causes an uneven experience.

[Calinou]

For future reference, this should be less of a necessity on a Linux distribution with a recent Mesa stack since https://gitlab.freedesktop.org/drm/amd/-/issues/1500 has been resolved. However, it can still improve performance (and latency) at times, so it's worth mentioning.

[Calinou]

Suggested change

	Chances are you're not running in "Hardware Independent Flip" because Windows must use DWM
	compositing to display the watermark on top of Godot. And DWM Compositing prevents entering the desired mode.
	Chances are you're not running in "Hardware Independent Flip" because Windows must use DWM
	compositing to display the watermark on top of Godot. DWM Compositing prevents entering
	the desired mode, which increases jitter and input lag.

[Calinou]

Suggested change

	Godot can only enter the good ones if it's fully covering a single monitor with nothing on top.
	Some newer HW may be able to enter "Hardware Composed: Independent Flip" even if not fullscreen though.
	Godot can only enter the good ones if it's fully covering a single monitor with nothing on top.
	Some newer hardware may be able to enter "Hardware Composed: Independent Flip" even if not fullscreen though, thanks to support for multiple plane overlays (MPO).
	This behavior can sometimes be unreliable (e.g. it may vary depending
	on monitor count or whether HDR is enabled), so it's still better to
	use fullscreen whenever possible.

[Calinou]

Suggested change

	**Set PresentMon to windowed mode**. Otherwise PresentMon's overlay `ironically prevents apps <https://github.com/GameTechDev/PresentMon/issues/367>`__
	from entering the "good" modes as it is displayed on top of Godot.
	You will have to use the recording option and later see the CSV capture to see what mode Godot was in.
	**Set PresentMon to windowed mode**. Otherwise, PresentMon's overlay
	`ironically prevents apps <https://github.com/GameTechDev/PresentMon/issues/367>`__
	from entering the "good" modes as it is displayed on top of Godot.
	You will have to use the recording option and later see the CSV capture
	to see what mode Godot was in.

[Calinou]

Suggested change

	Resources online assert that "Hardware Composed: Independent Flip" is the superior method of all.
	However our measurements do not conclusively align with such claims. Ultimately the best experience
	is done when all resources are entirely dedicated to one process. "Hardware Composed: Independent Flip"
	suggests that resources are being diverted to display something else too, even if that something is
	just giving CPU time to the DWM process.
	Resources online assert that "Hardware Composed: Independent Flip" is the superior method of all.
	However, our measurements do not conclusively align with such claims. Ultimately, the best experience
	is done when all resources are entirely dedicated to one process. "Hardware Composed: Independent Flip"
	suggests that resources are being diverted to display something else too, even if that something is
	just giving CPU time to the DWM process.

[Calinou]

Suggested change

	.. tip::
	This section only applies to Vulkan and OpenGL. It does not affect D3D12.
	.. note::
	This section only applies to Vulkan and OpenGL. It does not affect D3D12.

[Calinou]

Suggested change

	On Linux machines using proprietary NVIDIA drivers, every time the process **nvidia-smi** is launched it
	causes a stutter. Unfortunately, many 3rd party apps periodically launch **nvidia-smi** to get GPU temperature
	and frequency and display it on an overlay or similar. For example running **nvidia-smi** once
	per second completely ruins the gaming experience.
	On Linux machines using proprietary NVIDIA drivers, every time the process **nvidia-smi** is launched, it
	causes a stutter. Unfortunately, many third-party apps periodically launch **nvidia-smi** to get GPU temperature
	and frequency and display it on an overlay or similar. For example, running **nvidia-smi** once
	per second completely ruins the gaming experience.

[Calinou]

Suggested change

	If an app can tell you GPU frequency, fan speed or temperature, then it is a suspect.
	Disabling or removing such apps will fix the problem.
	If an app can tell you GPU frequency, fan speed or temperature, then it is a suspect.
	Disabling or removing such apps will fix the problem.

[Calinou]

Suggested change

	- `CPU-X <https://github.com/TheTumultuousUnicornOfDarkness/CPU-X>`__.
	- Linux Mint's Mate panel application "CPU Frequency Scaling Monitor" applet.
	Linux: xfce
	~~~~~~~~~~~
	- `CPU-X <https://github.com/TheTumultuousUnicornOfDarkness/CPU-X>`__.
	- Linux Mint's Mate panel application "CPU Frequency Scaling Monitor" applet.
	Linux: Xfce
	~~~~~~~~~~~

[Calinou]

Suggested change

	xfce's compositor is not good for low latency games and can cause jitter. Disable it.
	Xfce's compositor is not good for low-latency games and can cause jitter. Disable it.

[Calinou]

Suggested change

	If you still want to use a Compositor on xfce, prefer using a better one like picom:
	If you still want to use a compositor on Xfce, prefer using a better one like picom:

[Calinou]

Suggested change

	Latency Reduction
	~~~~~~~~~~~~~~~~~
	Latency reduction
	~~~~~~~~~~~~~~~~~

[Calinou]

Suggested change

	Starting with Godot 4.5, new pacing methods were introduced to reduce latency (and alleviate Jitter):
	Starting with Godot 4.5, new pacing methods were introduced to reduce latency (and alleviate jitter):

[Calinou]

Suggested change

	Waitable Swapchains are by far the superior method, but if that's not available AUTO/SEQUENTIAL will be used instead.
	Waitable Swapchains are by far the superior method, but if that's not available, ``AUTO``/``SEQUENTIAL`` will be used instead.

[Calinou]

Suggested change

	In all cases (*including* Waitable Swapchain method), **lowering latency implies sacrificing framerate**.
	The question is, how much FPS (frames per second) are you willing to sacrifice for latency. The relationship is not linear,
	which means the lower the latency you want to achieve the greater the FPS sacrifice, which can get ridiculously high.
	This is not a bug, it is just the nature of how it works.
	In all cases (*including* Waitable Swapchain method), **lowering latency implies sacrificing framerate**.
	The question is, how much FPS (frames per second) are you willing to sacrifice for latency. The relationship is not linear.
	This means the lower the latency you want to achieve, the greater the FPS sacrifice, which can become very significant.
	This is not a bug, it is just the nature of how it works.

[Calinou]

Collapse the two warnings together:

Suggested change

	.. warning::
	``low_extreme`` might get you better latency (or even be a placebo) but always at a very large FPS cost.
	Furthermore it may reintroduce microstutter. Caution is advised when seeking to lower latency too much.
	.. warning::
	Just because ``low_extreme`` works great in your machine doesn't mean it will work fine
	in other machines. Don't deploy to end users with this setting as a default.
	.. warning::
	``low_extreme`` might get you better latency (or even be a placebo) but always at a very large FPS cost.
	Furthermore, it may reintroduce microstutter. Caution is advised when seeking to lower latency too much.
	Just because ``low_extreme`` works great in your machine doesn't mean it will work fine
	in other machines. Don't deploy to end users with this setting as a default.

In general, we should avoid having multiple adominition blocks next to each other. Having 2 is sometimes acceptable, but we should definitely never have 3 or more.

[Calinou]

Suggested change

	| Setting | Target: Frames of latency (if Waitable Swapchains are available)| Waitable Swapchains Unavailable |
	| Setting | Target: Frames of latency (if Waitable Swapchains are available)| Waitable swapchains unavailable |

[Calinou]

Suggested change

	+=================+=================================================================+=================================+
	| low_extreme | 0 | SEQUENTIAL |
	+-----------------+-----------------------------------------------------------------+---------------------------------+
	| low | 1 | AUTO |
	+-----------------+-----------------------------------------------------------------+---------------------------------+
	| medium | rendering/rendering_device/vsync/frame_queue_size | PARALLEL (Disabled) |
	+-----------------+-----------------------------------------------------------------+---------------------------------+
	| high_throughput | Disabled | PARALLEL (Disabled) |
	+-----------------+-----------------------------------------------------------------+---------------------------------+
	+=================+=================================================================+=====================================+
	| low_extreme | 0 | ``SEQUENTIAL`` |
	+-----------------+-------------------------------------------------------------------+-----------------------------------+
	| low | 1 | ``AUTO`` |
	+-----------------+-------------------------------------------------------------------+-----------------------------------+
	| medium | rendering/rendering_device/vsync/frame_queue_size | ``PARALLEL`` (Disabled) |
	+-----------------+---------------------------------------------------------------------+---------------------------------+
	| high_throughput | Disabled | ``PARALLEL`` (Disabled) |
	+-----------------+---------------------------------------------------------------------+---------------------------------+

[Calinou]

Suggested change

	This table is read like this:
	- If Waitable Swapchains are available, at "low" Godot will target 1 frame of latency. Otherwise, at "low" it will use AUTO as fallback.
	- If Waitable Swapchains are available, at "medium" Godot will use the value in frame_queue_size as target for frames of latency. Otherwise it uses PARALLEL mode (which is the same as having no pacing method).
	.. tip::
	Godot's behavior on version 4.4 and earlier corresponds to ``high_throughput``.
	This table is read like this:
	- If Waitable Swapchains are available, at "low", Godot will target 1 frame of latency. Otherwise, at "low" it will use AUTO as fallback.
	- If Waitable Swapchains are available, at "medium" Godot will use the value in ``frame_queue_size`` as target for frames of latency. Otherwise, it uses ``PARALLEL`` mode (which is the same as having no pacing method).
	.. tip::
	Godot's behavior on version 4.4 and earlier corresponds to ``high_throughput``.

[Calinou]

Suggested change

	- ``--pacing-mode-mask 0x01`` will force to only use SEQUENTIAL_SYNC (if available).
	- ``--pacing-mode-mask 0x02`` will force to only use WAITABLE_SWAPCHAIN (if available).
	- ``--pacing-mode-mask 0x01`` will force to only use ``SEQUENTIAL_SYNC`` (if available).
	- ``--pacing-mode-mask 0x02`` will force to only use ``WAITABLE_SWAPCHAIN`` (if available).

[Calinou]

Suggested change

	Thus by launching with ``--pacing-mode-mask 0x01`` we can experience how it runs by using ``SEQUENTIAL_SYNC``.
	Now that we are in sequential sync pacing mode; again we can try ``--latency-mode`` makes any difference.
	You can try ``low_extreme`` (SEQUENTIAL), ``low`` (AUTO) and ``medium`` (PARALLEL) to see if they make a difference.
	Thus, by launching with ``--pacing-mode-mask 0x01`` we can experience how it runs by using ``SEQUENTIAL_SYNC``.
	Now that we are in sequential sync pacing mode; again we can try ``--latency-mode`` makes any difference.
	You can try ``low_extreme`` (``SEQUENTIAL``), ``low`` (``AUTO``) and ``medium`` (``PARALLEL``) to see if they make a difference.

[Calinou]

Suggested change

	**When to report issues:**
	- If WAITABLE_SWAPCHAIN at ``low`` or ``medium`` settings are causing problems. This could indicate an issue with the rendering API, the OS, or HW.
	- If SEQUENTIAL_SYNC at ``low`` is causing problems but works fine at ``low_extreme`` or ``medium``. This would indicate a problem in Godot's AUTO algorithm.
	- If ANDROID_SWAPPY is causing problems.
	**What NOT to report:**
	- ``low`` or ``low_extreme`` reduces the FPS.
	- ``AUTO`` does not improve latency.
	- ``SEQUENTIAL_SYNC`` does not improve latency.
	**When to report issues:**
	- If ``WAITABLE_SWAPCHAIN`` at ``low`` or ``medium`` settings are causing problems. This could indicate an issue with the rendering API, the OS, or hardware.
	- If ``SEQUENTIAL_SYNC`` at ``low`` is causing problems but works fine at ``low_extreme`` or ``medium``. This would indicate a problem in Godot's ``AUTO`` algorithm.
	- If ``ANDROID_SWAPPY`` is causing problems.
	**What NOT to report:**
	- ``low`` or ``low_extreme`` reduces the FPS.
	- ``AUTO`` does not improve latency.
	- ``SEQUENTIAL_SYNC`` does not improve latency.

[Calinou]

Looks great! I've made stylistic suggestions but the contents are pretty solid.

We should see if we can remake the Windows screenshots with fully English text later on, but it's not critical for getting this merged as the locations for the settings are obvious enough.

[darksylinc]

Thanks @Calinou for the editorial review. I've applied your fixes.

I've also added 2 more changes:

1. I added a note that nvidia-smi.exe exists on Windows too (but it is rarely a problem on Windows). Look for "nvidia-smi.exe" in the document.
2. Added "Third-party software" section.

We should see if we can remake the Windows screenshots with fully English text later on, but it's not critical for getting this merged as the locations for the settings are obvious enough.

Agreed. I tried to get them in full English but some text stayed in Spanish even after installing the English language pack and switching to it.