Merge pull request #52314 from lawnjelly/four_delta_smooth

Add frame delta smoothing option (4.x)

core/core_bind.cpp

@@ -224,6 +224,14 @@ int OS::get_low_processor_usage_mode_sleep_usec() const {
 	return ::OS::get_singleton()->get_low_processor_usage_mode_sleep_usec();
 }
 
+void OS::set_delta_smoothing(bool p_enabled) {
+	::OS::get_singleton()->set_delta_smoothing(p_enabled);
+}
+
+bool OS::is_delta_smoothing_enabled() const {
+	return ::OS::get_singleton()->is_delta_smoothing_enabled();
+}
+
 void OS::alert(const String &p_alert, const String &p_title) {
 	::OS::get_singleton()->alert(p_alert, p_title);
 }
@@ -556,6 +564,9 @@ void OS::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_low_processor_usage_mode_sleep_usec", "usec"), &OS::set_low_processor_usage_mode_sleep_usec);
 	ClassDB::bind_method(D_METHOD("get_low_processor_usage_mode_sleep_usec"), &OS::get_low_processor_usage_mode_sleep_usec);
 
+	ClassDB::bind_method(D_METHOD("set_delta_smoothing", "delta_smoothing_enabled"), &OS::set_delta_smoothing);
+	ClassDB::bind_method(D_METHOD("is_delta_smoothing_enabled"), &OS::is_delta_smoothing_enabled);
+
 	ClassDB::bind_method(D_METHOD("get_processor_count"), &OS::get_processor_count);
 	ClassDB::bind_method(D_METHOD("get_processor_name"), &OS::get_processor_name);
 
