Unity XR Input

В этом разделе руководства пользователя Unity содержится информация обо всех поддерживаемых Unity устройствах ввода для виртуальной реальностисистемы, которая погружает пользователей в искусственный трехмерный мир с реалистичными изображениями и звуками, используя гарнитуру и отслеживание движения. Подробнее
См. Словарь, дополненную реальность и приложения Windows Mixed Reality. На этой странице рассматриваются следующие темы:

• сопоставления ввода XR
• Доступ к устройствам ввода
• Доступ к функциям ввода на устройстве ввода
• Доступ к вводу XR через устаревшую систему ввода
• Тактильные ощущения

Платформы XR имеют множество функций ввода, которыми можно воспользоваться при разработке взаимодействия с пользователем. Ваше приложение может использовать определенные данные, которые относятся к положениям, поворотам, прикосновениям, кнопкам, джойстикам и датчикам пальцев. Однако доступ к этим функциям ввода может сильно различаться между платформами. Например, между Vive и Oculus Rift есть небольшая разница, но настольная платформа с поддержкой виртуальной реальности и мобильная платформа, такая как Daydream, отличаются гораздо больше.

Unity предоставляет структуру C# с именем InputFeatureUsage, которая определяет стандартный набор элементов управления физического устройства (таких как кнопки и триггеры) для доступа к пользовательскому вводу. на любой платформе. Это поможет вам идентифицировать типы ввода по имени. См. XR.Input.CommonUsages для определения каждого InputFeatureUsage.

Каждый элемент InputFeatureUsage соответствует обычному действию ввода или типу. Например, Unity определяет InputFeatureUsage, называемый trigger, как ввод по одной оси, которым управляет указательный палец, независимо от того, какой XRОбщий термин, охватывающий приложения виртуальной реальности (VR), дополненной реальности (AR) и смешанной реальности (MR). Устройства, поддерживающие эти формы интерактивных приложений, можно назвать устройствами XR. Подробнее
См. в Словарь. Вы можете использовать InputFeatureUsage, чтобы получить состояние триггера, используя его имя, поэтому вам не нужно настраивать ось (или кнопка на некоторых платформах XR) для обычной системы ввода Unity.

Сопоставление ввода XR

В следующей таблице перечислены имена стандартных контроллеров InputFeatureUsage и их сопоставление с контроллерами популярных систем XR:

(1) Сэндвич-кнопка относится к кнопке меню Vive. Эта кнопка сопоставляется с primaryButton, а не с menuButton, чтобы лучше обрабатывать кросс-платформенные приложения.

См. XR.Input.CommonUsages определение каждого InputFeatureUsage.

Доступ к устройствам ввода

InputDevice представляет собой любое физическое устройство, например контроллер, мобильный телефон или гарнитуру. Он может содержать информацию об отслеживании устройства, кнопках, джойстиках и других элементах управления вводом. Дополнительные сведения об API InputDevice см. в документации по InputDevice.

Используйте класс XR.InputDevices для доступа к устройствам ввода, которые в данный момент подключены к системе XR. Чтобы получить список всех подключенных устройств, используйте InputDevices.GetDevices:

var inputDevices = new List(); UnityEngine.XR.InputDevices.GetDevices(inputDevices); foreach (var device in inputDevices) { Debug.Log(string.Format("Device found with name '{0}' and role '{1}'", device.name, device.role.ToString())); }

Устройство ввода остается действительным во всех кадрах, пока система XR не отключит его. Используйте свойство InputDevice.IsValid, чтобы определить, представляет ли InputDevice активный контроллер.

Вы можете получить доступ к устройствам ввода следующим образом:

• Characteristics
• Role
• XR node

Доступ к устройствам ввода по характеристикам

Характеристики устройства описывают, на что способно устройство или для чего оно используется (например, крепится ли оно на голове). InputDeviceCharacteristics – это набор флагов, которые вы можете добавить в свой код для поиска устройств, соответствующих определенной спецификации. Вы можете фильтровать устройства по следующим характеристикам:

