Snapdragon Spaces 开发指南（10）

---

5.6.7 空间网格划分示例

警告
空间网格功能被标记为实验性的，因为软件包和 Snapdragon Spaces 服务端的优化目前正在破坏各个版本的向后兼容性。

此示例演示了如何生成和可视化近似现实世界环境的空间网格。有关空间网格划分以及 AR Foundation 的 AR Mesh Manager 组件功能的基本信息，请参阅 Unity 文档（打开新窗口）。为了使用此功能，必须在项目设置 > XR 插件管理 > OpenXR（> Android 选项卡）下的 OpenXR 插件设置中启用它。

5.6.7.1 示例如何工作

5.6.7.1.1 ARM网格管理器

ARMeshManager 组件必须附加到 ARSessionOrigin GameObject 的子级。该组件引用了当网格可用时将生成的 MeshFilter。

警告
将 ARMeshManager 组件附加到相机对象将导致对象的 Scale 发生变化，从原来的 (1, 1, 1) 变为 (10, 10, 10)。这将导致应用程序在头戴式设备上出现渲染问题，直到恢复原始相机比例。

不支持以下属性：

• 目前不支持更改生成的网格的密度。
• 切线、纹理坐标和颜色当前不作为网格的一部分生成。从 ARMeshManager 组件访问这些属性的缓冲区可能会生成空结果。
• 当前不支持更改并发队列大小。

默认情况下启用法线属性。

提示
构建应用程序时，对不受支持的 ARMeshManager 组件属性进行更改将会在控制台中出现警告。

通过订阅 ARMeshManager 组件的 meshesChanged 回调，可以检索有关何时添加、更新或删除网格的数据。

5.6.7.1.2 示例代码

    private ARMeshManager _meshManager;

        public void Awake() {
            _meshManager = FindObjectOfType<ARMeshManager>();
        }

        public override void OnEnable() {
            ...
            _meshManager.meshesChanged += OnMeshesChanged;
        }

        public override void OnDisable() {
            ...
            _meshManager.meshesChanged -= OnMeshesChanged;
        }

        void OnMeshesChanged(ARMeshesChangedEventArgs args) {
            foreach (MeshFilter meshFilter in args.added) {
                ...
            }

            foreach (MeshFilter meshFilter in args.updated) {
                ...
            }

            foreach (MeshFilter meshFilter in args.removed) {
                ...
            }
        }

5.6.7.1.3 Spaces AR 网格管理器配置

AR Mesh Manager 组件具有 Snapdragon Spaces Unity 包的子系统实现不支持的属性。当运行构建并启用空间网格（实验）功能时，尝试使用任何不受支持的属性将显示警告。建议使用（可选）Spaces AR Mesh Manager 配置组件，该组件具有用于配置生成的网格的附加选项。通过此组件，空间网格提供程序还可以处理来自运行时端的与 TrackingOriginMode.Floor 相关的摄像机高度偏移。如果在这种情况下不使用此组件，网格可能会出现在错误的位置。

该组件必须附加到与 ARMeshManager 组件相同的 GameObject。

• 计算 CPU 法线：
  • 如果启用，则会计算网格中每个顶点的 CPU 法线。
  • 某些顶点可能会在网格中重复（使用不同的索引）。
  • 这可能会导致生成的网格中出现可见的接缝。
  • 对于网格中的每个索引，引用该索引的每个三角形都有助于生成法线，但不同的索引（重复顶点）可以具有不同的法线。
  • 如果 ARMeshManager 组件上的计算 CPU 法线属性和法线属性未同时启用或禁用，则在构建应用程序时，控制台中将输出解释性警告。
• 使用平滑法线：
  • 如果启用，每个顶点的 cpu 法线都会平滑。
  • 所有引用具有相同空间但不同索引的顶点的三角形都会将这些重复顶点视为同一顶点。
  • 这可能会导致检测到的几何体中的硬边缘不太清晰，但会减少接缝的出现。
  • 计算平滑法线将使用增强的处理能力，并对性能产生影响。

