迁移指南
双渲染融合迁移指南
从 Snapdragon Spaces 版本 0.23.0 开始，双渲染融合不再作为单独的 tarball 包提供。现在，样本和插件组件已包含在 Snapdragon SDK 包中。请参考设置指南，了解如何将样本引入新项目或使用旧版双渲染融合的项目中。
迁移步骤
1、如果项目使用的是 0.13.0 至 0.19.1 版本中的预制件，请确保这些预制件已解包，并且不是样本文件夹中预制件的变体。
2、如果项目中已经导入了样本，请删除双渲染融合样本文件夹。
3、将新的 Snapdragon Spaces SDK 版本导入到现有项目中。
4、按照设置指南中的“导入样本”部分，导入新的双渲染融合样本。
5、参考设置指南，添加场景中可能缺少的组件，并特别关注故障排除部分。
版本差异
| 0.13.0 至 0.19.1 版本 | 0.23.0 及以后版本 | |
| 屏幕方向 | Lifecycle.cs | FusionScreenSetup.cs |
| 场景逻辑功能（退出、切换或切换场景） | Lifecycle.cs | FusionSceneManager.cs |
| 自动启动 XR 和管理 XR 相机 | DynamicOpenXRLoader.cs | DynamicOpenXRLoader |
| OpenXR 生命周期事件 | DynamicOpenXRLoader.cs | FusionLifecycleEvents.cs |
| Spaces Glass 状态 | - | SpacesGlassStatus.cs |
| Fusion Editor Simulator 组件 | FusionLogic.cs | FusionSimulator.cs |
版本0.13.0到0.21.0
旧版本双渲染融合
免责声明
前提条件
安装 Unity 编辑器时，必须添加 Android Build Support 模块，以便能够导出 .apk 文件。该模块也可以在安装后通过 Unity Hub 添加。
开始新的 3D Unity 项目
创建一个新的 3D（或 3D URP）Unity 项目，或使用现有的 Unity 项目。
导入 Snapdragon Spaces 包
Snapdragon Spaces for Unity SDK 以 tarball 文件形式提供。
请按照 Unity 的说明，通过 Unity 包管理器将 tarball (.tgz) 文件导入到项目中。该文件位于 Unity 包文件夹中。
| 注意！ 导入包后，Unity 可能会弹出提示以启用新的输入系统。点击“是”以确保 OpenXR 和 XR Interaction Toolkit 包的完整功能。如果还需要使用旧的输入系统，可以在 Player > Other Settings > Configuration 中将 Active Input Handling 设置为“Both”。 |
导入双渲染融合包
在 Snapdragon Spaces SDK for Unity 版本 0.13.0 到 0.21.0 之间，双渲染融合公测版作为实验性包提供。启用此功能的文件以单独的 Unity 包 tarball 形式提供，您可以在 Snapdragon Spaces for Unity SDK 下载页面找到。
请按照 Unity 的说明，通过 Unity 包管理器将 tarball (.tgz) 文件导入项目。该文件可以在双渲染融合包下载页面找到。
建议同时通过包管理器导入 Fusion Samples 示例包。
更改项目设置
要启用 Snapdragon Spaces OpenXR 插件，请进入 Edit > Project Settings > XR Plug-in Management 下的项目设置，打开 Android 标签页。
勾选 OpenXR 插件，但暂时不要勾选 Snapdragon Spaces 功能组。
接着，点击 OpenXR 菜单项以显示不同的 OpenXR 功能选项。注意新的“双渲染融合功能”，勾选 Base Runtime Feature 和 Dual Render Fusion Feature。点击 Dual Render Fusion 旁边的红色感叹号，以打开项目验证器。
项目验证器将显示多个修复选项，用于更新 Unity 项目和当前打开的场景，因此请确保在项目中打开了正确的场景。
双渲染融合功能验证器
请注意验证器中前缀为 [Dual Render Fusion (Experimental)] 的选项。应该首先解决这些问题，以更新项目和当前场景，然后再选择“全部修复”来处理项目中的其他问题。（这是因为双渲染融合的验证器选项可以解决一些其他默认的 Spaces 验证器问题。）
完成双渲染融合验证后，点击剩余条目旁边的修复按钮，以应用所需的项目设置。一些修复可能需要重新启动编辑器，这是正常的。
此时，双渲染融合应该已经正确启用，可以进行启动。有关更多信息和高级配置功能，请参见下文。
配置双渲染融合设置
双渲染融合功能的可用设置包括
1、验证打开的场景：启用此设置时，Unity 场景验证器将检查当前打开的场景中是否正确配置了 XR 相机和智能手机相机。如果项目的构建系统没有完整的功能场景（如附加场景），请禁用此设置，以避免构建阻塞。
双渲染融合示例
通过包管理器可以获取一系列示例场景和代码脚本：
1、Controller Prefab Sample Scene：这是一个示例场景，用于将 Android Companion Controller 适配到 Unity Prefab 中，并完全控制设置和退出按钮。有关更多详细信息，请参见下文的 Companion Controller 部分。
2、CubeManipulation：一个简单的场景，包含一个立方体，可以通过一个、两个或三个手指在触控板上移动，用于创建响应式多点触控界面。
3、LandscapeUISampleScene：一个简单的场景，包含一个横向画布，其中包含可交互的 UI 元素，用于操作立方体。
4、OpenXRLoadingTest：一个演示如何在智能手机上立即启动应用程序，并在与眼镜建立连接后启用 OpenXR 的场景。有关更多详细信息，请参见下文的 Dynamic OpenXR Loader 部分。
5、PortraitUISampleScene：一个简单的场景，包含一个纵向画布，其中包含可交互的 UI 元素。
伴侣控制器
有些开发者可能希望将现有的 Snapdragon Spaces 项目迁移到双渲染融合，并利用伴侣控制器的陀螺仪 3DOF 指向功能。请按照以下步骤将其添加到项目中：
要在 Unity 中复制伴侣控制器，需要一些资产和脚本。
1、如果需要，请按照提示导入 TextMeshPro。
2、将 CanvasControllerCompanion Prefab 从示例中拖到层级视图中。
3、由于 Prefab 中不包含 XR 相机，需要将两个 GameObject 连接到 XR 相机。如果没有设置，这些对象会自动检测 XR Origin 或 AR Session Origin 以使用附加的相机。也可以手动设置：
在 ControllerPositionHeadMirror 中设置 Ar Camera 字段。
在 GyroRotationReceiver 中设置 Ar Camera 字段。
确保将输入系统设置为“Both”，以启用陀螺仪控制。
5、将 ControllerPrefabInputActions 作为附加的 Action Asset 添加到 Input Action Manager 中。如果层级视图中没有 Input Action Manager，请创建一个 GameObject 并添加该组件。
6、要使用菜单按钮功能，可以直接使用标准的 Unity 输入系统，并在层级视图中的菜单按钮对象上添加 On Click() 事件。
7、要在设置菜单中添加更多选项，请暂时启用“Settings Overlay” GameObject，并将菜单项添加到“Scroll Box”列表中。（目前，“About”按钮没有功能，仅作为示例存在。）
动态 OpenXR 加载器
动态 OpenXR 加载器是一个实验性示例脚本，允许应用程序在眼镜连接后加载 OpenXR，类似于耳机的工作方式。此脚本会检测第二个显示器的存在，并在配置时启动 OpenXR。提供了多个回调函数，用于控制 OpenXR 开始连接时用户界面的行为。有关如何使用此脚本的示例，请参见 OpenXRLoadingTest 示例。
| 注意事项！ 1、目前不建议在启用手部跟踪功能的应用程序中使用此功能，由于动态 OpenXR 加载器与手部跟踪功能存在并发兼容性问题，使用此功能在应用程序初始化过程之外启动 OpenXR 可能会导致应用程序在尝试加载时突然退出。此问题将在未来版本中修复。 2、当 OpenXR 开始连接时，主线程会短暂阻塞。建议显示一些用户界面元素，以提示 OpenXR 正在连接，并在加载完成后显示确认状态。 |
功能验证配置
双渲染融合功能验证器用于轻松配置 Unity 项目和所选场景，以启用双渲染融合。以下是验证列表。
| 范围 | 验证项 | 描述 | 原因 |
| 项目 | 禁用自定义启动器 | 禁用“Base Runtime Feature”中的“Launch on Viewer”和“Launch Controller on Host”复选框 | 双渲染融合需要禁用自定义启动器功能（参见头戴式架构） |
| 场景 | 需要 AR 会话原点 | 确保场景中有 AR 会话原点（或 XR 原点）以及相关的 XR 摄像头 | AR Foundation 需要一个 XR 摄像头 |
| 场景 | 需要 AR 会话 | 确保场景中有 AR 会话和 AR 输入管理器 | AR Foundation 需要一个 AR 会话 |
| 场景 | 需要移动摄像头 | 确保场景中有一个表示移动设备屏幕的 Unity 摄像头 | 双渲染融合需要一个移动显示器进行渲染 |
| 场景 | 主摄像头标签 | 确保只有 XR 摄像头或其他非纹理渲染的摄像头被标记为“主摄像头”，而不是两个都标记 | 如果有两个摄像头被标记为“主摄像头”，可能会导致渲染错误或干扰其他依赖项 |
| 场景 | 摄像头渲染优先级 | 确保移动摄像头的渲染在 XR 摄像头之后进行 | 如果 XR 摄像头在移动摄像头之前渲染，移动显示器可能会被 XR 摄像头的图像覆盖 |
| 场景 | 摄像头视角目标 | 确保 XR 摄像头的视角目标设置为“Both”，而其他所有摄像头设置为“None” | 摄像头视角目标决定了每个摄像头将渲染到哪个显示器上 |
| 场景 | 移动摄像头视角目标（URP） | 显示警告，提醒检查移动摄像头的视角目标是否设置为“None” | URP 不能像内置渲染管线那样程序化地设置视角目标，因此需要手动检查 |
| 场景 | 摄像头显示目标 | 如果 XR 摄像头的目标显示器不是显示器 1，则建议添加一个 Fusion Logic GameObject 和组件 | 为了使双渲染融合能够正确地渲染到两个设备，两个显示目标必须设置为显示器 1。XR 摄像头默认设置为目标显示器 2，而“Fusion Logic”会在运行时将目标设置为正确的显示器 |
| 场景 | 音频监听器 | 如果场景中有多个音频监听器，建议关闭其中一个 | 多个音频监听器同时存在会导致 Unity 出现问题 |
| 场景 | 事件系统要求 | 如果场景中没有事件系统，则需要添加一个事件系统和默认输入模块 | 这是为了确保触控 UI 能够正确处理 |
应用程序在后台运行
双渲染融合架构的一个缺点是，应用程序不能像头戴式架构那样在后台运行，同时其他应用程序在前台运行。可以通过使用 Android 的画中画模式来克服这一限制，这种方式利用了标准的 Android 架构选项。
北京神木科技有限公司