Устройство	Характеристика
HeadMounted	Устройство крепится к голове пользователя. Он имеет отслеживание устройства и центральное отслеживание глаз. Этот флаг чаще всего используется для идентификации головных дисплеев (HMD)..
CameraКомпонент, который создает изображение определенной точки обзора в вашей сцене. Вывод либо рисуется на экране, либо фиксируется в виде текстуры. More info See in Словарь	Устройство имеет камеру слежения.
HeldInHand	Пользователь держит устройство в руке.
HandTracking	Устройство представляет собой физически отслеживаемую руку. Он отслеживает устройства и может содержать данные о руках и костях.
EyeTracking	Устройство может выполнять отслеживание взгляда и имеет функцию EyesData.
TrackedDevice	Устройство можно отслеживать в 3D-пространстве. Есть отслеживание устройств.
Controller	Устройство имеет входные данные для кнопок и осей и может использоваться как контроллер.
TrackingReference	Устройство представляет собой статический эталонный объект слежения. У него есть отслеживание устройств, но эти данные отслеживания не должны меняться..
Left	Используйте эту характеристику в сочетании с характеристиками HeldInHand или HandTracking, чтобы идентифицировать устройство как связанное с левой рукой.
Right	Используйте эту характеристику в сочетании с характеристиками HeldInHand или HandTracking, чтобы идентифицировать устройство как связанное с правой рукой.
Simulated6DOF	Устройство сообщает данные 6DOF, но имеет только датчики 3DOF. Unity моделирует позиционные данные.

Основной XR SDK сообщает об этих характеристиках. Вы можете найти их с помощью InputDevice.Characteristics. Устройство может и часто должно иметь несколько характеристик, которые можно фильтровать и получать к ним доступ с помощью битовых флагов.

InputDevices.GetDevicesWithCharacteristics позволяет искать все устройства с заданным набором характеристик. Например, вы можете искать Left, HeldInHand, Controller InputDevices, доступные в системе, с помощью следующего кода:

var leftHandedControllers = new List(); var desiredCharacteristics = UnityEngine.XR.InputDeviceCharacteristics.HeldInHand | UnityEngine.XR.InputDeviceCharacteristics.Left | UnityEngine.XR.InputDeviceCharacteristics.Controller; UnityEngine.XR.InputDevices.GetDevicesWithCharacteristics(desiredCharacteristics, leftHandedControllers); foreach (var device in leftHandedControllers) { Debug.Log(string.Format("Device name '{0}' has characteristics '{1}'", device.name, device.characteristics.ToString())); }

Устройства, которые находит эта функция, содержат как минимум указанные характеристики, но могут содержать дополнительные характеристики. Например, чтобы найти контроллер для левшей, вы можете искать только InputDeviceCharacteristic.Left, а не InputDeviceCharacteristic.Controller.

Доступ к устройствам ввода по роли

Роль устройства описывает общую функцию устройства ввода. Используйте перечисление InputDeviceRole, чтобы указать роль устройства. Определенные роли:

Роль	Описание
GameController	Консольный игровой контроллерУстройство для управления объектами и персонажами в игре. See in Словарь.
Generic	Устройство, представляющее основное устройство XR, например головной дисплей или мобильное устройство.
HardwareTracker	Устройство слежения.
LeftHanded	Устройство, связанное с левой рукой пользователя.
RightHanded	Устройство, связанное с правой рукой пользователя.
TrackingReference	Устройство, которое отслеживает другие устройства, например камеру слежения Oculus..

Основной SDK XR сообщает об этих ролях, но разные поставщики могут по-разному организовывать свои роли устройств. Кроме того, пользователь может менять руки, поэтому назначение ролей может не соответствовать руке, в которой пользователь держит устройство ввода. Например, пользователь должен настроить контроллер Daydream как правша или левша, но может держать контроллер в противоположной руке.

GetDevicesWithRole предоставляет список всех устройств с определенной InputDeviceRole. Например, вы можете использовать InputDeviceRole.GameController для получения любых подключенных устройств GameController:

var gameControllers = new List(); UnityEngine.XR.InputDevices.GetDevicesWithRole(UnityEngine.XR.InputDeviceRole.GameController, gameControllers); foreach (var device in gameControllers) { Debug.Log(string.Format("Device name '{0}' has role '{1}'", device.name, device.role.ToString())); }

Доступ к устройствам ввода с помощью узла XR

Узлы XR представляют собой физические точки отсчета в системе XR (например, положение головы пользователя, его правая и левая руки или эталон отслеживания, такой как камера Oculus).

Перечисление XRNode определяет следующие узлы:

