Mulai menggunakan OpenXR untuk Android XR

Perangkat XR yang kompatibel

Panduan ini membantu Anda membangun pengalaman untuk jenis perangkat XR ini.

Mempelajari jenis perangkat XR →

Headset XR

Kacamata XR Berkabel

Mempelajari jenis perangkat XR →

Sebelum mulai membangun dengan ekstensi OpenXR yang didukung atau dengan mesin yang didukung, tinjau konfigurasi manifes dan persyaratan izin di bagian berikut untuk memastikan aplikasi Anda dikonfigurasi untuk pengembangan XR.

Mengonfigurasi file manifes aplikasi Anda

Seperti project aplikasi Android lainnya, aplikasi Android XR Anda harus memiliki file AndroidManifest.xml dengan setelan manifes tertentu. File manifes menjelaskan informasi penting tentang aplikasi Anda ke alat build Android, sistem operasi Android, dan Google Play. Lihat panduan ringkasan manifes aplikasi untuk mengetahui informasi selengkapnya.

Catatan: Meskipun aplikasi yang dibuat dengan Unity, Unreal Engine, atau Godot untuk Android XR dibuat di atas OpenXR, Anda tidak perlu menambahkan sebagian besar elemen atau atribut manifes ini secara manual jika menggunakan plugin Android XR resmi untuk mesin tersebut. Plugin mesin dan preset ekspor mengonfigurasi manifes untuk aplikasi Anda berdasarkan setelan project dan build.

Untuk aplikasi yang dibedakan XR, file manifes Anda harus berisi elemen dan atribut berikut:

Properti PROPERTY_XR_ACTIVITY_START_MODE

Properti android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" memungkinkan sistem mengetahui bahwa aktivitas harus diluncurkan dalam mode tertentu saat aktivitas dimulai.

Properti ini memiliki nilai berikut:

• XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED (Khusus OpenXR)

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

Aplikasi yang dibuat dengan OpenXR diluncurkan di Ruang Penuh dan harus menggunakan mode mulai XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED. Ruang Penuh Tidak Terkelola memberi sinyal ke Android XR bahwa aplikasi menggunakan OpenXR.

Catatan: Jika Anda menggunakan salah satu paket Android XR untuk Unity, aplikasi Anda juga akan diluncurkan di Ruang Penuh. Namun, Anda tidak perlu menambahkan ini ke manifes secara manual. Paket Unity membuat manifes untuk aplikasi Anda berdasarkan setelan project dan build Anda.

<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>

Properti PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED

Properti android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED" menunjukkan bahwa aplikasi harus diluncurkan dengan jenis batas tertentu. Aplikasi Anda harus menentukan XR_BOUNDARY_TYPE_LARGE jika dirancang untuk memungkinkan pengguna bergerak di ruang fisik mereka. Menentukan XR_BOUNDARY_TYPE_NO_RECOMMENDATION tidak memberikan rekomendasi untuk jenis batas pengaman, sehingga sistem menggunakan jenis yang sudah digunakan.

<manifest ... >

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

Properti penampung spasial

Jika aplikasi Anda menggunakan ekstensi XR_EXT_spatial_container (diperkenalkan di Spatial API Level 4) untuk menampilkan konten dalam volume 3D terbatas atau panel 2D selain tampilan imersif penuh, Anda dapat mendeklarasikan properti manifes berikut di level <activity> atau <application> untuk memberikan petunjuk peluncuran ke runtime:

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES: Menentukan mode batas yang digunakan oleh aktivitas, dipisahkan oleh |.

  Nilai yang valid adalah:

  • "2d_panel"
  • "bounded"
  • "immersive"

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE: Menentukan mode batas awal aktivitas saat diluncurkan.

  Nilai yang valid adalah:

  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED

Catatan: Properti ini menggantikan kategori filter intent <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> saat menggunakan XR_EXT_spatial_container.

<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

Aplikasi OpenXR harus mendeklarasikan penggunaan library OpenXR native agar berhasil memuat runtime-nya. Tanpa deklarasi ini, runtime akan gagal dimuat.

<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>

Fitur PackageManager untuk aplikasi XR