默认情况下，当打开样本时，它会生成一个网格，其多边形适合检测到的环境。

• 启用计算 CPU 法线属性后，将通过使用具有 Cpu 法线材质的网格的标准着色器来可视化网格。
• 禁用计算 CPU 法线属性时，将使用自定义 MeshVisualization.shader 来可视化网格，该着色器生成的法线仅用于可视化目的。

5.7 双渲染融合（实验性）

双渲染融合是增强现实 (AR) 的一项新核心功能，可与 Snapdragon Spaces for Unity SDK 一起使用，并允许同时将渲染输出到移动屏幕和连接的增强现实设备，所有这些都在同一个 Android 活动中进行。这还允许使用移动触摸屏输入的全功能以及 Snapdragon Spaces 提供的完整感知功能。

警告
Dual Render Fusion 目前处于测试版（标记为实验版），作为 Snapdragon Spaces SDK for Unity（打开新窗口）版本 0.13.0 及更高版本的可选附加包。

要查看架构信息和支持的平台，请参阅双渲染融合架构页面。

5.7.1 简介

5.7.1.1双渲染功能

双渲染融合将智能手机设置为主显示器，同时将系留的 AR 耳机视为连接的辅助显示器。

在此屏幕截图中，AR 显示器针对显示器 2 进行编辑器内测试，而在设备上，AR 显示器应针对显示器 1。

这种双渲染功能能够将新的或现有的 2D 移动应用程序扩展到 3D 增强现实体验，而无需任何代码，因为其核心概念是将第二个游戏内摄像头添加到 2D 应用程序中，以充当扩展的 AR 显示器。

5.7.1.2 完整的多模态输入

双渲染融合还可以让开发人员受益，因为他们可以选择利用 Snapdragon Spaces SDK 启用的可用 XR 输入（包括手部跟踪、光线投射和凝视指针），同时还让用户方便和熟悉完整的移动触摸屏。凭借多点触控功能，用户界面可以像手机上的任何现有应用程序一样动态。

5.7.1.3 移动应用程序扩展

由于手机能够进行全功能输入和渲染，因此添加 AR 现在就像添加第二个游戏内摄像头来处理增强现实眼镜的姿势和输出一样简单。通过这种组合，现在可以以一种新的沉浸式方式查看现有的移动应用程序，同时保留熟悉的控制机制。这使得现有应用程序和演示能够快速移植到 Snapdragon Spaces 中。

5.7.1.4 用例示例

就像手机一样，双渲染融合的用例是无限的，因为这种类型的功能可用于增强当今任何现有的移动应用程序类型。以下是利用双渲染融合提供的自然输入时日常增强现实的一些示例。

5.7.1.4.1 网上购物

通过触摸屏输入，现在可以针对智能手机优化用户界面，同时可以定制世界级家具或服装等重要元素，并直接从连接的增强现实耳机进行查看。

5.7.1.4.2 媒体观看

开发人员可以结合自然的触摸屏输入功能，在智能手机上滑动浏览他们最喜欢的照片，同时使用增强现实中的手部跟踪移动和扩展单张照片。

5.7.1.4.3 游戏

双渲染融合还允许开发人员将智能手机用作移动游戏的全触摸屏控制器，同时在增强现实中显示游戏动作的额外沉浸式视图。

5.7.2 Unity 双渲染融合设置指南

本指南将详细解释如何开始在 Unity 中使用 Snapdragon Spaces SDK 来启用双渲染融合。

5.7.2.1 前提条件

版本
请注意，与 Snapdragon Spaces 配合使用的推荐 Unity 编辑器版本是 2021.3.16f1。不保证 Unity 编辑器的更高版本能够正常工作，并且不受官方支持。

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

5.7.2.2 从 3D Unity 项目开始

