Add Windows precision touchpad (PTP) absolute position support (proof of concept)

osu.Framework/Input/Handlers/Touchpad/TouchpadHandler.cs

@@ -0,0 +1,112 @@
+// Copyright (c) ppy Pty Ltd <[email protected]>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+using osu.Framework.Bindables;
+using osu.Framework.Input.StateChanges;
+using osu.Framework.Platform;
+using osu.Framework.Statistics;
+using osuTK;
+using osuTK.Input;
+
+namespace osu.Framework.Input.Handlers.Touchpad
+{
+    /// <summary>
+    /// For <see cref="IWindow"/> implementing <see cref="IHasTouchpadInput"/>. Translate the touchpad events to mouse events.
+    /// </summary>
+    public class TouchpadHandler : InputHandler, IHasCursorSensitivity
+    {
+        private static readonly GlobalStatistic<ulong> statistic_total_events = GlobalStatistics.Get<ulong>(StatisticGroupFor<TouchpadHandler>(), "Total events");
+
+        public override string Description => "Touchpad";
+
+        public override bool IsActive => true;
+
+        public BindableDouble Sensitivity { get; } = new BindableDouble(1)
+        {
+            MinValue = 1,
+            MaxValue = 10,
+            Precision = 0.01
+        };
+
+        private IHasTouchpadInput? window;
+
+        public override bool Initialize(GameHost host)
+        {
+            if (!base.Initialize(host))
+                return false;
+
+            if (host.Window is not IHasTouchpadInput hasTouchpadInput)
+                return false;
+
+            window = hasTouchpadInput;
+
+            Enabled.BindValueChanged(enabled =>
+            {
+                if (enabled.NewValue)
+                {
+                    window!.TouchpadDataUpdate += handleTouchpadUpdate;
+                }
+                else
+                {
+                    window!.TouchpadDataUpdate -= handleTouchpadUpdate;
+                }
+            }, true);
+
+            return true;
+        }
+
+        public override void Reset()
+        {
+            Sensitivity.SetDefault();
+            base.Reset();
+        }
+
+        private void handleTouchpadUpdate(TouchpadData data)
+        {
+            // We just use the first reported point (For PoC).
+            // This might not be the first finger touched.
+            foreach (var point in data.Points)
+            {
+                if (!point.Valid || !point.Confidence) continue;
+
+                var position = mapToWindow(data.Info, point);
+                enqueueInput(new MousePositionAbsoluteInput { Position = position });
+                break;
+            }
+
+            // TODO Real mouse button event should be suppressed (???) otherwise tapping can be converted to clicks by the OS
+            // TODO only enqueue when state changed
+            enqueueInput(new MouseButtonInput(MouseButton.Left, data.ButtonDown));
+        }
+
+        private Vector2 mapToWindow(TouchpadInfo info, TouchpadPoint point)
+        {
+            var center = window!.Size / 2;
+
+            // centered (-range/2 ~ range/2)
+            int x = point.X - info.XMin - info.XRange / 2;
+            int y = point.Y - info.YMin - info.YRange / 2;
+
+            // Minimum ratio to cover the whole window
+            float minimumRatio = Math.Max(
+                (float)window.Size.Width / info.XRange,
+                (float)window.Size.Height / info.YRange);
+            var toWindow = new Vector2(
+                center.Width + x * minimumRatio * (float)Sensitivity.Value,
+                center.Height + y * minimumRatio * (float)Sensitivity.Value);
+
+            return Vector2.Clamp(
+                toWindow,
+                Vector2.Zero,
+                new Vector2(window.Size.Width - 1, window.Size.Height - 1));
+        }
+
+        private void enqueueInput(IInput input)
+        {
+            PendingInputs.Enqueue(input);
+            FrameStatistics.Increment(StatisticsCounterType.MouseEvents);
+            statistic_total_events.Value++;
+        }
+    }
+}

osu.Framework/Platform/IHasTouchpadInput.cs

