NVIDIA CloudXR Client Unity 插件入门

本指南将逐步介绍在 Unity 中安装、实施和开始使用插件所需的步骤。本指南非常简单明了，但对偏离所述步骤的情况非常敏感。

提供的说明是为 Meta Quest 头戴式设备编写的（已使用 Meta Quest 2 测试）。其他头戴式设备可能可以使用，但可能需要进行超出本指南范围的调整，并且您的结果可能会有所不同。

要求

  • NVIDIA CloudXR Client Unity 插件软件包。

  • 与 CloudXR 4.0 集成的 XR 应用程序或与 CloudXR 4.0 Server SDK 集成的系统运行时，用于测试。

    本指南使用 SDK 中提供的 SteamVR 的 CloudXR Server 插件安装程序。

  • 支持 OpenXR 的头戴式设备

    本指南是使用 Meta Quest 2 或 Meta Quest Pro 头戴式设备编写的。

  • Unity 版本 2022.1.13f1、2022.2.12fa（插件已针对这些版本进行了广泛测试，更高或更早的版本可能有效，也可能无效）

可选支持软件

以下可选软件可能有助于在安装和播放期间管理您的 Android 设备

  • SideQuest，用于镜像和设备管理

  • Meta Quest Developer Hub，用于管理基于 Meta 的设备。

Unity Hub 配置

Unity 游戏引擎的安装通过 Unity Hub 进行管理。确保您已安装最新版本的 Unity Hub，并且已正确获得许可并正在运行。

  1. 打开 Unity Hub。选择 安装。

  2. 选择您的 Unity 版本。

    请注意，最近的 LTS 版本 (2022.3) 和其他最近的 Unity 版本可能不受支持；您可能需要从存档中选择您的 Unity 版本。

    注意：本指南是使用 Unity 版本 2022.2.12fa 编写的，插件主要使用 Unity 版本 2022.1.13f1 开发

  3. 选择以下各项

    • Android Build Support （包括任何嵌套选项）

    • Windows Build Support (IL2CPP)

  4. 选择 继续 并让其安装

创建新的 Unity 项目

1. 在 Unity Hub 中选择 项目。 1. 提供名称。 1. 选择 3D URP。

如果尚未安装，您可能需要选择 下载模板 图标

Creating a Unity image

创建 Unity 图像

为 Android 配置项目

本节配置新的 Unity 项目，以 Android 作为构建平台。

  1. 如果尚未打开，请打开新创建的空白 3D (URP) Unity 项目。

  2. 选择 文件 > 构建设置

  3. 选择 Android，然后选择 切换平台 按钮。 Setting Android Build

设置软件包和项目设置

下一步是在 Unity 中设置 XR 项目。在 XR 插件管理 中选择选项时，它们会被安装。取消选择这些选项不会卸载软件包。以下步骤利用了这种细微差别。

  1. 选择 窗口 > 软件包管理器

  2. 选择 编辑 > 项目设置

  3. 在 项目设置 中，选择 XR 插件管理 和 安装 XR 插件管理。

  4. 插件完成安装后，再次选择 XR 插件管理，此时应显示要支持的平台以及其他设置。

  5. 选择带有类似显示器图标的选项卡，然后选中 OpenXR。这将自动开始安装 OpenXR 插件 > 注意：如果系统提示您使用新的输入系统，请选择：“是” OpenXR Input Warning

  6. 在安装过程中，Unity 应重置并返回，同时打开软件包管理器和项目设置窗口。软件包管理器现在列出了 OpenXR 插件。

  7. 在项目设置配置窗口中，在 XR 插件管理下，选择 Android 图标选项卡

  8. 选中 OpenXR。这将显示红色警告，这没关系，但需要额外的配置。 Android OpenXR set

  9. 完成后，您应该只在 桌面 选项卡上的 OpenXR 和 Android 选项卡上的 OpenXR 中选中复选框。

  10. 在 软件包管理器 窗口中，通过选择软件包下拉列表将视图切换到 Unity 注册表。 Unity Registry Selector

  11. 选择 XR Interaction Toolkit 进行安装

    注意：此安装可能会提示一条关于 XR InteractionLayerMask 需要更新的消息。如果是这样，请选择“我已备份，继续”

    XRInteractionLayerMaskWarning

    XRInteractionLayerMaskWarning

    注意：如果您收到 IOException 错误，指示重新分析点缓冲区无效，则可能是您使用的目录包含不兼容的字符。将您的项目保存在不同的目录中，然后重试。

  12. 再次打开 项目设置 窗口，然后选择 Player

    1. 确认您在 Android 选项卡 上，然后展开 其他设置 部分

      1. 验证 自动图形 API 未选中

      2. 在图形 API 部分中删除 Vulkan，仅保留 OpenGLES3

      3. 取消选择 多线程渲染 ProjectSettingsOptions

      4. 向下滚动到 标识 部分，并将 最低 API 级别 设置为 Android 10 API 级别 29

      5. 在 配置 部分中，将 脚本后端 更改为 IL2CPP

      6. 对于 Meta Quest 平台（以及大多数当前的基于 Android 的平台），在 目标架构 中，确保仅选中 ARM64。删除其他复选标记。 ProjectSettingsBottom

  13. 在 项目设置 窗口中，选择 质量

    1. 删除 高保真度 和 平衡 级别。

    2. 确保仅保留 性能 级别。 renderquality

  14. 在同一 项目设置 页面中，选择 XR 插件管理。

    1. 在 Android 选项卡中，验证 OpenXR 是否已选中。指示的错误将在后续步骤中修复。

    2. 展开 左侧的 XR 插件管理 面板，然后选择 OpenXR。

      1. 在 OpenXR 功能组 下，选择 Meta Quest 支持。Unity 将显示一个错误图标，该图标将在下一步中修复。 xrpluginmetaquest

    3. 选择错误图标或导航到 XR 插件管理 中的 项目验证。

      1. 找到指示 OpenXR.Input.PoseControl 系统已弃用 的错误，然后选择 修复。这将需要一些时间才能完成。 projectvalidationfix

    4. 在 XR 插件管理 中，再次选择 OpenXR 以返回。

      1. 在 交互配置文件 中，添加 Oculus Touch Controller Profile。 openxroculuscontrollerprofile

      2. 完成后，任何指示的错误都应消失。

