Snapdragon Spaces 开发指南（4）

---

5 Unity

5.1 Unity 设置指南

本指南将详细解释如何在 Unity 中开始使用 Snapdragon Spaces SDK。

先决条件

版本

请注意，与 Snapdragon Spaces 配合使用的推荐 Unity 编辑器版本是2021.3.16f1。Unity 编辑器的更高版本可能运行良好，但尚未经过广泛测试。

安装 Unity 编辑器时必须添加 Android 构建支持才能导出 .apk 文件。之后也可以通过 Unity Hub 添加该模块。

导入包

Snapdragon Spaces SDK 以 tarball 文件形式提供。请遵循Unity 说明 （打开新窗口）使用位于Unity Package文件夹中的 tgz 文件将包导入到项目中。

提示

要使用相对路径（更适合版本控制）而不是绝对路径列出包，请将 tgz 文件复制到项目的 Packages 目录中，然后从那里添加它。

XR交互工具包导入

Snapdragon Spaces Unity 包依赖于 XR Interaction Toolkit 包。在导入Snapdragon Spaces包的过程中，导入XR Interaction Toolkit时可能会弹出两个提示：

• 启用新的输入系统：建议通过单击“是”来包含新的输入系统包，以确保 OpenXR 和 XR Interaction Toolkit 包的完整功能。如果还需要旧版输入系统，则可以将下的Active Input Handling值Player > Other Settings > Configuration设置为Both。
• 交互层蒙版更新：交互层蒙版更新器 （打开新窗口）可能会显示升级交互层蒙版的提示。如果之前未将 XR Interaction Toolkit 添加到项目中，则可以选择“否，谢谢” 。如果已经导入了2.0.0之前版本的XR交互工具包包，建议通过单击“我做了备份，继续！”来升级交互图层蒙版。

警告

更新到新的输入系统会重启Unity Editor，这是正常现象。这可能会导致混乱或留下崩溃的印象，但事实并非如此。如果您担心您的项目，请在更新之前按照建议保存或进行备份。

更改项目设置

要启用 Snapdragon Spaces OpenXR 插件，请导航至编辑 > 项目设置 > XR 插件管理下的项目设置，然后打开 Android 选项卡。检查OpenXR插件以及Snapdragon Spaces 功能组。最初，需要更新/修复一些项目设置。为此，请单击OpenXR旁边的红色感叹号以进入 OpenXR 项目验证窗口。单击条目旁边的修复按钮以应用所需的项目设置。最后应用该设置以启用两个输入系统，因为这可能需要重新启动编辑器。

启用空间功能

启用 OpenXR 设置中应在运行时处于活动状态的功能。下表列出了当前支持的功能以及可与其一起使用的相应 AR Foundation 管理器或 XR 子系统。

特征	AR 基金会/空间经理	XR子系统
基本运行时	增强现实会议AR 姿势驱动器	XR会话子系统
相机框架访问	AR相机管理器	XR相机子系统
手部追踪 Spaces	手部追踪管理器	Spaces.XRHandTracking子系统
命中测试	AR 光线投射管理器	XR射线投射子系统
图像追踪	AR跟踪图像管理器	XR图像跟踪子系统
平面检测	AR平面管理器	XRPlane子系统
空间锚点	AR主播经理	XR锚定子系统
空间网格划分（实验）	AR网格管理器	XRMesh子系统

导入样品

Snapdragon Spaces SDK 包附带示例资产，以展示如何使用包中包含的感知功能。要导入它们，只需在包管理器（位于“窗口”>“包管理器”下的菜单栏中）中选择包，然后单击Core Samples.

重要的

相机帧访问示例的实现需要在Player Settings (> Android Tab) > Other Settings group > Script Compilation > Allow ‘unsafe’ Code. 如果您不希望允许不安全代码，不需要 Camera Frame Access 示例，并且想要消除 OpenXR 项目验证中的错误，您可以从 Samples > Snapdragon Spaces > {SDK 中删除 Camera Frame Access Sample 文件夹版本} > 核心示例 > 场景。

