Uzamsal kapsayıcılarla oluşturma

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 →

Uzamsal kapsayıcılar, OpenXR'a hacimsel pencereleme özelliği getirir. OpenXR 1.1'deki XR_EXT_spatial_container ve XR_EXT_spatial_container_self_rendering uzantıları tarafından tanımlanan uzamsal kapsayıcı, kullanıcının alanında sistem tarafından yönetilen 3D hacimsel bir bölgedir. Uygulamanız, standart OpenXR oluşturma katmanlarını kullanarak bu bölgede 3D içerik oluşturur.

Geleneksel olarak, bir OpenXR oturumu kullanıcının tüm görüş alanına özel erişim talep eder. Spatial Containers, uygulamanızın kullanıcının ortamındaki sınırlı bir 3D kutu içinde 3D OpenXR içeriği oluşturmasına veya istediğiniz zaman sınırsız, tam ekran ve etkileyici bir deneyime geçmesine olanak tanır.

Uzamsal kapsayıcılar hakkında

Üç boyutlu kapsayıcı, Android XR sistemi tarafından yönetilen ve OpenXR uygulamanız tarafından oluşturulan sınırlı veya sınırsız bir 3D bölgedir:

  • Sınırlı mod: Uygulamanız 3D boyutlar (metre cinsinden genişlik, yükseklik ve derinlik) önerir ve sistem, kullanıcının ortamında 3D sınırlayıcı kutu ayırır. Uygulamanız, hacim içinde stereo 3D içerik oluşturur ve sistem, oluşturulan içeriği 3D kutunun sınırlarına göre kırpar.
  • Yoğun içerik modu: Üç boyutlu kapsayıcı, sonsuz sınırlara genişleyerek uygulamanıza geleneksel tam ekran OpenXR oturumu gibi kullanıcının tüm görüş alanını verir.
Tam Ekran Alanı modunda aynı anda çalışan üç uzamsal kapsayıcı: turuncu renkli, zemine kilitli 3D arazi kapsayıcısı, ekli 2D kullanıcı arayüzüne sahip mavi renkli 3D ördek modeli ve yeşil renkli 2D kullanıcı arayüzü kapsayıcısı.
Şekil 1. Tam Ekran Alanı modunda birden fazla üç boyutlu kapsayıcı: zemine kilitlenmiş üç boyutlu arazi hacmi (solda), iki boyutlu kullanıcı arayüzüyle eşlenmiş üç boyutlu ördek hacmi (ortada) ve iki boyutlu kullanıcı arayüzü kapsayıcısı (sağda).

Kullanıcıların üç boyutlu kapsayıcılarla etkileşim kurma şekli

Android XR sistemi, üç boyutlu kapsayıcının pencere kontrollerini ve fiziksel alandaki yerleşimini yöneterek uygulamalar arasında tutarlı bir etkileşim modeli sağlar:

  • Taşıma ve yeniden konumlandırma: Kullanıcılar, üç boyutlu alanda yeniden konumlandırmak için elle yapılan hareketleri (ör. sıkıştırma) veya hareket kumandalarını kullanarak uzamsal kapsayıcının sistem tutma yerini tutabilir.
  • Küçültme ve kapatma: Sistem penceresi kontrolleri, kullanıcıların tek tek uzamsal kapsayıcıları küçültmesine veya kapatmasına olanak tanır. Kullanıcı bir kapsayıcıyı kapattığında sistem, uygulamanızı bilgilendirir. Böylece uygulamanız kaynakları temizleyebilir.
  • Sahne algılama ile zemine sabitleme: Uygulamanız android.permission.SCENE_UNDERSTANDING_COARSE iznini beyan edip istediğinde sistem, yüzeye sabitlemeyi otomatik olarak etkinleştirir. Böylece kullanıcılar, Şekil 1'deki turuncu arazi kapsayıcısında gösterildiği gibi ek uygulama yapılandırması olmadan uzamsal kapsayıcıyı fiziksel zemine yerleştirip sabitleyebilir.
  • Doğrudan 3D etkileşim: Bir kapsayıcı odaklanmış ve etkileşimli olduğunda kullanıcılar, el takibi, göz bakışı veya 6DoF kumandaları kullanarak hacim içindeki 3D içerikle doğrudan etkileşim kurabilir.
