デバイスサポートと session report

デバイスのハードウェアや性能の違いにより、AR 機能は多くの場合すべてのデバイスで動作できるわけではありません。そのため、AR 機能を使用するときは、現在のデバイスのサポート状況を正確に判断することが非常に重要です。この記事では Unity においてデバイスの利用可否がどのように表されるか、および session report（ARSession.Report）を通じてデバイスサポートと session 利用可否の情報を取得する方法を説明します。

開始する前に

• ARSession の概要を通じて session の基本概念、構成、workflow を理解します

デバイスサポート、session 利用可否と assembly

各 AR 機能がサポートできるデバイスは異なります。例えば motion tracking はハードウェア部品に一定の要件があり、通常はデバイスのキャリブレーションも必要ですが、image tracking 機能はカメラが利用可能なほぼすべてのデバイスで動作できます。そのため、AR アプリケーションがあるデバイスで動作できるかを判断するには、通常、現在どの AR 機能を使用しているかを知る必要があります。言い換えれば、ある session がそのデバイスで動作できるかを判断します。

Unity では、上記の判断処理は session assembly（Assemble()）段階で完了します。assembly プロセスは、session に含まれるコンポーネントと現在のデバイスのサポート状況に基づき、session 開始前の最終状態を決定します。

assembly が成功すると、session は Ready 状態に入り、開始して実行を続けられます。assembly が失敗すると、session は Broken 状態に入り、session report（ARSession.Report）から具体的な失敗理由を問い合わせることができます。

session report

ARSession.Report プロパティは session の runtime report を提供します。session report には次の field が含まれます:

プロパティ	説明
Availability	完全な利用可否 report
BrokenReason	session が壊れた理由。session 状態が Broken のとき有効
Exception	session が壊れた具体的な exception。session 状態が Broken のとき有効

session report では、Availability によって各コンポーネントの利用可否を問い合わせたり、session が壊れたときに BrokenReason によって詳細な理由を問い合わせたりできます。

session report の例

例えば Windows 上で、session に ImageTrackerFrameFilter、CameraDeviceFrameSource、およびいくつかの他の frame source コンポーネントが含まれている場合、assembly プロセスは各コンポーネントの利用可否を確認し、次の report を生成します:

図では ARCoreFrameSource コンポーネントの Availability は Unavailable ですが、ImageTrackerFrameFilter と CameraDeviceFrameSource の Availability はどちらも Available であるため、session 全体の assembly は成功し、session は Ready 状態に入っています。

CameraDeviceFrameSource を session から削除すると、assembly プロセスは次の report を生成します:

FrameSources リスト数は 9 から 8 に変わっています。また、ImageTrackerFrameFilter コンポーネントの Availability は依然として Available ですが、利用可能な frame source コンポーネントがないため、session 全体の assembly は失敗し、session は Broken 状態に入ります。このとき report 内の BrokenReason field の値は NoAvailabileFrameSource であり、利用可能な frame source がないことを示します。

assembly プロセス以外にも、runtime 中に session が壊れることがあります。例えば、実行中のコンポーネントが誤って削除された場合などです。この場合も session report から具体的な破損理由を問い合わせることができます。

report の更新

session report は次のタイミングで変化します:

• assembly 第 1 段階完了
  この時点でコンポーネント利用可否 report を含む完全な session report が生成されます。session report の Availability 部分はこの時点で確定し、その後変化しません。 AssembleUpdate event からコンポーネント利用可否 report の更新を取得できます。
  assembly 後に session を直接開始した場合、StateChanged event からも session report 更新を取得できます。注目すべき session 状態には Ready と Broken があります。

• assembly 第 2 段階完了 この時点で新しいコンポーネント利用可否 report が生成されます。session が再起動されない限り、session report は更新されません。 AssembleUpdate event からコンポーネント利用可否 report の更新を取得できます。

• session 開始時、または runtime 中に session が壊れたとき
  session report の BrokenReason と Exception が更新されます。 StateChanged event から session report 更新を取得できます。注目すべき session 状態には Broken があります。

report 内容: session が壊れる理由

BrokenReason は session が壊れた理由を表し、次の状況があります:

理由	説明
Uninitialized	assembly プロセスで EasyAR Sense が正常に初期化されなかった
LicenseInvalid	assembly プロセスで EasyAR Sense license 検証に失敗した、または現在の使用に適用できない
SessionObjectIncomplete	assembly プロセスで session object が不完全。例えば URP で RendererFeature が正しく設定されていない
NoAvailabileFrameSource	assembly プロセスで利用可能な frame source がない。例えばすべての frame source が利用不可、または frame source が追加されていない。デフォルト session 設定の場合に限り、この状況はデバイスが現在選択した AR 機能をサポートしているかを示す
FrameSourceIncomplete	assembly プロセスで frame source が不完全。通常は custom frame source が frame source interface を正しく実装していない場合に発生
FrameFilterNotAvailabile	assembly プロセスで利用不可の frame filter が存在。この状況は一部の assembly option 下でのみ存在する。
StartFailed	開始失敗。例えば開始中に exception が発生
RunningFailed	実行失敗。例えば実行中のコンポーネントが誤って削除された、または URP で RendererFeature が正しく設定されていない。

report 内容: 利用可否情報

Availability は session 内の各コンポーネントの利用可否情報を提供します。次の field が含まれます:

Field	説明
FrameFilters	assembly プロセスで確認された frame filter 利用可否リスト
FrameSources	assembly プロセスで確認された frame source 利用可否リスト
PendingDeviceList	未完了のデバイスリスト download task
DeviceList	デバイスリスト download 結果

PendingDeviceList と DeviceList field は、デバイスサポートリストの download 状態を表すために使用されます。assembly 第 1 段階完了時、PendingDeviceList が空でない場合に限り、assembly は第 2 段階に入ります。この条件を使って AssembleUpdate が 2 回目に実行されるかを判断できます。

次のステップ

• 利用可否とデバイスサポートを判断することを試す