NEW: Hot path optimization for ReadValue/WriteValueIntoState for most used controls (requires opt-in) (#1606)

Co-authored-by: Ben Pitt <[email protected]>

Author: Dmytro Ivanov

Assets/Tests/InputSystem/CorePerformanceTests.cs

@@ -531,4 +531,66 @@ public void TODO_CanSaveAndRestoreSystemInLessThan10Milliseconds() // Currently
     }
 
     #endif
+
+    internal enum OptimizedControlsTest
+    {
+        OptimizedControls,
+        NormalControls
+    }
+
+    [Test, Performance]
+    [Category("Performance")]
+    [TestCase(OptimizedControlsTest.OptimizedControls)]
+    [TestCase(OptimizedControlsTest.NormalControls)]
+    public void Performance_OptimizedControls_ReadingMousePosition100kTimes(OptimizedControlsTest testSetup)
+    {
+        var useOptimizedControls = testSetup == OptimizedControlsTest.OptimizedControls;
+        InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kUseOptimizedControls, useOptimizedControls);
+
+        var mouse = InputSystem.AddDevice<Mouse>();
+        Assert.That(mouse.position.x.optimizedControlDataType, Is.EqualTo(useOptimizedControls ? InputStateBlock.FormatFloat : InputStateBlock.FormatInvalid));
+        Assert.That(mouse.position.y.optimizedControlDataType, Is.EqualTo(useOptimizedControls ? InputStateBlock.FormatFloat : InputStateBlock.FormatInvalid));
+        Assert.That(mouse.position.optimizedControlDataType, Is.EqualTo(useOptimizedControls ? InputStateBlock.FormatVector2 : InputStateBlock.FormatInvalid));
+
+        Measure.Method(() =>
+        {
+            var pos = new Vector2();
+            for (var i = 0; i < 100000; ++i)
+                pos += mouse.position.ReadValue();
+        })
+            .MeasurementCount(100)
+            .WarmupCount(5)
+            .Run();
+    }
+
+#if ENABLE_VR
+    [Test, Performance]
+    [Category("Performance")]
+    [TestCase(OptimizedControlsTest.OptimizedControls)]
+    [TestCase(OptimizedControlsTest.NormalControls)]
+    public void Performance_OptimizedControls_ReadingPose4kTimes(OptimizedControlsTest testSetup)
+    {
+        var useOptimizedControls = testSetup == OptimizedControlsTest.OptimizedControls;
+        InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kUseOptimizedControls, useOptimizedControls);
+
+        runtime.ReportNewInputDevice(XRTests.PoseDeviceState.CreateDeviceDescription().ToJson());
+
+        InputSystem.Update();
+
+        var device = InputSystem.devices[0];
+
+        var poseControl = device["posecontrol"] as UnityEngine.InputSystem.XR.PoseControl;
+        Assert.That(poseControl.optimizedControlDataType, Is.EqualTo(useOptimizedControls ? InputStateBlock.FormatPose : InputStateBlock.FormatInvalid));
+
+        Measure.Method(() =>
+        {
+            for (var i = 0; i < 4000; ++i)
+                poseControl.ReadValue();
+        })
+            .MeasurementCount(100)
+            .WarmupCount(5)
+            .Run();
+    }
+
+#endif
 }

Assets/Tests/InputSystem/CoreTests_Controls.cs

@@ -1378,4 +1378,45 @@ public void Controls_TouchControlStateCorrespondsToTouchState()
         Assert.That(UnsafeUtility.SizeOf<TouchState>(), Is.EqualTo(TouchState.kSizeInBytes));
         Assert.That(touchscreen.touches[0].stateBlock.alignedSizeInBytes, Is.EqualTo(TouchState.kSizeInBytes));
     }
+
+    [Test]
+    [Category("Controls")]
+    public void Controls_OptimizedControls_TrivialControlsAreOptimized()
+    {
+        var mouse = InputSystem.AddDevice<Mouse>();
+
+        InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kUseOptimizedControls, false);
+        Assert.That(mouse.position.x.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatInvalid));
+        Assert.That(mouse.position.y.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatInvalid));
+        Assert.That(mouse.position.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatInvalid));
+        Assert.That(mouse.leftButton.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatInvalid));
+
+        InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kUseOptimizedControls, true);
+        Assert.That(mouse.position.x.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatFloat));
+        Assert.That(mouse.position.y.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatFloat));
+        Assert.That(mouse.position.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatVector2));
+        Assert.That(mouse.leftButton.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatInvalid));
+
+        InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kUseOptimizedControls, false);
+        Assert.That(mouse.position.x.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatInvalid));
+        Assert.That(mouse.position.y.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatInvalid));
+        Assert.That(mouse.position.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatInvalid));
+        Assert.That(mouse.leftButton.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatInvalid));
+    }
+
+    [Test]
+    [Category("Controls")]
+    public void Controls_OptimizedControls_ParentChangesOptimization_IfChildIsNoLongerOptimized()
+    {
+        InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kUseOptimizedControls, true);
+
+        var mouse = InputSystem.AddDevice<Mouse>();
+
+        mouse.position.x.invert = true;
+        mouse.position.x.ApplyParameterChanges();
+
+        Assert.That(mouse.position.x.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatInvalid));
+        Assert.That(mouse.position.y.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatFloat));
+        Assert.That(mouse.position.optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatInvalid));
+    }
 }

