Enhances reported data.

Outputs/CRT/CRT.cpp

@@ -472,9 +472,11 @@ Outputs::Display::ScanStatus CRT::get_scaled_scan_status() const {
 	Outputs::Display::ScanStatus status;
 	status.field_duration = float(vertical_flywheel_->get_locked_period()) / float(time_multiplier_);
 	status.field_duration_gradient = float(vertical_flywheel_->get_last_period_adjustment()) / float(time_multiplier_);
+	status.retrace_duration = float(vertical_flywheel_->get_retrace_period()) / float(time_multiplier_);
 	status.current_position =
 		std::max(0.0f,
 			float(vertical_flywheel_->get_current_output_position()) / (float(vertical_flywheel_->get_locked_period()) * float(time_multiplier_))
 		);
+	status.hsync_count = vertical_flywheel_->get_number_of_retraces();
 	return status;
 }

Outputs/CRT/Internals/Flywheel.hpp

@@ -191,6 +191,20 @@ struct Flywheel {
 		return result;
 	}
 
+	/*!
+		@returns A count of the number of retraces so far performed.
+	*/
+	inline int get_number_of_retraces() {
+		return number_of_retraces_;
+	}
+
+	/*!
+		@returns The amount of time this flywheel spends in retrace, as supplied at construction.
+	*/
+	inline int get_retrace_period() {
+		return retrace_time_;
+	}
+
 	/*!
 		@returns `true` if a sync is expected soon or if the time at which it was expected (or received) was recent.
 	*/
@@ -201,17 +215,18 @@ struct Flywheel {
 	}
 
 	private:
-		const int standard_period_;		// the normal length of time between syncs
-		const int retrace_time_;		// a constant indicating the amount of time it takes to perform a retrace
-		const int sync_error_window_;	// a constant indicating the window either side of the next expected sync in which we'll accept other syncs
+		const int standard_period_;		// The idealised length of time between syncs.
+		const int retrace_time_;		// A constant indicating the amount of time it takes to perform a retrace.
+		const int sync_error_window_;	// A constant indicating the window either side of the next expected sync in which we'll accept other syncs.
 
-		int counter_ = 0;				// time since the _start_ of the last sync
-		int counter_before_retrace_;	// the value of _counter immediately before retrace began
-		int expected_next_sync_;		// our current expection of when the next sync will be encountered (which implies velocity)
+		int counter_ = 0;				// Time since the _start_ of the last sync.
+		int counter_before_retrace_;	// The value of _counter immediately before retrace began.
+		int expected_next_sync_;		// Our current expection of when the next sync will be encountered (which implies velocity).
 
-		int number_of_surprises_ = 0;	// a count of the surprising syncs
+		int number_of_surprises_ = 0;	// A count of the surprising syncs.
+		int number_of_retraces_ = 0;	// A count of the number of retraces to date.
 
-		int last_adjustment_ = 0;		// The amount by which
+		int last_adjustment_ = 0;		// The amount by which expected_next_sync_ was adjusted at the last sync.
 
 		/*
 			Implementation notes:

Outputs/ScanTarget.hpp

@@ -311,15 +311,23 @@ struct ScanTarget {
 };
 
 struct ScanStatus {
-	/// The current (prediced) length of a field.
+	/// The current (prediced) length of a field (including retrace).
 	Time::Seconds field_duration;
 	/// The difference applied to the field_duration estimate during the last field.
 	Time::Seconds field_duration_gradient;
-	/// The distance into the current field, from 0 (start of field) to 1 (end of field).
-	/// This is unlikely to be linear but should increase monotonically, being a measure
+	/// The amount of time this device spends in retrace.
+	Time::Seconds retrace_duration;
+	/// The distance into the current field, from a small negative amount (in retrace) through
+	/// 0 (start of visible area field) to 1 (end of field).
+	///
+	/// This will increase monotonically, being a measure
 	/// of the current vertical position — i.e. if current_position = 0.8 then a caller can
 	/// conclude that the top 80% of the visible part of the display has been painted.
 	float current_position;
+	/// The total number of hsyncs so far encountered;
+	int hsync_count;
+	/// @c true if retrace is currently going on; @c false otherwise.
+	bool is_in_retrace;
 
 	/*!
 		@returns this ScanStatus, with time-relative fields scaled by dividing them by @c dividend.
@@ -328,7 +336,9 @@ struct ScanStatus {
 		const ScanStatus result = {
 			.field_duration = field_duration / dividend,
 			.field_duration_gradient = field_duration_gradient / dividend,
-			.current_position = current_position
+			.retrace_duration = retrace_duration / dividend,
+			.current_position = current_position,
+			.hsync_count = hsync_count,
 		};
 		return result;
 	}
@@ -340,7 +350,9 @@ struct ScanStatus {
 		const ScanStatus result = {
 			.field_duration = field_duration * multiplier,
 			.field_duration_gradient = field_duration_gradient * multiplier,
-			.current_position = current_position
+			.retrace_duration = retrace_duration * multiplier,
+			.current_position = current_position,
+			.hsync_count = hsync_count,
 		};
 		return result;
 	}