创建新的 3D（或 3D URP）Unity 项目，或使用现有的 Unity 项目。

注意
如果转换已使用 Snapdragon Spaces 构建的项目，请备份该项目并直接导入双渲染融合包。

5.7.2.3 导入 Snapdragon Spaces 包

Snapdragon Spaces for Unity SDK（打开新窗口）以 tarball 文件形式提供。

请按照 Unity 说明（打开新窗口）通过添加位于 Unity Package 文件夹中的 tarball (.tgz) 文件，使用 Unity Package Manager 将包导入到项目中。

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

注意
导入包后，Unity 可能会显示启用新输入系统的提示。单击是以确保 OpenXR 和 XR 交互工具包包的完整功能。如果还需要旧的输入系统，则可以将播放器>其他设置>配置下的活动输入处理值设置为两者。

5.7.2.4 导入双渲染融合包

随着 Dual Render Fusion 作为实验包公开测试版，启用此功能的文件作为单独的 Unity 包 tarball 提供，可在 Snapdragon Spaces for Unity SDK 下载页面（打开新窗口）获取。

再次按照 Unity 说明（打开新窗口）使用 Unity 包管理器将包导入到项目中，添加位于 Dual Render Fusion 包下载中的 tarball (.tgz) 文件。

还建议此时通过包管理器导入 Fusion 示例。

5.7.2.5 更改项目设置

要启用 Snapdragon Spaces OpenXR 插件，请导航至编辑 > 项目设置 > XR 插件管理下的项目设置，然后打开 Android 选项卡。
检查 OpenXR 插件，但暂时不要检查 Snapdragon Spaces 功能组。

相反，单击 OpenXR 菜单项可显示不同的 OpenXR 功能选项。请注意新的双渲染融合功能，并检查基本运行时功能和双渲染融合功能，如图所示。单击“双渲染融合”旁边的红色感叹号以打开“项目验证器”。

项目验证器将显示多个修复选项，用于更新 Unity 项目和当前打开的场景，因此请确保在项目中打开正确的场景。

请注意带有前缀 [Dual Render Fusion (Experimental)] 的验证器选项。应首先解决这些问题以更新项目并打开场景，然后再为项目的其余部分选择全部修复。 （这是因为双渲染融合的验证器选项将解决其他一些默认空间验证器问题）

注意
如果 Dual Render Fusion 显示感叹号，但没有出现相关的 Project Validator 选项，请在 Packages > Snapdragon Spaces Dual Render Fusion (Experimental) > Runtime > FusionFeature.FeatureValidation 中重新导入 Fusion Feature Validator 脚本，以完全重新处理项目验证文件。

完成 Dual Render Fusion 验证后，单击剩余条目旁边的“修复”按钮以应用任何需要的项目设置。某些修复可能需要重新启动编辑器，这是正常的。

此时，应正确启用双渲染融合以进行启动。请参阅下文了解更多信息和高级配置功能。

5.7.2.6 配置双渲染融合设置

双渲染融合功能的可用设置包括：

1. Require Spaces Services（需要空间服务）- 启用此设置后，将确保 Base Runtime Feature（基本运行时功能）中的 **Check Installed Runtime（检查已安装的运行时）设置也处于打开状态。Check Installed Runtime" 可防止应用程序在未安装骁龙 Spaces 服务时启动。禁用此设置可允许应用程序以仅在移动模式下运行，从而允许应用程序作为独立体验在任何兼容的移动设备上运行，而无需兼容的 AR 眼镜。
2. 验证开放场景 - 启用此设置后，Unity 场景验证器将检查开放场景中是否存在正确配置的 XR 相机和移动相机。如果项目的构建系统没有全功能场景（例如附加场景），请禁用此设置以避免构建障碍。

5.7.2.7双渲染融合示例

包管理器提供了一系列示例场景和示例代码脚本。

