장치 지원 및 세션 보고서

장치 하드웨어 및 성능 차이로 인해 AR 기능은 종종 모든 장치에서 작동하지 않을 수 있습니다. 따라서 AR 기능을 사용할 때 현재 장치의 지원 여부를 정확히 판단하는 것이 매우 중요합니다. 이 문서에서는 Unity에서 장치 가용성이 어떻게 표현되는지, 그리고 세션 보고서(ARSession.Report)를 통해 장치 지원 및 세션 가용성 정보를 얻는 방법을 설명합니다.

시작하기 전에

• ARSession 소개를 통해 세션의 기본 개념, 구성 및 워크플로를 이해하세요

장치 지원, 세션 가용성 및 어셈블리

각 AR 기능이 지원할 수 있는 장치는 다릅니다. 예를 들어 모션 추적은 하드웨어 구성 요소에 대한 특정 요구 사항이 있으며 일반적으로 장치 보정이 필요하지만, 이미지 추적 기능은 거의 모든 카메라를 사용할 수 있는 장치에서 작동할 수 있습니다. 따라서 AR 애플리케이션이 특정 장치에서 실행될 수 있는지 여부를 판단하려면 일반적으로 현재 어떤 AR 기능을 사용하는지 알아야 하며, 이는 세션이 장치에서 실행될 수 있는지 여부를 판단하는 것과 같습니다.

Unity에서 위의 판단 과정은 세션 어셈블리(Assemble()) 단계에서 완료됩니다. 어셈블리 과정은 세션에 포함된 구성 요소와 현재 장치의 지원 여부에 따라 세션 시작 전 최종 상태를 결정합니다.

어셈블리가 성공하면 세션은 Ready 상태가 되며 계속 시작 및 실행될 수 있습니다. 어셈블리가 실패하면 세션은 Broken 상태가 되고, 세션 보고서(ARSession.Report)를 통해 구체적인 실패 원인을 조회할 수 있습니다.

세션 보고서

ARSession.Report 속성은 세션의 실행 보고서를 제공하며, 세션 보고서에는 다음 필드가 포함됩니다:

속성	설명
Availability	전체 가용성 보고서
BrokenReason	세션 손상 원인, 세션 상태가 Broken일 때 유효
Exception	세션 손상 구체적 예외, 세션 상태가 Broken일 때 유효

세션 보고서에서는 Availability를 통해 각 구성 요소의 가용성을 조회하거나, BrokenReason을 통해 세션이 손상되었을 때 손상된 상세 이유를 조회할 수 있습니다.

세션 보고서 예시

예를 들어, Windows에서 세션에 ImageTrackerFrameFilter, CameraDeviceFrameSource 및 여러 기타 frame source 구성 요소가 포함된 경우, 어셈블리 과정은 각 구성 요소의 가용성을 확인하고 다음과 같은 보고서를 생성합니다:

이미지에서 ARCoreFrameSource 구성 요소의 Availability는 Unavailable이지만, ImageTrackerFrameFilter와 CameraDeviceFrameSource의 Availability가 모두 Available이므로 전체 세션 어셈블리는 성공하며 세션은 성공적으로 Ready 상태에 진입합니다.

CameraDeviceFrameSource를 세션에서 제거하면 어셈블리 과정에서 다음과 같은 보고서가 생성됩니다:

FrameSources 목록 개수가 9에서 8로 변경되었으며, ImageTrackerFrameFilter 구성 요소의 Availability는 여전히 Available이지만 사용 가능한 frame source 구성 요소가 없으므로 전체 세션 어셈블리는 실패하고 세션은 Broken 상태에 진입합니다. 이때 보고서의 BrokenReason 필드 값은 NoAvailabileFrameSource이며, 이는 사용 가능한 frame source가 없음을 의미합니다.

어셈블리 과정 외에도 세션 실행 중에도 구성 요소가 예기치 않게 제거되는 등 손상이 발생할 수 있습니다. 이때에도 세션 보고서를 통해 구체적인 손상 원인을 조회할 수 있습니다.

보고서 업데이트

세션 보고서는 다음과 같은 시점에 변경됩니다:

• 어셈블리 1단계 완료
  이때 구성 요소 가용성 보고서를 포함한 완전한 세션 보고서가 생성됩니다. 세션 보고서의 Availability 부분은 이때 결정되어 더 이상 변하지 않습니다.
  AssembleUpdate 이벤트를 통해 구성 요소 가용성 보고서 업데이트를 받을 수 있습니다.
  어셈블리 후 바로 세션을 시작한 경우 StateChanged 이벤트를 통해 세션 보고서 업데이트를 받을 수 있습니다. 주목해야 할 세션 상태는 다음과 같습니다: Ready 및 Broken.

• 어셈블리 2단계 완료
  이때 새로운 구성 요소 가용성 보고서가 생성됩니다. 세션을 재시작하지 않는 한 세션 보고서는 업데이트되지 않습니다.
  AssembleUpdate 이벤트를 통해 구성 요소 가용성 보고서 업데이트를 받을 수 있습니다.

• 세션 시작 또는 실행 중 세션 손상 시
  세션 보고서의 BrokenReason 및 Exception이 업데이트됩니다.
  StateChanged 이벤트를 통해 세션 보고서 업데이트를 받을 수 있습니다. 주목해야 할 세션 상태는 다음과 같습니다: Broken.

보고서 내용: 세션 손상 원인

BrokenReason은 세션 손상 원인을 나타내며, 다음과 같은 경우가 있습니다:

원인	설명
Uninitialized	어셈블리 과정, EasyAR Sense 초기화 실패
LicenseInvalid	어셈블리 과정, EasyAR Sense 라이선스 검증 실패 또는 현재 사용에 부적합
SessionObjectIncomplete	어셈블리 과정, 세션 객체 불완전 (예: URP에서 RendererFeature 올바르게 구성되지 않음)
NoAvailabileFrameSource	어셈블리 과정, 사용 가능한 frame source 없음 (모든 frame source 사용 불가 또는 추가되지 않음). 기본 세션 구성에서만 해당하며, 이는 장치가 현재 선택한 AR 기능을 지원하지 않음을 나타냅니다
FrameSourceIncomplete	어셈블리 과정, frame source 불완전 (사용자 정의 frame source 시 frame source 인터페이스 올바르게 구현되지 않음)
FrameFilterNotAvailabile	어셈블리 과정, 사용 불가능한 frame filter 존재 (일부 어셈블리 옵션에서만 발생)
StartFailed	시작 실패 (시작 과정 중 예외 발생)
RunningFailed	실행 실패 (실행 중 구성 요소 예기치 않게 제거되거나 URP에서 RendererFeature 올바르게 구성되지 않음 등)

보고서 내용: 가용성 정보

Availability는 세션의 각 구성 요소 가용성 정보를 제공합니다. 다음 필드를 포함합니다:

필드	설명
FrameFilters	어셈블리 과정에서 검사된 frame filter 가용성 목록
FrameSources	어셈블리 과정에서 검사된 frame source 가용성 목록
PendingDeviceList	미완료 장치 목록 다운로드 작업
DeviceList	장치 목록 다운로드 결과

이 중 PendingDeviceList 및 DeviceList 필드는 장치 지원 목록 다운로드 상태를 나타냅니다. 어셈블리 1단계 완료 시, PendingDeviceList이 비어 있지 않은 경우에만 어셈블리가 2단계로 진행되며, 이 조건을 통해 AssembleUpdate가 두 번째로 실행될지 여부를 판단할 수 있습니다.

다음 단계

• 가용성 및 장치 지원 판단 시도하기