创建输入系统数据提供程序 - MRTK2

项目
07/12/2023

混合现实工具包输入系统是一个可扩展的系统，用于启用输入设备支持。为了添加对新硬件平台的支持，可能需要自定义输入数据提供程序。

本文介绍如何为输入系统创建自定义数据提供程序（也称为设备管理器）。此处显示的示例代码来自 WindowsMixedRealityDeviceManager。

可以在 MRTK/Providers/WindowsMixedReality 文件夹中找到此示例中使用的完整源代码。

命名空间和文件夹结构

数据提供程序可以作为第三方加载项分发，也可以作为 Microsoft 混合现实工具包的一部分分发。向 MRTK 提交新数据提供程序的审批过程因情况而异，在提交最初提案时将相互沟通。

重要

如果将输入系统数据提供程序提交到混合现实工具包存储库，命名空间必须以 Microsoft.MixedReality.Toolkit 开头（例如：Microsoft.MixedReality.Toolkit.WindowsMixedReality），并且代码应位于 MRTK/Providers 下的文件夹中（例如：MRTK/Providers/WindowsMixedReality）。

命名空间

数据提供程序需有一个命名空间来缓解潜在的名称冲突。建议在命名空间中包含以下组件。

公司名称
功能区域

例如，由 Contoso 公司创建的输入数据提供程序可以是“Contoso.MixedReality.Toolkit.Input”。

实现数据提供程序

指定接口和/或基类继承

所有输入系统数据提供程序必须实现 IMixedRealityInputDeviceManager 接口，该接口指定相机系统所需的最低功能。 MRTK 基础包括 BaseInputDeviceManager 类，该类提供所需功能的默认实现。对于基于 Unity 的 UInput 类构建的设备，UnityJoystickManager 类可用作基类。

注意

BaseInputDeviceManager 和 UnityJoystickManager 类提供所需的 IMixedRealityInputDeviceManager 实现。

public class WindowsMixedRealityDeviceManager :
    BaseInputDeviceManager,
    IMixedRealityCapabilityCheck
{ }

IMixedRealityCapabilityCheck 由 WindowsMixedRealityDeviceManager 用来指示它为一组输入功能提供支持，具体而言就是关节手，凝视-手势-语音手部和运动控制器。

应用 MixedRealityDataProvider 属性

创建输入系统数据提供程序的关键步骤是将 MixedRealityDataProvider 属性应用于类。在输入系统配置文件中选择时，此步骤可为提供程序设置默认配置文件和平台。

[MixedRealityDataProvider(
    typeof(IMixedRealityInputSystem),
    SupportedPlatforms.WindowsUniversal,
    "Windows Mixed Reality Device Manager")]
public class WindowsMixedRealityDeviceManager :
    BaseInputDeviceManager,
    IMixedRealityCapabilityCheck
{ }

实现 IMixedRealityDataProvider 方法

定义类后，下一步是提供 IMixedRealityDataProvider 接口的实现。

注意

BaseInputDeviceManager 类通过 BaseService 类为 IMixedRealityDataProvider 方法仅提供空实现。这些方法的详细信息通常特定于数据提供程序。

数据提供程序应实现的方法为：

Destroy()
Disable()
Enable()
Initialize()
Reset()
Update()

实现数据提供程序逻辑

下一步是添加用于管理输入设备的逻辑，包括要支持的任何控制器。

实现控制器类

WindowsMixedRealityDeviceManager 的示例定义并实现以下控制器类。

可以在 MRTK/Providers/WindowsMixedReality 文件夹中找到每个类的源代码。

WindowsMixedRealityArticulatedHand.cs
WindowsMixedRealityController.cs
WindowsMixedRealityGGVHand.cs

注意

并非所有设备管理器都支持多种控制器类型。

应用 MixedRealityController 属性

接下来，将 MixedRealityController 属性应用于类。此属性指定控制器的类型（例如：关节手），左右手使用习惯（例如：左手或右手）和可选的控制器图像。

[MixedRealityController(
    SupportedControllerType.WindowsMixedReality,
    new[] { Handedness.Left, Handedness.Right },
    "StandardAssets/Textures/MotionController")]
{ }

配置交互映射

下一步是定义控制器支持的交互映射集。对于通过 Unity 的输入类接收其数据的设备，控制器映射工具是一个有用的资源，用于确认要分配到交互的正确轴和按钮映射。

下面的示例是从 GenericOpenVRController 类简化而来的，该类位于 MRTK/Providers/OpenVR 文件夹中。

public override MixedRealityInteractionMapping[] DefaultLeftHandedInteractions => new[]
{
    // Controller Pose
    new MixedRealityInteractionMapping(0, "Spatial Pointer", AxisType.SixDof, DeviceInputType.SpatialPointer, MixedRealityInputAction.None),
    // Left Trigger Squeeze
    new MixedRealityInteractionMapping(1, "Trigger Position", AxisType.SingleAxis, DeviceInputType.Trigger, ControllerMappingLibrary.AXIS_9),
    // Left Trigger Press (Select)
    new MixedRealityInteractionMapping(2, "Trigger Press (Select)", AxisType.Digital, DeviceInputType.TriggerPress, KeyCode.JoystickButton14),
};

