使用 Instant Preview

使用 Instant Preview 跳过构建流程,在您的手机上即时测试 ARCore 应用。 点击 Unity 中的 Play,利用来自手机的真实输入和输出预览您的应用。

概览

Instant Preview 由适用于您的支持 ARCore 的手机的 Android 应用和 Unity 插件组成。

要求

Windows(仅限独立 GPU)macOS 开发计算机支持 Instant Preview。

在集成 GPU 的 Windows 计算机上,Unity 编辑器的视频 feed 不会镜像回您的手机。

要使用 Instant Preview,您需要具备以下条件:

硬件

软件

请参阅 ARCore SDK for Unity 快速入门指南,了解有关软件版本要求和安装的完整详情。

在 Unity 中使用 Instant Preview

本指南假定您已在 Unity 中创建 ARCore 项目。 如果您是第一次使用 ARCore,请参阅 ARCore SDK for Unity 快速入门指南,了解安装和设置步骤。

设置 Instant Preview

  1. 在 Unity 编辑器中打开您的 ARCore 场景。

  2. 通过 USB 将您的手机连接到开发计算机。 确保您的手机上启用了开发者选项和调试

  3. 在 Unity 编辑器中点击 Play。 Instant Preview 应用启动,并且您的 ARCore 场景开始在线播放。

    • 如果您在计算机或手机上看到询问您是否想安装 Instant Preview Android 应用的对话框,请点击或点按 Okay 进行确认。

    • 如果您的手机上安装的 ARCore 版本不够新,可能会将您转到应用商店安装 ARCore,然后再继续。

  4. 将您的手机四处移动以检测平面、放置物体或使用其他您要在自己的应用中测试的 ARCore 功能。

    请参阅处理来自手机的输入,了解有关在 Instant Preview 中预览触摸输入的详情。

  5. 在 Unity 编辑器中点击 Pause,或点按您手机上的系统返回按钮,以停止在线播放并退出预览。

  6. (可选步骤)您可以在应用暂停时将您的在线播放配置更改为 Wi-Fi

处理来自手机的输入

在 Instant Preview 中,在应用 AR 场景上的触摸输入不会自动将输入事件传播至您的 Unity 实现。

要设置触摸输入传播,请在任何引用 Unity Input 类的控制器脚本中使用 InstantPreviewInput 类。 在控制器脚本顶部添加以下代码:

#if UNITY_EDITOR
     // NOTE:
     // - InstantPreviewInput does not support `deltaPosition`.
     // - InstantPreviewInput does not support input from
     //   multiple simultaneous screen touches.
     // - InstantPreviewInput might miss frames. A steady stream
     //   of touch events across frames while holding your finger
     //   on the screen is not guaranteed.
     // - InstantPreviewInput does not generate Unity UI event system
     //   events from device touches. Use mouse/keyboard in the editor
     //   instead.
     using Input = InstantPreviewInput;
#endif

例如,演示场景的 HelloAR Controller 脚本使用 InstantPreviewInput 来检测和传播触摸输入事件。

InstantPreviewInput 类与 Unity 的 Input 类似。

通过 Wi-Fi 连接在线播放

Instant Preview 在通过 USB 或 Wi-Fi 在线播放时的工作方式相同。

默认情况下,Instant Preview 使用 USB。 通过 USB 在线播放最适合开发会话持续时间较长的情况。

请在测试会话较短或 USB 电缆会限制必要的手机移动时使用 Wi-Fi。