Узел XR	Описание
CenterEye	Точка посередине между зрачками глаз пользователя.
GameController	Игровой контроллер консольного типа. Ваше приложение может иметь несколько игровых контроллеров..
HardwareTracker	Аппаратное устройство слежения, обычно прикрепленное к пользователю или физическому предмету. Может существовать несколько узлов аппаратного трекера.
Head	Центральная точка головы пользователя, рассчитанная системой XR.
LeftEye	Левый глаз пользователя.
LeftHand	Левая рука пользователя.
RightEye	Правый глаз пользователя.
RightHand	Правая рука пользователя.
TrackingReference	Контрольная точка отслеживания, например камера Oculus. Может существовать несколько эталонных узлов отслеживания.

Используйте InputDevices.GetDevicesAtXRNode, чтобы получить список устройств, связанных с определенным XRNode. В следующем примере показано, как получить контроллер для левшей:

var leftHandDevices = new List(); 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!"); }

Прослушивание подключений и отключений устройств

Устройства ввода неизменны от кадра к кадру, но могут подключаться или отключаться в любое время. Чтобы избежать повторной проверки того, подключено ли устройство к платформе, используйте InputDevices.deviceConnected и InputDevices.deviceDisconnected для уведомления приложения о подключении или отключении устройства. Они также предоставляют вам ссылку на недавно подключенное устройство ввода.

Поскольку вы можете сохранять эти ссылки в нескольких кадрах, устройство может отключиться или стать недоступным по другой причине. Чтобы проверить, доступны ли входные данные устройства, используйте InputDevice.isValid. СкриптыЧасть кода, позволяющая создавать собственные компоненты, запускать игровые события, изменять свойства компонентов с течением времени и реагировать на действия пользователя. вводите любым удобным для вас способом. Подробнее
См. в Словарь, что устройства доступа должны проверять это в начале каждого кадра. прежде чем они попытаются использовать это устройство.

Доступ к функциям ввода на устройстве ввода

Вы можете прочитать функцию ввода, например состояние кнопки-триггера, с определенного InputDevice. Например, чтобы прочитать состояние правого триггера, выполните следующие действия:

1. Используйте InputDeviceRole.RightHanded или XRNode.RightHand чтобы получить экземпляр правого устройства.
2. Получив нужное устройство, используйте метод InputDevice.TryGetFeatureValue для доступа к текущему состоянию.

TryGetFeatureValue() пытается получить доступ к текущему значению функции и возвращает:

• true, если он успешно извлекает указанное значение функции
• false, если текущее устройство не поддерживает указанную функцию или устройство недействительно (то есть контроллер больше не активен)

Чтобы получить определенную кнопку, сенсорный ввод или значение оси джойстика, используйте класс CommonUsages. CommonUsages включает каждый InputFeatureUsage в таблицу сопоставления ввода XR, а также как функции отслеживания, такие как положение и вращение. В следующем примере кода CommonUsages.triggerButton используется для определения того, нажимает ли пользователь в данный момент кнопку триггера на определенном InputDevice экземпляр:

bool triggerValue; if (device.TryGetFeatureValue(UnityEngine.XR.CommonUsages.triggerButton, out triggerValue) && triggerValue) { Debug.Log("Trigger button is pressed."); }

Вы также можете использовать метод InputDevice.TryGetFeatureUsages, чтобы получить список всех InputFeatureUsage, который предоставляет устройство. Эта функция возвращает список элементов InputFeatureUsage, которые имеют свойства типа и имени, описывающие функцию. В следующем примере перечислены все булевы функции, предоставляемые данным устройством ввода:

var inputFeatures = new List(); if (device.TryGetFeatureUsages(inputFeatures)) { foreach (var feature in inputFeatures) { if (feature.type == typeof(bool)) { bool featureValue; if (device.TryGetFeatureValue(feature.As(), out featureValue)) { Debug.Log(string.Format("Bool feature {0}'s value is {1}", feature.name, featureValue.ToString())); } } } }

Пример для основной кнопки

Разные конфигурации контроллера обеспечивают доступ к разным функциям. Например, у вас может быть несколько контроллеров в одной системе, разные контроллеры в разных системах или разные кнопки на одних и тех же контроллерах с разными SDK. Это разнообразие усложняет поддержку ввода из ряда систем XR. Unity API InputFeatureUsage помогает получать входные данные, не зависящие от платформы.

