Android Dev Summit이 Android XR 전용 트랙과 함께 돌아왔습니다. 직접 사용해 보고 의견을 보내주세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Android XR용 OpenXR 시작하기

적용 가능한 XR 기기

이 가이드는 이러한 유형의 XR 기기를 위한 환경을 빌드하는 데 도움이 됩니다.

XR 기기 유형 알아보기 →

XR 헤드셋

유선 XR 글라스

XR 기기 유형 알아보기 →

지원되는 OpenXR 확장 프로그램 또는 지원되는 엔진으로 빌드를 시작하기 전에 다음 섹션의 매니페스트 구성 및 권한 요구사항을 검토하여 앱이 XR 개발용으로 구성되어 있는지 확인하세요.

앱의 매니페스트 파일 구성

다른 Android 앱 프로젝트와 마찬가지로 Android XR 앱에는 특정 매니페스트 설정이 있는 AndroidManifest.xml 파일이 있어야 합니다. 매니페스트 파일은 Android 빌드 도구, Android 운영체제, Google Play에 앱에 관한 필수 정보를 설명합니다. 자세한 내용은 앱 매니페스트 개요 가이드를 참고하세요.

XR 차별화 앱의 경우 매니페스트 파일에 다음 요소와 속성이 포함되어야 합니다.

PROPERTY_XR_ACTIVITY_START_MODE 속성

android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" 속성은 활동이 시작될 때 특정 모드에서 활동이 실행되어야 함을 시스템에 알립니다.

이 속성에는 다음 값이 있습니다.

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED (OpenXR만 해당)

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

OpenXR로 빌드된 앱은 전체 공간에서 실행되며 XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED 시작 모드를 사용해야 합니다. 관리되지 않는 전체 공간은 앱이 OpenXR을 사용한다는 것을 Android XR에 알립니다.


<manifest ... >

   <application ... >
       <property
           android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
           android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED" />
       <activity
           android:name="com.example.myapp.MainActivity" ... >

           <intent-filter>
               <action android:name="android.intent.action.MAIN" />

               <category android:name="android.intent.category.LAUNCHER" />
               <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />
           </intent-filter>
       </activity>
   </application>
</manifest>

PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED 속성

android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED" 속성은 애플리케이션이 특정 유형의 경계로 실행되어야 함을 나타냅니다. 사용자가 실제 공간을 이동할 수 있도록 설계된 경우 앱에서 XR_BOUNDARY_TYPE_LARGE를 지정해야 합니다. XR_BOUNDARY_TYPE_NO_RECOMMENDATION를 지정하면 안전 경계 유형에 대한 권장사항이 제공되지 않으므로 시스템은 이미 사용 중인 유형을 사용합니다.

<manifest ... >

   <application ... >
       <property
           android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED"
           android:value="XR_BOUNDARY_TYPE_LARGE" />
   </application>
</manifest>

공간 컨테이너 속성

앱이 XR_EXT_spatial_container 확장 프로그램 (Spatial API 수준 4에 도입됨)을 사용하여 완전 몰입형 뷰 외에도 제한된 3D 볼륨 또는 2D 패널에 콘텐츠를 표시하는 경우 <activity> 또는 <application> 수준에서 다음 매니페스트 속성을 선언하여 런타임에 실행 힌트를 제공할 수 있습니다.

org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES: 활동에서 사용하는 경계 모드를 지정합니다(|로 구분).

유효한 값은 다음과 같습니다.
- "2d_panel"
- "bounded"
- "immersive"
org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE: 시작 시 활동의 초기 경계 모드를 지정합니다.

유효한 값은 다음과 같습니다.
- XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED
- XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE
- XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED

<manifest ... >

   <application ... >
       <activity
           android:name="com.example.myapp.MainActivity" ... >
           <property
               android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
               android:value="bounded|immersive" />
           <property
               android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
               android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED" />
       </activity>
   </application>
</manifest>

<uses-native-library> OpenXR

OpenXR 애플리케이션은 런타임을 성공적으로 로드하기 위해 네이티브 OpenXR 라이브러리 사용을 선언해야 합니다. 이 선언이 없으면 런타임이 로드되지 않습니다.

<manifest ... >

    <application ... >

    <uses-native-library android:name="libopenxr.google.so" android:required="false" />

       <activity
           android:name="com.example.myapp.MainActivity" ... >

           <intent-filter>
               <action android:name="android.intent.action.MAIN" />

               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>
        </activity>
    </application>
</manifest>

XR 앱용 PackageManager 기능

Google Play 스토어를 통해 앱을 배포할 때 앱 매니페스트에 필요한 하드웨어 또는 소프트웨어 기능을 지정할 수 있습니다. uses-feature 요소를 사용하면 Play 스토어에서 사용자에게 표시되는 앱을 적절하게 필터링할 수 있습니다.

다음 기능은 XR 차별화 앱에만 적용됩니다.

android.software.xr.api.openxr

