NEW: Improve performance when reading control values (#1569)

Author: andrew-oc

Assets/Tests/InputSystem/APIVerificationTests.cs

@@ -81,7 +81,12 @@ private static bool IsTypeWhichCanHavePublicFields(TypeReference type)
                 resolved.Interfaces.Any(i => i.InterfaceType.FullName == typeof(IInputEventTypeInfo).FullName) ||
 
                 // serializable types may depend on the field names to match serialized data (eg. Json)
-                resolved.Attributes.HasFlag(TypeAttributes.Serializable)
+                resolved.Attributes.HasFlag(TypeAttributes.Serializable) ||
+
+                // These types need to use fields because they are returned as ref readonly from InputAction.value and we
+                // want to avoid defensive copies being created for every property access. Also, we can't use the types
+                // Bone and Eyes here because they don't exist on some platforms
+                resolved.Name == "Bone" || resolved.Name == "Eyes"
             )
                 return true;
 
@@ -517,22 +522,27 @@ private static string FilterIgnoredChanges(string line)
         }
     }
 
+    /// <summary>
+    /// Use a scoped exclusion property to exclude members of a type from API verification when the member's names are not
+    /// unique in the entire project and you don't want to exclude the unrelated members. This type will scope the exlusion
+    /// to just a particular namespace and type.
+    /// </summary>
     internal readonly struct ScopedExclusion
     {
-        public ScopedExclusion(string version, string ns, string type, string method)
+        public ScopedExclusion(string version, string ns, string type, params string[] members)
         {
             Version = version;
             Namespace = ns;
             Type = type;
-            Method = method;
+            Members = members;
         }
 
         public string Version { get; }
         public string Namespace { get; }
         public string Type { get; }
-        public string Method { get; }
+        public string[] Members { get; }
 
-        public bool IsMatch(List<string> scopeStack, string method)
+        public bool IsMatch(List<string> scopeStack, string member)
         {
             var namespaceScope = string.Empty;
             var typeScope = string.Empty;
@@ -545,7 +555,7 @@ public bool IsMatch(List<string> scopeStack, string method)
                     typeScope = scopeStack[i].Trim();
             }
 
-            return namespaceScope == Namespace && typeScope == Type && method.Trim() == Method;
+            return namespaceScope == Namespace && typeScope == Type && Members.Contains(member.Trim());
         }
     }
 
@@ -554,7 +564,7 @@ public class ScopedExclusionPropertyAttribute : PropertyAttribute
     {
         public const string ScopedExclusions = "ScopedExclusions";
 
-        public ScopedExclusionPropertyAttribute(string version, string ns, string type, string method)
+        public ScopedExclusionPropertyAttribute(string version, string ns, string type, params string[] method)
         {
             Properties.Add(ScopedExclusions, new ScopedExclusion(version, ns, type, method));
         }

Assets/Tests/InputSystem/CorePerformanceTests.cs

@@ -560,6 +560,8 @@ public void Performance_OptimizedControls_ReadingMousePosition100kTimes(Optimize
     {
         var useOptimizedControls = testSetup == OptimizedControlsTest.OptimizedControls;
         InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kUseOptimizedControls, useOptimizedControls);
+        InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kUseReadValueCaching, useOptimizedControls);
+        InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kParanoidReadValueCachingChecks, false);
 
         var mouse = InputSystem.AddDevice<Mouse>();
         Assert.That(mouse.position.x.optimizedControlDataType, Is.EqualTo(useOptimizedControls ? InputStateBlock.FormatFloat : InputStateBlock.FormatInvalid));
@@ -586,6 +588,8 @@ public void Performance_OptimizedControls_ReadingPose4kTimes(OptimizedControlsTe
     {
         var useOptimizedControls = testSetup == OptimizedControlsTest.OptimizedControls;
         InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kUseOptimizedControls, useOptimizedControls);
+        InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kUseReadValueCaching, useOptimizedControls);
+        InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kParanoidReadValueCachingChecks, false);
 
         runtime.ReportNewInputDevice(XRTests.PoseDeviceState.CreateDeviceDescription().ToJson());
 