@@ -631,6 +642,7 @@ void OS::_bind_methods() {
 
 	ADD_PROPERTY(PropertyInfo(Variant::BOOL, "low_processor_usage_mode"), "set_low_processor_usage_mode", "is_in_low_processor_usage_mode");
 	ADD_PROPERTY(PropertyInfo(Variant::INT, "low_processor_usage_mode_sleep_usec"), "set_low_processor_usage_mode_sleep_usec", "get_low_processor_usage_mode_sleep_usec");
+	ADD_PROPERTY(PropertyInfo(Variant::BOOL, "delta_smoothing"), "set_delta_smoothing", "is_delta_smoothing_enabled");
 
 	// Those default values need to be specified for the docs generator,
 	// to avoid using values from the documentation writer's own OS instance.

core/core_bind.h

@@ -141,6 +141,9 @@ public:
 	void set_low_processor_usage_mode_sleep_usec(int p_usec);
 	int get_low_processor_usage_mode_sleep_usec() const;
 
+	void set_delta_smoothing(bool p_enabled);
+	bool is_delta_smoothing_enabled() const;
+
 	void alert(const String &p_alert, const String &p_title = "ALERT!");
 	void crash(const String &p_message);
 

core/os/os.cpp

@@ -151,6 +151,14 @@ int OS::get_low_processor_usage_mode_sleep_usec() const {
 	return low_processor_usage_mode_sleep_usec;
 }
 
+void OS::set_delta_smoothing(bool p_enabled) {
+	_delta_smoothing_enabled = p_enabled;
+}
+
+bool OS::is_delta_smoothing_enabled() const {
+	return _delta_smoothing_enabled;
+}
+
 String OS::get_executable_path() const {
 	return _execpath;
 }

core/os/os.h

@@ -52,6 +52,7 @@ class OS {
 	bool _keep_screen_on = true; // set default value to true, because this had been true before godot 2.0.
 	bool low_processor_usage_mode = false;
 	int low_processor_usage_mode_sleep_usec = 10000;
+	bool _delta_smoothing_enabled = false;
 	bool _verbose_stdout = false;
 	bool _debug_stdout = false;
 	String _local_clipboard;
@@ -154,6 +155,9 @@ public:
 	virtual void set_low_processor_usage_mode_sleep_usec(int p_usec);
 	virtual int get_low_processor_usage_mode_sleep_usec() const;
 
+	void set_delta_smoothing(bool p_enabled);
+	bool is_delta_smoothing_enabled() const;
+
 	virtual Vector<String> get_system_fonts() const { return Vector<String>(); };
 	virtual String get_system_font_path(const String &p_font_name, int p_weight = 400, int p_stretch = 100, bool p_italic = false) const { return String(); };
 	virtual Vector<String> get_system_font_path_for_text(const String &p_font_name, const String &p_text, const String &p_locale = String(), const String &p_script = String(), int p_weight = 400, int p_stretch = 100, bool p_italic = false) const { return Vector<String>(); };

doc/classes/OS.xml

@@ -670,6 +670,9 @@
 		</method>
 	</methods>
 	<members>
+		<member name="delta_smoothing" type="bool" setter="set_delta_smoothing" getter="is_delta_smoothing_enabled" default="true">
+			If [code]true[/code], the engine filters the time delta measured between each frame, and attempts to compensate for random variation. This will only operate on systems where V-Sync is active.
+		</member>
 		<member name="low_processor_usage_mode" type="bool" setter="set_low_processor_usage_mode" getter="is_in_low_processor_usage_mode" default="false">
 			If [code]true[/code], the engine optimizes for low processor usage by only refreshing the screen if needed. Can improve battery consumption on mobile.
 		</member>

doc/classes/ProjectSettings.xml

@@ -284,6 +284,11 @@
 		<member name="application/config/windows_native_icon" type="String" setter="" getter="" default="&quot;&quot;">
 			Icon set in [code].ico[/code] format used on Windows to set the game's icon. This is done automatically on start by calling [method DisplayServer.set_native_icon].
 		</member>
+		<member name="application/run/delta_smoothing" type="bool" setter="" getter="" default="true">
+			Time samples for frame deltas are subject to random variation introduced by the platform, even when frames are displayed at regular intervals thanks to V-Sync. This can lead to jitter. Delta smoothing can often give a better result by filtering the input deltas to correct for minor fluctuations from the refresh rate.
+			[b]Note:[/b] Delta smoothing is only attempted when [member display/window/vsync/vsync_mode] is set to [code]enabled[/code], as it does not work well without V-Sync.
+			It may take several seconds at a stable frame rate before the smoothing is initially activated. It will only be active on machines where performance is adequate to render frames at the refresh rate.
+		</member>
 		<member name="application/run/disable_stderr" type="bool" setter="" getter="" default="false">
 			If [code]true[/code], disables printing to standard error. If [code]true[/code], this also hides error and warning messages printed by [method @GlobalScope.push_error] and [method @GlobalScope.push_warning]. See also [member application/run/disable_stdout].
 			Changes to this setting will only be applied upon restarting the application.

main/main.cpp

@@ -470,6 +470,7 @@ void Main::print_help(const char *p_binary) {
 	OS::get_singleton()->print("  --disable-render-loop             Disable render loop so rendering only occurs when called explicitly from script.\n");
 	OS::get_singleton()->print("  --disable-crash-handler           Disable crash handler when supported by the platform code.\n");
 	OS::get_singleton()->print("  --fixed-fps <fps>                 Force a fixed number of frames per second. This setting disables real-time synchronization.\n");
+	OS::get_singleton()->print("  --delta-smoothing <enable>        Enable or disable frame delta smoothing ['enable', 'disable'].\n");
 	OS::get_singleton()->print("  --print-fps                       Print the frames per second to the stdout.\n");
 	OS::get_singleton()->print("\n");
 
@@ -794,6 +795,7 @@ Error Main::setup(const char *execpath, int argc, char *argv[], bool p_second_ph
 	Vector<String> breakpoints;
 	bool use_custom_res = true;
 	bool force_res = false;
+	bool delta_smoothing_override = false;
 
 	String default_renderer = "";
 	String default_renderer_mobile = "";
@@ -1003,6 +1005,29 @@ Error Main::setup(const char *execpath, int argc, char *argv[], bool p_second_ph
 				OS::get_singleton()->print("Missing tablet driver argument, aborting.\n");
 				goto error;
 			}
+		} else if (I->get() == "--delta-smoothing") {
+			if (I->next()) {
+				String string = I->next()->get();
+				bool recognised = false;
+				if (string == "enable") {
+					OS::get_singleton()->set_delta_smoothing(true);
+					delta_smoothing_override = true;
+					recognised = true;
+				}
+				if (string == "disable") {
+					OS::get_singleton()->set_delta_smoothing(false);
+					delta_smoothing_override = false;
+					recognised = true;
+				}
+				if (!recognised) {
+					OS::get_singleton()->print("Delta-smoothing argument not recognised, aborting.\n");
+					goto error;
+				}
+				N = I->next()->next();
+			} else {
+				OS::get_singleton()->print("Missing delta-smoothing argument, aborting.\n");
+				goto error;
+			}
 		} else if (I->get() == "--single-window") { // force single window
 
 			single_window = true;
@@ -1930,6 +1955,11 @@ Error Main::setup(const char *execpath, int argc, char *argv[], bool p_second_ph
 	OS::get_singleton()->set_low_processor_usage_mode_sleep_usec(
 			GLOBAL_DEF(PropertyInfo(Variant::INT, "application/run/low_processor_mode_sleep_usec", PROPERTY_HINT_RANGE, "0,33200,1,or_greater"), 6900)); // Roughly 144 FPS
 
+	GLOBAL_DEF("application/run/delta_smoothing", true);
+	if (!delta_smoothing_override) {
+		OS::get_singleton()->set_delta_smoothing(GLOBAL_GET("application/run/delta_smoothing"));
+	}
+
 	GLOBAL_DEF("display/window/ios/allow_high_refresh_rate", true);
 	GLOBAL_DEF("display/window/ios/hide_home_indicator", true);
 	GLOBAL_DEF("display/window/ios/hide_status_bar", true);

main/main_timer_sync.cpp

@@ -30,6 +30,9 @@
 
 #include "main_timer_sync.h"
 
+#include "core/os/os.h"
+#include "servers/display_server.h"
+
 void MainFrameTime::clamp_process_step(double min_process_step, double max_process_step) {
 	if (process_step < min_process_step) {
 		process_step = min_process_step;
@@ -40,6 +43,258 @@ void MainFrameTime::clamp_process_step(double min_process_step, double max_proce
 
 /////////////////////////////////
 
+void MainTimerSync::DeltaSmoother::update_refresh_rate_estimator(int64_t p_delta) {
+	// the calling code should prevent 0 or negative values of delta
+	// (preventing divide by zero)
+
+	// note that if the estimate gets locked, and something external changes this
+	// (e.g. user changes to non-vsync in the OS), then the results may be less than ideal,
+	// but usually it will detect this via the FPS measurement and not attempt smoothing.
+	// This should be a rare occurrence anyway, and will be cured next time user restarts game.
+	if (_estimate_locked) {
+		return;
+	}
+
+	// First average the delta over NUM_READINGS
+	_estimator_total_delta += p_delta;
+	_estimator_delta_readings++;
+
+	const int NUM_READINGS = 60;
+
+	if (_estimator_delta_readings < NUM_READINGS) {
+		return;
+	}
+
+	// use average
+	p_delta = _estimator_total_delta / NUM_READINGS;
+
+	// reset the averager for next time
+	_estimator_delta_readings = 0;
+	_estimator_total_delta = 0;
+
+	///////////////////////////////
+
+	int fps = Math::round(1000000.0 / p_delta);
+
+	// initial estimation, to speed up converging, special case we will estimate the refresh rate
+	// from the first average FPS reading
+	if (_estimated_fps == 0) {
+		// below 50 might be chugging loading stuff, or else
+		// dropping loads of frames, so the estimate will be inaccurate
+		if (fps >= 50) {
+			_estimated_fps = fps;
+#ifdef GODOT_DEBUG_DELTA_SMOOTHER
+			print_line("initial guess (average measured) refresh rate: " + itos(fps));
+#endif
+		} else {
+			// can't get started until above 50
+			return;
+		}
+	}
+
+	// we hit our exact estimated refresh rate.
+	// increase our confidence in the estimate.
+	if (fps == _estimated_fps) {
+		// note that each hit is an average of NUM_READINGS frames
+		_hits_at_estimated++;
+
+		if (_estimate_complete && _hits_at_estimated == 20) {
+			_estimate_locked = true;
+#ifdef GODOT_DEBUG_DELTA_SMOOTHER
+			print_line("estimate LOCKED at " + itos(_estimated_fps) + " fps");
+#endif
+			return;
+		}
+
+		// if we are getting pretty confident in this estimate, decide it is complete
+		// (it can still be increased later, and possibly lowered but only for a short time)
+		if ((!_estimate_complete) && (_hits_at_estimated > 2)) {
+			// when the estimate is complete we turn on smoothing
+			if (_estimated_fps) {
+				_estimate_complete = true;
+				_vsync_delta = 1000000 / _estimated_fps;
+
+#ifdef GODOT_DEBUG_DELTA_SMOOTHER
+				print_line("estimate complete. vsync_delta " + itos(_vsync_delta) + ", fps " + itos(_estimated_fps));
+#endif
+			}
+		}
+
+#ifdef GODOT_DEBUG_DELTA_SMOOTHER
+		if ((_hits_at_estimated % (400 / NUM_READINGS)) == 0) {
+			String sz = "hits at estimated : " + itos(_hits_at_estimated) + ", above : " + itos(_hits_above_estimated) + "( " + itos(_hits_one_above_estimated) + " ), below : " + itos(_hits_below_estimated) + " (" + itos(_hits_one_below_estimated) + " )";
+
+			print_line(sz);
+		}
+#endif
+
+		return;
+	}
+
+	const int SIGNIFICANCE_UP = 1;
+	const int SIGNIFICANCE_DOWN = 2;
+
+	// we are not usually interested in slowing the estimate
+	// but we may have overshot, so make it possible to reduce
+	if (fps < _estimated_fps) {
+		// micro changes
+		if (fps == (_estimated_fps - 1)) {
+			_hits_one_below_estimated++;
+
+			if ((_hits_one_below_estimated > _hits_at_estimated) && (_hits_one_below_estimated > SIGNIFICANCE_DOWN)) {
+				_estimated_fps--;
+				made_new_estimate();
+			}
+
+			return;
+		} else {
+			_hits_below_estimated++;
+
+			// don't allow large lowering if we are established at a refresh rate, as it will probably be dropped frames
+			bool established = _estimate_complete && (_hits_at_estimated > 10);
+
+			// macro changes
+			// note there is a large barrier to macro lowering. That is because it is more likely to be dropped frames
+			// than mis-estimation of the refresh rate.
+			if (!established) {
+				if (((_hits_below_estimated / 8) > _hits_at_estimated) && (_hits_below_estimated > SIGNIFICANCE_DOWN)) {
+					// decrease the estimate
+					_estimated_fps--;
+					made_new_estimate();
+				}
+			}
+
+			return;
+		}
+	}
+
+	// Changes increasing the estimate.
+	// micro changes
+	if (fps == (_estimated_fps + 1)) {
+		_hits_one_above_estimated++;
+
+		if ((_hits_one_above_estimated > _hits_at_estimated) && (_hits_one_above_estimated > SIGNIFICANCE_UP)) {
+			_estimated_fps++;
+			made_new_estimate();
+		}
+		return;
+	} else {
+		_hits_above_estimated++;
+
+		// macro changes
+		if ((_hits_above_estimated > _hits_at_estimated) && (_hits_above_estimated > SIGNIFICANCE_UP)) {
+			// increase the estimate
+			int change = fps - _estimated_fps;
+			change /= 2;
+			change = MAX(1, change);
+
+			_estimated_fps += change;
+			made_new_estimate();
+		}
+		return;
+	}
+}
+
+bool MainTimerSync::DeltaSmoother::fps_allows_smoothing(int64_t p_delta) {
+	_measurement_time += p_delta;
+	_measurement_frame_count++;
+
+	if (_measurement_frame_count == _measurement_end_frame) {
+		// only switch on or off if the estimate is complete
+		if (_estimate_complete) {
+			int64_t time_passed = _measurement_time - _measurement_start_time;
+
+			// average delta
+			time_passed /= MEASURE_FPS_OVER_NUM_FRAMES;
+
+			// estimate fps
+			if (time_passed) {
+				double fps = 1000000.0 / time_passed;
+				double ratio = fps / (double)_estimated_fps;
+
+				//print_line("ratio : " + String(Variant(ratio)));
+
+				if ((ratio > 0.95) && (ratio < 1.05)) {
+					_measurement_allows_smoothing = true;
+				} else {
+					_measurement_allows_smoothing = false;
+				}
+			}
+		} // estimate complete
+
+		// new start time for next iteration
+		_measurement_start_time = _measurement_time;
+		_measurement_end_frame += MEASURE_FPS_OVER_NUM_FRAMES;
+	}
+
+	return _measurement_allows_smoothing;
+}
+
+int64_t MainTimerSync::DeltaSmoother::smooth_delta(int64_t p_delta) {
+	// Conditions to disable smoothing.
+	// Note that vsync is a request, it cannot be relied on, the OS may override this.
+	// If the OS turns vsync on without vsync in the app, smoothing will not be enabled.
+	// If the OS turns vsync off with sync enabled in the app, the smoothing must detect this
+	// via the error metric and switch off.
+	// Also only try smoothing if vsync is enabled (classical vsync, not new types) ..
+	// This condition is currently checked before calling smooth_delta().
+	if (!OS::get_singleton()->is_delta_smoothing_enabled() || Engine::get_singleton()->is_editor_hint()) {
+		return p_delta;
+	}
+
+	// only attempt smoothing if vsync is selected
+	DisplayServer::VSyncMode vsync_mode = DisplayServer::get_singleton()->window_get_vsync_mode(DisplayServer::MAIN_WINDOW_ID);
+	if (vsync_mode != DisplayServer::VSYNC_ENABLED) {
+		return p_delta;
+	}
+
+	// Very important, ignore long deltas and pass them back unmodified.
+	// This is to deal with resuming after suspend for long periods.
+	if (p_delta > 1000000) {
+		return p_delta;
+	}
+
+	// keep a running guesstimate of the FPS, and turn off smoothing if
+	// conditions not close to the estimated FPS
+	if (!fps_allows_smoothing(p_delta)) {
+		return p_delta;
+	}
+
+	// we can't cope with negative deltas .. OS bug on some hardware
+	// and also very small deltas caused by vsync being off.
+	// This could possibly be part of a hiccup, this value isn't fixed in stone...
+	if (p_delta < 1000) {
+		return p_delta;
+	}
+
+	// note still some vsync off will still get through to this point...
+	// and we need to cope with it by not converging the estimator / and / or not smoothing
+	update_refresh_rate_estimator(p_delta);
+
+	// no smoothing until we know what the refresh rate is
+	if (!_estimate_complete) {
+		return p_delta;
+	}
+
+	// accumulate the time we have available to use
+	_leftover_time += p_delta;
+
+	// how many vsyncs units can we fit?
+	int64_t units = _leftover_time / _vsync_delta;
+
+	// a delta must include minimum 1 vsync
+	// (if it is less than that, it is either random error or we are no longer running at the vsync rate,
+	// in which case we should switch off delta smoothing, or re-estimate the refresh rate)
+	units = MAX(units, 1);
+
+	_leftover_time -= units * _vsync_delta;
+	// print_line("units " + itos(units) + ", leftover " + itos(_leftover_time/1000) + " ms");
+
+	return units * _vsync_delta;
+}
+
+/////////////////////////////////////
+
 // returns the fraction of p_physics_step required for the timer to overshoot
 // before advance_core considers changing the physics_steps return from
 // the typical values as defined by typical_physics_steps
@@ -236,6 +491,8 @@ double MainTimerSync::get_cpu_process_step() {
 	uint64_t cpu_ticks_elapsed = current_cpu_ticks_usec - last_cpu_ticks_usec;
 	last_cpu_ticks_usec = current_cpu_ticks_usec;
 
+	cpu_ticks_elapsed = _delta_smoother.smooth_delta(cpu_ticks_elapsed);
+
 	return cpu_ticks_elapsed / 1000000.0;
 }
 

main/main_timer_sync.h

@@ -33,6 +33,9 @@
 
 #include "core/config/engine.h"
 
+// Uncomment this define to get more debugging logs for the delta smoothing.
+// #define GODOT_DEBUG_DELTA_SMOOTHER
+
 struct MainFrameTime {
 	double process_step; // delta time to advance during process()
 	int physics_steps; // number of times to iterate the physics engine
@@ -42,6 +45,66 @@ struct MainFrameTime {
 };
 
 class MainTimerSync {
+	class DeltaSmoother {
+	public:
+		// pass the recorded delta, returns a smoothed delta
+		int64_t smooth_delta(int64_t p_delta);
+
+	private:
+		void update_refresh_rate_estimator(int64_t p_delta);
+		bool fps_allows_smoothing(int64_t p_delta);
+
+		// estimated vsync delta (monitor refresh rate)
+		int64_t _vsync_delta = 16666;
+
+		// keep track of accumulated time so we know how many vsyncs to advance by
+		int64_t _leftover_time = 0;
+
+		// keep a rough measurement of the FPS as we run.
+		// If this drifts a long way below or above the refresh rate, the machine
+		// is struggling to keep up, and we can switch off smoothing. This
+		// also deals with the case that the user has overridden the vsync in the GPU settings,
+		// in which case we don't want to try smoothing.
+		static const int MEASURE_FPS_OVER_NUM_FRAMES = 64;
+
+		int64_t _measurement_time = 0;
+		int64_t _measurement_frame_count = 0;
+		int64_t _measurement_end_frame = MEASURE_FPS_OVER_NUM_FRAMES;
+		int64_t _measurement_start_time = 0;
+		bool _measurement_allows_smoothing = true;
+
+		// we can estimate the fps by growing it on condition
+		// that a large proportion of frames are higher than the current estimate.
+		int32_t _estimated_fps = 0;
+		int32_t _hits_at_estimated = 0;
+		int32_t _hits_above_estimated = 0;
+		int32_t _hits_below_estimated = 0;
+		int32_t _hits_one_above_estimated = 0;
+		int32_t _hits_one_below_estimated = 0;
+		bool _estimate_complete = false;
+		bool _estimate_locked = false;
+
+		// data for averaging the delta over a second or so
+		// to prevent spurious values
+		int64_t _estimator_total_delta = 0;
+		int32_t _estimator_delta_readings = 0;
+
+		void made_new_estimate() {
+			_hits_above_estimated = 0;
+			_hits_at_estimated = 0;
+			_hits_below_estimated = 0;
+			_hits_one_above_estimated = 0;
+			_hits_one_below_estimated = 0;
+
+			_estimate_complete = false;
+
+#ifdef GODOT_DEBUG_DELTA_SMOOTHER
+			print_line("estimated fps " + itos(_estimated_fps));
+#endif
+		}
+
+	} _delta_smoother;
+
 	// wall clock time measured on the main thread
 	uint64_t last_cpu_ticks_usec = 0;
 	uint64_t current_cpu_ticks_usec = 0;