要通过 Wi-Fi 在线播放:

  1. 确保您的手机和开发计算机连接到同一 Wi-Fi 网络。

  2. 确保您的网络针对 Instant Preview 进行了配置:

    • 您开发系统上的任何防火墙软件都必须配置为允许 Unity 接受 49838 端口上的 TCP 连接。
    • 您的路由器和/或网络防火墙必须停用客户端隔离,以便您的手机和开发计算机可通过您的网络相互直接通信。
    • 您的路由器和/或网络防火墙必须允许端口 49838 上从您的开发计算机到多播地址 239.170.165.207 的广播流量。
  3. 确保 Instant Preview 已启用。 在 Unity 中,验证在 Edit > Project Settings > ARCore 中勾选了 Instant Preview Enabled

  4. 在 Unity 编辑器中点击 Play。 这会使您手机上的 Instant Preview 应用可检测到您的开发计算机。

  5. 在您的手机上,打开 ARCore Instant Preview 应用。 如果目前未安装 Instant Preview,请按照设置 Instant Preview 步骤安装该应用。

  6. 在您的手机上,点按应用中的“Preview via…”下拉列表。

    • 您的开发计算机应列为您的手机所用 Wi-Fi 网络名称下的可用设备之一。 如果您的手机未列出,请参阅问题排查
    • 选择您的开发计算机以开始在线播放。
    • 使用 Unity 编辑器中的 PlayStop 来开始和停止在线播放。

停用 Instant Preview

Instant Preview 默认情况下处于启用状态。 要在 Unity 编辑器中停用 Instant Preview,请转到
Edit > Project Settings > ARCore 并取消选中 Instant Preview Enabled

性能提示

长宽比
Instant Preview 会镜像您手机上的游戏窗口。 将您的窗口长宽比设置为与您用于测试的手机一致。 如果长宽比不一致,您的应用出现在游戏窗口或手机上时可能呈拉伸状。

在 macOS 中使用 Metal
如果您在 macOS 中工作,请使用 Metal 替代 OpenGL 进行渲染。 转到 Player Settings > Settings for PC, Mac & Linux Standalone > Other Settings > Metal Editor Support 以启用 Metal 渲染。

问题排查

  • 检查 Unity Console 中有无 Instant Preview 错误。

此外,还要确保:

  • 其他使用 Instant Preview 的 Unity 实例未处于运行状态。 同一时间只能有一个实例处于运行状态。

  • 您的项目中启用了 Instant Preview。 确保在 Edit > Project Settings > ARCore 中勾选了 Instant Preview Enabled

  • 您的手机已通过 USB 或 Wi-Fi 连接到计算机。

  • 您的手机处于解锁状态,并启用了开发者选项和调试

  • 在 Unity 的 Build Settings 中,您的构建平台设置为 Android,并且您为 ARCore 启用了播放器设置。 否则,请参阅 Unity 快速入门指南中的配置详情。

  • 当您在 Unity 中点击 Play 时,Console 会显示 Instant Preview version <version_number>

如果您通过 Wi-Fi 在线播放:

  • 检查您的网络和防火墙设置。

  • Windows 开发计算机上:

    1. 打开 Windows Firewall with Advanced Security 管理面板,并删除 IncomingOutgoing 规则中任何提及 Unity 的内容。

    2. 重新启动 Unity 并在 Windows 提示时允许连接。

  • 如果您没有合适的 Wi-Fi 网络,或许可以使用您的手机作为热点:

    1. 在您的手机上,停用移动数据以防止您的开发计算机通过热点使用移动数据。

    2. 在您的手机上配置并启用安全 Wi-Fi 热点。

    3. 在您的开发计算机上,连接到您手机上的 Wi-Fi 热点。

      即使无法连接互联网,您的开发计算机和手机也应能建立 Instant Preview 连接。

局限性

Instant Preview 具有下列局限性。

不支持 Activity 暂停/继续事件
使用 Instant Preview 时不支持暂停和继续 ARCore 会话的应用 Activity 暂停事件

不支持 ARCore 会话配置变更
使用 Instant Preview 时不支持停用光估测和平面查找等会话配置变更。

有限的触摸输入支持
InstantPreviewInput 不支持:

  • Unity 界面事件系统事件:在 Unity 编辑器中直接使用鼠标或键盘与这些元素进行互动。

屏幕方向设置
Instant Preview 根据预览窗口的长宽比确定使用的屏幕方向。 如果长宽比发生变化,Instant Preview 将重启以正确匹配屏幕方向。