Feature/fix fps calculation (#191)

* Fix PeriodicAsyncTimer for Avalonia and Blazor apps for more accurate timer.

* Make common FrameTimer class in the Highbyte.DotNet6502.Systems library that is used by Avalonia, Blazor  WASM and Headless apps.

Author: highbyte

src/apps/Avalonia/Highbyte.DotNet6502.App.Avalonia.Core/PeriodicAsyncTimer.cs

@@ -1,84 +1,16 @@
-using System;
-using System.Diagnostics;
-using System.Threading;
-using System.Threading.Tasks;
 using Avalonia.Threading;
-using Highbyte.DotNet6502.Systems;
+using Highbyte.DotNet6502.Systems.Timing;
 
 namespace Highbyte.DotNet6502.App.Avalonia.Core;
 
 /// <summary>
-/// A timer that uses .NET built-in PeriodicTimer.
-/// As PeriodicTimer runs on the thread it is created on, we need to marshal the Elapsed event to the UI thread.
+/// Avalonia-specific <see cref="FrameTimer"/> that marshals the Elapsed event to the UI thread.
+/// All pacing/precision logic lives in <see cref="FrameTimer"/>.
 /// </summary>
-public class PeriodicAsyncTimer : IScriptingTickTimer, IAsyncDisposable
+public sealed class PeriodicAsyncTimer : FrameTimer
 {
-    private CancellationTokenSource? _cts;
-    private readonly Stopwatch _stopwatch = Stopwatch.StartNew();
-    private long _lastTick;
-
-    public double IntervalMilliseconds { get; set; }
-    public long TimeSinceLastTickMilliseconds { get; private set; }
-
-    public event EventHandler? Elapsed;
-
-    event EventHandler IScriptingTickTimer.Elapsed
-    {
-        add => Elapsed += value;
-        remove => Elapsed -= value;
-    }
-
-    public void Start()
-    {
-        Stop();
-        _cts?.Cancel();
-        _cts?.Dispose();
-        _cts = new CancellationTokenSource();
-        _ = StartTimerAsync();
-    }
-
-    private async Task StartTimerAsync()
-    {
-        var timer = new PeriodicTimer(TimeSpan.FromMilliseconds(IntervalMilliseconds));
-
-        try
-        {
-            while (await timer.WaitForNextTickAsync(_cts!.Token))
-            {
-                var time = _stopwatch.ElapsedMilliseconds;
-                TimeSinceLastTickMilliseconds = time - _lastTick;
-                _lastTick = time;
-
-                // Marshal to UI thread for Avalonia
-                await Dispatcher.UIThread.InvokeAsync(() =>
-                {
-                    Elapsed?.Invoke(this, EventArgs.Empty);
-                }, DispatcherPriority.Render);
-            }
-        }
-        catch (OperationCanceledException)
-        {
-            // Expected when cancellation is requested
-        }
-        finally
-        {
-            timer.Dispose();
-        }
-    }
-
-    public void Stop()
-    {
-        _cts?.Cancel();
-    }
-
-    public void Dispose()
-    {
-        Stop();
-    }
-
-    public ValueTask DisposeAsync()
+    public PeriodicAsyncTimer()
+        : base(action => Dispatcher.UIThread.InvokeAsync(action, DispatcherPriority.Render).GetTask())
     {
-        Dispose();
-        return ValueTask.CompletedTask;
     }
 }

src/apps/Avalonia/Highbyte.DotNet6502.App.Avalonia.Core/ViewModels/MainViewModel.cs

@@ -1356,8 +1356,8 @@ private void UpdateStatusFps()
         {
             var fpsStat = _hostApp.GetStats()
                 .FirstOrDefault(s => s.name.EndsWith("OnUpdateFPS", StringComparison.OrdinalIgnoreCase));
-            if (fpsStat.stat is Highbyte.DotNet6502.Systems.Instrumentation.Stats.AveragedStat averaged && averaged.Value.HasValue)
-                StatusFpsText = $"{Math.Round(averaged.Value.Value)} fps";
+            if (fpsStat.stat is Highbyte.DotNet6502.Systems.Instrumentation.Stats.PerSecondTimedStat perSecond && perSecond.Value.HasValue)
+                StatusFpsText = $"{Math.Round(perSecond.Value.Value)} fps";
             else
                 StatusFpsText = string.Empty;
         }

src/apps/Highbyte.DotNet6502.App.Headless/HeadlessHostApp.cs

@@ -3,6 +3,7 @@
 using Highbyte.DotNet6502.Systems;
 using Highbyte.DotNet6502.Systems.Audio;
 using Highbyte.DotNet6502.Systems.Input;
+using Highbyte.DotNet6502.Systems.Timing;
 using Microsoft.Extensions.Logging;
 
 namespace Highbyte.DotNet6502.App.Headless;
@@ -16,7 +17,7 @@ public class HeadlessHostApp : HostApp<NullInputHandlerContext, NullAudioHandler
     private new readonly ILogger _logger;
     private readonly CancellationTokenSource _appCts;
 
-    private HeadlessPeriodicTimer? _updateTimer;
+    private FrameTimer? _updateTimer;
 
     // IDebuggableHostApp
     public bool WaitForExternalDebugger { get; set; }
@@ -112,7 +113,7 @@ public override void OnAfterClose()
     // --- Scripting timer ---
 
     protected override IScriptingTickTimer CreateScriptingTickTimer(double intervalMs) =>
-        new HeadlessPeriodicTimer { IntervalMilliseconds = intervalMs };
+        new FrameTimer { IntervalMilliseconds = intervalMs };
 
     protected override void OnScriptingEngineSet()
     {
@@ -161,10 +162,10 @@ public override void OnAfterRunEmulatorOneFrame(ExecEvaluatorTriggerResult execE
 
     // --- Timer helpers ---
 
-    private HeadlessPeriodicTimer CreateUpdateTimerForSystem(ISystem system)
+    private FrameTimer CreateUpdateTimerForSystem(ISystem system)
     {
         double updateIntervalMS = (1 / system.Screen.RefreshFrequencyHz) * 1000;
-        var timer = new HeadlessPeriodicTimer { IntervalMilliseconds = updateIntervalMS };
+        var timer = new FrameTimer { IntervalMilliseconds = updateIntervalMS };
         timer.Elapsed += UpdateTimerElapsed;
         return timer;
     }

src/apps/Highbyte.DotNet6502.App.Headless/HeadlessPeriodicTimer.cs

@@ -14,6 +14,7 @@
 using Highbyte.DotNet6502.Systems.Instrumentation.Stats;
 using Highbyte.DotNet6502.Systems.Rendering;
 using Highbyte.DotNet6502.Systems.Rendering.VideoFrameProvider;
+using Highbyte.DotNet6502.Systems.Timing;
 using Toolbelt.Blazor.Gamepad;
 
 namespace Highbyte.DotNet6502.App.WASM.Emulator.Skia;
@@ -43,7 +44,7 @@ public class SkiaWASMHostApp : HostApp<AspNetInputHandlerContext, WASMAudioHandl
 
     private readonly IJSRuntime _jsRuntime;
     private readonly Highbyte.DotNet6502.App.WASM.Pages.Index _wasmHostUIViewModel;
-    private PeriodicAsyncTimer? _updateTimer;
+    private FrameTimer? _updateTimer;
 
     private WasmMonitor _monitor = default!;
     public WasmMonitor Monitor => _monitor;
@@ -213,11 +214,11 @@ public override void OnAfterClose()
     }
 
 
-    private PeriodicAsyncTimer CreateUpdateTimerForSystem(ISystem system)
+    private FrameTimer CreateUpdateTimerForSystem(ISystem system)
     {
         // Number of milliseconds between each invokation of the main loop. 60 fps -> (1/60) * 1000  -> approx 16.6667ms
         double updateIntervalMS = (1 / system.Screen.RefreshFrequencyHz) * 1000;
-        var updateTimer = new PeriodicAsyncTimer();
+        var updateTimer = new FrameTimer();
         updateTimer.IntervalMilliseconds = updateIntervalMS;
         updateTimer.Elapsed += UpdateTimerElapsed;
         return updateTimer;

src/apps/Highbyte.DotNet6502.App.WASM/Emulator/Skia/PeriodicAsyncTimer.cs

@@ -2,45 +2,63 @@
 
 namespace Highbyte.DotNet6502.Systems.Instrumentation.Stats;
 
-// Credit to instrumentation/stat code to: https://github.com/davidwengier/Trains.NET    
-public class PerSecondTimedStat : AveragedStat
+// Credit to instrumentation/stat code to: https://github.com/davidwengier/Trains.NET
+public class PerSecondTimedStat : IStat
 {
-    private readonly Stopwatch _sw;
-    public PerSecondTimedStat()
-        : base(60) // Average over 60 samples
+    private const int SampleCount = 60;
+
+    private readonly Stopwatch _sw = new();
+    private double? _emaElapsedMs;
+    private double? _fakeValue;
+
+    // Compute FPS as 1 / E[T], not E[1/T]. The latter is upward-biased when intervals vary
+    // (Jensen's inequality), which on browsers - where Task.Delay clamping causes 30%+ jitter
+    // in frame intervals - makes a true 59.83 fps loop read as ~62 fps. Averaging the elapsed
+    // time and inverting gives an unbiased estimate of the true average rate.
+    public double? Value
     {
-        _sw = new Stopwatch();
+        get
+        {
+            if (_fakeValue.HasValue)
+                return _fakeValue.Value;
+            if (!_emaElapsedMs.HasValue || _emaElapsedMs.Value <= 0)
+                return null;
+            return 1000.0 / _emaElapsedMs.Value;
+        }
     }
 
     public void Update()
     {
         if (_sw.IsRunning)
         {
-            //var elapsedMs = _sw.ElapsedMilliseconds;
             var elapsedMs = _sw.Elapsed.TotalMilliseconds;
 #if DEBUG
             if (elapsedMs == 0)
                 throw new NotImplementedException("Elapsed 0.0 milliseconds, cannot handle division by 0");
 #endif
-            var perSecond = 1000.0 / elapsedMs;
-            SetValue(perSecond);
+            if (_emaElapsedMs == null)
+                _emaElapsedMs = elapsedMs;
+            else
+                _emaElapsedMs = (_emaElapsedMs.Value * (SampleCount - 1) + elapsedMs) / SampleCount;
         }
         _sw.Restart();
     }
 
-
-    public override string GetDescription()
+    public string GetDescription()
     {
-        if (Value == null)
+        var value = Value;
+        if (value == null)
             return "null";
-        if (Value < 0.01)
+        if (value < 0.01)
             return "< 0.01";
-        return Math.Round(Value ?? 0, 2).ToString();
+        return Math.Round(value ?? 0, 2).ToString();
     }
 
+    public bool ShouldShow() => Value.HasValue;
+
     // For unit testing
     public void SetFakeFPSValue(double fps)
     {
-        SetValue(fps);
+        _fakeValue = fps;
     }
 }