1. 控制器预制件示例场景 - 用于将 Snapdragon Spaces 的 Android 配套控制器调整为 Unity 预制件的示例场景，可完全控制设置和退出按钮。有关更多详细信息，请参阅下面的配套控制器。
2. CubeManipulation - 一个带有立方体的简单场景，可以使用触摸板上的一个、两个或三个手指移动该立方体，作为创建响应式多点触控界面的辅助工具。
3. LandscapeUISampleScene - 一个带有 Landscape Canvas 的简单场景，其中包含用于操作立方体的可交互 Canvas UI 元素。
4. OpenXRLoadingTest - 该场景演示了允许应用程序在智能手机上立即启动，然后在与眼镜建立连接后启用 OpenXR。有关更多详细信息，请参阅下面的动态 OpenXR 加载器。
5. PortraitUISampleScene - 一个简单的场景，带有包含可交互 Canvas UI 元素的 Portrait Canvas。

5.7.2.7.1 配套控制器

一些开发人员希望迁移现有的 Snapdragon Spaces 项目以使用双渲染融合，并利用陀螺仪 3DOF 指向的配套控制器功能。请按照以下步骤将其添加到项目中。

要在 Unity 中复制配套控制器，需要多个资源以及一些脚本。

1. 如果需要，请在出现提示时导入 TextMeshPro。

2. 将 CanvasControllerCompanion Prefab 从 Samples 拖到 Hierarchy 中。

3. 两个游戏对象需要连接到 XR 相机，因为它不是预制件的一部分。如果未设置这些，将自动检测 XR Origin 或 AR Session Origin 以使用连接的相机。或者，可以在此处手动设置它们：

   在 ControllerPositionHeadMirror 的 Ar Camera 字段下。

   
   在 GyroRotationReceiver 中的 Ar Camera 字段下。

   

4. 确保输入系统设置为两者以启用陀螺仪控制：

   

5. 将 ControllerPrefabInputActions 作为附加操作资源添加到输入操作管理器。如果层次结构中没有输入操作管理器，请创建一个游戏对象并添加组件。

   

6. 要利用菜单按钮功能，可以仅使用标准 Unity 输入系统并将 On Click() 事件添加到代表菜单按钮的层次结构中的按钮对象。

   

7. 要在“设置”菜单中添加更多选项，请暂时打开“设置覆盖游戏对象”并将菜单项添加到“滚动框”列表中。 （目前，“关于”按钮没有任何功能，仅作为示例。）

   

5.7.2.7.2 动态 OpenXR 加载器

Dynamic OpenXR Loader 是一个实验性示例脚本，允许应用程序在连接眼镜后加载 OpenXR，类似于耳机工作原理的概念。该脚本只是检测辅助显示器是否存在，然后启动 OpenXR（如果已配置）。当 OpenXR 开始连接时，可以使用多个回调来控制用户界面的行为。请参阅 OpenXRLoadingTest 示例以查看如何使用此脚本的示例。

注意

1. 目前不建议启用手势追踪功能的应用程序使用此功能。目前，动态 OpenXR 加载器的并发性与手部跟踪功能不兼容，并且在应用程序初始化过程之外使用此功能启动 OpenXR 可能会导致应用程序在尝试加载时突然退出。这将在未来版本中修复。
2. 当 OpenXR 开始连接时，主线程会被阻塞一小段时间。建议显示一些 UI 元素，表明 OpenXR 正在连接，并让该元素在加载完成后显示确认状态。

5.7.2.8 功能验证配置

双渲染融合功能验证器设置为轻松配置 Unity 项目和选定场景以启用双渲染融合。这是验证列表。