Saat mendistribusikan aplikasi melalui Google Play Store, Anda dapat menentukan fitur hardware atau software yang diperlukan dalam manifes aplikasi. Elemen uses-feature memungkinkan Google Play Store memfilter aplikasi yang ditampilkan kepada pengguna dengan tepat.

Fitur berikut khusus untuk aplikasi yang dibedakan XR.

android.software.xr.api.openxr

Aplikasi yang menargetkan platform Android XR dan di-build dengan OpenXR atau Unity harus menyertakan fitur ini dalam manifes aplikasi dengan atribut android:required yang ditetapkan ke true.

Aplikasi yang menggunakan Paket Ekstensi Android XR untuk Unity versi 1.0.0 atau yang lebih tinggi atau Unity OpenXR: Paket Android XR versi 0.5.0-exp.1 atau yang lebih tinggi tidak perlu menambahkan elemen ini secara manual ke manifes aplikasi. Kedua paket ini akan memasukkan elemen ini ke dalam manifes aplikasi untuk Anda.

Perangkat dapat menentukan versi untuk fitur ini, yang menunjukkan versi OpenXR tertinggi yang didukung oleh perangkat. 16 bit yang lebih tinggi mewakili bilangan utama, dan 16 bit yang lebih rendah menunjukkan bilangan minor. Misalnya, untuk menentukan OpenXR versi 1.1, nilainya akan ditetapkan ke "0x00010001".

Aplikasi dapat menggunakan versi fitur untuk menunjukkan versi minimum OpenXR yang diperlukan aplikasi. Misalnya, jika aplikasi Anda memerlukan dukungan OpenXR versi 1.1, deklarasikan fitur berikut:

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

android.software.xr.api.spatial

Aplikasi OpenXR yang memerlukan ekstensi yang diperkenalkan dalam versi Spatial API Android XR tertentu dapat mendeklarasikan fitur android.software.xr.api.spatial dengan android:version yang ditetapkan ke level Spatial API minimum yang diperlukan (seperti "1", "2", "3", atau "4"). Lihat Membangun dengan ekstensi OpenXR yang didukung untuk memeriksa versi Spatial API yang diperlukan untuk setiap ekstensi.

<!-- 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

Fitur ini menunjukkan bahwa aplikasi memerlukan input dari pengontrol gerakan 6DoF (derajat kebebasan) presisi tinggi agar dapat berfungsi dengan benar. Jika aplikasi Anda mendukung pengontrol dan tidak dapat berfungsi tanpanya, tetapkan nilainya ke true. Jika aplikasi Anda mendukung pengontrol, tetapi dapat beroperasi tanpa pengontrol, tetapkan ke false.

Catatan: Pengontrol gerakan 6DoF adalah sepasang pengontrol hardware, satu untuk setiap tangan. Setiap pengontrol dilacak secara independen di ruang melalui enam derajat kebebasan - baik gerakan linear maupun rotasi. Pengontrol ini biasanya memiliki beberapa tombol fisik, termasuk pemicu serta respons haptik.

<!-- 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

Flag ini menunjukkan bahwa aplikasi memerlukan pelacakan gerak tangan fidelitas tinggi agar berfungsi dengan benar, termasuk posisi, orientasi, dan kecepatan sendi di tangan pengguna. Jika aplikasi Anda mendukung pelacakan gerak tangan dan tidak dapat berfungsi tanpanya, tetapkan nilai ke true. Jika aplikasi Anda mendukung pelacakan gerak tangan, tetapi dapat beroperasi tanpanya, tetapkan ke false.

Catatan: Flag ini tidak diperlukan untuk mendeteksi gestur dasar seperti mencubit, menusuk, membidik, dan menggenggam.

<!-- 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

Flag ini menunjukkan bahwa aplikasi memerlukan pelacakan gerak mata fidelitas tinggi agar input berfungsi dengan benar. Jika aplikasi Anda mendukung pelacakan gerak mata untuk input dan tidak dapat berfungsi tanpanya, tetapkan nilainya ke true. Jika aplikasi Anda mendukung pelacakan gerak mata untuk input, tetapi dapat beroperasi tanpanya, tetapkan ke 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