@@ -0,0 +1,77 @@
+// Copyright (c) ppy Pty Ltd <[email protected]>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+using System.Collections.Generic;
+
+namespace osu.Framework.Platform
+{
+    /// <summary>
+    /// Window has touchpad input reported
+    /// </summary>
+    internal interface IHasTouchpadInput : IWindow
+    {
+        /// <summary>
+        /// Publish the touchpad data. Read by <see cref="Input.Handlers.Touchpad.TouchpadHandler"/>.
+        /// </summary>
+        public event Action<TouchpadData>? TouchpadDataUpdate;
+    }
+
+    /// <summary>Information for the whole touchpad.</summary>
+    public struct TouchpadData
+    {
+        /// <summary>Static information.</summary>
+        public readonly TouchpadInfo Info;
+
+        /// <summary>Valid touch points.</summary>
+        public readonly List<TouchpadPoint> Points;
+
+        /// <summary>Is the touchpad pressed down?</summary>
+        public readonly bool ButtonDown;
+
+        public TouchpadData(TouchpadInfo info, List<TouchpadPoint> points, bool buttonDown)
+        {
+            Info = info;
+            Points = points;
+            ButtonDown = buttonDown;
+        }
+    }
+
+    /// <summary>Information for the whole touchpad.</summary>
+    public struct TouchpadInfo
+    {
+        /// <summary>Arbitrary numerical value to differentiate individual touchpads.</summary>
+        public IntPtr Handle;
+
+        /// <summary>The limit for the raw XY values.</summary>
+        /// <remarks>
+        /// <para>To map the values to 0~1, use `(value-min)/range`.</para>
+        /// <para>The YRange/XRange value is the aspect ratio of the touchpad.</para>
+        /// </remarks>
+        public int XMin, YMin, XRange, YRange;
+    }
+
+    /// <summary>Information for every touch point.</summary>
+    public struct TouchpadPoint
+    {
+        public int X, Y;
+
+        /// <summary>Unique ID for the contact.</summary>
+        /// <remarks>
+        /// The position of one contact in the array may and will change, if fingers are added or removed.
+        /// </remarks>
+        public int ContactId;
+
+        /// <summary>Is finger in contact with the touchpad?</summary>
+        /// <remarks>
+        /// If false, the XY coordinate may still be valid, but the finger can be in a hover state.
+        /// </remarks>
+        public bool Valid;
+
+        /// <summary>Is touch point too large to be considered invalid?</summary>
+        /// <remarks>
+        /// If false, this contact may be a palm-touchpad contact.
+        /// </remarks>
+        public bool Confidence;
+    }
+}

osu.Framework/Platform/SDLGameHost.cs

@@ -11,6 +11,7 @@
 using osu.Framework.Input.Handlers.Pen;
 using osu.Framework.Input.Handlers.Tablet;
 using osu.Framework.Input.Handlers.Touch;
+using osu.Framework.Input.Handlers.Touchpad;
 using osu.Framework.Platform.SDL2;
 using osu.Framework.Platform.SDL3;
 using SixLabors.ImageSharp.Formats.Png;
@@ -50,6 +51,8 @@ protected override IEnumerable<InputHandler> CreateAvailableInputHandlers()
             if (FrameworkEnvironment.UseSDL3)
                 yield return new PenHandler();
 
+            // Touchpad should get priority over mouse, same reason as tablets.
+            yield return new TouchpadHandler();
             yield return new MouseHandler();
             yield return new TouchHandler();
             yield return new JoystickHandler();

osu.Framework/Platform/Windows/Native/Hid.cs