Assets/Tests/InputSystem/Plugins/XRTests.cs

@@ -1021,7 +1021,7 @@ public FourCC format
     }
 
     [StructLayout(LayoutKind.Explicit)]
-    unsafe struct PoseDeviceState : IInputStateTypeInfo
+    internal unsafe struct PoseDeviceState : IInputStateTypeInfo
     {
         [FieldOffset(0)] public byte isTracked;
         [FieldOffset(4)] public uint trackingState;
@@ -1123,5 +1123,20 @@ public void Controls_XRAxisControls_AreClampedToOneMagnitude()
         Assert.That((device["Vector2/x"] as AxisControl).EvaluateMagnitude(), Is.EqualTo(1f).Within(0.0001f));
         Assert.That((device["Vector2/y"] as AxisControl).EvaluateMagnitude(), Is.EqualTo(1f).Within(0.0001f));
     }
+
+    [Test]
+    [Category("Controls")]
+    public void Controls_OptimizedControls_PoseControl_IsOptimized()
+    {
+        InputSystem.settings.SetInternalFeatureFlag(InputFeatureNames.kUseOptimizedControls, true);
+
+        runtime.ReportNewInputDevice(PoseDeviceState.CreateDeviceDescription().ToJson());
+
+        InputSystem.Update();
+
+        var device = InputSystem.devices[0];
+
+        Assert.That((device["posecontrol"] as PoseControl).optimizedControlDataType, Is.EqualTo(InputStateBlock.FormatPose));
+    }
 }
 #endif

Packages/com.unity.inputsystem/CHANGELOG.md

@@ -13,6 +13,7 @@ however, it has to be formatted properly to pass verification tests.
 ### Added
 - Added support for reading Tracking State in [TrackedPoseDriver](xref:UnityEngine.InputSystem.XR.TrackedPoseDriver) to constrain whether the input pose is applied to the Transform. This should be used when the device supports valid flags for the position and rotation values, which is the case for XR poses.
 - 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.
 
 ### Fixed
 - Fixed composite bindings incorrectly getting a control scheme assigned when pasting into input asset editor with a control scheme selected.

Packages/com.unity.inputsystem/InputSystem/Controls/AxisControl.cs

@@ -1,8 +1,12 @@
+using System.Runtime.CompilerServices;
 using UnityEngine.InputSystem.LowLevel;
 using UnityEngine.InputSystem.Processors;
+using UnityEngine.InputSystem.Utilities;
 
 ////REVIEW: change 'clampToConstant' to simply 'clampToMin'?
 
