Поддержка устройств и session report

Из-за различий в аппаратной части и производительности устройств AR-функции часто не могут работать на всех устройствах. Поэтому при использовании AR-функций очень важно точно определить поддержку текущего устройства. В этой статье описано, как в Unity выражается доступность устройства и как получить информацию о поддержке устройств и доступности session через session report (ARSession.Report).

Перед началом

• Изучите базовые понятия, состав и workflow session через введение в ARSession

Поддержка устройств, доступность 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 предоставляет runtime-отчёт session. Session report содержит следующие поля:

Свойство	Описание
Availability	Полный отчёт о доступности
BrokenReason	Причина повреждения session, действительно когда состояние session равно Broken
Exception	Конкретное исключение повреждения session, действительно когда состояние session равно Broken

В session report можно использовать Availability для запроса доступности каждого компонента или BrokenReason для запроса подробной причины повреждения, когда session повреждена.

Пример session report

Например, в Windows, если session содержит ImageTrackerFrameFilter, CameraDeviceFrameSource и несколько других компонентов frame source, процесс assembly проверит доступность каждого компонента и создаст следующий отчёт:

Видно, что хотя Availability компонента ARCoreFrameSource имеет значение Unavailable, поскольку Availability у ImageTrackerFrameFilter и CameraDeviceFrameSource оба равны Available, assembly всей session успешна, и session успешно переходит в состояние Ready.

Если удалить CameraDeviceFrameSource из session, процесс assembly создаст следующий отчёт:

Видно, что количество элементов в списке FrameSources изменилось с 9 на 8. Хотя Availability компонента ImageTrackerFrameFilter всё ещё равно Available, из-за отсутствия доступного компонента frame source assembly всей session завершается неудачно, и session переходит в состояние Broken. В этот момент значение поля BrokenReason в отчёте равно NoAvailabileFrameSource, что означает отсутствие доступного frame source.

Помимо процесса assembly, session может быть повреждена и во время выполнения, например если работающий компонент был случайно удалён. В этом случае конкретную причину повреждения также можно запросить через session report.

Обновление отчёта

Session report изменяется в следующие моменты:

• Завершение первого этапа assembly
  В этот момент создаётся полный session report, включая отчёт о доступности компонентов. Часть Availability session report определяется в этот момент и больше не изменяется. Обновление отчёта о доступности компонентов можно получить через событие AssembleUpdate.
  Если session запускается сразу после assembly, обновление session report также можно получить через событие StateChanged. Состояния session, на которые нужно обратить внимание: Ready и Broken.

• Завершение второго этапа assembly В этот момент создаётся новый отчёт о доступности компонентов. Если session не перезапущена, session report больше не обновляется. Обновление отчёта о доступности компонентов можно получить через событие AssembleUpdate.

• При запуске session или повреждении session во время выполнения
  BrokenReason и Exception в session report обновляются. Обновление session report можно получить через событие StateChanged. Состояния session, на которые нужно обратить внимание: Broken.

Содержание отчёта: причины повреждения session

BrokenReason означает причину повреждения session. Возможны следующие ситуации:

Причина	Описание
Uninitialized	Процесс assembly: EasyAR Sense не был успешно инициализирован
LicenseInvalid	Процесс assembly: проверка license EasyAR Sense завершилась неудачно или license неприменима к текущему использованию
SessionObjectIncomplete	Процесс assembly: object session неполный. Например, RendererFeature неправильно настроен в URP
NoAvailabileFrameSource	Процесс assembly: нет доступного frame source. Например, все frame source недоступны или ни один frame source не добавлен. Только при конфигурации session по умолчанию эта ситуация означает поддержку устройством выбранной текущей AR-функции
FrameSourceIncomplete	Процесс assembly: frame source неполный. Обычно возникает, когда custom frame source неправильно реализует interface frame source
FrameFilterNotAvailabile	Процесс assembly: существует недоступный frame filter. Эта ситуация существует только при некоторых assembly options.
StartFailed	Запуск не удался. Например, во время запуска возникло exception
RunningFailed	Runtime failed. Например, работающий компонент был случайно удалён или RendererFeature неправильно настроен в URP.

Содержание отчёта: информация о доступности

Availability предоставляет информацию о доступности каждого компонента в session. Он содержит следующие поля:

Поле	Описание
FrameFilters	Список доступности frame filter, проверенных во время assembly
FrameSources	Список доступности frame source, проверенных во время assembly
PendingDeviceList	Незавершённая задача загрузки списка устройств
DeviceList	Результат загрузки списка устройств

Поля PendingDeviceList и DeviceList используются для отображения состояния загрузки списка поддержки устройств. Когда первый этап assembly завершён, тогда и только тогда, когда PendingDeviceList не пуст, assembly переходит на второй этап. Это условие можно использовать, чтобы определить, будет ли AssembleUpdate выполнено во второй раз.

Следующие шаги

• Попробуйте определять доступность и поддержку устройств