Sınırlı mavi bir uzamsal kapsayıcıda el takibi kullanarak 3D ördekle etkileşim kuran bir kullanıcı.
Şekil 2. Sınırlı bir uzamsal kapsayıcıda el takibi özelliğini kullanarak 3D içerikle etkileşim kuran bir kullanıcı.
  • Sınırlı ve yoğun içerik modları arasında geçiş yapma: Kullanıcı veya uygulamanız, OpenXR oturumunu yeniden başlatmadan bir kapsayıcıyı sınırlı 3D kutu ile sınırsız tam ekran yoğun içerik görünümü arasında değiştirebilir.
Sınırlı bir uzamsal kapsayıcıdan sınırsız tam ekran etkileyici görünüme geçişten sonraki 3D ördek sahnesi.
Şekil 3. Sınırlı moddan yoğun içerik moduna geçtikten sonra kullanıcının görüş alanını dolduran uzamsal kapsayıcı.
  • Hareket halindeyken takip modu: Sistem, her bir uzamsal kapsayıcının koordinat alanının (xrCreateSpatialContainerSpaceEXT) duruşunu kontrol ettiğinden kullanıcılar, sistem penceresi kontrollerinden takip modunu etkinleştirebilir. Böylece, sınırlı bir 3D kapsayıcı, uygulamanızda ek yapılandırma gerektirmeden kullanıcıları otomatik olarak takip eder ve kullanıcılar dolaşırken görüş alanlarında kalır.

Android XR'da üç boyutlu kapsayıcıları kullanma

Spatial Containers ile uygulama oluştururken sahnenizi kapsayıcının sınırlarına, durum değişikliklerine ve arka plan karışım moduna göre tasarlayın.

3D içeriğinizi kapsayıcı sınırlarına uyarlama

Sınırlı modda, uzamsal kapsayıcı alanının (xrCreateSpatialContainerSpaceEXT) başlangıç noktası (0, 0, 0), 3D sınırlayıcı kutunun merkezindedir. Sistem, kullanıcının ortamındaki kapsayıcı alanının pozunu yönettiğinden uygulamanız, 3D içeriğini (0, 0, 0) ile ilişkili olarak oluşturur. Sistem ise kullanıcının yeniden konumlandırma ve takip modunu yönetir. Sistem, kutunun genişliği, yüksekliği veya derinliği dışında oluşturulan tüm geometrileri kırparak içeriğin kendisine atanan hacim içinde kalmasını sağlar.

Uygulamanız, çalışma zamanından gelen sınır değişikliği etkinliklerini dinlemeli ve 3D sahnenizi ölçeklendirmeli veya yeniden konumlandırmalıdır. Böylece önemli içerikler, kapsayıcının mevcut boyutlarına sığar. Kapsayıcı yoğun içerik moduna geçtiğinde sınırlar sonsuz olur ve sahnenizi tam 1:1 dünya ölçeğine geri yükleyebilirsiniz.

Kapsayıcı durumu değişikliklerine yanıt verme

Görünürlük ve odak yalnızca uygulama düzeyinde yönetilmez. Her uzamsal kapsayıcı kendi durumunu bildirir. Böylece uygulamanız buna göre tepki verebilir:

  • Görünürlük: Kapsayıcının şu anda gösterilip gösterilmediğini belirtir. Kapsayıcı gizliyken animasyonları, sesleri veya simülasyon güncellemelerini duraklatın. Uygulamanız bir kapsayıcıyı göstermeyi veya gizlemeyi de isteyebilir.
  • Etkileşim kurulabilirlik: Kapsayıcıya odaklanılıp odaklanılmadığını ve el takibi, kumandalar veya göz bakışından kullanıcı girişi alınıp alınmadığını gösterir. Odak değiştiğinde etkileşimli vurgulamaları ve giriş işlemeyi etkinleştirin veya devre dışı bırakın.
  • Sınır modu: Kapsayıcının şu anda XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT (3D kutuya kırpılmış) veya XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT (sınırsız tam ekran) modunda olup olmadığını gösterir. Mod değiştiğinde sahne ölçeğinizi güncelleyin ve ortam görsellerini (ör. gökyüzü kutuları veya geçiş) açıp kapatın. Uygulamanız, sınırlı ve yoğun içerik modları arasında geçiş isteğinde de bulunabilir.

Sınırlı modda alfa karışımlı şeffaflık kullanma

Sınırlı modda, şeffaf arka plan sayesinde kullanıcının fiziksel ortamı ve diğer pencereler 3D modellerinizin etrafında görünür kalır. Kameranızı veya görüntü alanınızı şeffaf bir arka planla yapılandırın ve alfa karışımı ortam karışım modunu kullanın. Yoğun içerik moduna geçerken geçiş özelliğini etkin durumda tutabilir veya opak bir gökyüzü kutusu ortamına geçebilirsiniz.

