디바이스 지원과 session report

디바이스 hardware와 성능 차이로 인해 AR 기능은 많은 경우 모든 디바이스에서 실행될 수 없습니다. 따라서 AR 기능을 사용할 때 현재 디바이스의 지원 상황을 정확하게 판단하는 것은 매우 중요합니다. 이 문서에서는 Unity에서 디바이스 사용 가능성이 어떻게 표현되는지, 그리고 session report(ARSession.Report)를 통해 디바이스 지원과 session 사용 가능성 정보를 얻는 방법을 소개합니다.

시작하기 전에

• ARSession 소개를 통해 session의 기본 개념, 구성 및 workflow를 이해합니다

디바이스 지원, session 사용 가능성 및 assembly

각 AR 기능이 지원할 수 있는 디바이스는 다릅니다. 예를 들어 motion tracking은 hardware 구성 요소에 일정한 요구 사항이 있고 일반적으로 디바이스 calibration이 필요하지만, image tracking 기능은 camera가 사용 가능한 거의 모든 디바이스에서 실행될 수 있습니다. 따라서 AR app이 어떤 디바이스에서 실행될 수 있는지 판단하려면 보통 현재 어떤 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 과정 외에도 session 실행 중에도 손상 상황이 발생할 수 있습니다. 예를 들어 실행 중인 컴포넌트가 실수로 제거되는 경우입니다. 이때도 session report를 통해 구체적인 손상 원인을 조회할 수 있습니다.

report 업데이트

session report는 다음 시점에 변경됩니다:

• assembly 첫 번째 단계 완료
  이때 컴포넌트 사용 가능성 report를 포함한 완전한 session report가 생성됩니다. session report의 Availability 부분은 이때 확정되며 더 이상 변경되지 않습니다. AssembleUpdate event를 통해 컴포넌트 사용 가능성 report 업데이트를 얻을 수 있습니다.
  assembly 후 session을 바로 시작한 경우 StateChanged event를 통해서도 session report 업데이트를 얻을 수 있습니다. 주의해야 할 session 상태는 Ready 및 Broken입니다.

• assembly 두 번째 단계 완료 이때 새로운 컴포넌트 사용 가능성 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 첫 번째 단계가 완료될 때, PendingDeviceList가 비어 있지 않은 경우에만 assembly가 두 번째 단계로 들어갑니다. 이 조건을 사용하여 AssembleUpdate가 두 번째로 실행될지 판단할 수 있습니다.

다음 단계

• 사용 가능성과 디바이스 지원 판단을 시도합니다