范围	验证	描述	原因
项目	禁用自定义启动器	禁用基本运行时功能中用于在查看器上启动和在主机上启动控制器的复选框	双渲染融合需要禁用自定义启动器行为（请参阅头戴式架构）
场景	需要 AR 会话来源	确保 AR 会话原点（或 XR 原点）和关联的 XR 相机位于场景中	AR Foundation 需要 XR 相机
场景	需要 AR 会话	确保 AR 会话和 AR 输入管理器位于场景中	AR Foundation 需要一个 AR 会话
场景	需要移动相机	确保代表移动设备屏幕的 Unity 相机位于场景中	双渲染融合需要移动显示器进行渲染
场景	主相机标签	确保只有 XR 相机或其他非纹理渲染相机被标记为主相机，而不是两者都被标记为主相机	将两个相机标记为 MainCamera 可能会导致渲染错误或破坏其他依赖项
场景	相机渲染优先级	确保移动相机在 XR 相机之后渲染	如果 XR 相机在移动相机之后渲染，则移动显示将被 XR 相机的副本取代
场景	相机眼睛目标	确保 XR 相机眼睛目标设置为两者，所有其他相机设置为无	相机眼睛目标确定每个相机将渲染到哪个显示器
场景	移动摄像头眼目标 (URP)	显示警告以检查移动摄像头眼睛目标是否设置为无	URP 无法以与内置渲染管道相同的方式以编程方式设置眼睛目标，因此会显示警告以手动检查它
场景	相机显示目标	如果 XR 摄像头目标显示器未设置为显示器 1，建议添加 Fusion Logic 游戏对象和组件	两个显示目标必须设置为显示 1，双渲染融合才能正确渲染到两个设备。 XR 相​​机默认设置为目标显示 2，“Fusion Logic”在运行时将目标设置为正确的显示
场景	音频监听器	如果场景中有多个音频侦听器处于活动状态，建议关闭其中一个音频侦听器	如果存在多个音频监听器，Unity 将不满意
场景	需要事件系统	添加事件系统和默认输入模块（如果不存在）	这是对要处理的任何触摸 UI 的帮助检查

5.7.2.9 应用程序背景

双渲染融合架构的一个缺点是应用程序不能纯粹在后台运行，而另一个应用程序在前台运行，这与头戴式架构不同。通过使用 Android 的画中画（打开新窗口）模式，可以使用标准 Android 架构选项以不同的方式克服此限制。

5.7.3 双渲染融合已知问题

5.7.3.1 应用程序后台问题

默认情况下，使用 Dual Render Fusion 构建的应用程序不会在后台运行。这是一种已知行为，因为 Dual Render Fusion 应用程序在移动设备的前台运行，并在另一个应用程序运行时被置于后台。这可以通过 Android 画中画（打开新窗口）模式来解决，但一个优雅的解决方案仍在研究和开发中。

5.7.3.2 手机屏幕黑屏

如果尝试运行 Fusion 应用程序时手机屏幕黑屏，请确保在 OpenXR 设置中选中双渲染融合功能，并且移动设备正在运行 Snapdragon Spaces Services 0.13.0 或更高版本。此外，验证该项目是否是使用 OpenXR 1.6.0 或更高版本构建的。

5.7.3.3 即使启用了双渲染融合功能，伴侣控制器也会启动

如果配套控制器仍自动启动，请确保在 OpenXR 设置中选中双渲染融合功能，并且基本运行时功能设置未选中在查看器上启动应用程序和在主机上启动控制器。

5.7.3.4 应用程序无法在未安装 Snapdragon Spaces 服务的手机上运行

如果应用程序在未安装 Snapdragon Spaces Services 的手机上运行时显示启动错误，这意味着在 Unity 项目中选中了 Require Spaces Services。取消选中此框可允许应用程序在未安装 Snapdragon Spaces 服务的设备上运行。

5.7.3.5 眼镜中的渲染以分屏模式出现

这可能是由于 Snapdragon Spaces 服务中未启用 Android 权限造成的。不幸的是，如果应用程序在此状态下运行，则需要卸载并重新安装 Snapdragon Spaces Services。执行此操作，然后打开Snapdragon Spaces Services应用程序并确保启用“在其他应用程序上显示”权限，重新启动手机并尝试再次运行该应用程序。

