Table of Contents

設備支持和 session 報告

由於設備硬件和性能差異，AR 功能很多時候並不能在所有設備上運行。所以在使用 AR 功能時準確判斷當前設備的支持情況是非常重要的。本文介紹了在 Unity 中，設備可用性是如何表達的，以及如何通過 session 報告（ARSession.Report）獲取設備支持和 session 可用性的信息。

開始之前

  • 通過 ARSession 簡介 瞭解 session 的基本概念、組成和工作流程

設備支持、session 可用性與組裝

每個 AR 功能可以支持的設備是不同的。比如運動跟蹤對硬件元器件有一定要求且通常需要對設備進行標定，而圖像跟蹤功能則可以在幾乎所有攝像頭可用的設備上運行。所以判斷一個 AR 應用是否可以在某個設備上運行，通常需要知道當前使用哪些 AR 功能，或者換個說法就是判斷某個 session 是否可以在設備上運行。

在 Unity 中，上述判斷過程是在 session 組裝（Assemble()）階段完成的。組裝過程會根據 session 中包含的組件和當前設備的支持情況，決定 session 啓動前的最終狀態。

如果組裝成功，session 會進入 Ready 狀態，並可以繼續啓動和運行；如果組裝失敗，session 會進入 Broken 狀態，並且可以通過 session 報告（ARSession.Report）查詢具體的失敗原因。

session 報告

ARSession.Report 屬性提供了 session 的運行報告，一份 session 報告包含以下字段：

屬性 描述
Availability 完整的可用性報告
BrokenReason session 損壞原因，當 session 狀態爲 Broken 時有效
Exception session 損壞具體異常，當 session 狀態爲 Broken 時有效

在 session 報告中，可以通過 Availability 查詢每個組件的可用性，或是通過 BrokenReason 在 session 損壞時查詢損壞的詳細原因。

一份 session 報告示例

比如，在 Windows 上，如果 session 中包含 ImageTrackerFrameFilter、CameraDeviceFrameSource 以及若干個其它 frame source 組件，那麼組裝過程會檢查每個組件的可用性，並生成如下報告：

alt text

可以看到圖中雖然 ARCoreFrameSource 組件的 Availability 是 Unavailable，但是由於 ImageTrackerFrameFilter 和 CameraDeviceFrameSource 的 Availability 都是是 Available，所以整個 session 的組裝是成功的，且 session 成功進入了 Ready 狀態。

如果我們把 CameraDeviceFrameSource 從 session 中移除，那麼組裝過程會生成如下報告：

alt text

可以看到 FrameSources 列表數目從 9 變成了 8，並且雖然 ImageTrackerFrameFilter 組件的 Availability 仍然是 Available，但是由於沒有可用的 frame source 組件，所以整個 session 的組裝失敗，session 進入了 Broken 狀態。此時報告中 BrokenReason 字段數值是 NoAvailabileFrameSource，表示沒有可用的 frame source。

除了組裝過程之外，session 運行過程中也可能出現損壞的情況，比如某個運行中的組件被意外移除等。此時同樣可以通過 session 報告查詢具體的損壞原因。

報告更新

session 報告會在以下時間點發生變化：

  • 組裝第一階段完成
    這時會生成一份完整的 session 報告，包含組件可用性報告。session 報告的 Availability 部分會在這時確定並不再變化。 可以通過 AssembleUpdate 事件獲取組件可用性報告更新。
    如果組裝之後直接啓動了 session，也可以通過 StateChanged 事件獲取 session 報告更新。需要關注的 session 的狀態包括： Ready 和 Broken。

  • 組裝第二階段完成 這時會生成一份新的組件可用性報告。除非 session 重啓，否則 session 報告不會更新。 可以通過 AssembleUpdate 事件獲取組件可用性報告更新。

  • session 啓動或運行過程中 session 損壞時
    session 報告的 BrokenReason 和 Exception 會更新。 可以通過 StateChanged 事件獲取 session 報告更新。需要關注的 session 的狀態包括：Broken。

報告內容：session 損壞的原因

BrokenReason 表示 session 損壞的原因，有以下這些情況：

原因 描述
Uninitialized 組裝過程，EasyAR Sense 未成功初始化
LicenseInvalid 組裝過程，EasyAR Sense license 驗證失敗或不適用於當前使用
SessionObjectIncomplete 組裝過程，session 物體不完整。比如在 URP 中未正確配置 RendererFeature
NoAvailabileFrameSource 組裝過程，無可用的 frame source。比如所有 frame source 都不可用或未添加任何 frame source。在且僅在默認 session 配置下，這種情況說明設備當前選擇的 AR 功能的支持
FrameSourceIncomplete 組裝過程，frame source 不完整。一般多出現在自定義 frame source 時未正確實現 frame source 接口
FrameFilterNotAvailabile 組裝過程，存在不可用的 frame filter。這種情況只存在於部分組裝選項下。
StartFailed 啓動失敗。比如啓動過程中出現異常
RunningFailed 運行失敗。比如運行中的組件被意外移除，或是 URP 中未正確配置 RendererFeature 等。

報告內容：可用性信息

Availability 提供了 session 中每個組件的可用性信息。它包含以下字段：

字段 描述
FrameFilters 組裝過程檢查過的 frame filter 可用性列表
FrameSources 組裝過程檢查過的 frame source 可用性列表
PendingDeviceList 未完成的設備列表下載任務
DeviceList 設備列表下載結果

其中 PendingDeviceList 和 DeviceList 字段用於表示設備支持列表的下載狀態。組裝第一階段完成時，當且僅當 PendingDeviceList 非空時，組裝會進入第二階段，可以使用這個條件來判斷 AssembleUpdate 是否會第二次執行。

後續步驟