Özelliklerin kullanılabilirlik durumunu kontrol etme ve manifest dosyanızı yapılandırma

Üç boyutlu kapsayıcılar, üç boyutlu API düzeyi 4 veya sonraki sürümleri destekleyen bir Android XR cihaz gerektirir. Android API düzeyini doğrudan kontrol etmek yerine OpenXR çalışma zamanını sorgulayarak uzamsal kapsayıcıların desteklenip desteklenmediğini belirleyin. Bunun için xrEnumerateInstanceExtensionProperties işlevini çağırarak XR_EXT_spatial_container ve XR_EXT_spatial_container_self_rendering uzantılarının mevcut olduğunu doğrulayın, ardından xrGetSystemProperties işlevini XrSystemSpatialContainerPropertiesEXT ile çağırarak supportsBounded ve supportsImmersive uzantılarını inceleyin.

Spatial Containers kullanan bir uygulama oluşturmadan önce etkinlik başlatma modunuzu ve özelliğe özgü izinleri AndroidManifest.xml içinde yapılandırın.

AndroidManifest.xml dosyasında Tam Ekran Alanı modunu etkinleştirme

Üç Boyutlu Container'lar, bağımsız OpenXR uygulamaları için bile Tam Ekran Alanı Yönetilen modunu gerektirir. Geleneksel tam ekran OpenXR uygulamaları, sistem pencere yönetimi olmadan ekranın özel kontrolünü ele geçirmek için XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED bildirir. Buna karşılık, üç boyutlu kapsayıcıları kullanan bir uygulama, tam ekran alanı modunda 3D sınırlı hacimleri, pencere kontrollerini ve uzamsal yerleşimi yönetmek için Android XR sistem oluşturucusunu kullanır ve android.window.PROPERTY_XR_ACTIVITY_START_MODE değerini XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED olarak ayarlamalıdır:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application ...>
        <!-- Spatial Containers require Full Space Managed mode -->
        <property
            android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
            android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED" />

        <activity android:name=".MainActivity" ...>
            <!-- Optional hint declaring which bounds modes the activity uses -->
            <property
                android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
                android:value="XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT|XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT" />
        </activity>
    </application>
</manifest>

Özelliğe özel izinleri beyan etme ve isteme

Temel bir uzamsal kapsayıcı oluşturmak ve oluşturmak için tehlikeli çalışma zamanında istenen izinler gerekmez. Ancak belirli özellikler için ilgili Android XR izinlerinin beyan edilmesi ve istenmesi gerekir:

  • Sahne algılamayı kullanarak bir uzamsal kapsayıcıyı fiziksel zemine kilitlemek ve sabitlemek için çalışma zamanında tehlikeli android.permission.SCENE_UNDERSTANDING_COARSE iznini beyan edin ve isteyin.
  • OpenXR'da kullanıcının kafa pozunu izlemek için android.permission.HEAD_TRACKING öğesini tanımlayın ve isteyin.
<uses-permission android:name="android.permission.HEAD_TRACKING" />
<uses-permission android:name="android.permission.SCENE_UNDERSTANDING_COARSE" />

Çalışma zamanında tehlikeli XR izinlerini bildirme ve isteme hakkında ayrıntılı bilgi için XR izinlerini anlama başlıklı makaleyi inceleyin.

Projenizde Spatial Containers'ı etkinleştirme

Unity, Godot veya doğrudan C++'ta OpenXR kullanarak Spatial Containers ile uygulama geliştirebilirsiniz. Tercih ettiğiniz ortamın ön koşullarını, düzenleyici kurulumunu ve kod örneğini görmek için bir sekme seçin:

Unity

Ön koşullar

Projenizi yapılandırma

  1. Edit > Project Settings > XR Plug-in Management > OpenXR'a (Düzenle > Proje Ayarları > XR Eklenti Yönetimi > OpenXR) gidin.
  2. Android XR (Uzantılar): Oturum Yönetimi'nin yanındaki Ayarlar'ı tıklayın ve Sürükleyici XR'ın işaretini kaldırın.
  3. OpenXR Feature Groups (OpenXR Özellik Grupları) listesinde Spatial Container'ı (Uzamsal Kapsayıcı) etkinleştirin.