导入示例后，有一个帮助工具可以通过单击菜单栏中的“窗口”>“Snapdragon Spaces”>“将场景添加到构建设置”来将示例场景添加到构建设置。

自定义控制器设置

Snapdragon Spaces Unity 包包含在主机设备上启动应用程序时生成控制器的可能性。默认情况下，该功能在BaseRuntimeFeature中启用，该功能位于Edit > Project Settings > XR Plug-in Management > OpenXR (> Android Tab) > OpenXR Feature Groups > BaseRuntimeFeature（通过单击齿轮）。

如果需要具有不同外观和稍微不同功能的自定义实现，则可以按照自定义控制器部分中描述的步骤构建替代控制器存档。

这些步骤生成的存档可以包含在 Unity 项目的 Assets 文件夹中的任何位置，并且必须启用“使用自定义控制器”切换（这还需要启用“在主机上启动控制器”选项）。

警告

在某些情况下，添加自定义控制器存档可能会导致 Gradle 缓存错误。在这种情况下，删除在项目文件夹中生成的临时 Gradle 项目文件夹Temp > gradleOut可能会解决该问题。

添加新的交互配置文件

要使用与 Snapdragon Spaces 插件中包含的交互配置文件不同的交互配置文件，必须将其添加到项目中。要在 Unity 中添加新的交互配置文件，应将其添加到Project Settings > XR Plug-in Management > OpenXR (> Android Tab) > Interaction Profiles. 然后您可以使用新配置文件的输入配置相应的输入操作。

5.2 场景设置

警告
本指南假设您已具备 AR Foundation 和 OpenXR 知识。更详细的概述请访问AR基金会官方 （打开新窗口）和OpenXR （打开新窗口）统一文档。

这是建议的示例场景层次结构，以便在 AR Foundation 和 XR Interaction Toolkit 支持下运行项目：

AR基金会

要启用位置头部跟踪，场景中需要以下对象：

• 增强现实会议
• AR 会话起源
  - AR 相机（将其标记为“MainCamera”）

要手动创建这些游戏对象，请在层次结构面板中右键单击并选择XR > AR Session或XR > AR Session Origin。

警告

例如，如果不需要检索 RGB 相机帧，请禁用GameObject中的AR Camera Manager和组件，以避免已知问题部分中提到的与相机生命周期相关的问题。AR Camera BackgroundAR Camera

直通（仅适用于 MR 设备）

直通 （打开新窗口）指将物理环境作为图像带到VR设备上的可能性。要激活，请在UI > Floating Panel内，有一个Extend Content面板，其中包含用于启用或禁用Passthrough 的复选框。仅当设备兼容直通时，该面板才会对用户有效。此检查是Start()在MainMenuSampleController.cs脚本中使用完成的IsPassthroughSupported()。

UI 面板上的复选框调用OnPassthroughToggle()中的函数MainMenuSampleController，该函数将设置PassthroughToggle中的BaseRuntimeFeature，这将使用户能够查看或隐藏物理环境图像。也可以通过按下每个控制器上的每个主按钮（“X”和“A”按钮）来切换它。

警告

会话摄像机必须将其背景alpha 设置为 0，以便在 Unity 场景上正确使用和可视化Passthrough 。如果已启用直通且会话摄像机的背景设置错误，日志中将显示自动警告。

5.3 交互组件

交互预制件包含三个预制件，用于 Snapdragon Spaces 示例支持的不同交互方法。

交互管理器组件位于该预制件的根 GameObject 中。它包含不同交互输入模式的方法以及处理输入交互切换的代码。

对于AR 设备，如果 Unity 项目中未包含 QCHT 包或手部跟踪与目标设备不兼容，则默认配置将从手部跟踪开始，然后回退到凝视指针。否则，它将从Hand Tracking > Gaze Pointer > Device Input切换。

