NEW: Pen.isSupported, Mouse.isSupported and Touchscreen.isPressureSupported [ISX-2046, ISX-2079]

Assets/Tests/InputSystem/CoreTests_Devices.cs

@@ -5895,4 +5895,168 @@ public unsafe void Devices_DoesntErrorOutOnMaxTouchCount()
                 BeginTouch(i, new Vector2(i * 1.0f, i * 2.0f), time: 0);
         }, Throws.Nothing);
     }
+
+#if UNITY_INPUTSYSTEM_SUPPORTS_CAPABILITY_QUERIES
+    // Platform capability queries. These are addressed to the engine's system endpoint rather than
+    // to a device, because they answer "can this platform do X" rather than "is an X connected".
+    // What a given platform actually answers is asserted natively in the engine repository, from
+    // PlatformDependent, where the file location gates the test to that platform.
+
+    private unsafe void AnswerCapabilityQuery(FourCC type, InputCapabilitySupport answer)
+    {
+        runtime.SetDeviceCommandCallback(NativeInputCapabilities.systemDeviceId,
+            (id, command) =>
+            {
+                if (command->type != type)
+                    return InputDeviceCommand.GenericFailure;
+
+                *(InputCapabilitySupport*)((byte*)command + InputDeviceCommand.kBaseCommandSize) = answer;
+                return InputDeviceCommand.GenericSuccess;
+            });
+    }
+
+    [Test]
+    [Category("Devices")]
+    [TestCase(InputCapabilitySupport.Supported, true)]
+    [TestCase(InputCapabilitySupport.NotSupported, false)]
+    // Unknown collapses to false: the platform has not answered, and a maybe is not something a
+    // bool property can express.
+    [TestCase(InputCapabilitySupport.Unknown, false)]
+    public void Devices_PenIsSupported_ReflectsWhatThePlatformAnswers(InputCapabilitySupport answer, bool expected)
+    {
+        AnswerCapabilityQuery(QueryPenSupportedCommand.Type, answer);
+
+        Assert.That(Pen.isSupported, Is.EqualTo(expected));
+    }
+
+    [Test]
+    [Category("Devices")]
+    [TestCase(InputCapabilitySupport.Supported, true)]
+    [TestCase(InputCapabilitySupport.NotSupported, false)]
+    [TestCase(InputCapabilitySupport.Unknown, false)]
+    public void Devices_MouseIsSupported_ReflectsWhatThePlatformAnswers(InputCapabilitySupport answer, bool expected)
+    {
+        AnswerCapabilityQuery(QueryMouseSupportedCommand.Type, answer);
+
+        Assert.That(Mouse.isSupported, Is.EqualTo(expected));
+    }
+
+    [Test]
+    [Category("Devices")]
+    [TestCase(InputCapabilitySupport.Supported, true)]
+    [TestCase(InputCapabilitySupport.NotSupported, false)]
+    [TestCase(InputCapabilitySupport.Unknown, false)]
+    public void Devices_TouchscreenIsPressureSupported_ReflectsWhatThePlatformAnswers(InputCapabilitySupport answer, bool expected)
+    {
+        AnswerCapabilityQuery(QueryTouchPressureSupportedCommand.Type, answer);
+
+        Assert.That(Touchscreen.isPressureSupported, Is.EqualTo(expected));
+    }
+
+    // The properties describe the platform, not a device, so they must answer without one. This is
+    // the case that separates them from Device.current != null.
+    [Test]
+    [Category("Devices")]
+    public void Devices_CapabilityQueries_AreAnsweredWithNoDeviceAdded()
+    {
+        AnswerCapabilityQuery(QueryPenSupportedCommand.Type, InputCapabilitySupport.Supported);
+
+        Assert.That(InputSystem.devices, Is.Empty);
+        Assert.That(Pen.isSupported, Is.True);
+        Assert.That(Pen.current, Is.Null);
+    }
+
+    // The endpoint is addressed by a reserved id. A capability query must not be delivered to a
+    // real device, which would let a device answer a question about the platform.
+    [Test]
+    [Category("Devices")]
+    public unsafe void Devices_CapabilityQueries_AreNotDeliveredToDevices()
+    {
+        var pen = InputSystem.AddDevice<Pen>();
+        var receivedByDevice = 0;
+        runtime.SetDeviceCommandCallback(pen,
+            (id, command) =>
+            {
+                if (command->type == QueryPenSupportedCommand.Type)
+                    ++receivedByDevice;
+                return InputDeviceCommand.GenericFailure;
+            });
+        AnswerCapabilityQuery(QueryPenSupportedCommand.Type, InputCapabilitySupport.Supported);
+
+        Assert.That(Pen.isSupported, Is.True);
+        Assert.That(receivedByDevice, Is.Zero);
+    }
+
+    // A platform capability cannot change while the application runs, so reading the property
+    // repeatedly must not keep issuing commands.
+    [Test]
+    [Category("Devices")]
+    public unsafe void Devices_CapabilityQueries_AreOnlyIssuedOnce()
+    {
+        var queryCount = 0;
+        runtime.SetDeviceCommandCallback(NativeInputCapabilities.systemDeviceId,
+            (id, command) =>
+            {
+                if (command->type != QueryPenSupportedCommand.Type)
+                    return InputDeviceCommand.GenericFailure;
+
+                ++queryCount;
+                *(InputCapabilitySupport*)((byte*)command + InputDeviceCommand.kBaseCommandSize) =
+                    InputCapabilitySupport.Supported;
+                return InputDeviceCommand.GenericSuccess;
+            });
+
+        Assert.That(Pen.isSupported, Is.True);
+        Assert.That(Pen.isSupported, Is.True);
+        Assert.That(Pen.isSupported, Is.True);
+
+        Assert.That(queryCount, Is.EqualTo(1));
+    }
+
+    // Nothing answers, which is what an engine without the endpoint looks like. The property must
+    // report false rather than throwing, and must not retry on every read.
+    [Test]
+    [Category("Devices")]
+    public void Devices_CapabilityQueries_ReportFalseWhenNothingAnswers()
+    {
+        Assert.That(Pen.isSupported, Is.False);
+        Assert.That(Mouse.isSupported, Is.False);
+        Assert.That(Touchscreen.isPressureSupported, Is.False);
+    }
+
+    // Nothing generates the mirror of the engine's enum, and a reordering would silently invert
+    // Supported and NotSupported across the boundary. The engine pins the same values from its side.
+    [Test]
+    [Category("Devices")]
+    public void Devices_CapabilitySupport_MatchesTheEngineWireValues()
+    {
+        Assert.That((byte)InputCapabilitySupport.Unknown, Is.EqualTo((byte)CapabilityState.Unknown));
+        Assert.That((byte)InputCapabilitySupport.NotSupported, Is.EqualTo((byte)CapabilityState.NotSupported));
+        Assert.That((byte)InputCapabilitySupport.Supported, Is.EqualTo((byte)CapabilityState.Supported));
+    }
+
+    // Same reasoning for the codes: the package spells them as FourCC characters, matching every
+    // other command in the Commands folder, while the engine declares them as integer constants.
+    [Test]
+    [Category("Devices")]
+    public void Devices_CapabilityQueryCodes_MatchTheEngineCodes()
+    {
+        Assert.That((int)QueryPenSupportedCommand.Type, Is.EqualTo(NativeInputCapabilities.queryPenSupported));
+        Assert.That((int)QueryMouseSupportedCommand.Type, Is.EqualTo(NativeInputCapabilities.queryMouseSupported));
+        Assert.That((int)QueryTouchPressureSupportedCommand.Type,
+            Is.EqualTo(NativeInputCapabilities.queryTouchPressureSupported));
+    }
+
+    // The payload the package sends must be exactly the one byte the engine's payload validation
+    // accepts. The base command header is stripped before it reaches native.
+    [Test]
+    [Category("Devices")]
+    public void Devices_CapabilityQueryPayload_IsOneByteAfterTheCommandHeader()
+    {
+        Assert.That(QueryPenSupportedCommand.kSize - InputDeviceCommand.kBaseCommandSize, Is.EqualTo(1));
+        Assert.That(QueryMouseSupportedCommand.kSize - InputDeviceCommand.kBaseCommandSize, Is.EqualTo(1));
+        Assert.That(QueryTouchPressureSupportedCommand.kSize - InputDeviceCommand.kBaseCommandSize, Is.EqualTo(1));
+    }
+
+#endif // UNITY_INPUTSYSTEM_SUPPORTS_CAPABILITY_QUERIES
 }

