Restructure and reimplement vsync options

-Add a v-sync mode setting which allows to choose between DISABLED, ON, ADAPTIVE and MAILBOX
-Removed the V-Sync via Compositor option

2 files changed, 44 insertions, 37 deletions

diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml
index ef20174ee6..17b51d5cbe 100644
--- a/doc/classes/DisplayServer.xml
+++ b/doc/classes/DisplayServer.xml
@@ -44,9 +44,11 @@
 			</return>
 			<argument index="0" name="mode" type="int" enum="DisplayServer.WindowMode">
 			</argument>
-			<argument index="1" name="flags" type="int">
+			<argument index="1" name="vsync_mode" type="int" enum="DisplayServer.VSyncMode">
 			</argument>
-			<argument index="2" name="rect" type="Rect2i" default="Rect2i(0, 0, 0, 0)">
+			<argument index="2" name="flags" type="int">
+			</argument>
+			<argument index="3" name="rect" type="Rect2i" default="Rect2i(0, 0, 0, 0)">
 			</argument>
 			<description>
 			</description>
@@ -671,34 +673,6 @@
 				[b]Note:[/b] This method is implemented on Android, iOS and UWP.
 			</description>
 		</method>
-		<method name="vsync_is_enabled" qualifiers="const">
-			<return type="bool">
-			</return>
-			<description>
-			</description>
-		</method>
-		<method name="vsync_is_using_via_compositor" qualifiers="const">
-			<return type="bool">
-			</return>
-			<description>
-			</description>
-		</method>
-		<method name="vsync_set_enabled">
-			<return type="void">
-			</return>
-			<argument index="0" name="enabled" type="bool">
-			</argument>
-			<description>
-			</description>
-		</method>
-		<method name="vsync_set_use_via_compositor">
-			<return type="void">
-			</return>
-			<argument index="0" name="enabled" type="bool">
-			</argument>
-			<description>
-			</description>
-		</method>
 		<method name="window_attach_instance_id">
 			<return type="void">
 			</return>
@@ -791,6 +765,15 @@
 			<description>
 			</description>
 		</method>
+		<method name="window_get_vsync_mode" qualifiers="const">
+			<return type="int" enum="DisplayServer.VSyncMode">
+			</return>
+			<argument index="0" name="window_id" type="int" default="0">
+			</argument>
+			<description>
+				Returns the VSync mode of the given window.
+			</description>
+		</method>
 		<method name="window_move_to_foreground">
 			<return type="void">
 			</return>
@@ -995,6 +978,19 @@
 			<description>
 			</description>
 		</method>
+		<method name="window_set_vsync_mode">
+			<return type="void">
+			</return>
+			<argument index="0" name="vsync_mode" type="int" enum="DisplayServer.VSyncMode">
+			</argument>
+			<argument index="1" name="window_id" type="int" default="0">
+			</argument>
+			<description>
+				Sets the VSync mode of the given window.
+				See [enum DisplayServer.VSyncMode] for possible values and how they affect the behavior of your application.
+				Depending on the platform and used renderer, the engine will fall back to [constant VSYNC_ENABLED], if the desired mode is not supported.
+			</description>
+		</method>
 		<method name="window_set_window_event_callback">
 			<return type="void">
 			</return>
@@ -1151,5 +1147,18 @@
 		</constant>
 		<constant name="WINDOW_EVENT_DPI_CHANGE" value="6" enum="WindowEvent">
 		</constant>
+		<constant name="VSYNC_DISABLED" value="0" enum="VSyncMode">
+			No vertical synchronization, which means the engine will display frames as fast as possible (tearing may be visible).
+		</constant>
+		<constant name="VSYNC_ENABLED" value="1" enum="VSyncMode">
+			Default vertical synchronization mode, the image is displayed only on vertical blanking intervals (no tearing is visible).
+		</constant>
+		<constant name="VSYNC_ADAPTIVE" value="2" enum="VSyncMode">
+			Behaves like [constant VSYNC_DISABLED] when the framerate drops below the screen's refresh rate to reduce stuttering (tearing may be visible), otherwise vertical synchronization is enabled to avoid tearing.
+		</constant>
+		<constant name="VSYNC_MAILBOX" value="3" enum="VSyncMode">
+			Displays the most recent image in the queue on vertical blanking intervals, while rendering to the other images (no tearing is visible).
+			Although not guaranteed, the images can be rendered as fast as possible, which may reduce input lag.
+		</constant>
 	</constants>
 </class>
diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml
index 1847a316e1..d497e418bc 100644
--- a/doc/classes/ProjectSettings.xml
+++ b/doc/classes/ProjectSettings.xml
@@ -445,7 +445,7 @@
 		</member>
 		<member name="debug/settings/fps/force_fps" type="int" setter="" getter="" default="0">
 			Maximum number of frames per second allowed. The actual number of frames per second may still be below this value if the game is lagging.
-			If [member display/window/vsync/use_vsync] is enabled, it takes precedence and the forced FPS number cannot exceed the monitor's refresh rate.
+			If [member display/window/vsync/vsync_mode] is set to [code]Enabled[/code] or [code]Adaptive[/code], it takes precedence and the forced FPS number cannot exceed the monitor's refresh rate.
 			This setting is therefore mostly relevant for lowering the maximum FPS below VSync, e.g. to perform non-real-time rendering of static frames, or test the project under lag conditions.
 		</member>
 		<member name="debug/settings/gdscript/max_call_stack" type="int" setter="" getter="" default="1024">
@@ -532,12 +532,10 @@
 		<member name="display/window/size/width" type="int" setter="" getter="" default="1024">
 			Sets the game's main viewport width. On desktop platforms, this is the default window size. Stretch mode settings also use this as a reference when enabled.
 		</member>
-		<member name="display/window/vsync/use_vsync" type="bool" setter="" getter="" default="true">
-			If [code]true[/code], enables vertical synchronization. This eliminates tearing that may appear in moving scenes, at the cost of higher input latency and stuttering at lower framerates. If [code]false[/code], vertical synchronization will be disabled, however, many platforms will enforce it regardless (such as mobile platforms and HTML5).
-		</member>
-		<member name="display/window/vsync/vsync_via_compositor" type="bool" setter="" getter="" default="false">
-			If [code]Use Vsync[/code] is enabled and this setting is [code]true[/code], enables vertical synchronization via the operating system's window compositor when in windowed mode and the compositor is enabled. This will prevent stutter in certain situations. (Windows only.)
-			[b]Note:[/b] This option is experimental and meant to alleviate stutter experienced by some users. However, some users have experienced a Vsync framerate halving (e.g. from 60 FPS to 30 FPS) when using it.
+		<member name="display/window/vsync/vsync_mode" type="String" setter="" getter="" default="&quot;Enabled&quot;">
+			Sets the VSync mode for the main game window.
+			See [enum DisplayServer.VSyncMode] for possible values and how they affect the behavior of your application.
+			Depending on the platform and used renderer, the engine will fall back to [code]Enabled[/code], if the desired mode is not supported.
 		</member>
 		<member name="editor/node_naming/name_casing" type="int" setter="" getter="" default="0">
 			When creating node names automatically, set the type of casing in this project. This is mostly an editor setting.