Assets/Tests/InputSystem/CoreTests_Controls.cs

@@ -436,6 +436,93 @@ public void Controls_CanCheckWhetherControlIsAtDefaultValue_IgnoringNoise()
         }
     }
 
+    [Test]
+    [Category("Controls")]
+    public unsafe void Controls_ValueIsReadFromStateMemoryOnlyWhenControlHasBeenMarkedAsStale()
+    {
+        // disable paranoid checks because this test is consciously writing to state memory directly
+        InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kParanoidReadValueCachingChecks, false);
+
+        var gamepad = InputSystem.AddDevice<Gamepad>();
+
+        // read the value once initially so it gets cached
+        var value = gamepad.leftTrigger.value;
+
+        // Note that we have to write a different value here (0.5) to the one we write below, otherwise the
+        // state comparison during the state update won't see any difference between the values and won't
+        // mark the control as stale
+        gamepad.leftTrigger.WriteValueIntoState(0.5f, gamepad.currentStatePtr);
+
+        // because we wrote the state manually into the current state ptr, the stale flag is not set, so calling
+        // value should return whatever was previously cached (0 by default).
+        Assert.That(gamepad.leftTrigger.value, Is.EqualTo(0));
+
+        // calling ApplyParameterChanges should recursively invalidate cached values
+        gamepad.ApplyParameterChanges();
+        Assert.That(gamepad.leftTrigger.value, Is.EqualTo(0.5f));
+
+        InputSystem.QueueStateEvent(gamepad, new GamepadState {leftTrigger = 0.75f});
+        InputSystem.Update();
+
+        // but this time, we updated state through the system which *does* set the stale flag on controls that
+        // have changed.
+        Assert.That(gamepad.leftTrigger.value, Is.EqualTo(0.75f));
+    }
+
+    [Test]
+    [Category("Controls")]
+    public void Controls_ValueCachingWorksAcrossEntireDeviceMemoryRange()
+    {
+        var keyboard = InputSystem.AddDevice<Keyboard>();
+
+        // read all values to initially mark everything as cached
+        foreach (var control in keyboard.allControls)
+        {
+            var v = ((ButtonControl)control).value;
+        }
+
+        foreach (var control in keyboard.allControls)
+        {
+            Assert.That(control.m_CachedValueIsStale, Is.False);
+        }
+
+        var keyboardState = new KeyboardState((Key[])Enum.GetValues(typeof(Key)));
+        InputSystem.QueueStateEvent(keyboard, keyboardState);
+        InputSystem.Update();
+
+        foreach (var control in keyboard.allControls)
+        {
+            if (control == keyboard.imeSelected) // not a real key
+                continue;
+
+            Assert.That(control.m_CachedValueIsStale, Is.True);
+        }
+    }
+
+    [Test]
+    [Category("Controls")]
+    public void Controls_ValueIsSetToDefaultStateOnInitialization()
+    {
+        var json = @"
+            {
+                ""name"" : ""CustomGamepad"",
+                ""extend"" : ""Gamepad"",
+                ""controls"" : [
+                    {
+                        ""name"" : ""rightTrigger"",
+                        ""defaultState"" : ""0.5""
+                    }
+                ]
+            }
+        ";
+
+        InputSystem.RegisterLayout(json);
+        var gamepad = InputDevice.Build<Gamepad>("CustomGamepad");
+        InputSystem.AddDevice(gamepad);
+
+        Assert.That(gamepad.rightTrigger.value, Is.EqualTo(0.5f));
+    }
+
     [Test]
     [Category("Controls")]
     public unsafe void Controls_CanWriteValueFromObjectIntoState()

Packages/com.unity.inputsystem/CHANGELOG.md