+////TODO: if AxisControl fields where properties, we wouldn't need ApplyParameterChanges, maybe it's ok breaking change?
+
 namespace UnityEngine.InputSystem.Controls
 {
     /// <summary>
@@ -177,6 +181,7 @@ public enum Clamp
         /// <seealso cref="normalize"/>
         /// <seealso cref="scale"/>
         /// <seealso cref="invert"/>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
         protected float Preprocess(float value)
         {
             if (scale)
@@ -234,16 +239,37 @@ protected override void FinishSetup()
         /// <inheritdoc />
         public override unsafe float ReadUnprocessedValueFromState(void* statePtr)
         {
-            var value = stateBlock.ReadFloat(statePtr);
-            ////REVIEW: this isn't very raw
-            return Preprocess(value);
+            switch (m_OptimizedControlDataType)
+            {
+                case InputStateBlock.kFormatFloat:
+                    return *(float*)((byte*)statePtr + m_StateBlock.m_ByteOffset);
+                case InputStateBlock.kFormatByte:
+                    return *((byte*)statePtr + m_StateBlock.m_ByteOffset) != 0 ? 1.0f : 0.0f;
+                default:
+                {
+                    var value = stateBlock.ReadFloat(statePtr);
+                    ////REVIEW: this isn't very raw
+                    return Preprocess(value);
+                }
+            }
         }
 
         /// <inheritdoc />
         public override unsafe void WriteValueIntoState(float value, void* statePtr)
         {
-            value = Unpreprocess(value);
-            stateBlock.WriteFloat(statePtr, value);
+            switch (m_OptimizedControlDataType)
+            {
+                case InputStateBlock.kFormatFloat:
+                    *(float*)((byte*)statePtr + m_StateBlock.m_ByteOffset) = value;
+                    break;
+                case InputStateBlock.kFormatByte:
+                    *((byte*)statePtr + m_StateBlock.m_ByteOffset) = (byte)(value >= 0.5f ? 1 : 0);
+                    break;
+                default:
+                    value = Unpreprocess(value);
+                    stateBlock.WriteFloat(statePtr, value);
+                    break;
+            }
         }
 
         /// <inheritdoc />
@@ -277,5 +303,28 @@ public override unsafe float EvaluateMagnitude(void* statePtr)
 
             return NormalizeProcessor.Normalize(value, min, max, 0);
         }
+
+        protected override FourCC CalculateOptimizedControlDataType()
+        {
+            var noProcessingNeeded =
+                clamp == Clamp.None &&
+                invert == false &&
+                normalize == false &&
+                scale == false;
+
+            if (noProcessingNeeded &&
+                m_StateBlock.format == InputStateBlock.FormatFloat &&
+                m_StateBlock.sizeInBits == 32 &&
+                m_StateBlock.bitOffset == 0)
+                return InputStateBlock.FormatFloat;
+            if (noProcessingNeeded &&
+                m_StateBlock.format == InputStateBlock.FormatBit &&
+                // has to be 8, otherwise we might be mapping to a state which only represents first bit in the byte, while other bits might map to some other controls
+                // like in the mouse where LMB/RMB map to the same byte, just LMB maps to first bit and RMB maps to second bit
+                m_StateBlock.sizeInBits == 8 &&
+                m_StateBlock.bitOffset == 0)
+                return InputStateBlock.FormatByte;
+            return InputStateBlock.FormatInvalid;
+        }
     }
 }

Packages/com.unity.inputsystem/InputSystem/Controls/ButtonControl.cs

@@ -1,3 +1,4 @@
+using System.Runtime.CompilerServices;
 using UnityEngine.InputSystem.LowLevel;
 using UnityEngine.Scripting;
 
