Android XR için OpenXR'yi kullanmaya başlama

Uygun XR cihazlar

Bu kılavuz, bu tür XR cihazları için deneyimler geliştirmenize yardımcı olur.

XR cihaz türleri hakkında bilgi edinin →

XR Kulaklığı

Kablolu XR Gözlükleri

XR cihaz türleri hakkında bilgi edinin →

Desteklenen OpenXR uzantılarıyla veya desteklenen bir motorla geliştirmeye başlamadan önce, uygulamanızın XR geliştirme için yapılandırıldığından emin olmak üzere aşağıdaki bölümlerde yer alan manifest yapılandırmasını ve izin şartlarını inceleyin.

Uygulamanızın manifest dosyasını yapılandırma

Diğer Android uygulama projelerinde olduğu gibi Android XR uygulamanızda da belirli manifest ayarlarına sahip bir AndroidManifest.xml dosyası bulunmalıdır. Manifesto dosyası, uygulamanızla ilgili temel bilgileri Android derleme araçlarına, Android işletim sistemine ve Google Play'e açıklar. Daha fazla bilgi için uygulama manifestine genel bakış kılavuzuna bakın.

Not: Android XR için Unity, Unreal Engine veya Godot ile geliştirilen uygulamalar OpenXR üzerinde derlenir. Ancak bu motorlar için resmi Android XR eklentilerini kullanırsanız bu manifest öğelerinin veya özelliklerinin çoğunu manuel olarak eklemeniz gerekmez. Motor eklentileri ve dışa aktarma hazır ayarları, projenize ve derleme ayarlarınıza göre uygulamanızın manifest dosyasını yapılandırır.

XR'a özel uygulamalar için manifesto dosyanızda aşağıdaki öğeler ve özellikler bulunmalıdır:

PROPERTY_XR_ACTIVITY_START_MODE özelliği

android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE" özelliği, sistemin bir etkinliğin başlatıldığında belirli bir modda başlatılması gerektiğini bilmesini sağlar.

Bu özellik aşağıdaki değerlere sahiptir:

• XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED (Yalnızca OpenXR)

XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED

OpenXR ile oluşturulan uygulamalar Tam Ekran Alanı'nda başlatılır ve XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED başlatma modunu kullanmalıdır. Yönetilmeyen Tam Ekran Alanı, Android XR'a uygulamanın OpenXR kullandığını bildirir.

Not: Unity için Android XR paketlerinden birini kullanırsanız uygulamanız Tam Ekran Alanı'nda da başlatılır. Ancak bunu manifest dosyanıza manuel olarak eklemeniz gerekmez. Unity paketleri, projenize ve derleme ayarlarınıza göre uygulamanızın manifest dosyasını oluşturur.

<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 özelliği

android:name="android.window.PROPERTY_XR_BOUNDARY_TYPE_RECOMMENDED" özelliği, uygulamanın belirli bir sınır türüyle başlatılması gerektiğini belirtir. Uygulamanız, kullanıcıların fiziksel alanlarında hareket etmelerine olanak tanıyacak şekilde tasarlanmışsa XR_BOUNDARY_TYPE_LARGE değerini belirtmelidir. XR_BOUNDARY_TYPE_NO_RECOMMENDATION değerini belirtmek, güvenlik sınırı türü için herhangi bir öneri sağlamaz. Bu nedenle sistem, halihazırda kullanılan türü kullanır.

<manifest ... >

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

Uzamsal kapsayıcı özellikleri