Assets/Tests/InputSystem/Unity.InputSystem.Tests.asmdef

@@ -81,6 +81,11 @@
             "name": "Unity",
             "expression": "6000.5.0a8",
             "define": "UNITY_INPUTSYSTEM_SUPPORTS_FOCUS_EVENTS"
+        },
+        {
+            "name": "Unity",
+            "expression": "6000.7.0a6",
+            "define": "UNITY_INPUTSYSTEM_SUPPORTS_CAPABILITY_QUERIES"
         }
     ],
     "noEngineReferences": false

Packages/com.unity.inputsystem/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased] - yyyy-mm-dd
 
+### Added
+
+- Added `Pen.isSupported`, `Mouse.isSupported` and `Touchscreen.isPressureSupported`, reporting what the current platform is capable of rather than what is connected right now. These are not drop-in replacements for the legacy `UnityEngine.Input` equivalents; see the "Device capability and device availability" section of the migration documentation for how they differ, and for how to check whether a device is available to read from. [ISX-2046] [ISX-2079]
+
 ### Fixed
 
 - Fixed the Inspector help button for a selected `.inputactions` asset ("Open Reference for Input Action Importer") opening a missing documentation page; it now links to the Action Assets manual page [UUM-149518](https://issuetracker.unity3d.com/product/unity/issues/guid/UUM-149518)

Packages/com.unity.inputsystem/Documentation~/corresponding-old-new-api.md

@@ -67,6 +67,30 @@ Directly reading hardware controls bypasses the new Input System's action-based
 [`Input.imeIsSelected`](https://docs.unity3d.com/ScriptReference/Input-imeIsSelected.html)|Use: [`Keyboard.current.imeSelected`](xref:UnityEngine.InputSystem.Keyboard)
 [`Input.inputString`](https://docs.unity3d.com/ScriptReference/Input-inputString.html)|Subscribe to the [`Keyboard.onTextInput`](xref:UnityEngine.InputSystem.Keyboard) event:<br/>`Keyboard.current.onTextInput += character => /* ... */;`
 
+## Device capability and device availability
+
+Several Input Manager properties, such as [`Input.mousePresent`](https://docs.unity3d.com/ScriptReference/Input-mousePresent.html) and
+[`Input.stylusTouchSupported`](https://docs.unity3d.com/ScriptReference/Input-stylusTouchSupported.html), answered
+two questions at once, and answered them differently depending on the platform. On some platforms they were a
+hardcoded constant meaning roughly "this platform has this kind of device", and on others they performed real
+hardware detection.
+
+The new Input System separates the two:
+- **Does this platform even support this input interface?**
+  Use the capability properties: [`Mouse.isSupported`](xref:UnityEngine.InputSystem.Mouse),
+  [`Pen.isSupported`](xref:UnityEngine.InputSystem.Pen) and [`Touchscreen.isPressureSupported`](xref:UnityEngine.InputSystem.Touchscreen).
+  These never change while the application runs, so read them once and decide whether to offer device-specific
+  functionality.
+- **Is a device available to read from right now?** Use `Device.current != null && Device.current.enabled`.
+  Both parts matter. A non-null `current` only means a device object is registered, which some platforms do
+  unconditionally regardless of whether hardware is attached, and `enabled` is what tells you the device is
+  active. The Device Simulator is a good example of the difference: while simulating a touch device it disables
+  the native mouse and pen without removing them, so `current` stays non-null while `enabled` becomes false.
+
+Because the old properties mixed these two meanings, the capability properties are **not drop-in replacements**.
+On platforms where the old property performed real detection, the new property answers the capability question
+instead, so it can be `true` where the old one was `false`. The tables below note this per API.
+
 ## Mouse
 
 `MonoBehaviour.OnMouse` events, such as [MonoBehaviour.OnMouseDown](https://docs.unity3d.com/ScriptReference/MonoBehaviour.OnMouseDown.html), are supported in Unity 6.4 and later.
@@ -77,19 +101,19 @@ Directly reading hardware controls bypasses the new Input System's action-based
 [`Input.GetMouseButtonDown`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonDown.html)<br/>Example: `Input.GetMouseButtonDown(0)`|Use [`wasPressedThisFrame`](xref:UnityEngine.InputSystem.Controls.ButtonControl) on the corresponding mouse button.<br/>Example: `InputSystem.Mouse.current.leftButton.wasPressedThisFrame`
 [`Input.GetMouseButtonUp`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonUp.html)<br/>Example: `Input.GetMouseButtonUp(0)`|Use [`wasReleasedThisFrame`](xref:UnityEngine.InputSystem.Controls.ButtonControl) on the corresponding mouse button.<br/>Example: `InputSystem.Mouse.current.leftButton.wasReleasedThisFrame`
 [`Input.mousePosition`](https://docs.unity3d.com/ScriptReference/Input-mousePosition.html)|Use [`Mouse.current.position.ReadValue()`](xref:UnityEngine.InputSystem.Mouse)<br/>Example: `Vector2 position = Mouse.current.position.ReadValue();`<br/> **Note:** Mouse simulation from touch isn't implemented yet.
-[`Input.mousePresent`](https://docs.unity3d.com/ScriptReference/Input-mousePresent.html)|No corresponding API yet.
+[`Input.mousePresent`](https://docs.unity3d.com/ScriptReference/Input-mousePresent.html)|Use [`Mouse.isSupported`](xref:UnityEngine.InputSystem.Mouse) to check whether the platform supports mouse input at all.<br/>Example: `if (Mouse.isSupported) ShowMouseSettings();`<br/>**Note:** Not a drop-in replacement; see [Device capability and device availability](#device-capability-and-device-availability) above. Input System does not currently deliver mouse input on iOS, iPadOS or visionOS, so `Mouse.isSupported` is `false` there even though the platform itself supports indirect mice. Requires a recent Editor version.
 
 ## Touch and Pen
 
 |Input Manager (Old)|Input System (New)|
 |--|--|
 [`Input.GetTouch`](https://docs.unity3d.com/ScriptReference/Input.GetTouch.html)<br/>For example:<br/>`Touch touch = Input.GetTouch(0);`<br/>`Vector2 touchPos = touch.position;`|Use [`EnhancedTouch.Touch.activeTouches[i]`](xref:UnityEngine.InputSystem.EnhancedTouch.Touch)<br/>Example: `Vector2 touchPos = EnhancedTouch.Touch.activeTouches[0].position;`<br/> **Note:** Enable enhanced touch support first by calling [`EnhancedTouch.Enable()`](xref:UnityEngine.InputSystem.EnhancedTouch.EnhancedTouchSupport).
-[`Input.multiTouchEnabled`](https://docs.unity3d.com/ScriptReference/Input-multiTouchEnabled.html)|No corresponding API yet.
+[`Input.multiTouchEnabled`](https://docs.unity3d.com/ScriptReference/Input-multiTouchEnabled.html)|There is no direct equivalent, because this is a setting rather than a hardware capability. To get the same first-touch-wins behaviour, read [`primaryTouch`](xref:UnityEngine.InputSystem.Touchscreen) instead of iterating all touches, or bind to `<Touchscreen>/primaryTouch`.<br/>Example: `if (Touchscreen.current != null && Touchscreen.current.primaryTouch.press.isPressed)`<br/>**Note:** Two differences from setting `Input.multiTouchEnabled = false`. First, `primaryTouch` filters only itself: [`touches`](xref:UnityEngine.InputSystem.Touchscreen), the `<Touchscreen>/touch*` bindings and [`EnhancedTouch`](xref:UnityEngine.InputSystem.EnhancedTouch.Touch) still report every finger, whereas the legacy setting suppressed additional touches globally. Second, when the finger that started the primary touch lifts while other fingers are still down, the primary touch is retained rather than ended until the last finger is released, so a control bound to it stays actuated in the meantime.
 [`Input.simulateMouseWithTouches`](https://docs.unity3d.com/ScriptReference/Input-multiTouchEnabled.html)|No corresponding API yet.
-[`Input.stylusTouchSupported`](https://docs.unity3d.com/ScriptReference/Input-stylusTouchSupported.html)|No corresponding API yet.
+[`Input.stylusTouchSupported`](https://docs.unity3d.com/ScriptReference/Input-stylusTouchSupported.html)|Use [`Pen.isSupported`](xref:UnityEngine.InputSystem.Pen) to check whether the platform supports pen input at all.<br/>Example: `if (Pen.isSupported) ShowPenSettings();`<br/>**Note:** Not a drop-in replacement; see [Device capability and device availability](#device-capability-and-device-availability) above. Requires a recent Editor version.
 [`Input.touchCount`](https://docs.unity3d.com/ScriptReference/Input-touchCount.html)|[`EnhancedTouch.Touch.activeTouches.Count`](xref:UnityEngine.InputSystem.EnhancedTouch.Touch)<br/> **Note:** Enable enhanced touch support first by calling [`EnhancedTouchSupport.Enable()`](xref:UnityEngine.InputSystem.EnhancedTouch.EnhancedTouchSupport)
 [`Input.touches`](https://docs.unity3d.com/scriptreference/input-touches.html)|[`EnhancedTouch.Touch.activeTouches`](xref:UnityEngine.InputSystem.EnhancedTouch.Touch)<br/> **Note:** Enable enhanced touch support first by calling [`EnhancedTouch.Enable()`](xref:UnityEngine.InputSystem.EnhancedTouch.EnhancedTouchSupport)
-[`Input.touchPressureSupported`](https://docs.unity3d.com/ScriptReference/Input-touchPressureSupported.html)|No corresponding API yet.
+[`Input.touchPressureSupported`](https://docs.unity3d.com/ScriptReference/Input-touchPressureSupported.html)|Use [`Touchscreen.isPressureSupported`](xref:UnityEngine.InputSystem.Touchscreen) to check whether the platform delivers a real pressure value with touch input.<br/>Example: `if (Touchscreen.isPressureSupported) UsePressureForBrushWidth();`<br/>**Note:** When this is `false`, [`pressure`](xref:UnityEngine.InputSystem.Controls.TouchControl) reports a constant `1` while a finger is down rather than a measured value. This is a platform-wide answer rather than a per-device one. Requires a recent Editor version.
 [`Input.touchSupported`](https://docs.unity3d.com/ScriptReference/Input-touchSupported.html)|[`Touchscreen.current != null`](xref:UnityEngine.InputSystem.Touchscreen)
 [`Input.backButtonLeavesApp`](https://docs.unity3d.com/ScriptReference/Input-backButtonLeavesApp.html)|No corresponding API yet.
 [`GetPenEvent`](https://docs.unity3d.com/ScriptReference/Input.GetPenEvent.html)<br/>[`GetLastPenContactEvent`](https://docs.unity3d.com/ScriptReference/Input.GetLastPenContactEvent.html)<br/>[`ResetPenEvents`](https://docs.unity3d.com/ScriptReference/Input.ResetPenEvents.html)<br/>[`ClearLastPenContactEvent`](https://docs.unity3d.com/ScriptReference/Input.ClearLastPenContactEvent.html)|Use: [`Pen.current`](xref:UnityEngine.InputSystem.Pen)<br/>See the [Pen, tablet and stylus support](devices-pen.md) docs for more information.

Packages/com.unity.inputsystem/InputSystem/Runtime/Devices/Commands/InputCapabilitySupport.cs

@@ -0,0 +1,36 @@
+#if UNITY_INPUTSYSTEM_SUPPORTS_CAPABILITY_QUERIES
+namespace UnityEngine.InputSystem.LowLevel
+{
+    /// <summary>
+    /// Answer to a platform capability query, meaning what the platform can deliver rather than
+    /// what is currently connected.
+    /// </summary>
+    /// <remarks>
+    /// Mirrors <c>CapabilityState</c> in the engine's <c>Modules/Input/InputDeviceIOCTL.h</c>, whose
+    /// wire values are pinned by tests on both sides. <see cref="Unknown"/> is zero so that an
+    /// unwritten payload, or a platform that has not implemented a query, reads as "we do not know"
+    /// rather than as a confident <see cref="NotSupported"/>.
+    ///
+    /// The value space is open. Treat anything other than <see cref="Supported"/> as not supported
+    /// rather than rejecting it, because a newer engine may answer with a value this version of the
+    /// package does not know about.
+    /// </remarks>
+    internal enum InputCapabilitySupport : byte
+    {
+        /// <summary>
+        /// The platform has no answer, typically because it has not implemented the query yet.
+        /// </summary>
+        Unknown = 0,
+
+        /// <summary>
+        /// The platform definitively cannot deliver it.
+        /// </summary>
+        NotSupported = 1,
+
+        /// <summary>
+        /// The platform definitively can deliver it.
+        /// </summary>
+        Supported = 2
+    }
+}
+#endif // UNITY_INPUTSYSTEM_SUPPORTS_CAPABILITY_QUERIES