Flag ini menunjukkan bahwa aplikasi memerlukan hardware pelacakan wajah agar dapat berfungsi dengan benar. Jika aplikasi Anda mendukung pelacakan wajah dan tidak dapat berfungsi tanpanya, tetapkan nilainya ke true. Jika aplikasi Anda mendukung pelacakan wajah, tetapi dapat beroperasi tanpanya, tetapkan ke 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

Flag ini menunjukkan bahwa aplikasi menggunakan lokasi GPS akurat di perangkat, seperti saat menggunakan ekstensi OpenXR geospasial (XR_ANDROID_geospatial dan XR_ANDROID_geospatial_anchor). Tetapkan android:required ke true jika aplikasi Anda tidak dapat berfungsi tanpa hardware GPS, atau false jika dapat beroperasi tanpanya.

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

Catatan: Pelacakan gerak tangan, pelacakan gerak mata, pelacakan wajah, pelacakan tubuh, pemahaman scene, dan lokasi adalah kemampuan yang sensitif terhadap privasi dan mengharuskan aplikasi meminta izin runtime. Lihat Memahami izin untuk XR untuk mengetahui informasi selengkapnya tentang mendeklarasikan dan meminta izin.

Memahami izin untuk OpenXR

Banyak ekstensi OpenXR mengakses data dan kemampuan sensor yang sensitif terhadap privasi. Untuk menggunakan ekstensi ini, aplikasi Anda harus mendeklarasikan elemen <uses-permission> yang diperlukan dalam file AndroidManifest.xml dan meminta izin berbahaya saat runtime sebelum memanggil fungsi OpenXR yang sesuai.

<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>

Tabel berikut merangkum izin Android berbahaya yang diperlukan oleh ekstensi OpenXR yang didukung di Android XR. Untuk mengetahui detail selengkapnya tentang izin XR di semua SDK, lihat Memahami izin untuk XR.

Izin	Kemampuan	Ekstensi OpenXR
android.permission.EYE_TRACKING_COARSE	Pose, status, dan orientasi mata dengan presisi rendah (seperti untuk avatar).	XR_ANDROID_eye_tracking (xrGetCoarseTrackingEyesInfoANDROID)
android.permission.EYE_TRACKING_FINE	Pandangan mata presisi tinggi untuk pemilihan, input, interaksi, dan foveated rendering yang dilacak mata.	XR_ANDROID_eye_tracking (xrGetFineTrackingEyesInfoANDROID) XR_EXT_eye_gaze_interaction XR_META_foveation_eye_tracked XR_VARJO_foveated_rendering
android.permission.FACE_TRACKING	Melacak bentuk campuran wajah dan merender ekspresi wajah.	XR_ANDROID_face_tracking XR_ANDROID_face_tracking_data_source
android.permission.RECORD_AUDIO	Input audio untuk sumber data pelacakan wajah berbasis audio.	XR_ANDROID_face_tracking_data_source
android.permission.HAND_TRACKING	Melacak pose sendi tangan, kecepatan, status bidikan, dan representasi mesh tangan.	XR_ANDROID_hand_mesh XR_EXT_hand_tracking XR_FB_hand_tracking_aim XR_FB_hand_tracking_mesh
android.permission.BODY_TRACKING	Melacak pose sendi tubuh dan proporsi kerangka.	XR_ANDROID_body_tracking
android.permission.SCENE_UNDERSTANDING_COARSE	Pelacakan bidang, pelacakan objek, pelacakan gambar/penanda/kode QR, anchor, persistensi, raycasting terhadap objek yang dapat dilacak, estimasi pencahayaan, dan mesh passthrough.	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	Tekstur kedalaman, meshing scene, estimasi pencahayaan cubemap, raycasting kedalaman, dan anotasi spasial.	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	Lokasi dan orientasi yang akurat terkait Bumi untuk pelacakan dan anchor Geospasial.	XR_ANDROID_geospatial XR_ANDROID_geospatial_anchor

Langkah berikutnya

Setelah selesai mengonfigurasi manifes aplikasi dan meninjau informasi penting, pelajari cara membangun aplikasi dengan OpenXR:

• Membangun dengan ekstensi OpenXR yang didukung
• Membangun dengan mesin yang didukung