Android XR 플랫폼을 타겟팅하고 OpenXR 또는 Unity로 빌드된 앱은 앱 매니페스트에 이 기능을 포함해야 하며 android:required 속성은 true로 설정해야 합니다.

Unity용 Android XR 확장 프로그램 패키지 버전 1.0.0 이상 또는 Unity OpenXR: Android XR 패키지 버전 0.5.0-exp.1 이상을 사용하는 앱은 이 요소를 앱 매니페스트에 수동으로 추가할 필요가 없습니다. 이 두 패키지는 이 요소를 앱 매니페스트에 삽입합니다.

기기는 이 기능의 버전을 지정할 수 있으며, 이는 기기에서 지원하는 OpenXR의 최고 버전을 나타냅니다. 상위 16비트는 메이저 번호를 나타내고, 하위 16비트는 마이너 번호를 나타냅니다. 예를 들어 OpenXR 버전 1.1을 지정하려면 값을 "0x00010001"로 설정합니다.

앱은 기능 버전을 사용하여 앱에 필요한 OpenXR의 최소 버전을 나타낼 수 있습니다. 예를 들어 앱에 OpenXR 버전 1.1 지원이 필요한 경우 다음 기능을 선언합니다.

<uses-feature android:name="android.software.xr.api.openxr"
    android:version="0x00010001"
    android:required="true" />

android.software.xr.api.spatial

특정 Android XR Spatial API 버전에 도입된 확장 프로그램이 필요한 OpenXR 앱은 android:version를 필요한 최소 Spatial API 수준 (예: "1", "2", "3", "4")으로 설정하여 android.software.xr.api.spatial 기능을 선언할 수 있습니다. 각 확장 프로그램에 필요한 Spatial API 버전을 확인하려면 지원되는 OpenXR 확장 프로그램으로 빌드를 참고하세요.

<!-- Indicates that the app requires Android XR Spatial API Level 4 or higher. -->
<uses-feature android:name="android.software.xr.api.spatial"
    android:version="4"
    android:required="true" />

android.hardware.xr.input.controller

이 기능은 앱이 제대로 작동하려면 고정밀 6DoF(자유도) 모션 컨트롤러의 입력이 필요함을 나타냅니다. 앱이 컨트롤러를 지원하고 컨트롤러 없이는 작동할 수 없는 경우 값을 true로 설정합니다. 앱이 컨트롤러를 지원하지만 컨트롤러 없이도 작동할 수 있다면 false로 설정합니다.

<!-- Sets android:required to true, indicating that your app can't function on devices without controllers. -->
<uses-feature android:name="android.hardware.xr.input.controller" android:required="true" />

android.hardware.xr.input.hand_tracking

이 플래그는 앱이 제대로 작동하려면 사용자 손의 관절 위치, 방향, 속도를 포함한 고화질 핸드 트래킹이 필요함을 나타냅니다. 앱이 핸드 트래킹을 지원하고 핸드 트래킹 없이는 작동할 수 없는 경우 값을 true로 설정합니다. 앱이 핸드 트래킹을 지원하지만 핸드 트래킹 없이도 작동할 수 있는 경우 false로 설정합니다.

<!-- Sets android:required to true, indicating that your app can't function on devices without hand tracking. -->
<uses-feature android:name="android.hardware.xr.input.hand_tracking" android:required="true" />

android.hardware.xr.input.eye_tracking

이 플래그는 입력이 올바르게 작동하려면 앱에 고화질 눈 추적이 필요함을 나타냅니다. 앱이 입력을 위해 눈 추적을 지원하고 눈 추적 없이는 작동할 수 없는 경우 값을 true로 설정합니다. 앱이 입력을 위한 눈 추적을 지원하지만 눈 추적 없이도 작동할 수 있는 경우 false로 설정합니다.

<!-- Sets android:required to true, indicating that your app can't function on devices without eye tracking. -->
<uses-feature android:name="android.hardware.xr.input.eye_tracking" android:required="true" />

android.hardware.xr.input.face_tracking

이 플래그는 앱이 올바르게 작동하려면 얼굴 추적 하드웨어가 필요함을 나타냅니다. 앱이 얼굴 추적을 지원하고 얼굴 추적 없이는 작동할 수 없는 경우 값을 true로 설정합니다. 앱이 얼굴 추적을 지원하지만 얼굴 추적 없이도 작동할 수 있는 경우 false로 설정합니다.

<!-- Sets android:required to true, indicating that your app can't function on devices without face tracking. -->
<uses-feature android:name="android.hardware.xr.input.face_tracking" android:required="true" />

android.hardware.location.gps

이 플래그는 앱이 기기에서 정확한 GPS 위치를 사용함을 나타냅니다(예: 지리 공간 OpenXR 확장 프로그램(XR_ANDROID_geospatial 및 XR_ANDROID_geospatial_anchor)을 사용하는 경우). 앱이 GPS 하드웨어 없이 작동할 수 없는 경우 android:required를 true로 설정하고, GPS 하드웨어 없이 작동할 수 있는 경우 false로 설정합니다.