@@ -75,6 +76,7 @@ public ButtonControl()
         /// <returns>True if <paramref name="value"/> crosses the threshold to be considered pressed.</returns>
         /// <seealso cref="pressPoint"/>
         /// <seealso cref="InputSettings.defaultButtonPressPoint"/>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public new bool IsValueConsideredPressed(float value)
         {
             return value >= pressPointOrDefault;

Packages/com.unity.inputsystem/InputSystem/Controls/InputControl.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics;
+using System.Runtime.CompilerServices;
 using UnityEngine.InputSystem.Controls;
 using UnityEngine.InputSystem.LowLevel;
 using UnityEngine.InputSystem.Utilities;
@@ -853,6 +854,114 @@ protected internal uint stateOffsetRelativeToDeviceRoot
         internal PrimitiveValue m_MinValue;
         internal PrimitiveValue m_MaxValue;
 
+        internal FourCC m_OptimizedControlDataType;
+
+        /// <summary>
+        /// For some types of control you can safely read/write state memory directly
+        /// which is much faster than calling ReadUnprocessedValueFromState/WriteValueIntoState.
+        /// This method returns a type that you can use for reading/writing the control directly,
+        /// or it returns InputStateBlock.kFormatInvalid if it's not possible for this type of control.
+        /// </summary>
+        /// <remarks>
+        /// For example, AxisControl might be a "float" in state memory, and if no processing is applied during reading (e.g. no invert/scale/etc),
+        /// then you could read it as float in memory directly without calling ReadUnprocessedValueFromState, which is faster.
+        /// Additionally, if you have a Vector3Control which uses 3 AxisControls as consecutive floats in memory,
+        /// you can cast the Vector3Control state memory directly to Vector3 without calling ReadUnprocessedValueFromState on x/y/z axes.
+        ///
+        /// The value returned for any given control is computed automatically by the Input System, when the control's setup configuration changes. <see cref="InputControl.CalculateOptimizedControlDataType"/>
+        /// There are some parameter changes which don't trigger a configuration change (such as the clamp, invert, normalize, and scale parameters on AxisControl),
+        /// so if you modify these, the optimized data type is not automatically updated. In this situation, you should manually update it by calling <see cref="InputControl.ApplyParameterChanges"/>.
+        /// </remarks>
+        public FourCC optimizedControlDataType => m_OptimizedControlDataType;
+
+        /// <summary>
+        /// Calculates and returns a optimized data type that can represent a control's value in memory directly.
+        /// The value then is cached in <see cref="InputControl.optimizedControlDataType"/>.
+        /// This method is for internal use only, you should not call this from your own code.
+        /// </summary>
+        protected virtual FourCC CalculateOptimizedControlDataType()
+        {
+            return InputStateBlock.kFormatInvalid;
+        }
+
+        /// <summary>
+        /// Apply built-in parameters changes (e.g. <see cref="AxisControl.invert"/>, others) and recompute <see cref="InputControl.optimizedControlDataType"/> for impacted controls.
+        /// </summary>
+        /// <remarks>
+        /// </remarks>
+        public void ApplyParameterChanges()
+        {
+            // First we go through all children of our own hierarchy
+            SetOptimizedControlDataTypeRecursively();
+
+            // Then we go through all parents up to the root, because our own change might influence their optimization status
+            // e.g. let's say we have a tree where root is Vector3 and children are three AxisControl
+            // And user is calling this method on AxisControl which goes from Float to NotOptimized.
+            // Then we need to also transition Vector3 to NotOptimized as well.
+
+            var currentParent = parent;
+            while (currentParent != null)
+            {
+                currentParent.SetOptimizedControlDataType();
+                currentParent = currentParent.parent;
+            }
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        private void SetOptimizedControlDataType()
+        {
+            // setting check need to be inline so we clear optimizations if setting is disabled after the fact
+            m_OptimizedControlDataType = InputSettings.optimizedControlsFeatureEnabled
+                ? CalculateOptimizedControlDataType()
+                : (FourCC)InputStateBlock.kFormatInvalid;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal void SetOptimizedControlDataTypeRecursively()
+        {
+            // Need to go depth-first because CalculateOptimizedControlDataType might depend on computed values of children
+            if (m_ChildCount > 0)
+            {
+                foreach (var inputControl in children)
+                    inputControl.SetOptimizedControlDataTypeRecursively();
+            }
+
+            SetOptimizedControlDataType();
+        }
+
+        // This function exists to warn users to start using ApplyParameterChanges for edge cases that were previously not intentionally supported,
+        // where control properties suddenly change underneath us without us anticipating that.
+        // This is mainly to AxisControl fields being public and capable of changing at any time even if we were not anticipated such a usage pattern.
+        // Also it's not clear if InputControl.stateBlock.format can potentially change at any time, likely not.
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        // Only do this check in development builds and editor in hope that it will be sufficient to catch any misuse during development.
+        [Conditional("DEVELOPMENT_BUILD"), Conditional("UNITY_EDITOR")]
+        internal void EnsureOptimizationTypeHasNotChanged()
+        {
+            if (!InputSettings.optimizedControlsFeatureEnabled)
+                return;
+
+            var currentOptimizedControlDataType = CalculateOptimizedControlDataType();
+            if (currentOptimizedControlDataType != optimizedControlDataType)
+            {
+                Debug.LogError(
+                    $"Control '{name}' / '{path}' suddenly changed optimization state due to either format " +
+                    $"change or control parameters change (was '{optimizedControlDataType}' but became '{currentOptimizedControlDataType}'), " +
+                    "this hinders control hot path optimization, please call control.ApplyParameterChanges() " +
+                    "after the changes to the control to fix this error.");
+
+                // Automatically fix the issue
+                // Note this function is only executed in editor and development builds
+                m_OptimizedControlDataType = currentOptimizedControlDataType;
+            }
+
+            if (m_ChildCount > 0)
+            {
+                foreach (var inputControl in children)
+                    inputControl.EnsureOptimizationTypeHasNotChanged();
+            }
+        }
+
         [Flags]
         internal enum ControlFlags
         {
@@ -935,6 +1044,7 @@ internal void CallFinishSetupRecursive()
             for (var i = 0; i < list.Count; ++i)
                 list[i].CallFinishSetupRecursive();
             FinishSetup();
+            SetOptimizedControlDataTypeRecursively();
         }
 
         internal string MakeChildPath(string path)
@@ -1162,6 +1272,7 @@ public override unsafe bool CompareValue(void* firstStatePtr, void* secondStateP
             return UnsafeUtility.MemCmp(firstValuePtr, secondValuePtr, UnsafeUtility.SizeOf<TValue>()) != 0;
         }
 
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public TValue ProcessValue(TValue value)
         {
             if (m_ProcessorStack.length > 0)