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 是否會第二次執行。

後續步驟