尝试项目的首次构建

此时，您可以随意设计连接前客户端大厅环境。但是，为了验证上述配置步骤是否正确完成，建议先尝试通用构建。

  1. 通过 USB-C 连接将您的 Quest 头戴式设备连接到您的 Unity 开发 PC。在头戴式设备中，系统可能会提示您允许与 Unity 通信所需的必要权限。

  2. 在 Unity 编辑器中，如果尚未停靠或打开，请在 文件 菜单中打开 构建设置

  3. 假设之前的步骤已完成，则应已为目标构建设置 Android 平台。单击 构建 以开始编译（或 Build And Run 以在您连接的 HMD 上查看结果）。

恭喜！ 您现在应该已成功为 Quest 头戴式设备在 Unity 中构建了一个 OpenXR 项目。下一步涉及实施 CloudXR 插件并将 XR 交互性添加到项目中。

将 CloudXR 插件导入 Unity

Unity 的 CloudXR 插件以 tarball 形式提供，其中包含插件代码和示例脚本。以下步骤说明如何将其安装到您的项目中。

  1. 再次打开 软件包管理器（窗口 > 软件包管理器）

  2. 选择加号图标和 从 tarball 添加软件包

  3. 选择已下载的 CloudXR 插件软件包中的 .tar 文件。完成后，将添加一个名为 NVIDIA CloudXR Client for Unity 的新软件包。 addpluginpackage

  4. 选择插件中的 示例 选项卡，然后选择 导入 以将示例内容包含在项目中。 xrsamples

配置 XR 摄像机/控制器并附加 CloudXR 插件

以下步骤假设已实施 XR Interaction Toolkit。如果使用其他软件包（XR 插件管理 或 AR Foundation），您的摄像机具体信息可能会有所不同。

  1. 在您的 Unity 层次结构中，创建一个新的 XR Origin。

    • 右键单击 层次结构内

    • 选择 XR > XR Origin

  2. 删除 层次结构中列出的根/原始 Main Camera。新创建的 XR Origin 将是指定的摄像机。完全通用的层次结构应类似于图像。 xrhierarchy

  3. 选择 XR Origin 对象。在检查器中，将 跟踪原点模式 更改为 设备。这可确保在流式传输时摄像机方向和控制器正确显示。 xrtrackingmode

  4. 选择 XR Origin > Camera Offset 中的新 Main Camera 对象

  5. 在检查器面板中向对象添加新的 组件。选择 添加组件 > NVIDIA > CloudXR Manager XRAddComponent

  6. 再次打开 项目设置（编辑 > 项目设置）。选择 XR 插件管理 > OpenXR。选择 Android 图标 选项卡。

  7. 选中 功能组 中的 CloudXR Pose Capture 选项。

恭喜！ 您现在拥有一个应用了 CloudXR 插件的 XR Unity 项目。

添加有助于 CloudXR 服务器连接的示例脚本

这些步骤使用提供的 Unity 示例脚本和着色器进行项目。这些脚本仅出于教育目的而提供，并非旨在用于生产工作负载。强烈建议查看源代码并根据您所需的客户端连接体验对其进行自定义。

  1. 在项目层次结构中，选择 XR Origin > Camera Offset 中的 Main Camera

  2. 在您的 项目 浏览器窗口中，展开 Assets > Samples > NVIDIA CloudXR Client > 0.0.0 > CloudXR for Unity

  3. 拖动 AutoConnectCloudXR 脚本到 Main Camera 对象的检查器面板以应用。 upiaddsample

  4. 将 IP 地址 更改 为您的网络可访问的 CloudXR 测试服务器

向项目渲染器添加着色器

此时，CloudXR 客户端可以连接到服务器，但无法显示返回的帧。这添加了一个着色器，以便可以将服务器返回的帧显示在客户端上。

  1. 在 项目 浏览器窗口中，选择 Settings > URP-Performant-Renderer

  2. 在项目检查器中，选择 添加渲染器功能 > CxrRenderer Feature urprenderer

  3. 通过以下任一方式查找 CxrReprojection 着色器示例

    1. 在 项目 浏览器窗口中导航到 Assets > Samples > NVIDIA CloudXR Client > 0.0.0 > CloudXR for Unity 并将其拖动过来。

    或者，更确切地说

    1. 选择着色器行上的圆形图标，然后搜索 CxrReprojection

cxrreprojection

cxrreprojection

最终构建您的项目并进行测试

  1. 再次打开您的 构建设置（文件 > 构建设置）以验证 Android 仍然是目标平台

  2. 选择 Build and Run 按钮。提供新的构建名称或覆盖现有的 .apk 文件。

构建完成后，示例脚本将尝试连接到指定的 IP 地址。如果该 IP 在网络上可访问并且在服务器或应用程序上运行正确版本的 CloudXR，则头戴式设备将连接并开始流式传输。