对于VR/MR 设备，如果跟踪控制器，它将自动以XR 控制器作为默认输入模式启动。否则，它将以“手部追踪”作为默认输入方式开始。交互预制件中的自动控制器开关组件会检测控制器跟踪状态，并在跟踪控制器时自动禁用手部跟踪，或者在没有跟踪控制器时启用手部跟踪。用户可以按左侧控制器上的菜单按钮在 XR 控制器/手部跟踪和注视指针输入模式之间切换。

手部追踪

请参阅QCHT 手部跟踪以获取相关文档

XR交互管理器

每个场景至少需要一个XR 交互管理器，以便在交互器和交互对象之间建立连接。

输入操作必须通过输入操作管理器启用。要手动添加它们，请找到输入操作管理器脚本并将输入操作资产添加为元素。这些资产位于共享资产 > 输入操作下的示例路径中。

凝视指针

凝视指针由以下游戏对象组成：

Gaze Interaction UI组件已添加到XR Gaze Interactor游戏对象中。它管理与XR Gaze Interactor的交互 （打开新窗口）场景中包含 UI 对象的组件以及计时器持续时间和指针的“单击”功能。

注视指针限制
目前，凝视指针只能通过XR Simple Interactable与场景中的 UI 对象进行交互 （打开新窗口）组件，与Pointer Controller不同，Pointer Controller 可以与 UI 和 3D 对象交互。

XR Gaze Interactor 还具有Spaces Composition Layer组件。有关使用合成图层渲染视图锁定内容的文档，请参阅Unity Gaze Pointer 合成图层示例。

控制器经理

控制器管理器由以下游戏对象组成：

在根游戏对象上，XR 控制器管理器组件XRControllerProfile从交互管理器组件接收。如果Host Controller正在使用，设备指针将被激活。设备指针包含主机控制器网格和输入引用。如果使用具有两个控制器的 VR 设备，XR 控制器游戏对象将被激活。XR 控制器预制件包含用于左右控制器的两个游戏对象以及基于动作的控制器 包含对每个控制器预制件的引用和特定输入引用的组件。

交互管理器将XRControllerProfile根据输入设备将所选内容发送到 XR 控制器管理器 正在使用中。请参阅Microsoft 混合现实运动控制器配置文件的 Unity 文档 或Oculus Touch 控制器配置文件

输入备忘单

用于输入操作的按钮：

	主机控制器	XR 控制器右	XR 控制器左
选择	点击触控板	右触发按钮	左触发按钮
凝视/指针开关	菜单按钮	没有任何	左侧菜单按钮
触摸板	触控板	右操纵杆	左操纵杆
锚点位置确认	点击触控板	任意触发按钮	任意触发按钮

控制器触觉

控制器触觉通过交互管理器的SendHapticImpulse发送 （打开新窗口）XR 控制器管理器的功能。调用时SendHapticImpulse，按下 UI 按钮或滚动时，主机控制器和 XR 控制器上都会触发触觉脉冲。

警告
目前，无论哪一个控制器触发操作，两个 XR 控制器都能感受到触觉反馈。

XR 控制器的控制器动画

中的每个 XR 控制器XRControllers都有对其 XR 控制器预制件的引用，其中包含带有按钮混合形状的控制器网格。

每个预制件都附有一个XR 控制器输入动画。该脚本将更新混合形状权重值与控制器每个按钮接收到的值，创建按钮动画。

编辑相机控制器

虽然构建时间可能相当耗时，但编辑器相机控制器允许在 Unity 编辑器本身内进行快速测试，并提供在凝视指针和控制器之间切换的快捷键。切换的关键是编辑器控制台中的输出。

提示
XR设备模拟器 （打开新窗口）还与 Snapdragon Spaces 示例兼容，用于编辑器模拟交互。

互动套餐
Snapdragon Spaces 插件与许多交互包配合得很好。请参阅具体页面，了解如何开始使用这些内容的详细信息：

MRTK3
QCHT
XRIT