Sınırları sorgulamak, kapsayıcı etkinliklerine yanıt vermek ve sınırlı ile yoğun içerik modları arasında geçiş yapmak için C# dilinde XRSpatialContainerFeature kullanın:

void OnEnable()
{
    XRSpatialContainerFeature.OnSpatialContainerBoundsChanged += OnBoundsChanged;
}

private void OnBoundsChanged(Vector3 bounds, bool infiniteBounds)
{
    float minScale = Mathf.Min(bounds.x, bounds.y, bounds.z);
    transform.localScale = infiniteBounds ? Vector3.one : Vector3.one * minScale;
}

public void SetImmersiveMode(bool immersive)
{
    XRSpatialContainerFeature.TryRequestBoundsMode(immersive);
}

Proje kurulumu, manifest yapılandırması ve izin yönetimiyle ilgili tüm adımlar için Unity'de uzamsal kapsayıcıları kullanma başlıklı makaleyi inceleyin.

Godot

Ön koşullar

Projenizi yapılandırma

  1. Project > Project Settings'e (Proje > Proje Ayarları) gidin, Advanced Settings'i (Gelişmiş Ayarlar) etkinleştirin ve General > XR > OpenXR > Extensions'a (Genel > XR > OpenXR > Uzantılar) gidin.
  2. Spatial Container (Uzamsal Kapsayıcı) alt bölümünde Enabled'ı (Etkin) seçin ve Bounds Mode (Sınır Modu) ile Bounds'u (Sınırlar) yapılandırın.
  3. Proje > Dışa aktar... > Android'e gidin ve Android XR Özellikleri bölümünde Deneysel Özellikleri Kullan'ı seçin.

Kapsayıcı sınırlarına ve mod değişikliklerine yanıt vermek için GDScript'te OpenXRSpatialContainerExtension singleton'ını kullanın:

func _ready() -> void:
    if OpenXRSpatialContainerExtension.is_enabled():
        OpenXRSpatialContainerExtension.spatial_container_bounds_changed.connect(
            _on_bounds_changed
        )

func _on_bounds_changed(_rid: RID, bounds: Vector3) -> void:
    scale = Vector3.ONE * min(bounds.x, bounds.y, bounds.z)

func set_immersive_mode() -> void:
    OpenXRSpatialContainerExtension.request_main_spatial_container_bounds_mode(
        OpenXRSpatialContainerState.IMMERSIVE
    )

Proje ayarlarının tamamı, dışa aktarma izinleri ve GDScript örnekleri için Godot'da Spatial Containers'ı kullanma başlıklı makaleyi inceleyin.

OpenXR

Ön koşullar

XrInstance öğenizi oluştururken XR_EXT_spatial_container ve XR_EXT_spatial_container_self_rendering özelliklerini etkinleştirin, ardından uzamsal kapsayıcınızı oluşturup oluşturun:

// 1. Enable the Spatial Container extensions during xrCreateInstance
const char* enabledExtensions[] = {
    XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME,
    XR_EXT_SPATIAL_CONTAINER_SELF_RENDERING_EXTENSION_NAME,
};

// 2. Configure and create a self-rendering spatial container
XrSpatialContainerConfigurationSelfRenderingEXT selfRenderingConfig{
    .type = XR_TYPE_SPATIAL_CONTAINER_CONFIGURATION_SELF_RENDERING_EXT,
    .next = nullptr,
    .viewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
    .suggestedBounds = {1.5f, 1.5f, 1.5f}, // Width, height, depth in meters
};

XrSpatialContainerCreateInfoEXT createInfo{
    .type = XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT,
    .next = &selfRenderingConfig,
    .spatialContainerConfig =
        reinterpret_cast<const XrSpatialContainerConfigurationBaseHeaderEXT*>(
            &selfRenderingConfig),
};

XrSpatialContainerEXT spatialContainer = XR_NULL_HANDLE;
xrCreateSpatialContainerEXT(session, &createInfo, &spatialContainer);

// 3. Request bounded mode and make the container visible
xrRequestSpatialContainerBoundsModeEXT(
    spatialContainer, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT);
xrRequestSpatialContainerVisibilityEXT(spatialContainer, XR_TRUE);

Aşağıdaki kaynakları da incelemenizi öneririz:

OpenXR™ ve OpenXR logosu, The Khronos Group Inc. şirketine ait ticari markalardır ve Çin, Avrupa Birliği, Japonya ve Birleşik Krallık'ta ticari marka olarak tescillidir.