@@ -0,0 +1,159 @@
+// Copyright (c) ppy Pty Ltd <[email protected]>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+using System.Runtime.InteropServices;
+
+// ReSharper disable InconsistentNaming
+// (We are using the original names from the Windows API with type prefix removed.)
+
+namespace osu.Framework.Platform.Windows.Native
+{
+    internal class Hid
+    {
+        public const long HIDP_STATUS_SUCCESS = 0x00110000;
+
+        [DllImport("hid.dll")]
+        public static extern long HidP_GetCaps(IntPtr PreparsedData, out HIDP_CAPS Capabilities);
+
+        [DllImport("hid.dll")]
+        public static extern long HidP_GetValueCaps(HIDP_REPORT_TYPE ReportType, [Out] HIDP_VALUE_CAPS[] ValueCaps, ref ulong ValueCapsLength, IntPtr PreparsedData);
+
+        [DllImport("hid.dll")]
+        public static extern long HidP_GetLinkCollectionNodes([Out] HIDP_LINK_COLLECTION_NODE[] LinkCollectionNodes, ref ulong LinkCollectionNodesLength, IntPtr PreparsedData);
+
+        [DllImport("hid.dll")]
+        public static extern long HidP_GetUsageValue(
+            HIDP_REPORT_TYPE ReportType, ushort UsagePage, ushort LinkCollection, ushort Usage, out ulong UsageValue,
+            IntPtr PreparsedData, byte[] Report, ulong ReportLength);
+
+        [DllImport("hid.dll")]
+        public static extern long HidP_GetUsagesEx(
+            HIDP_REPORT_TYPE ReportType, ushort LinkCollection, [Out] USAGE_AND_PAGE[] ButtonList, ref ulong UsageLength,
+            IntPtr PreparsedData, byte[] Report, ulong ReportLength);
+    }
+
+    [StructLayout(LayoutKind.Sequential, Pack = 4)]
+    public struct HIDP_CAPS
+    {
+        public ushort Usage;
+        public ushort UsagePage;
+        public ushort InputReportByteLength;
+        public ushort OutputReportByteLength;
+        public ushort FeatureReportByteLength;
+        private unsafe fixed ushort Reserved[17];
+
+        public ushort NumberLinkCollectionNodes;
+
+        public ushort NumberInputButtonCaps;
+        public ushort NumberInputValueCaps;
+        public ushort NumberInputDataIndices;
+
+        public ushort NumberOutputButtonCaps;
+        public ushort NumberOutputValueCaps;
+        public ushort NumberOutputDataIndices;
+
+        public ushort NumberFeatureButtonCaps;
+        public ushort NumberFeatureValueCaps;
+        public ushort NumberFeatureDataIndices;
+    }
+
+    public enum HIDP_REPORT_TYPE
+    {
+        HidP_Input,
+        HidP_Output,
+        HidP_Feature
+    }
+
+    [StructLayout(LayoutKind.Sequential, Pack = 4)]
+    public struct HIDP_VALUE_CAPS
+    {
+        public ushort UsagePage;
+        public byte ReportID;
+        public byte IsAlias;
+
+        public ushort BitField;
+        public ushort LinkCollection;
+
+        public ushort LinkUsage;
+        public ushort LinkUsagePage;
+
+        public byte IsRange;
+        public byte IsStringRange;
+        public byte IsDesignatorRange;
+        public byte IsAbsolute;
+
+        public byte HasNull;
+        private byte Reserved;
+        public ushort BitSize;
+
+        public ushort ReportCount;
+        private unsafe fixed ushort Reserved2[5];
+
+        public uint UnitsExp;
+        public uint Units;
+
+        public int LogicalMin, LogicalMax;
+        public int PhysicalMin, PhysicalMax;
+        public Union union;
+
+        [StructLayout(LayoutKind.Explicit, Pack = 4)]
+        public struct Union
+        {
+            [FieldOffset(0)]
+            public _Range Range;
+
+            [FieldOffset(0)]
+            public _NotRange NotRange;
+        }
+
+        [StructLayout(LayoutKind.Sequential, Pack = 4)]
+        public struct _Range
+        {
+            public ushort UsageMin, UsageMax;
+            public ushort StringMin, StringMax;
+            public ushort DesignatorMin, DesignatorMax;
+            public ushort DataIndexMin, DataIndexMax;
+        }
+
+        [StructLayout(LayoutKind.Sequential, Pack = 4)]
+        public struct _NotRange
+        {
+            public ushort Usage;
+            private ushort Reserved1;
+            public ushort StringIndex;
+            private ushort Reserved2;
+            public ushort DesignatorIndex;
+            private ushort Reserved3;
+            public ushort DataIndex;
+            private ushort Reserved4;
+        }
+    }
+
+    [StructLayout(LayoutKind.Sequential, Pack = 4)]
+    public struct HIDP_LINK_COLLECTION_NODE
+    {
+        public ushort LinkUsage;
+        public ushort LinkUsagePage;
+        public ushort Parent;
+        public ushort NumberOfChildren;
+        public ushort NextSibling;
+        public ushort FirstChild;
+
+        // The original definition is:
+        //     ULONG    CollectionType: 8;  // As defined in 6.2.2.6 of HID spec
+        //     ULONG    IsAlias : 1; // This link node is an allias of the next link node.
+        //     ULONG    Reserved: 23;
+        // Fortunately the value is not used here. Don't bother parsing the bitfield now.
+        public UInt32 _bitfield;
+
+        public IntPtr UserContext;
+    }
+
+    [StructLayout(LayoutKind.Sequential, Pack = 4)]
+    public struct USAGE_AND_PAGE
+    {
+        public ushort Usage;
+        public ushort UsagePage;
+    }
+}