Feature: mouse capture to main Window (#1805)

* feat: window mouse relative mode (crossplatform)

refactor: disable/enable mouse capture, inside ViewBox

feature: mouse capture (crossplatform)

Signed-off-by: Maximilien Noal <noal.maximilien@gmail.com>

fix: address mouse capture review feedback (#1962)

* Initial plan

* fix: address all mouse capture PR review comments

Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

fix: linux xorg mouse grab / release API usage

feat: implement mouse capture functionality for macOS, Windows, and Linux

refactor: Debug.Assert pr feedback

chore: remove asserts

refactor: X11 backend for mouse capture

refactor: remove mouse capture backend implementations and update MainWindow for pointer capture

refactor: simplify mouse capture logic by removing pointer parameter and related code

chore: Remove mouse capture hint logic and update cycles UI focus

Removed UpdateMouseCaptureHint from MainWindowViewModel and its usage. Assigned x:Name to cycles limiting NumericUpDown and added a GotFocus handler to redirect focus to the video buffer, preventing unwanted focus retention. Updated MainWindow constructor and cleaned up related code.

fix: Add focus handler for Time Modifier NumericUpDown

Assigned x:Name to the Time Modifier NumericUpDown and wired its GotFocus event to reuse the CyclesLimitingNumericUpDown_GotFocus handler, ensuring consistent focus behavior with other numeric controls.

chore: Removed video Scale menu (does not work anymore)

chore: removed Alt-Fx tooltips (does not work since Docker framework usage)

feat: implement SDL2 relative mouse capture via Silk.NET.SDL

Agent-Logs-Url: https://github.com/OpenRakis/Spice86/sessions/2ec37724-28f3-4554-87ea-77d4ac254956

Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

fix: rename SdlDeltaScale to VirtualScreenWidth and fix typo

Agent-Logs-Url: https://github.com/OpenRakis/Spice86/sessions/2ec37724-28f3-4554-87ea-77d4ac254956

Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

feat: introduce IMouseCaptureBackend wrapper with WindowsMouseCaptureBackend

Agent-Logs-Url: https://github.com/OpenRakis/Spice86/sessions/f8d95506-9f12-49e7-bdd2-d1d12481410c

Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

fix: guard OnClosed unsubscribe by UsesRelativeMouseMode and remove unused Marshal calls

Agent-Logs-Url: https://github.com/OpenRakis/Spice86/sessions/f8d95506-9f12-49e7-bdd2-d1d12481410c

Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

fix: restore mouse capture hint in window title bar

Agent-Logs-Url: https://github.com/OpenRakis/Spice86/sessions/12eed9de-aed2-49b0-b862-7c9f82e8b39b

Co-authored-by: maximilien-noal <1087524+maximilien-noal@users.noreply.github.com>

fix: Dispose pattern

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

* chore: remove part of a comment

---------

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Author: maximilien-noal

src/Directory.Packages.props

@@ -58,6 +58,7 @@
     <PackageVersion Include="Xaml.Behaviors.Avalonia" Version="12.0.0" />
     <PackageVersion Include="Spice86.Audio" Version="11.4.0" />
     <PackageVersion Include="FastExpressionCompiler" Version="5.4.1" />
+    <PackageVersion Include="Silk.NET.SDL" Version="2.23.0" />
     <PackageVersion Include="Tmds.DBus.Protocol" Version="0.92.0" />
   </ItemGroup>
 </Project>

src/Spice86/App.axaml.cs

@@ -53,11 +53,6 @@ private void OnSplashWindowLoaded(
                 desktop.Args!)!;
         Spice86DependencyInjection dependencyInjection = new(configuration, mainWindow);
         if (mainWindow.DataContext is MainWindowViewModel mainVm) {
-            mainVm.CloseMainWindow += (_, _) => mainWindow.Close();
-            mainVm.InvalidateBitmap += mainWindow.Image.InvalidateVisual;
-            mainWindow.Image.PointerMoved += (s, e) => mainVm.OnMouseMoved(e, mainWindow.Image);
-            mainWindow.Image.PointerPressed += (s, e) => mainVm.OnMouseButtonDown(e, mainWindow.Image);
-            mainWindow.Image.PointerReleased += (s, e) => mainVm.OnMouseButtonUp(e, mainWindow.Image);
             mainVm.Disposing += dependencyInjection.Dispose;
         }
         desktop.MainWindow = mainWindow;

src/Spice86/Native/IMouseCaptureBackend.cs

@@ -0,0 +1,47 @@
+namespace Spice86.Native;
+
+using System;
+
+/// <summary>
+/// Abstraction over platform-specific mouse capture strategies.
+/// </summary>
+internal interface IMouseCaptureBackend : IDisposable {
+    /// <summary>
+    /// Gets a value indicating whether mouse capture is currently active.
+    /// </summary>
+    bool IsCaptured { get; }
+
+    /// <summary>
+    /// Gets a value indicating whether this backend hides the cursor and reports only relative
+    /// mouse deltas (e.g. SDL relative mode). When <see langword="false"/>, the cursor remains
+    /// visible and the host Avalonia pointer events continue to carry absolute coordinates.
+    /// </summary>
+    bool UsesRelativeMouseMode { get; }
+
+    /// <summary>
+    /// Performs any one-time platform initialisation required before
+    /// <see cref="EnableCapture"/> or <see cref="DisableCapture"/> may be called.
+    /// </summary>
+    /// <param name="nativeWindowHandle">
+    /// The platform-native window handle (HWND on Windows, X11 Window ID on Linux, NSWindow* on macOS).
+    /// </param>
+    /// <returns><see langword="true"/> if initialisation succeeded; otherwise <see langword="false"/>.</returns>
+    bool TryInitialize(nint nativeWindowHandle);
+
+    /// <summary>Enables mouse capture.</summary>
+    /// <returns><see langword="true"/> if capture was successfully enabled.</returns>
+    bool EnableCapture();
+
+    /// <summary>Disables mouse capture.</summary>
+    /// <returns><see langword="true"/> if capture was successfully disabled.</returns>
+    bool DisableCapture();
+
+    /// <summary>
+    /// Returns the accumulated relative mouse motion since the last call.
+    /// Always returns <c>(0, 0)</c> for backends where <see cref="UsesRelativeMouseMode"/> is
+    /// <see langword="false"/>.
+    /// </summary>
+    /// <param name="dx">Horizontal delta in pixels (positive = right).</param>
+    /// <param name="dy">Vertical delta in pixels (positive = down).</param>
+    void GetRelativeMouseDelta(out int dx, out int dy);
+}

src/Spice86/Native/SdlMouseCapture.cs

@@ -0,0 +1,160 @@
+namespace Spice86.Native;
+
+using Silk.NET.SDL;
+
+using System;
+using System.IO;
+
+/// <summary>
+/// SDL2-based mouse capture backend for non-Windows platforms.
+/// Uses <c>SDL_SetRelativeMouseMode</c> to hide the cursor and report relative mouse deltas.
+/// Precompiled SDL2 native libraries are bundled via Silk.NET.SDL (Ultz.Native.SDL),
+/// covering macOS (universal) and Linux (x64/arm64/arm).
+/// </summary>
+internal sealed class SdlMouseCapture : IMouseCaptureBackend {
+    private Sdl? _sdl;
+    private bool _initialized;
+    private bool _isCaptured;
+    private bool _disposed;
+
+    /// <summary>
+    /// Gets a value indicating whether the SDL subsystem was successfully initialized.
+    /// </summary>
+    public bool IsInitialized => _initialized;
+
+    /// <summary>
+    /// Gets a value indicating whether relative mouse capture is currently active.
+    /// </summary>
+    public bool IsCaptured => _isCaptured;
+
+    /// <inheritdoc/>
+    /// <remarks><see langword="true"/>: cursor is hidden and only deltas are reported.</remarks>
+    public bool UsesRelativeMouseMode => true;
+
+    /// <summary>
+    /// Initializes the SDL video subsystem.
+    /// If the SDL2 native library is unavailable, this returns <see langword="false"/> without throwing.
+    /// </summary>
+    /// <param name="nativeWindowHandle">The platform-native window handle (HWND on Windows, X11 Window ID on Linux, NSWindow* on macOS).</param>
+    /// <returns><see langword="true"/> if initialization succeeded; otherwise <see langword="false"/>.</returns>
+    public bool TryInitialize(nint nativeWindowHandle) {
+        if (_initialized) {
+            return true;
+        }
+
+        if (nativeWindowHandle == nint.Zero) {
+            return false;
+        }
+
+        try {
+            _sdl = Sdl.GetApi();
+        } catch (FileNotFoundException) {
+            return false;
+        } catch (DllNotFoundException) {
+            return false;
+        }
+
+        // Suppress SDL's default signal handlers so they don't interfere with the host app.
+        _sdl.SetHint("SDL_NO_SIGNAL_HANDLERS", "1");
+
+        // Initialize only the video subsystem so SDL can manage mouse state.
+        int result = _sdl.Init(Sdl.InitVideo);
+        if (result != 0) {
+            _sdl.Dispose();
+            _sdl = null;
+            return false;
+        }
+
+        _initialized = true;
+        return true;
+    }
+
+    /// <summary>
+    /// Enables SDL relative mouse mode.
+    /// The cursor is hidden and mouse motion is reported as relative deltas only.
+    /// </summary>
+    /// <returns><see langword="true"/> if relative mode was enabled successfully.</returns>
+    public bool EnableCapture() {
+        if (!_initialized || _isCaptured || _sdl is null) {
+            return false;
+        }
+
+        int result = _sdl.SetRelativeMouseMode(SdlBool.True);
+        if (result != 0) {
+            return false;
+        }
+
+        _isCaptured = true;
+        return true;
+    }
+
+    /// <summary>
+    /// Disables SDL relative mouse mode, restoring normal cursor behaviour.
+    /// </summary>
+    /// <returns><see langword="true"/> if relative mode was disabled successfully.</returns>
+    public bool DisableCapture() {
+        if (!_initialized || !_isCaptured || _sdl is null) {
+            return false;
+        }
+
+        int result = _sdl.SetRelativeMouseMode(SdlBool.False);
+        if (result != 0) {
+            return false;
+        }
+
+        _isCaptured = false;
+        return true;
+    }
+
+    /// <summary>
+    /// Retrieves the accumulated relative mouse motion since the last call.
+    /// Analogous to SDL_GetRelativeMouseState used in dosbox-staging.
+    /// </summary>
+    /// <param name="dx">Horizontal delta in screen pixels (positive = right).</param>
+    /// <param name="dy">Vertical delta in screen pixels (positive = down).</param>
+    public void GetRelativeMouseDelta(out int dx, out int dy) {
+        if (!_initialized || _sdl is null) {
+            dx = 0;
+            dy = 0;
+            return;
+        }
+
+        // SDL_PumpEvents processes pending OS events so GetRelativeMouseState is up to date.
+        _sdl.PumpEvents();
+
+        int x = 0;
+        int y = 0;
+        unsafe {
+            _sdl.GetRelativeMouseState(&x, &y);
+        }
+
+        dx = x;
+        dy = y;
+    }
+
+    /// <inheritdoc/>
+    public void Dispose() {
+        if (_disposed) {
+            return;
+        }
+
+        _disposed = true;
+
+        if (_sdl is null) {
+            return;
+        }
+
+        if (_isCaptured) {
+            _sdl.SetRelativeMouseMode(SdlBool.False);
+            _isCaptured = false;
+        }
+
+        if (_initialized) {
+            _sdl.QuitSubSystem(Sdl.InitVideo);
+            _initialized = false;
+        }
+
+        _sdl.Dispose();
+        _sdl = null;
+    }
+}

src/Spice86/Native/WindowsMouseCaptureBackend.cs

@@ -0,0 +1,109 @@
+namespace Spice86.Native;
+
+using System;
+
+/// <summary>
+/// Windows-specific mouse capture backend. Uses <c>ClipCursor</c> to confine the cursor
+/// to the emulator window, and <c>SetCapture</c>/<c>ReleaseCapture</c> to ensure mouse
+/// messages continue reaching the window even when the cursor temporarily touches an edge.
+/// Avalonia <c>PointerMoved</c> events still fire with absolute window-relative coordinates
+/// — no delta polling is required.
+/// </summary>
+internal sealed class WindowsMouseCaptureBackend : IMouseCaptureBackend {
+    private nint _windowHandle;
+    private bool _isCaptured;
+    private bool _disposed;
+
+    /// <inheritdoc/>
+    public bool IsCaptured => _isCaptured;
+
+    /// <inheritdoc/>
+    /// <remarks>
+    /// <see langword="false"/>: the cursor remains visible and Avalonia pointer events carry
+    /// absolute coordinates. The host window simply clips the cursor to its bounds.
+    /// </remarks>
+    public bool UsesRelativeMouseMode => false;
+
+    /// <inheritdoc/>
+    public bool TryInitialize(nint nativeWindowHandle) {
+        if (nativeWindowHandle == nint.Zero) {
+            return false;
+        }
+
+        _windowHandle = nativeWindowHandle;
+        return true;
+    }
+
+    /// <inheritdoc/>
+    /// <remarks>
+    /// May be called repeatedly (e.g. on window move/resize) to refresh the clip rectangle.
+    /// </remarks>
+    public bool EnableCapture() {
+        if (_windowHandle == nint.Zero) {
+            return false;
+        }
+
+        bool gotClientRect = WindowsMouseCaptureInterop.GetClientRect(_windowHandle, out WindowsMouseCaptureInterop.ClipRect clientRect);
+        if (!gotClientRect) {
+            return false;
+        }
+
+        WindowsMouseCaptureInterop.WinPoint topLeft = new WindowsMouseCaptureInterop.WinPoint { X = clientRect.Left, Y = clientRect.Top };
+        WindowsMouseCaptureInterop.WinPoint bottomRight = new WindowsMouseCaptureInterop.WinPoint { X = clientRect.Right, Y = clientRect.Bottom };
+
+        bool topLeftConverted = WindowsMouseCaptureInterop.ClientToScreen(_windowHandle, ref topLeft);
+        if (!topLeftConverted) {
+            return false;
+        }
+
+        bool bottomRightConverted = WindowsMouseCaptureInterop.ClientToScreen(_windowHandle, ref bottomRight);
+        if (!bottomRightConverted) {
+            return false;
+        }
+
+        WindowsMouseCaptureInterop.ClipRect screenRect = new WindowsMouseCaptureInterop.ClipRect {
+            Left = topLeft.X,
+            Top = topLeft.Y,
+            Right = bottomRight.X,
+            Bottom = bottomRight.Y
+        };
+
+        WindowsMouseCaptureInterop.SetCapture(_windowHandle);
+        bool clipResult = WindowsMouseCaptureInterop.ClipCursor(ref screenRect);
+        if (clipResult) {
+            _isCaptured = true;
+        }
+
+        return clipResult;
+    }
+
+    /// <inheritdoc/>
+    public bool DisableCapture() {
+        WindowsMouseCaptureInterop.ReleaseCapture();
+        bool clipResult = WindowsMouseCaptureInterop.ClipCursor(IntPtr.Zero);
+        _isCaptured = false;
+        return clipResult;
+    }
+
+    /// <inheritdoc/>
+    /// <remarks>
+    /// Always returns <c>(0, 0)</c>: absolute coordinates come from Avalonia pointer events.
+    /// </remarks>
+    public void GetRelativeMouseDelta(out int dx, out int dy) {
+        dx = 0;
+        dy = 0;
+    }
+
+    /// <inheritdoc/>
+    public void Dispose() {
+        if (_disposed) {
+            return;
+        }
+
+        _disposed = true;
+
+        if (_isCaptured) {
+            DisableCapture();
+        }
+    }
+}

src/Spice86/Native/WindowsMouseCaptureInterop.cs

@@ -0,0 +1,54 @@
+namespace Spice86.Native;
+
+using System;
+using System.Runtime.InteropServices;
+
+/// <summary>
+/// Windows user32.dll P/Invoke declarations used by <see cref="WindowsMouseCaptureBackend"/>.
+/// </summary>
+internal static partial class WindowsMouseCaptureInterop {
+    /// <summary>Screen-coordinate rectangle used by <see cref="ClipCursor(ref ClipRect)"/>.</summary>
+    [StructLayout(LayoutKind.Sequential)]
+    internal struct ClipRect {
+        public int Left;
+        public int Top;
+        public int Right;
+        public int Bottom;
+    }
+
+    /// <summary>Point structure used by <see cref="ClientToScreen"/>.</summary>
+    [StructLayout(LayoutKind.Sequential)]
+    internal struct WinPoint {
+        public int X;
+        public int Y;
+    }
+
+    /// <summary>Confines the cursor to the supplied rectangle (screen coordinates).</summary>
+    [LibraryImport("user32.dll", SetLastError = true, EntryPoint = "ClipCursor")]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    internal static partial bool ClipCursor(ref ClipRect rect);
+
+    /// <summary>Removes the cursor clipping rectangle.</summary>
+    [LibraryImport("user32.dll", SetLastError = true, EntryPoint = "ClipCursor")]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    internal static partial bool ClipCursor(IntPtr rect);
+
+    /// <summary>Retrieves the client-area bounding rectangle of the specified window.</summary>
+    [LibraryImport("user32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    internal static partial bool GetClientRect(IntPtr hWnd, out ClipRect lpRect);
+
+    /// <summary>Converts a client-area coordinate to screen coordinates.</summary>
+    [LibraryImport("user32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    internal static partial bool ClientToScreen(IntPtr hWnd, ref WinPoint lpPoint);
+
+    /// <summary>Sets the mouse capture to the specified window.</summary>
+    [LibraryImport("user32.dll", SetLastError = true)]
+    internal static partial IntPtr SetCapture(IntPtr hWnd);
+
+    /// <summary>Releases mouse capture from a window.</summary>
+    [LibraryImport("user32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    internal static partial bool ReleaseCapture();
+}