@@ -15,6 +15,7 @@ however, it has to be formatted properly to pass verification tests.
 - Added `InputSettings.shortcutKeysConsumeInput`. This allows programmatic access to opt-in to the enhanced shortcut key behaviour ([case ISXB-254](https://issuetracker.unity3d.com/product/unity/issues/guid/ISXB-254))).
 - Significantly optimized cost of `ReadValue`/`ReadUnprocessedValueFromState`/`WriteValueIntoState` for some control types. Optimization is opt-in for now, please call `InputSystem.settings.SetInternalFeatureFlag("USE_OPTIMIZED_CONTROLS", true);` in your project to enable it. You can observe which controls are optimized by looking at new optimized column in device debugger. You will need to call a new `InputControl.ApplyParameterChanges()` method if the code is changing `AxisControl` fields after initial setup is done.
 - Added the ability to change the origin positioning and movement behaviour of the OnScreenStick (`OnScreenStick.cs`) via the new `behaviour` property. This currently supports three modes of operation, two of which are new in addition to the previous behaviour. Based on the user contribution from [eblabs](https://github.com/eblabs) in [#658](https://github.com/Unity-Technologies/InputSystem/pull/658).
+- Significantly optimized cost of `InputAction.ReadValue` and `InputControl.ReadValue` calls by introducing caching behaviour to input controls. Input controls now keep track of whether their underlying state has been changed and only read the value from the underlying state and apply processors when absolutely necessary. Optimization is opt-in for now, please call `InputSystem.settings.SetInternalFeatureFlag("USE_READ_VALUE_CACHING", true);` in your project to enable it. If there are issues try enabling `InputSystem.settings.SetInternalFeatureFlag("PARANOID_READ_VALUE_CACHING_CHECKS", true);` and check in the console if there are any errors regarding caching.
 
 ### Fixed
 - Fixed composite bindings incorrectly getting a control scheme assigned when pasting into input asset editor with a control scheme selected.
@@ -51,6 +52,7 @@ however, it has to be formatted properly to pass verification tests.
 - Fixed an issue where PlayerInput behavior description was not updated when changing action assset ([case ISXB-286](https://issuetracker.unity3d.com/product/unity/issues/guid/ISXB-286)).
 
 ### Changed
+- Readded OnDisable() member to MultiplayerEventSystem which was previously removed from the API
 - Improved performance of HID descriptor parsing by moving json parsing to a simple custom predicitve parser instead of relying on Unity's json parsing. This should improve domain reload times when there are many HID devices connected to a machine.
 
 ## [1.4.2] - 2022-08-12

Packages/com.unity.inputsystem/Documentation~/Controls.md

@@ -8,6 +8,7 @@
 * [Actuation](#control-actuation)
 * [Noisy Controls](#noisy-controls)
 * [Synthetic Controls](#synthetic-controls)
+* [Performance Optimization](#performance-optimization)
 
 An Input Control represents a source of values. These values can be of any structured or primitive type. The only requirement is that the type is [blittable](https://docs.microsoft.com/en-us/dotnet/framework/interop/blittable-and-non-blittable-types).
 
@@ -229,3 +230,33 @@ A synthetic Control is a Control that doesn't correspond to an actual physical c
 Whether a given Control is synthetic is indicated by its [`InputControl.synthetic`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_synthetic) property.
 
 The system considers synthetic Controls for [interactive rebinding](ActionBindings.md#interactive-rebinding) but always favors non-synthetic Controls. If both a synthetic and a non-synthetic Control that are a potential match exist, the non-synthetic Control wins by default. This makes it possible to interactively bind to `<Gamepad>/leftStick/left`, for example, but also makes it possible to bind to `<Gamepad>/leftStickPress` without getting interference from the synthetic buttons on the stick.
+
+## Performance Optimization
+
+### Avoiding defensive copies
+
+Use [`InputControl<T>.value`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_value) instead of [`InputControl<T>.ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) to avoid creating a copy of the control state on every call, as the former returns the value as `ref readonly` while the latter always makes a copy. Note that this optimization only applies if the call site assigns the return value to a variable that has been declared 'ref readonly'. Otherwise a copy will be made as before. Additionally, be aware of defensive copies that can be allocated by the compiler when it is unable to determine that it can safely use the readonly reference i.e. if it can't determine that the reference won't be changed, it will create a defensive copy for you. For more details, see https://learn.microsoft.com/en-us/dotnet/csharp/write-safe-efficient-code#use-ref-readonly-return-statements.
+
+
+### Control Value Caching
+
+When the 'USE_READ_VALUE_CACHING' internal feature flag is set, the Input System will switch to an optimized path for reading control values. This path efficiently marks controls as 'stale' when they have been actuated and subsequent calls to [`InputControl<T>.ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) will only apply control processing when absolutely necessary. Control processing in this case can mean any hard-coded processing that might exist on the control, such as with [`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html) which has built-in inversion, normalisation, scaling etc, or any processors that have been applied to the controls' [processor stack](Processors.md#processors-on-controls). This can have a significant positive impact on performance, especially when using complex composite input actions with many composite parts, such as a movement input action that could be bound to W, A, S, and D on the keyboard, two gamepad sticks and a DPad.
+
+This feature is not enabled by default as it can result in the following minor behavioural changes:
+ * Some control processors use global state. Without cached value optimizations, it is possible to read the control value, change the global state, read the control value again, and get a new value due to the fact that the control processor runs on every call. With cached value optimizations, reading the control value will only ever return a new value if the physical control has been actuated. Changing the global state of a control processor will have no effect otherwise.
+ * Writing to device state using low-level APIs like [`InputControl<T>.WriteValueIntoState`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_WriteValueIntoState__0_System_Void__) does not set the stale flag and subsequent calls to [`InputControl<T>.value`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_value) will not reflect those changes.
+ * After changing properties on [`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html) the [`ApplyParameterChanges`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_ApplyParameterChanges) has to be called to invalidate cached value.
+
+Processors that need to run on every read can set their respective caching policy to EvaluateOnEveryRead. That will disable caching on controls that are using such processor.
+
+If there are any non-obvious inconsistencies, 'PARANOID_READ_VALUE_CACHING_CHECKS' internal feature flag can be enabled to compare cached and uncached value on every read and log an error if they don't match.
+
+### Optimized control read value
+
+When the 'USE_OPTIMIZED_CONTROLS' internal feature flag is set, the Input System will use faster way to use state memory for some controls instances.
+
+Most controls are flexible with regards to memory representation, like [`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html) can be one bit, multiple bits, a float, etc, or in [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html) where x and y can have different memory representation. Yet for most controls there are common memory representation patterns, for example [`AxisControl`](../api/UnityEngine.InputSystem.Controls.AxisControl.html) are floats or single bytes, or some [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html) are two consequitive floats in memory. If a control is matching a common representation we can bypass reading children control and cast memory directly to the common representation. For example if [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html) is two consequitive floats in memory we can bypass reading `x` and `y` separately and just cast whole state memory to `Vector2`, this only works if `x` and `y` don't need any processing applied to them.
+
+Optimized controls compute a potential memory representation in [`InputControl.CalculateOptimizedControlDataType()`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_CalculateOptimizedControlDataType), store it [`InputControl.optimizedControlDataType`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_optimizedControlDataType) and then inside [`ReadUnprocessedValueFromState`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadUnprocessedValueFromState_) used it to decide to cast memory directly instead of reading every children control on it's own to reconstruct the controls state.
+
+[`InputControl.ApplyParameterChanges()`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_ApplyParameterChanges) should be called after changes to ensure [`InputControl.optimizedControlDataType`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_optimizedControlDataType) is updated to the correct value when configuration changes after [`InputControl.FinishSetup()`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_FinishSetup_) was called, like value of [`AxisControl.invert`](../api/UnityEngine.InputSystem.Controls.AxisControl.html#UnityEngine_InputSystem_Controls_AxisControl_invert) flips or other cases.

Packages/com.unity.inputsystem/InputSystem/Actions/InputActionRebindingExtensions.cs

@@ -2355,7 +2355,7 @@ private unsafe void OnEvent(InputEventPtr eventPtr, InputDevice device)
                         {
                             // Haven't seen this control changing actuation yet. Record its current actuation as its
                             // starting actuation and ignore the control if we haven't reached our actuation threshold yet.
-                            startingMagnitude = control.EvaluateMagnitude();
+                            startingMagnitude = control.magnitude;
                             m_StartingActuations.Add(control, startingMagnitude);
                         }