В следующем примере осуществляется доступ к элементу InputFeatureUsage, который называется primaryButton, независимо от того, какой контроллер или устройство ввода предоставляет его. Пример включает класс, который сканирует доступные устройства на наличие primaryButton по мере их подключения. Класс отслеживает значение функции на любом подключенном устройстве и, если значение изменяется, класс отправляет UnityEvent.

Чтобы использовать этот класс, добавьте его как компонент к любому GameObjectфундаментальному объекту в сценах Unity, который может представлять персонажей. , реквизит, декорации, камеры, путевые точки и многое другое. Функциональность GameObject определяется прикрепленными к нему компонентами. Подробнее
См. в Словарь в СценаСцена содержит окружение и меню вашей игры. Думайте о каждом уникальном файле сцены как об уникальном уровне. В каждой сцене вы размещаете свое окружение, препятствия и декорации, по сути проектируя и создавая свою игру по частям. Подробнее
См. в Словарь. Например:

using System.Collections.Generic; using UnityEngine; using UnityEngine.Events; using UnityEngine.XR; [System.Serializable] public class PrimaryButtonEvent : UnityEvent { } public class PrimaryButtonWatcher : MonoBehaviour { public PrimaryButtonEvent primaryButtonPress; private bool lastButtonState = false; private List devicesWithPrimaryButton; private void Awake() { if (primaryButtonPress == null) { primaryButtonPress = new PrimaryButtonEvent(); } devicesWithPrimaryButton = new List(); } void OnEnable() { List allDevices = new List(); InputDevices.GetDevices(allDevices); foreach(InputDevice device in allDevices) 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 device) { bool discardedValue; if (device.TryGetFeatureValue(CommonUsages.primaryButton, out discardedValue)) { devicesWithPrimaryButton.Add(device); // Add any devices that have a primary button. } } private void InputDevices_deviceDisconnected(InputDevice device) { if (devicesWithPrimaryButton.Contains(device)) devicesWithPrimaryButton.Remove(device); } void Update() { bool tempState = false; foreach (var device in devicesWithPrimaryButton) { bool primaryButtonState = false; tempState = device.TryGetFeatureValue(CommonUsages.primaryButton, out primaryButtonState) // did get a value && primaryButtonState // the value we got || tempState; // cumulative result from other controllers } if (tempState != lastButtonState) // Button state changed since last frame { primaryButtonPress.Invoke(tempState); lastButtonState = tempState; } } }

Следующий класс PrimaryReactor использует PrimaryButtonWatcher для обнаружения нажатия основной кнопки и, в ответ на нажатие, вращает свой родительский GameObject. Чтобы использовать этот класс, добавьте его в видимый игровой объект, например куб, и перетащите ссылку PrimaryButtonWatcher в свойство Watcher.

using 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 Quaternion offRotation; private Quaternion 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(Quaternion fromRotation, Quaternion toRotation) { float t = 0; while (t < rotationDuration) { transform.rotation = Quaternion.Lerp(fromRotation, toRotation, t / rotationDuration); t += Time.deltaTime; yield return null; } } }

Доступ к данным отслеживания рук

InputDevices поддерживает устройства слежения за руками. Устройство слежения за руками всегда:

• имеет HandTracking характеристику
• содержит CommonUsages.HandData использование Hand тип

Данные отслеживания рук состоят из объекта Hand и набора до 21 функции ввода Bone. Каждая Кость имеет положение и ориентацию, а также ссылки как на родительскую, так и на любые дочерние кости в иерархии. Объект Hand может получить либо корневую кость, либо список костей для каждого отдельного пальца.

Когда Hand.TryGetRootBone получает корневую кость, он извлекает объект, представляющий кость, расположенную чуть выше запястья. Вы также можете получить список костей, представляющих каждый отдельный палец. Вызов Hand.TryGetFingerBones возвращает список костей, представляющих этот палец, от сустава до кончика.

Доступ к данным отслеживания взгляда

Устройства ввода поддерживают устройства слежения за глазами, а также устройства слежения за руками. Отслеживание взгляда состоит из положения левого и правого глаза, местоположения в трехмерном пространстве, куда смотрит пользователь, и количества морганий каждого отдельного глаза. Его тип данных — Eyes. Чтобы получить его с устройства, используйте CommonUsages.eyesData.

Ассоциация XRInputSubsystem и InputDevice

Unity предоставляет две системы ввода: устаревшую систему ввода и Архитектура подключаемого модуля XR представлена ​​в 2019.2. В новой настройке каждое InputDevice связано с XRInputSubsystem. Эти объекты подсистемы управляют глобальным поведением ввода, которое не связано с каким-либо конкретным устройством ввода (например, управление источником отслеживания или центрирование отслеживаемых устройств).

Каждое InputDevice содержит ссылку на связанную с ним подсистему. Эта ссылка пуста, если устройство создано на интегрированной платформе. Вы также можете получить все активные объекты XRInputSubsystem с помощью SubsystemManager.GetInstances, а каждая XRInputSubsystem может получить свои устройства с помощью XRInputSubsystem.TryGetInputDevices.

Вы можете использовать подсистему ввода для центрирования устройств с помощью UnityEngine.XR.XRInputSubsystem. Recenter устанавливает текущую позицию HMD в качестве нового исходного положения для всех устройств. Он возвращает false для устройств, которые не могут быть центрированы, или если платформа не поддерживает центрирование.

Чтобы получить границу отслеживания, используйте TryGetBoundaryPoints. Он состоит из ряда трехмерных точек, расположенных по часовой стрелке, где значение y находится на уровне пола, и они отмечают указанную пользователем «безопасную зону» для размещения контента и взаимодействия. Вы можете прослушивать изменения этой границы с помощью XRInputSubsystem.boundaryChanged.

Подсистема XRInputSubsystem также отвечает за режим источника отслеживания, который обеспечивает контекст того, где находится источник мира отслеживания. Unity поддерживает следующие режимы источника отслеживания:

• Устройство: исходное местоположение — первое известное местоположение основного устройства отображения; часто HMD или телефон.
• Этаж: исходное положение находится в известном месте на полу.
• Ссылка для отслеживания: местоположение источника находится на устройстве InputDevice с установленной характеристикой TrackingReference.
• Неизвестно: тип источника отслеживания неизвестен. Это может быть связано с системным сбоем или отсутствием поддержки режима отслеживания.

Для управления режимом источника отслеживания можно использовать три API:

• XRInputSubsystem.TrySetTrackingOriginMode устанавливает режим источника отслеживания
• XRInputSubystem.GetTrackingOriginMode извлекает режим источника отслеживания
• XRInputSubsystem.GetSupportedTrackingOriginModes извлекает все режимы источника отслеживания, поддерживаемые SDK

Ввод XR через устаревшую систему ввода

Вы по-прежнему можете использовать устаревшую систему ввода, состоящую из Input и XR.InputTracking, чтобы получить функции ввода XR. Для этого используйте соответствующие устаревшие входные индексы из таблицы сопоставлений входных данных XR на этой странице. В разделе Ввод в разделе Настройки проигрывателяНастройки, позволяющие установить различные финальная игра, созданная Unity. Подробнее
См. в Словарь (меню: Редактировать > Настройки проектаБольшой набор настроек, которые позволяют настраивать физику, аудио, сеть, графику, ввод и ведут себя многие другие области вашего проекта. Подробнее
См. в разделе Словарь > Ввод), создайте сопоставление осей, чтобы добавить соответствующее сопоставление от имени ввода к индексу оси для функции устройства платформы. Чтобы получить значение кнопки или оси, используйте Input.GetAxis или Input.GetButton. и передайте сопоставленную ось или имя кнопки.

Дополнительную информацию об использовании кнопок и осей джойстика см. в документации по InputManager.

Тактильные ощущения

Вы можете отправлять тактильные события на InputDevice. Тактильные ощущения принимают форму импульса с амплитудой и продолжительностью.

Не все платформы поддерживают все типы тактильных ощущений, но вы можете запросить у устройства тактильные возможности. Следующий пример получает устройство ввода для правой руки, проверяет, поддерживает ли устройство тактильные ощущения, а затем воспроизводит импульс, если оно поддерживает:

List devices = new List(); UnityEngine.XR.InputDevices.GetDevicesWithRole(UnityEngine.XR.InputDeviceRole.RightHanded, devices); foreach (var device in devices) { UnityEngine.XR.HapticCapabilities capabilities; if (device.TryGetHapticCapabilities(out capabilities)) { if (capabilities.supportsImpulse) { uint channel = 0; float amplitude = 0.5f; float duration = 1.0f; device.SendHapticImpulse(channel, amplitude, duration); } } }

---

• Обновлена таблица сопоставлений ввода XR и обновлены примеры кода в 2019.2
• Новые функции и поведение в 2019.1