Unity XR 输入
访问 VR AR 的设备控制和Features。
阅读时间22 分钟最后更新于 8 天前
Unity 用户手册的本节提供有关 Unity 支持的All虚拟现实、增强现实和 Windows 混合现实Applications程序的输入Devices的信息。Page 涵盖以下主题:
XR 平台具有丰富的输入Features,在设计用户交互When可以利用这些功能。应用程序程序可以使用引用位置、旋转、触摸、按钮、游戏杆和手指传感器的指定的数据。但是,访问这些输入Features可能会因平台而异。实例表明,桌面端 VR 头盔之间可能存在微小差异,但已启用 VR 的桌面平台和独立平台移动端头盔可能差异更大。
Unity 提供了名为 InputFeatureUsage 的 C# 结构,该结构定义了访问 Any Platform 用户输入的物理设备控制(例如按钮和触发器)的标准设置。这些有助于按 Name 识别输入类型。有关每个的定义,请参阅 XR.input.CommonUsages。
InputFeatureUsage每个对应于一个共同的输入 Action 或类型。例如,Unity 将称为 的定义为由索引手指控制的单一轴输入,无论您使用哪个 XR 平台。您可以使用 使用其 Name 获取状态,因此无需为常规 Unity 输入系统设置轴(或 ON 某些 XR 平台的按钮)。
InputFeatureUsagetriggerInputFeatureUsageInputFeatureUsagetriggerXR 输入射
下表列出了标准控制器名称以及它们如何映射到常用 XR 系统的控制器:
InputFeatureUsageInputFeatureUsage | 功能类型 | Legacy 输入索引(左控制器/右控制器) | WMR | Oculus | GearVR | 白日夢 | OpenVR(完整) | 萬岁 | Oculus via OpenVR | 通过 OpenVR 实现 WMR |
|---|---|---|---|---|---|---|---|---|---|---|
| primary2DAxis | 2D 轴 | [(1,2)/(4,5)] | 触控板 | 游戏杆 | 触控板 | 触控板 | 触控板/游戏杆 | 触控板 | 游戏杆 | 游戏杆 |
| trigger | 轴 | [9/10] | Trigger(触发器) | Trigger(触发器) | Trigger(触发器) | Trigger(触发器) | Trigger(触发器) | Trigger(触发器) | Trigger(触发器) | Trigger(触发器) |
| grip | 轴 | [11/12] | 握把 | 握把 | 保险杠 | 握把 | 握把 | 握把 | 握把 | |
| secondary2DAxis | 2D 轴 | [(17,18)/(19,20)] | 游戏杆 | 触控板 | ||||||
| secondary2DAxisClick | 按钮 | [18/19] | 游戏杆 - 单击 | |||||||
| primaryButton | 按钮 | [2/0] | [X/A] - 按 | 应用 | 主要 | 主(三明治按钮)(1) | 主要 (Y/B) | 菜单 | ||
| primaryTouch | 按钮 | [12/10] | [X/A] - 触摸 | |||||||
| secondaryButton | 按钮 | [3/1] | [Y/B] - 按 | 备用 | 备用 (X/A) | |||||
| secondaryTouch | 按钮 | [13/11] | [Y/B] - 触摸 | |||||||
| gripButton | 按钮 | [4/5] | Grip - 按 | Grip - 按 | Grip - 按 | Grip - 按 | Grip - 按 | Grip - 按 | ||
| triggerButton | 按钮 | [14/15] | 触发器 - 按 | 触发器 - 按 | 触发器 - 按 | 触发器 - 按 | 触发器 - 按 | 触发器 - 按 | 触发器 - 触摸 | 触发器 - 按 |
| menuButton | 按钮 | [6/7] | 菜单 | Start(仅限左控制器) | ||||||
| primary2DAxisClick | 按钮 | [8/9] | 触控板 - 单击 | Thumbstick - 按 | 触控板 - 按 | 触控板 - 按 | 触控板/游戏杆 - 按 | 触控板 - 按 | 游戏杆 - 按 | 触控板 - 按 |
| primary2DAxisTouch | 按钮 | [16/17] | 触控板 - 触控 | Thumbstick - Touch | 触控板 - 触控 | 触控板 - 触控 | 触控板/游戏杆 - 触控 | 触控板 - Touch | 游戏杆 - 触摸 | 触控板 - 触控 |
| batteryLevel | 轴 | battery.level | ||||||||
| userPresence | 按钮 | 用户存在 | 用户存在 |
(1) Sandwich 按钮是指 Vive 菜单按钮。为了更好地手柄跨平台 Applications,此按钮映射到 primaryButton 而不是 menuButton。
请参阅 XR.input.CommonUsages 以了解每个的定义。
InputFeatureUsage访问输入 Devices
InputDevice 代表任何物理设备,例如控制器、移动端 Phone 或头盔。它可以包含有关设备跟踪、按钮、游戏杆和Other输入控制的信息。有关 ON API 的更多信息,请参阅 ON InputDevice 文档。
InputDevice使用 XR.InputDevices 类可以访问当前连接到 XR System 的输入 Devices。要获取 All connected Devices 的列表,请使用 InputDevices.GetDevices:
var inputDevices = new List<UnityEngine.XR.InputDevice>();UnityEngine.XR.InputDevices.GetDevices(inputDevices);Foreach(inputDevices 中的不同设备){ Debug.Log(string.Format("Device found with name '{0}' and role '{1}'", device.name, device.role.ToString()));}
输入设备在帧之间保持有效,直到 XR System断开连接。使用 InputDevice.IsValid 属性可确定是否仍代表活动控制器。
InputDevice您可以通过以下方式访问输入 Devices:
- Characteristics(特征):
- 角色
- XR 节点
按特征访问输入 Devices
设备特征描述了设备的功能或用途(例如,设备是否为头部安装)。InputDeviceCharacteristics 是一系列标志,可添加到代码中以搜索符合特定规格的 Devices。您可以按以下特征过滤器Devices:
设备 | 特色 |
|---|---|
| HeadMounted | 设备所挂的到用户的头部。它具有设备跟踪和中心眼睛跟踪。此标志最常用于标识头部安装显示器 (HMD)。 |
| Camera | 设备具有摄像机追迹。 |
| HeldInHand | 用户将设备握在手中。 |
| HandTracking | 设备表示物理跟踪的手。它具有设备跟踪功能,可能包含手和骨骼数据。 |
| EyeTracking | 该设备可进行眼睛跟踪并具有 EyesData 功能。 |
| TrackedDevice | 可在 3D Space间中跟踪设备。它具有设备跟踪。 |
| Controller(数据控制者) | 设备具有按钮和轴的输入数据,可用作控制器。 |
| TrackingReference | 设备表示Static跟踪引用Object。它具有设备跟踪功能,但该跟踪数据不应Change。 |
| 左 | 将此特征与 HeldInHand 或 HandTracking 特征结合使用,可将设备标识为与左关联。 |
| 右 | 将此特征与 HeldInHand 或 HandTracking 特征结合使用,可将设备识别为与右手关联。 |
| Simulated6DOF | 设备会Reports 6DOF 数据,但只有 3DOF 传感器。Unity 模拟位置数据。 |
XR 提供程序插件会Reports这些特征。您可以使用 InputDevice.Characteristics 查找它们。设备可以并且通常应该具有多个个特征,您可以使用位标志进行过滤器和访问。
InputDevices.GetDevicesWithCharacteristics 提供了一种搜索具有给定特征设置的 All Devices 的方法。例如,可使用以下代码searchSystem中可用的 左、HoldInHand、控制器 InputDevice:
var leftHandedControllers = new List<UnityEngine.XR.InputDevice>();var desiredCharacteristics = UnityEngine.XR.InputDeviceCharacteristics.HeldInHand | UnityEngine.XR.InputDeviceCharacteristics.Left | UnityEngine.XR.InputDeviceCharacteristics.Controller;UnityEngine.XR.InputDevices.GetDevicesWithCharacteristics(desiredCharacteristics, leftHandedControllers);Foreach(leftHandedControllers 中的不同设备){ Debug.Log(string.Format("Device name '{0}' has characteristics '{1}'", device.name, device.characteristics.ToString()));}
此函数找到的Devices至少包含指定的特征,但可能包含其他特征。例如,要查找左手控制器,只能查找 InputDeviceCharacteristic.left,而不能查找 InputDeviceCharacteristic.Controller。
按角色访问输入 Devices
设备角色描述输入设备的 General 函数。使用 InputDeviceRole 枚举可指定设备角色。定义的角色包括:
角色 | 描述 |
|---|---|
| GameController | 控制台样式的游戏控制器。 |
| 通用 | 表示核心 XR 设备的设备,例如头部式显示器或移动端设备。 |
| HardwareTracker | 跟踪设备。 |
| LeftHanded | 与用户左关联的设备。 |
| RightHanded | 与用户右手关联的设备。 |
| TrackingReference | 跟踪OtherDevices的设备,例如 Oculus 跟踪摄像Camera。 |
XR 提供程序插件会Reports这些角色,但不同的提供程序可能会以不同方式组织其设备角色。此外,用户可以切换手,因此角色分配可能与用户握持输入设备的手不Match。例如,用户可以将控制器配置为右手或左手,但以 Other 手握住控制器。
GetDevicesWithRole 提供具有指定的任何 Devices 的列表。例如,您可以使用 获取任何连接的 Devices:
InputDeviceRoleInputDeviceRole.GameControllerGameControllervar gameControllers = new List<UnityEngine.XR.InputDevice>();UnityEngine.XR.InputDevices.GetDevicesWithRole(UnityEngine.XR.InputDeviceRole.GameController, gameControllers);Foreach(GameControllers 中的不同设备){ Debug.Log(string.Format("Device name '{0}' has role '{1}'", device.name, device.role.ToString()));}
通过 XR 节点访问输入 Devices
XR 节点表示 XR System 中的物理参考点(例如,用户的头部位置、他们的左右手或跟踪参考,例如 Oculus Camera)。
XRNode 枚举定义了以下节点:
XR 节点 | 描述 |
|---|---|
| CenterEye | 用户眼睛瞳孔中间的一点。 |
| GameController | 控制台样式的游戏控制器。您的应用程序可以有多个游戏控制器 Devices。 |
| HardwareTracker | 硬件跟踪设备,通常所挂的到用户或物理Item。可以存在多个硬件跟踪器节点。 |
| 头部 | 用户头部的中心点,由 XR System 计算。 |
| LeftEye | 用户的左。 |
| LeftHand | 用户的左。 |
| RightEye | 用户的右眼。 |
| RightHand | 用户的右手。 |
| TrackingReference | 跟踪参考点,例如 Oculus Camera。可以存在多个跟踪参考节点。 |
使用 InputDevices.GetDevicesAtXRNode 获取与指定关联的 Devices 列表。以下示例演示了如何获取左手控制器:
XRNodevar leftHandDevices = new List<UnityEngine.XR.InputDevice>();UnityEngine.XR.InputDevices.GetDevicesAtXRNode(UnityEngine.XR.XRNode.LeftHand, leftHandDevices);if(leftHandDevices.Count == 1){ UnityEngine.XR.InputDevice device = leftHandDevices[0]; Debug.Log(string.Format("Device name '{0}' with role '{1}'", device.name, device.role.ToString()));}else if(leftHandDevices.Count > 1){ Debug.Log("Found more than one left hand!");}
监听设备连接和断开连接
输入 Devices 在帧与帧之间保持一致,但可以在 Any 时间连接或断开连接。要避免重复检查设备是否已连接到平台,请使用 InputDevices.deviceConnected 和 InputDevices.deviceDisconnected 在设备连接或断开连接时通知应用程序。这些还为您提供了对新连接的输入设备的引用。
由于可以在多个个帧保留这些引用,因此设备可能会断开连接连接,或者不再可用。要检查设备的输入是否仍然可用,请使用 InputDevice.isValid。访问输入 Devices 的脚本应在尝试使用该设备之前,在每个帧的 Start 进行检查。
访问输入设备ON的输入Features
可从指定的 InputDevice 读取输入功能,例如触发器按钮的状态。例如,要读取右触发器的状态,请执行以下步骤:
- 使用 InputDeviceRole.RightHanded 或 XRNode.RightHand 获取右手设备的实例。
- 拥有正确的设备后,使用 InputDevice.TryGetFeatureValue 方法来访问当前状态。
TryGetFeatureValue()- 如果成功检索到指定的功能值,则为 true
- 如果当前设备不Support指定功能,或者设备无效(即控制器不再Active),则为 false
要获取特定按钮、触摸输入或 Joystick Axis 值,请使用 CommonUsages 类。 包括 XR 输入 Mapping 表中的每个以及跟踪功能(如位置和 Rotation)。以下代码示例使用 CommonUsages.triggerButton 来检测用户当前是否正在按下特定实例的触发器按钮:
CommonUsagesInputFeatureUsageInputDevicebool triggerValue;if (device.TryGetFeatureValue(UnityEngine.XR.CommonUsages.triggerButton, out triggerValue) && triggerValue){ Debug.Log("Trigger button is pressed.");}
还可以使用 InputDevice.TryGetFeatureUsages 方法获取设备提供的每个的列表。此函数返回 InputFeatureUsage 项的列表,这些项具有描述该功能的类型和 Name 属性。以下示例枚举了给定输入设备提供的All布尔值Features:
InputFeatureUsagevar inputFeatures = new List<UnityEngine.XR.InputFeatureUsage>();if (device.TryGetFeatureUsages(inputFeatures)){ Foreach(inputFeatures 中的不同功能) { if (feature.type == typeof(bool)) { bool featureValue; if (device.TryGetFeatureValue(feature.As<bool>(), out featureValue)) { Debug.Log(string.Format("Bool feature {0}'s value is {1}", feature.name, featureValue.ToString())); } } }}
primaryButton 示例
不同的控制器配置提供对不同 Features 的访问。例如,一个系统上可能有多个控制器,不同系统上可能有不同的控制器,或者具有不同 SDK 的相同控制器上可能有不同的按钮。这种多样性使得Support来自一范围 XR 系统的输入变得更加复杂。Unity API 可帮助您获取不依赖于平台的输入。
InputFeatureUsage以下示例将访问 调用的 ,无论哪个控制器或输入设备提供该 。该示例包含一类,可在连接时扫描可用 Devices 以查找。该类监控任何连接设备上的功能 ON 的值,如果该值发生更改,该类将分发 UnityEvent。
InputFeatureUsageprimaryButtonprimaryButton要使用类,请将其作为组件添加到Scene中的Any游戏对象对象。例如:
using System.Collections.Generic;using UnityEngine;using UnityEngine.Events;using UnityEngine.XR;[Serializablepublic class PrimaryButtonEvent :UnityEvent<bool> { }public class PrimaryButtonWatcher :MonoBehaviour{ public PrimaryButtonEvent primaryButtonPress; private bool lastButtonState = false; private list<InputDevice> devicesWithPrimaryButton; private void 唤醒() { if (primaryButtonPress == null) { primaryButtonPress = new PrimaryButtonEvent(); } devicesWithPrimaryButton = new List<InputDevice>(); } void OnEnable() { 列表<InputDevice> allDevices = 新建列表<InputDevice>(); InputDevices.GetDevices(allDevices); Foreach(所有Device 中的 InputDevice 设备) InputDevices_deviceConnected(device); InputDevices.deviceConnected += InputDevices_deviceConnected; InputDevices.deviceDisconnected += InputDevices_deviceDisconnected; } private void OnDisable() { InputDevices.deviceConnected -= InputDevices_deviceConnected; InputDevices.deviceDisconnected -= InputDevices_deviceDisconnected; devicesWithPrimaryButton.Clear(); } private void InputDevices_deviceConnected(InputDevice 设备) { bool discardedValue; if (device.TryGetFeatureValue(CommonUsages.primaryButton, out discardedValue)) { devicesWithPrimaryButton.添加(设备); // 添加具有主按钮的任何 Devices。 } } private void InputDevices_deviceDisconnected(InputDevice 设备) { if (devicesWithPrimaryButton.Contains(device)) devicesWithPrimaryButton.Remove(device); } void Update() { bool tempState = false; Foreach(设备中的各种设备WithPrimaryButton) { bool primaryButtonState = false; tempState = 设备。TryGetFeatureValue(CommonUsages.primaryButton, out primaryButtonState) // 确实获得了值 && primaryButtonState // 我们获取的值 || tempState; // Other控制器的累积result } if (tempState != lastButtonState) // Button state changed since last frame { primaryButtonPress.Invoke(tempState); lastButtonState = tempState; } }}
以下 类使用该来检测 When you press a primary button and in response of a press, rotate its父游戏对象。要使用这类,请将其添加到可见游戏对象(例如 Cube),然后将引用拖动到 Watcher 属性。
PrimaryReactorPrimaryButtonWatcherPrimaryButtonWatcherusing System.Collections;using UnityEngine;public class PrimaryReactor :MonoBehaviour{ public PrimaryButtonWatcher watcher; public bool IsPressed = false; // used to display button state in the Unity Inspector window public Vector3 rotationAngle = new Vector3(45, 45, 45); public float rotationDuration = 0.25f; // seconds private 四元数 offRotation; private 四元数 onRotation; private Coroutine rotator; void Start() { watcher.primaryButtonPress.AddListener(onPrimaryButtonEvent); offRotation = this.transform.rotation; onRotation = Quaternion.Euler(rotationAngle) * offRotation; } public void onPrimaryButtonEvent(bool pressed) { IsPressed = pressed; if (rotator != null) StopCoroutine(rotator); if (pressed) rotator = StartCoroutine(AnimateRotation(this.transform.rotation, onRotation)); else rotator = StartCoroutine(AnimateRotation(this.transform.rotation, offRotation)); } private IEnumerator AnimateRotation(四元数 fromRotation、四元数 toRotation) { 浮点 t = 0;float while (t < rotationDuration) { transform.rotation = Quaternion.Lerp(fromRotation, toRotation, t / rotationDuration); t += Time.deltaTime; 返回 null } }}
访问手跟踪数数据
InputDevices Support手跟踪Devices。手动跟踪设备始终:
- 具有 HandTracking 特性
- 包含 Hand 类型的 CommonUsages.HandData 用法
手部跟踪数据由一个 Hand Object和一系列最多 21 个骨骨骼输入Features组成。每个骨骼都有位置和方向,以及对层级视图中的父和 Any 子骨骼的引用。Hand Object 可以获取 Root Bone 或每个手指的骨骼列表。
当 Hand.TryGetRootBone 获取 Root Bone 时,它会检索表示位于手腕正上方的骨骼的对象。您还可以获取代表每个手指的骨骼列表。调用 Hand.TryGetFingerBones 会返回代表该手指的骨骼的列表(从关节到尖端)。
访问眼睛跟踪数据
输入DevicesSupport眼睛跟踪Devices以及手部跟踪Devices。眼睛跟踪包括左和右眼位置、用户正在观察的 3D Space间中的位置以及每只眼睛的眨眼amount。其数据类型为 Eyes。要从设备检索,请使用 CommonUsages.eyesData。
XRInputSubsystem 和 InputDevice 关联
Unity 提供了两个输入系统:Legacy Input System 和 2019.2 中引入的 XR 插件架构。在新建设置中,每个 InputDevice 都与 XRInputSubsystem 关联。这些子系统对象Control与Any指定的输入设备无关的全局输入行为(例如,管理跟踪Origin或重新显示跟踪Devices)。
每个 InputDevice 都包含对其关联子系统的引用。如果设备来自集成平台,则此引用为 null。您还可以使用 SubsystemManager.GetInstances<XRInputSubsystem> 获取所有激活的 XRInputSubsystem 对象,每个 XRInputSubsystem 都可以使用 XRInputSubsystem.TryGetInputDevices 获取其 Devices。
您可以使用输入子系统来更新具有 UnityEngine.XR.XRInputSubsystem 的 Devices。Recenter 将 HMD 的当前位置设置为AllDevices的新建Origin。对于无法重新居中或平台不Support重新居中的Devices,它将返回 false。
要检索跟踪边界,请使用 TryGetBoundaryPoints。它由一系列顺时针排序的 3D 点组成,其中 y 值位于 Floor 关卡,它们标记出用户指定的“Safe Safe 区域”来放置内容和交互。您可以使用 XRInputSubsystem.boundaryChanged 监听此边界的更改。
XRInputSubsystem 还负责跟踪 Origin 模式,该模式为跟踪世界的 Origin 位置提供上下文。Unity 支持以下跟踪 Origin 模式:
- 设备Origin 的位置位于主显示设备的第一个已知位置;通常是 HMD 或 Phone。
- Floor:原点的位置位于地板上的已知位置。
- 跟踪参考:Origin的位置位ON设置了 TrackingReference 特性的 InputDevice 上。
- UNKNOWN跟踪 Origin 的类型未知。这可能是由于系统故障或缺少跟踪原点模式支持。
可以使用三个 API 来管理跟踪 Origin 模式:
- XRInputSubsystem.TrySetTrackingOriginMode 设置跟踪 Origin 模式
- XRInputSubystem.GetTrackingOriginMode 检索跟踪 Origin 模式
- XRInputSubsystem.GetSupportedTrackingOriginModes 检索 SDK 支持的所有跟踪 Origin 模式
通过LegacyInput System的 XR 输入
您仍然可以使用由输入和 XR.InputTracking 组成的 Legacy Input System 来检索 XR 输入功能。为此,请使用本页面上的 XR 输入映射表中的相应 Legacy 输入索引。在的输入部分(菜单:编辑 > > 输入),创建轴映射,为平台设备的功能添加从输入 Name 到轴索引的适当 Mapping。要检索按钮或轴值,请使用 input.GetAxis 或 input.GetButton,然后输入现在映射的轴或按钮 Name 中的通道。
Player Settings(播放器设置)
?
项目设置
?
有关如何使用按钮和操作杆轴的更多信息,请参阅 ON InputManager 文档。
触觉
您可以将触觉事件发送到 InputDevice。触觉采用 ON 脉冲形式,具有幅度和 Duration。
并非All平台都SupportAll类型的触觉,但您可以查询设备的触觉功能。以下示例获取右手的输入设备,检查设备是否具有触觉功能,然后播放脉冲(如果能够):
列表<UnityEngine.XR.InputDevice> Devices = 新建列表<UnityEngine.XR.InputDevice>(); UnityEngine.XR.InputDevices.GetDevicesWithRole(UnityEngine.XR.InputDeviceRole.RightHanded, devices);Foreach(Devices中的设备不同){ UnityEngine.XR.HapticCapabilities capabilities; if (device.TryGetHapticCapabilities(out capabilities)) { if (capabilities.supportsImpulse) { uint 通道 = 0; float amplitude = 0.5f; 浮点 Duration = 1.0f; device.SendHapticImpulse(channel, amplitude, duration); } }}