注意

ControllerMappingLibrary 类为 Unity 输入轴和按钮定义提供符号常量。

引发通知事件

为了启用应用程序以响应来自用户的输入，数据提供程序需要引发与控制器状态更改对应的通知事件，如 IMixedRealityInputHandler 和 IMixedRealityInputHandler<T> 接口中所定义。

对于数字（按钮）类型控件，引发 OnInputDown 和 OnInputUp 事件。

// inputAction is the input event that is to be raised.
if (interactionSourceState.touchpadPressed)
{
    InputSystem?.RaiseOnInputDown(InputSource, ControllerHandedness, inputAction);
}
else
{
    InputSystem?.RaiseOnInputUp(InputSource, ControllerHandedness, inputAction);
}

对于模拟控件（例如：触摸板位置），应引发 InputChanged 事件。

InputSystem?.RaisePositionInputChanged(InputSource, ControllerHandedness, interactionMapping.MixedRealityInputAction, interactionSourceState.touchpadPosition);

添加 Unity 探查器检测

性能在混合现实应用程序中非常重要。每个组件都增加了应用程序必须考虑的一些开销。为此，必须确保所有输入数据提供程序在内部循环和经常使用的代码路径中包含 Unity 探查器检测。

建议在检测自定义提供程序时实现 MRTK 使用的模式。

        private static readonly ProfilerMarker GetOrAddControllerPerfMarker = new ProfilerMarker("[MRTK] WindowsMixedRealityDeviceManager.GetOrAddController");

        private async void GetOrAddController(InteractionSourceState interactionSourceState)
        {
            using (GetOrAddControllerPerfMarker.Auto())
            {
                // Code to be measured.
            }
        }

注意

用于标识探查器标记的名称是任意的。 MRTK 使用以下模式。

“[product] className.methodName - 可选备注”

建议自定义数据提供程序遵循类似的模式，以帮助在分析跟踪时简化特定组件和方法的标识。

创建配置文件和检查器

在混合现实工具包中，数据提供程序使用配置文件进行配置。

具有其他配置选项（例如：InputSimulationService）的数据提供程序应创建配置文件和检查器以允许客户修改行为，使其最适合应用程序的需求。

可以在 MRTK.Services/InputSimulation 文件夹中找到本部分中的示例的完整代码。

定义配置文件

配置文件内容应镜像观察程序的可访问属性（例如：更新间隔）。每个接口中定义的所有用户可配置属性应包含在配置文件中。

[CreateAssetMenu(
    menuName = "Mixed Reality Toolkit/Profiles/Mixed Reality Simulated Input Profile",
    fileName = "MixedRealityInputSimulationProfile",
    order = (int)CreateProfileMenuItemIndices.InputSimulation)]
public class MixedRealityInputSimulationProfile : BaseMixedRealityProfile
{ }

CreateAssetMenu 属性可应用于配置文件类，使客户能够使用“创建”>“资产”>“混合现实工具包”>“配置文件”菜单创建配置文件实例。

实现检查器

配置文件检查器是用于配置和查看配置文件内容的用户界面。每个配置文件检查器应扩展 `BaseMixedRealityToolkitConfigurationProfileInspector 类。

[CustomEditor(typeof(MixedRealityInputSimulationProfile))]
public class MixedRealityInputSimulationProfileInspector : BaseMixedRealityToolkitConfigurationProfileInspector
{ }

CustomEditor 属性向 Unity 告知检查器应用到的资产类型。

创建程序集定义

混合现实工具包使用程序集定义 (.asmdef) 文件来指定组件之间的依赖关系并帮助 Unity 缩短编译时间。

建议为所有数据提供程序及其编辑器组件创建程序集定义文件。

如果使用前面示例中的文件夹结构，ContosoInput 数据提供程序将有两个 .asmdef 文件。

第一个程序集定义用于数据提供程序。在此示例中，此定义名为 ContosoInput，位于示例的 ContosoInput 文件夹中。此程序集定义必须指定对 Microsoft.MixedReality.Toolkit 及其所依赖的任何其他程序集的依赖关系。

ContosoInputEditor 程序集定义指定配置文件检查器和编辑器特定的任何代码。此文件必须位于编辑器代码的根文件夹中。在此示例中，该文件位于 ContosoInput\Editor 文件夹中。此程序集定义包含对 ContosoInput 程序集的引用，以及：

Microsoft.MixedReality.Toolkit
Microsoft.MixedReality.Toolkit.Editor.Inspectors
Microsoft.MixedReality.Toolkit.Editor.Utilities

注册数据提供程序

创建后，可将数据提供程序注册到输入系统，并在应用程序中使用。

Registered input system data providers

打包和分发

作为第三方组件分发的数据提供程序的具体打包和分发细节由开发人员决定。最常见的解决方案可能是生成一个 .unitypackage，通过 Unity Asset Store 进行分发。

如果数据提供程序作为“Microsoft 混合现实工具包”包的一部分提交和接受，Microsoft MRTK 团队会将其打包，作为 MRTK 产品/服务的一部分进行分发。

通过