5.7.3.6 眼镜中的渲染出现在有限的水平视野中

这可能是由于使用 Dual Render Fusion 运行应用程序时未在 Snapdragon Spaces Services 中启用 Android 权限的结果。不幸的是，如果应用程序在此状态下运行，则需要卸载并重新安装 Snapdragon Spaces Services。执行此操作，然后打开Snapdragon Spaces Services应用程序并确保启用“在其他应用程序上显示”权限，重新启动手机并尝试再次运行该应用程序。

5.7.3.7 运行带有动态照明的应用程序会导致崩溃

在某些情况下，运行使用动态光照的应用程序可能会导致应用程序崩溃。在这些情况下，一些人发现放弃动态照明可以获得良好的结果。此外，某些后处理效果可能与手机屏幕兼容，但与眼镜不兼容。

5.7.3.8 眼镜中的渲染呈现出不同的性能

默认情况下，Unity 游戏内渲染相机会从游戏内相机姿势的角度渲染所有内容。由于双渲染融合会渲染到多个摄像头，因此如果场景过于复杂，即使手机屏幕被 2D 画布覆盖，也可能会产生较高的性能成本。仅渲染画布时，可以通过在渲染到手机的 相机 组件中将剔除蒙版 值设置为 Nothing 来优化性能。渲染世界空间对象时，删除剔除蒙版字段中除对象图层以外的所有图层。

5.8 Unity 迁移指南

5.8.1 0.15.0 中的重大变化

• 确保与 QCHT3 兼容的 QCHT 助手已被删除。请更新至QCHT4+。

5.8.2 0.14.0 中的重大变化

• 这些以前公开的类已被标记为内部类：
  • SpatialMeshingFeature
  • PlaneDetectionFeature
  • ImageTrackingFeature
• 用于切换检测到的平面的凸包计算的选项已从该功能的 OpenXR 设置页面移至名为 SpacesARPlaneManagerConfig 的组件，该组件可以添加到 ARPlaneManager 旁边。

5.9 Unity 的已知问题

目前有几个已知问题可能会影响开发工作流程。这些都是已知问题，将在 Unity 包或 Snapdragon Spaces Services 运行时的未来版本中得到解决。
如果不存在问题，请检查整体 SDK 已知问题

5.9.1 Gradle 构建问题

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

5.9.2 手部追踪问题

5.9.2.1 一般

• 头部运动可能会引起手部运动。

5.9.2.2 UX限制

• 释放对象只能通过张开手势来执行。
• 在某些情况下，双手之间的咬合可能会导致左右手翻转。
• 如果显示手部头像，则指尖可能会感觉到一些抖动。一般来说，不建议在 AR 环境中显示头像。

5.9.3 AR Foundation相关问题

5.9.3.1 AR Raycast Hit 成功时报告错误的可追踪 ID

如果在平面检测功能设置中启用了使用场景理解平面检测，则 ARRaycastHit.trackableId 字段将始终返回 0-0 的 trackableId 作为命中的可跟踪对象的会话唯一标识符。如果禁用使用场景理解平面检测，则 ARRaycastHit.trackableId 将返回光线投射已命中的平面的 trackableId。

5.9.3.2 AR 网格管理器属性

AR Mesh Manager 组件具有 Snapdragon Spaces Unity 包的子系统实现不支持的属性。当运行构建并启用**空间网格（实验）**功能时，尝试使用任何不受支持的属性将显示警告。建议使用感知示例描述中所述的 Spaces AR Mesh Manager 配置。

5.9.3.3 AR 相机管理器和 AR 相机背景问题

在场景中启用 AR 相机管理器和 AR 相机背景将创建与物理相机的连接，以检索有关其可用性的信息。在启用这些组件的场景之间来回移动可能会对连接产生负面影响并导致意外结果，例如应用程序冻结。