<uses-feature android:name="android.hardware.location.gps" android:required="false" />

OpenXR 권한 이해하기

많은 OpenXR 확장 프로그램이 개인 정보 보호에 민감한 센서 데이터 및 기능에 액세스합니다. 이러한 확장 프로그램을 사용하려면 앱이 AndroidManifest.xml 파일에서 필수 <uses-permission> 요소를 선언하고 상응하는 OpenXR 함수를 호출하기 전에 런타임 시 위험한 권한을 요청해야 합니다.

<manifest ... >
    <!-- Example dangerous permissions required by specific OpenXR extensions -->
    <uses-permission android:name="android.permission.SCENE_UNDERSTANDING_COARSE" />
    <uses-permission android:name="android.permission.HAND_TRACKING" />
    ...
</manifest>

다음 표에는 Android XR에서 지원되는 OpenXR 확장 프로그램에 필요한 위험한 Android 권한이 요약되어 있습니다. 모든 SDK의 XR 권한에 관한 자세한 내용은 XR 권한 이해하기를 참고하세요.

권한	기능	OpenXR 확장 프로그램
`android.permission.EYE_TRACKING_COARSE`	낮은 정밀도의 눈 자세, 상태, 방향 (예: 아바타용)	`XR_ANDROID_eye_tracking` (`xrGetCoarseTrackingEyesInfoANDROID`)
`android.permission.EYE_TRACKING_FINE`	선택, 입력, 상호작용, 눈 추적 포비티드 렌더링을 위한 고정밀 시선	`XR_ANDROID_eye_tracking` (`xrGetFineTrackingEyesInfoANDROID`) `XR_EXT_eye_gaze_interaction` `XR_META_foveation_eye_tracked` `XR_VARJO_foveated_rendering`
`android.permission.FACE_TRACKING`	얼굴 블렌드셰이프 추적 및 얼굴 표정 렌더링	`XR_ANDROID_face_tracking` `XR_ANDROID_face_tracking_data_source`
`android.permission.RECORD_AUDIO`	오디오 기반 얼굴 추적 데이터 소스의 오디오 입력입니다.	`XR_ANDROID_face_tracking_data_source`
`android.permission.HAND_TRACKING`	손 관절 포즈, 속도, 조준 상태, 손 메시 표현을 추적합니다.	`XR_ANDROID_hand_mesh` `XR_EXT_hand_tracking` `XR_FB_hand_tracking_aim` `XR_FB_hand_tracking_mesh`
`android.permission.BODY_TRACKING`	신체 관절 자세 및 골격 비율 추적	`XR_ANDROID_body_tracking`
`android.permission.SCENE_UNDERSTANDING_COARSE`	평면 추적, 객체 추적, 이미지/마커/QR 코드 추적, 앵커, 지속성, 추적 가능 항목에 대한 레이캐스팅, 조명 추정, 패스 스루 메시	`XR_ANDROID_anchor_sharing_export` `XR_ANDROID_composition_layer_passthrough_mesh` `XR_ANDROID_device_anchor_persistence` `XR_ANDROID_light_estimation` `XR_ANDROID_raycast` `XR_ANDROID_spatial_anchor_space` `XR_ANDROID_spatial_component_subsumed_by` `XR_ANDROID_spatial_discovery_bounds` `XR_ANDROID_spatial_entity_bound_anchor` `XR_ANDROID_spatial_object_tracking` `XR_ANDROID_trackables` `XR_ANDROID_trackables_image` `XR_ANDROID_trackables_marker` `XR_ANDROID_trackables_object` `XR_ANDROID_trackables_qr_code` `XR_EXT_spatial_anchor` `XR_EXT_spatial_image_tracking` `XR_EXT_spatial_marker_tracking` `XR_EXT_spatial_mesh_tracking` `XR_EXT_spatial_object_tracking` `XR_EXT_spatial_persistence` `XR_EXT_spatial_persistence_operations` `XR_EXT_spatial_plane_tracking`
`android.permission.SCENE_UNDERSTANDING_FINE`	깊이 텍스처, 장면 메시, 큐브맵 조명 추정, 깊이 레이캐스팅, 공간 주석	`XR_ANDROID_depth_texture` `XR_ANDROID_light_estimation_cubemap` `XR_ANDROID_scene_meshing` `XR_ANDROID_spatial_annotation_tracking` `XR_ANDROID_spatial_discovery_raycast`
`android.permission.ACCESS_FINE_LOCATION`	지리 공간 추적 및 앵커를 위한 정확한 지구 상대 위치 및 방향입니다.	`XR_ANDROID_geospatial` `XR_ANDROID_geospatial_anchor`

다음 단계

앱의 매니페스트 구성을 완료하고 중요한 정보를 검토했으므로 이제 OpenXR로 빌드하는 방법을 살펴보세요.