Uygulamanız, tam kapsamlı görünümlerin yanı sıra sınırlı 3D hacimlerde veya 2D panellerde içerik sunmak için XR_EXT_spatial_container uzantısını (Spatial API düzeyi 4'te kullanıma sunulmuştur) kullanıyorsa çalışma zamanına başlatma ipuçları sağlamak için <activity> veya <application> düzeyinde aşağıdaki manifest özelliklerini tanımlayabilirsiniz:

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES: Etkinlik tarafından kullanılan sınır modlarını belirtir. Modlar | ile ayrılır.

  Geçerli değerler şunlardır:

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

• org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE: Başlatıldığında etkinliğin ilk sınır modunu belirtir.

  Geçerli değerler şunlardır:

  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE
  • XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED

Not: Bu özellikler, XR_EXT_spatial_container kullanılırken <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> intent filtresi kategorisinin yerini alır.

<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 uygulamaları, çalışma zamanını başarıyla yüklemek için yerel OpenXR kitaplığının kullanımını beyan etmelidir. Bu bildirim olmadan çalışma zamanı yüklenemez.

<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 uygulamaları için PackageManager özellikleri

Google Play Store üzerinden uygulama dağıtırken uygulama manifestinde gerekli donanım veya yazılım özelliklerini belirtebilirsiniz. uses-feature öğesi, Google Play Store'un kullanıcılara gösterilen uygulamaları uygun şekilde filtrelemesine olanak tanır.

Aşağıdaki özellikler XR'a özel uygulamalara özgüdür.

android.software.xr.api.openxr

Android XR platformunu hedefleyen ve OpenXR veya Unity ile geliştirilen uygulamaların, uygulama manifest dosyasında android:required özelliği true olarak ayarlanmış şekilde bu özelliği içermesi gerekir.

Unity için Android XR Uzantıları Paketi'nin 1.0.0 veya sonraki bir sürümünü ya da Unity OpenXR: Android XR Paketi'nin 0.5.0-exp.1 veya sonraki bir sürümünü kullanan uygulamaların bu öğeyi uygulama manifestine manuel olarak eklemesi gerekmez. Bu iki paket, bu öğeyi sizin için uygulama manifestine ekler.

Cihazlar, bu özellik için bir sürüm belirtebilir. Bu sürüm, cihaz tarafından desteklenen en yüksek OpenXR sürümünü gösterir. Üstteki 16 bit ana numarayı, alttaki 16 bit ise alt numarayı temsil eder. Örneğin, OpenXR 1.1 sürümünü belirtmek için değer "0x00010001" olarak ayarlanır.

Uygulamalar, uygulamanın gerektirdiği minimum OpenXR sürümünü belirtmek için özellik sürümünü kullanabilir. Örneğin, uygulamanız OpenXR 1.1 sürümü desteği gerektiriyorsa aşağıdaki özelliği beyan edin:

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

android.software.xr.api.spatial

Belirli bir Android XR Spatial API sürümünde sunulan uzantıları gerektiren OpenXR uygulamaları, android.software.xr.api.spatial özelliğini android:version, gereken minimum Spatial API düzeyine (ör. "1", "2", "3" veya "4") ayarlanmış şekilde tanımlayabilir. Her uzantı için gereken Spatial API sürümünü kontrol etmek üzere Desteklenen OpenXR uzantılarıyla derleme bölümüne bakın.

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

Bu özellik, uygulamanın düzgün çalışması için yüksek hassasiyetli, 6DoF (serbestlik derecesi) hareket kontrol cihazından giriş alması gerektiğini gösterir. Uygulamanız kumandaları destekliyorsa ve kumanda olmadan çalışamıyorsa değeri true olarak ayarlayın. Uygulamanız kumandaları destekliyor ancak kumanda olmadan da çalışabiliyorsa false olarak ayarlayın.

Not: 6DoF hareket kumandaları, her el için bir tane olmak üzere iki donanım kumandadan oluşur. Her kumanda, altı serbestlik derecesi (hem doğrusal hem de dönme hareketleri) aracılığıyla uzayda bağımsız olarak izlenir. Bu kumandalarda genellikle tetikleyici ve dokunsal geribildirim gibi çeşitli donanım düğmeleri bulunur.

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

Bu işaret, uygulamanın doğru şekilde çalışması için kullanıcının elindeki eklemlerin konumu, yönü ve hızı dahil olmak üzere yüksek doğruluklu el takibi gerektiğini gösterir. Uygulamanız el takibini destekliyorsa ve bu özellik olmadan çalışamıyorsa değeri true olarak ayarlayın. Uygulamanız el takibini destekliyor ancak bu özellik olmadan da çalışabiliyorsa false olarak ayarlayın.

Not: Bu işaret; sıkıştırma, dürtme, nişan alma ve kavrama gibi temel hareketleri algılamak için gerekli değildir.

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

Bu işaret, uygulamanın giriş için yüksek doğruluklu göz takibi gerektirdiğini gösterir. Uygulamanız giriş için göz takibini destekliyorsa ve bu özellik olmadan çalışamıyorsa değeri true olarak ayarlayın. Uygulamanız giriş için göz takibini destekliyor ancak bu özellik olmadan da çalışabiliyorsa false olarak ayarlayın.

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

Bu işaret, uygulamanın düzgün çalışması için yüz takibi donanımı gerektiğini gösterir. Uygulamanız yüz takibini destekliyorsa ve bu özellik olmadan çalışamıyorsa değeri true olarak ayarlayın. Uygulamanız yüz takibini destekliyor ancak bu özellik olmadan da çalışabiliyorsa false olarak ayarlayın.

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

Bu işaret, uygulamanın cihazda tam GPS konumunu kullandığını gösterir. Örneğin, coğrafi OpenXR uzantıları (XR_ANDROID_geospatial ve XR_ANDROID_geospatial_anchor) kullanılırken bu işaret kullanılır. Uygulamanız GPS donanımı olmadan çalışamıyorsa android:required değerini true, GPS donanımı olmadan çalışabiliyorsa false olarak ayarlayın.

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

Not: El takibi, göz takibi, yüz takibi, vücut takibi, sahne algılama ve konum, gizlilik açısından hassas özelliklerdir ve uygulamaların çalışma zamanında istenen izin istemesini gerektirir. İzinleri beyan etme ve isteme hakkında daha fazla bilgi için XR için izinleri anlama başlıklı makaleyi inceleyin.

OpenXR izinleri hakkında bilgi

Birçok OpenXR uzantısı, gizlilik açısından hassas sensör verilerine ve özelliklerine erişir. Bu uzantıları kullanmak için uygulamanızın hem AndroidManifest.xml dosyasında gerekli <uses-permission> öğelerini beyan etmesi hem de ilgili OpenXR işlevlerini çağırmadan önce çalışma zamanında tehlikeli izinler istemesi gerekir.

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

Aşağıdaki tabloda, Android XR'da desteklenen OpenXR uzantıları için gereken tehlikeli Android izinleri özetlenmiştir. Tüm SDK'lardaki XR izinleriyle ilgili ayrıntılı bilgi için XR izinlerini anlama başlıklı makaleyi inceleyin.

İzin	İşlemler	OpenXR uzantıları
android.permission.EYE_TRACKING_COARSE	Düşük hassasiyetli göz duruşu, durumu ve yönü (ör. avatarlar için).	XR_ANDROID_eye_tracking (xrGetCoarseTrackingEyesInfoANDROID)
android.permission.EYE_TRACKING_FINE	Seçim, giriş, etkileşimler ve göz takipli foveated rendering için yüksek hassasiyetli göz bakışı.	XR_ANDROID_eye_tracking (xrGetFineTrackingEyesInfoANDROID) XR_EXT_eye_gaze_interaction XR_META_foveation_eye_tracked XR_VARJO_foveated_rendering
android.permission.FACE_TRACKING	Yüz karışım şekillerini izleme ve yüz ifadelerini oluşturma.	XR_ANDROID_face_tracking XR_ANDROID_face_tracking_data_source
android.permission.RECORD_AUDIO	Sese dayalı yüz takibi veri kaynakları için ses girişi.	XR_ANDROID_face_tracking_data_source
android.permission.HAND_TRACKING	El eklemi pozlarını, hızlarını, hedefleme durumunu ve el örgüsü temsilini izleme.	XR_ANDROID_hand_mesh XR_EXT_hand_tracking XR_FB_hand_tracking_aim XR_FB_hand_tracking_mesh
android.permission.BODY_TRACKING	Vücut eklem pozlarını ve iskelet oranlarını izleme	XR_ANDROID_body_tracking
android.permission.SCENE_UNDERSTANDING_COARSE	Düzlem izleme, nesne izleme, resim/işaretçi/QR kodu izleme, sabitleyiciler, kalıcılık, izlenebilir öğelere karşı ışın dökümü, ışık tahmini ve geçiş ağları.	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	Derinlik dokuları, sahne örgüsü, küp haritası ışık tahmini, derinlik ışın dökümü ve uzamsal ek açıklamalar.	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	Coğrafi izleme ve sabitleyiciler için Dünya'ya göre hassas konum ve yön.	XR_ANDROID_geospatial XR_ANDROID_geospatial_anchor

Sonraki adımlar

Uygulamanızın manifest dosyasını yapılandırmayı ve önemli bilgileri incelemeyi tamamladığınıza göre OpenXR ile neler geliştirebileceğinizi keşfedin:

• Desteklenen OpenXR uzantılarıyla derleme yapma
• Desteklenen motorlarla derleme