CLK/ClockReceiver/VSyncPredictor.hpp

//
//  VSyncPredictor.hpp
//  Clock Signal
//
//  Created by Thomas Harte on 14/06/2020.
//  Copyright © 2020 Thomas Harte. All rights reserved.
//

#pragma once

#include "TimeTypes.hpp"
#include <cassert>
#include <cmath>
#include <cstdio>

namespace Time {

/*!
	For platforms that provide no avenue into vsync tracking other than block-until-sync,
	this class tracks: (i) how long frame draw takes; (ii) the apparent frame period; and
	(iii) optionally, timer jitter; in order to suggest when you should next start drawing.
*/
class VSyncPredictor {
public:
	/*!
		Announces to the predictor that the work of producing an output frame has begun.
	*/
	void begin_redraw() {
		redraw_begin_time_ = nanos_now();
	}

	/*!
		Announces to the predictor that the work of producing an output frame has ended;
		the predictor will use the amount of time between each begin/end pair to modify
		its expectations as to how long it takes to draw a frame.
	*/
	void end_redraw() {
		redraw_period_.post(nanos_now() - redraw_begin_time_);
	}

	/*!
		Informs the predictor that a block-on-vsync has just ended, i.e. that the moment this
		machine calls retrace is now. The predictor uses these notifications to estimate output
		frame rate.
	*/
	void announce_vsync() {
		const auto now = nanos_now();

		if(last_vsync_) {
			last_vsync_ += frame_duration_;
			vsync_jitter_.post(last_vsync_ - now);
			last_vsync_ = (last_vsync_ + now) >> 1;
		} else {
			last_vsync_ = now;
		}
	}

	/*!
		Sets the frame rate for the target display.
	*/
	void set_frame_rate(float rate) {
		frame_duration_ = Nanos(1'000'000'000.0f / rate);
	}

	/*!
		@returns The time this class currently believes a whole frame occupies.
	*/
	Time::Nanos frame_duration() {
		return frame_duration_;
	}

	/*!
		Adds a record of how much jitter was experienced in scheduling; these values will be
		factored into the @c suggested_draw_time if supplied.

		A positive number means the timer occurred late. A negative number means it occurred early.
	*/
	void add_timer_jitter(Time::Nanos jitter) {
		timer_jitter_.post(jitter);
	}

	/*!
		Announces to the vsync predictor that output is now paused. This ends frame period
		calculations until the next announce_vsync() restarts frame-length counting.
	*/
	void pause() {
		last_vsync_ = 0;
	}

	/*!
		@return The time at which redrawing should begin, given the predicted frame period, how
		long it appears to take to draw a frame and how much jitter there is in scheduling
		(if those figures are being supplied).
	*/
	Nanos suggested_draw_time() {
		const auto mean = redraw_period_.mean() + timer_jitter_.mean() + vsync_jitter_.mean();
		const auto variance = redraw_period_.variance() + timer_jitter_.variance() + vsync_jitter_.variance();

		// Permit three standard deviations from the mean, to cover 99.9% of cases.
		const auto period = mean + Nanos(3.0f * sqrt(float(variance)));

		return last_vsync_ + frame_duration_ - period;
	}

private:
	class VarianceCollector {
		public:
			VarianceCollector(Time::Nanos default_value) {
				sum_ = default_value * 128;
				for(int c = 0; c < 128; ++c) {
					history_[c] = default_value;
				}
			}

			void post(Time::Nanos value) {
				sum_ -= history_[write_pointer_];
				sum_ += value;
				history_[write_pointer_] = value;
				write_pointer_ = (write_pointer_ + 1) & 127;
			}

			Time::Nanos mean() {
				return sum_ / 128;
			}

			Time::Nanos variance() {
				// I haven't yet come up with a better solution that calculating this
				// in whole every time, given the way that the mean mutates.
				Time::Nanos variance = 0;
				for(int c = 0; c < 128; ++c) {
					const auto difference = ((history_[c] * 128) - sum_) / 128;
					variance += (difference * difference);
				}
				return variance / 128;
			}

		private:
			Time::Nanos sum_;
			Time::Nanos history_[128];
			size_t write_pointer_ = 0;
	};

	Nanos redraw_begin_time_ = 0;
	Nanos last_vsync_ = 0;
	Nanos frame_duration_ = 1'000'000'000 / 60;

	VarianceCollector vsync_jitter_{0};
	VarianceCollector redraw_period_{1'000'000'000 / 60};	// A less convincing first guess.
	VarianceCollector timer_jitter_{0};						// Seed at 0 in case this feature isn't used by the owner.
};

}