OpenXR Geliştirme Kılavuzu

OpenXR, Khronos Group tarafından tanımlanan ve sürdürülen, açık ve telif ücretsiz bir XR (VR/AR/MR) arayüz standardıdır. Temel amacı, geliştiricilerin "bir kez yaz, her yerde çalıştır" yaklaşımını benimsemesini sağlamaktır. Böylece her cihazın kendi API setine sahip olmasından kaynaklanan parçalanma sorunu çözülür. LCC Unity SDK artık OpenXR standardını desteklemektedir. Bu sayede 3DGS verileri, belirli bir VR cihaz üreticisinin sağladığı SDK olmadan OpenXR uyumlu cihazlarda görüntülenebilir.

Sürüm Gereksinimleri

Bu kılavuzda kullanılan yazılım ve eklenti sürümleri aşağıdadır. Aynı sürümlerle geliştirme yapmanız önerilir; test edilmemiş diğer sürümlerde uyumluluk sorunları olabilir:

Not:

1. OpenXR bir standarttır. Çeşitli VR cihaz üreticileri tüm özelliklerini veya yalnızca bir kısmını destekleyebilir. Bu nedenle kullanmadan önce ilgili cihazın destek durumunu kontrol etmeniz gerekir.
2. OpenXR standardı ortak teknik belirtimleri tanımlar. Ancak cihaza özgü özellikler için yine de üretici SDK'sı veya üretici OpenXR Extension desteği gerekir. Kareler arası akıcılığı artıran ATW (Asynchronous Time Warp), PTW (Late Stage Reprojection) ve benzeri teknolojiler buna örnektir.
3. Bu kılavuz ağırlıklı olarak gerçek VR cihazlarında OpenXR geliştirmeyi gösterir. LCC Unity SDK, OpenXR masaüstü uygulama geliştirmeyi (PCVR hariç) desteklemez.

Geliştirme İş Akışı

Adım 1: URP Projesi Oluşturma

Proje şablonunda Universal 3D (URP görüntüleme hattı) türünü seçin, aşağıda gösterildiği gibi:

Universal 3D Projesi Oluşturma

Adım 2: Platformu Değiştirme

Proje oluşturulduktan sonra Unity menüsünden File → Build Profiles seçeneğini seçerek derleme penceresini açın ve platformu aşağıda gösterildiği gibi Android olarak değiştirin:

Build Profiles'ta platformu Android olarak değiştirme

Adım 3: Unity OpenXR'ı İçe Aktarma

Unity menüsünden Window → Package Manager yolunu izleyerek UPM penceresini açın, soldaki listeden Unity Registry seçeneğini seçin, arama kutusuna OpenXR yazın, arama sonuçlarından OpenXR Plugin seçeneğini seçip aşağıda gösterildiği gibi yükleyin:

OpenXR Plugin'i Unity Registry'den Yükleme

Adım 4: XR Interaction Toolkit'i İçe Aktarma

Soldaki listeden Unity Registry seçeneğini seçin, arama kutusuna XR yazın, arama sonuçlarından XR Interaction Toolkit seçeneğini seçip aşağıda gösterildiği gibi yükleyin:

XR Interaction Toolkit'i Unity Registry'den Yükleme

Adım 5: LCC Unity SDK'yı İçe Aktarma

Unity menüsünden Window → Package Manager yolunu izleyerek UPM penceresini açın, soldaki ＋ simgesine tıklayın, açılır menüden Install package from disk seçeneğini seçin, LCC Unity SDK'yı bulun ve içe aktarmak için package.json dosyasını seçin:

LCC Unity SDK'yı Install package from disk ile içe aktarma

Adım 6: Unity Ortamını Ayarlama

XR Plug-in Management'ı Yapılandırma (Android platformu)

Unity menü çubuğundan File → Project Settings öğesini seçin, soldan XR Plug-in Management öğesini seçin, Android platform sekmesinde OpenXR ve Initialize XR on Startup seçeneklerini işaretleyin, aşağıda gösterildiği gibi:

Android platformunda OpenXR ve Initialize XR on Startup seçeneklerini işaretleme

XR Plug-in Management'ı Yapılandırma (Masaüstü platformu)

LCC Unity SDK masaüstü OpenXR geliştirmeyi desteklemediğinden, Desktop platformunda OpenXR veya Initialize XR on Startup seçeneğini işaretlemeyin, aşağıda gösterildiği gibi:

Desktop platformunda OpenXR veya Initialize XR on Startup seçeneğini işaretlememe

Not: Masaüstü PCVR için PCVR Akışı bölümüne bakın.

OpenXR görüntüleme modunu ve etkileşim yapılandırmasını ayarlama

XR Plug-in Management altındaki OpenXR öğesini seçin ve Android platformunda Render Mode değerini Single Pass Instanced veya Multi-View olarak ayarlayın. OpenXR için Interaction Profiles ayarlanması gerektiğinden genellikle Oculus Touch Controller Profile veya benzer cihaz performans özelliklerine sahip bir profil seçin, aşağıda gösterildiği gibi:

OpenXR Render Mode ve Interaction Profiles ayarlama

Proje Doğrulama

XR Plug-in Management altındaki Project Validation öğesini seçin ve gerekli ayarları tamamlamak için Fix All düğmesine tıklayın (şimdilik işlem yapmadan bırakıp daha sonra elle de oluşturabilirsiniz), aşağıda gösterildiği gibi:

Project Validation'da Fix All düğmesine tıklama

Player Yapılandırması (Desktop Platformu)

Project Settings penceresinin solunda Player öğesini seçin, Desktop platformuna geçin, Other Settings bölümünü genişletin, Auto Graphics API seçeneğinin işaretini kaldırın, Graphics APIs sırasını Direct3D12, Vulkan, Direct3D11 olarak ayarlayın ve diğer grafik API'lerini kaldırın. Color Space değerini Gamma olarak ayarlayın, aşağıda gösterildiği gibi:

Desktop platformunda grafik API'lerini ve Gamma renk uzayını ayarlama

Not: Bazı VR cihazları Gamma renk uzayını desteklemez. Bu durumda yalnızca Linear renk uzayını seçebilirsiniz. Linear renk uzayında görüntülenen LCC sahneleri biraz soluk görünür.

Player Yapılandırması (Android Platformu)

Project Settings penceresinin solunda Player öğesini seçin, Android platformuna geçin, Other Settings bölümünü genişletin, Auto Graphics API seçeneğinin işaretini kaldırın, Graphics APIs değerini Vulkan olarak ayarlayın ve diğer grafik API'lerini kaldırın. Color Space değerini Gamma olarak ayarlayın, aşağıda gösterildiği gibi:

Android platformunda grafik API'sini Vulkan, renk uzayını Gamma olarak ayarlama

Android Platformu Komut Dosyası Arka Ucunu ve Girişi Ayarlama

Android platformunun Other Settings sekmesinde aşağı kaydırın ve Minimum API Level = Android 12L (API Level 32) veya üzeri, Scripting Backend = IL2CPP, Target Architectures = ARM64, Active Input Handling = Input System Package (New) veya Both olarak ayarlayın, aşağıda gösterildiği gibi:

Minimum API Level, Scripting Backend, Target Architectures ve Active Input Handling Ayarlarını Yapma

Grafik ve Kalite Ayarlarını Kontrol Etme

Project Settings penceresinin solundan Graphics öğesini seçin ve Mobile platformunun kullandığı Default Render Pipeline öğesine karşılık gelen Render Asset dosyasını kontrol edin. Bu örnekte bu dosya Mobile_RPAsset dosyasıdır:

Mobile Platformunda Default Render Pipeline Render Asset Dosyasını Kontrol Etme

Project Settings penceresinin solundan Quality öğesini seçin, Mobile platformunun kullandığı Default Render Pipeline öğesine karşılık gelen Render Asset dosyasını kontrol edin (bu örnekte Mobile_RPAsset). Ardından aşağıda gösterildiği gibi Resolution Scaling Fixed DPI Factor = 0.7, VSync Count = Don't Sync olarak ayarlayın:

Quality Ayarlarında DPI Factor ve VSync Değerlerini Ayarlama

Render Asset Dosyasını Yapılandırma

Mobile platformunun kullandığı Default Render Pipeline öğesine karşılık gelen Render Asset dosyasını bulun (bu örnekte Mobile_RPAsset), Asset'i seçin ve özellik penceresinde (Inspector) şunları yapın: Depth Texture, Opaque Texture, HDR seçeneklerinin işaretini kaldırın; Anti Aliasing (MSAA) = Disabled, Render Scale = 0.7, Upscaling Filter = Automatic olarak ayarlayın, aşağıda gösterildiği gibi:

Render Asset Dosyasında Depth/Opaque Texture, HDR ve MSAA Seçeneklerini Kapatma, Render Scale Değerini 0.7 Yapma

Bu Render Asset dosyasına karşılık gelen Renderer öğesini bulun. Bu örnekte bu öğe Mobile_Renderer (Universal Renderer Data) dosyasıdır. İlgili özelliklerini aşağıda gösterildiği gibi özellikler penceresinde (Inspector) ayarlayın:

Mobile_Renderer (Universal Renderer Data) Özelliklerini Yapılandırma

Adım 7: Sahneyi Oluşturma

Unity'de yepyeni bir sahne oluşturun, Main Camera ve Directional Light nesnelerini silin, hiyerarşi penceresinin (Hierarchy) boş bir alanına sağ tıklayın ve açılan menüden XR → XR Origin (VR) öğesini seçerek gerekli XR nesnelerini oluşturun.

Adım 8: Sahneyi Yapılandırma

Hiyerarşi penceresinde (Hierarchy) XR Origin (VR) GameObject'ini seçin ve özellik penceresinin (Inspector) XR Origin bileşeninde Tracking Origin Mode değerini Floor olarak ayarlayın. Diğer ilgili özellikler aşağıda gösterildiği gibidir:

XR Origin Tracking Origin Mode Değerini Floor Olarak Ayarlama

Hiyerarşi penceresinde (Hierarchy) XR Origin (VR) altındaki Main Camera GameObject'ini seçin ve özellik penceresinde (Inspector) Camera bileşeni özelliklerini ayarlayın: Clipping Planes Near = 0.3, Far = 5000; Anti-aliasing = No Anti-aliasing; Opaque Texture = Off, Depth Texture = Off; Background Type = Solid Color, Background = siyah; HDR = Off, MSAA = Off. Diğer özellikler aşağıda gösterildiği gibidir:

XR Origin (VR) altındaki Main Camera nesnesinin Camera bileşeni özelliklerini ayarlama

Adım 9: Sahneyi Yükleyecek Kodu Yazma

Hiyerarşi penceresinde (Hierarchy) sağ tıklayıp Create Empty seçeneğiyle boş bir nesne oluşturun, adını LCCManager yapın, Transform değerlerini sıfırlayın ve Add Component ile LCCManager betiğini ekleyin, aşağıda gösterildiği gibi:

LCCManager Boş Nesnesini Oluşturma ve LCCManager Betiğini Ekleme

Hiyerarşi penceresinde (Hierarchy) Create Empty seçeneğine sağ tıklayarak bir boş nesne daha oluşturun, adını LCCRenderer yapın ve Transform bileşeninde Rotation.x = -90, Scale.x = -1 olarak ayarlayın. Aşağıda gösterilmiştir:

LCCRenderer Boş Nesnesini Oluşturma ve Koordinat Sistemlerini Hizalamak İçin Rotation.x = -90, Scale.x = -1 Ayarlama

Rotation.x = -90 ve Scale.x = -1 değerleri, LCC veri koordinat sisteminden (Z yukarı, sağ elli) Unity koordinat sistemine (Y yukarı, sol elli) geçiş için kullanılan hizalama dönüşümüdür. Ayrıntılar için Unity SDK'ya Giriş sayfasındaki "LCC veri koordinat sistemi" bölümüne bakın.

Bu noktada hiyerarşi penceresindeki (Hierarchy) GameObject yapısı aşağıda gösterildiği gibidir:

Hierarchy penceresinin yapısı

Aşağıdaki kodla LCCRenderer.cs adında bir C# betiği yazın:

using LCCCore;
using UnityEngine;
using UnityEngine.XR;

public class LCCRenderer : MonoBehaviour
{
    public LCCManager m_manager;
    public string m_FilePath;

    private LCCCore.Renderer m_renderer;

    void Start()
    {
#if UNITY_EDITOR
        m_manager.SetPlatformType(PlatformType.PC);
        m_renderer = m_manager.GetRender(this.gameObject.transform);
        m_renderer.Load(m_FilePath, onProgress, onLoaded);
#else
        m_manager.SetPlatformType(PlatformType.OpenXR);
        m_renderer = m_manager.GetRender(this.gameObject.transform);
        m_renderer.Load($"{Application.persistentDataPath}/LccData/meta.lcc2", onProgress, onLoaded);
#endif
    }

    private void onProgress(float v)
    {
        Debug.Log("progress:" + v);
    }

    private void onLoaded()
    {
        m_manager.SetStartLod(2);
        m_renderer.SetEnvironment(false);
        Debug.Log("Data loaded");
    }
}

Betiği hiyerarşi penceresindeki (Hierarchy) LCCRenderer GameObject'ine ekleyin, ardından LCCManager GameObject'ini özellik penceresinde (Inspector) betiğin Manager özelliğine sürükleyin ve son olarak LCC dosya yolunu girin.

Unity Editor'de kolayca hata ayıklamak ve doğrudan bir Android cihaza derleme yapmak için kod, çalışma ortamını ayırt etmekte derleme makrolarını kullanır. Unity Editor'de doğrudan m_FilePath ile belirtilen adres kullanılır; Android cihazda ise cihaz üzerindeki veri kaynağı kullanılır. Cihaz üzerindeki verilerin yerleştirilme yöntemi şöyledir:

1. Derlenen uygulamayı VR cihazında bir kez çalıştırın.
2. Uygulama yüklendikten sonra veri dizinine girin (genellikle Device storage → Android → data → app BundleID → Files; belirli dizin için Android uygulama yükleme yoluna bakın) ve Files alt dizininin altında LccData adlı bir klasör oluşturun.
3. Tüm LCC veri kaynaklarını LccData klasörüne kopyalayın.

Not: Uygulamada veri kaynağını doğrudan uygulama paketine eklemek yerine bir sunucuya yerleştirmeniz önerilir.

Optimizasyon Uygulamaları

Yukarıdaki adımlar LCC verilerinin VR cihazında normal şekilde görüntülenmesini sağlar, ancak iki temel sorun vardır:

2D Uygulama Penceresi Görünümü

Cihaz üreticisinin SDK'sı olmadan OpenXR standardına göre geliştirilen uygulamalar, VR cihazlarında her zaman 3D uygulama olarak tanınmaz. VR cihaz sistemi bunları genellikle 2D uygulama olarak ele alır ve 2D uygulama penceresi görüntülenir. Bu sorunu çözmek için iki yöntem vardır:

• Cihaz üreticisinin SDK'sını veya OpenXR uzantısını projeye ekleyin. Bu durumda ilgili sorunları cihaz üreticisinin yazılımı yönetir.
• AndroidManifest.xml dosyasını özelleştirin.

Manifest dosyasını özelleştirme adımları şöyledir: Project Settings penceresinin solunda Player öğesini seçin, Android platformuna geçin, Publishing Settings bölümünü genişletin ve Custom Main Manifest seçeneğini işaretleyin. Bu işlem özel bir Manifest dosyası oluşturur (aşağıda gösterilmiştir):

Özel bir Manifest dosyası oluşturmak için Custom Main Manifest seçeneğini işaretleyin

AndroidManifest.xml dosyasını bulun ve VR işaretini ekleyin. Böylece VR cihazı uygulamayı 3D sürükleyici uygulama olarak tanır ve başlatılan uygulama 3D alanda görüntülenir. Örnek:

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <application>

        <!--Used when Application Entry is set to GameActivity, otherwise remove this activity block-->
        <activity android:name="com.unity3d.player.UnityPlayerGameActivity"
                  android:theme="@style/BaseUnityGameActivityTheme"
                  android:resizeableActivity="false">
            <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>
            <meta-data android:name="unityplayer.UnityActivity" android:value="true" />
            <meta-data android:name="android.app.lib_name" android:value="game" />
        </activity>
    </application>
</manifest>

Görüntüleme kare hızı 90FPS'in altına düştüğünde takılma

OpenXR standardı kare ara değerleme, yumuşatma gibi konuları tanımlamaz. Kare hızı 90FPS'e ulaşamadığında baş çevrilirken veya hareket edilirken belirgin bir takılma hissedilir. Özellikle sınırlı donanım performansında akıcılığı artırarak daha iyi bir deneyim sunmak için cihaz üreticileri genellikle ara kare oluşturma, kare ara değerleme ve yumuşatma gibi teknikler sağlar. Örnekler: ATW (Asynchronous Time Warp), PTW (Late Stage Reprojection).

Cihaz OpenXR'ı destekliyorsa cihaz üreticileri genellikle bir OpenXR uzantısı veya OpenXR'ı doğrudan destekleyen bir SDK sunar. Bu durumda daha akıcı bir deneyim için cihaz üreticisinin SDK'sını projeye eklemeniz en iyisidir.

İlgili Kaynaklar

• Proje ayarları ve performans optimizasyonu için Proje Ayarları Optimizasyon Kılavuzu ve Görüntüleme Performans Parametreleri Kılavuzu bölümlerine bakın.
• VR cihazının cihaz üzerinde 3DGS görüntüleme kapasitesi yaklaşık 700.000 Gauss primitifidir. Büyük sahneleri görüntülerken StartLOD değerini 2 olarak ayarlamanız ve ortam verisi görüntülemeyi kapatmanız önerilir. Büyük sahneler PC akışıyla daha akıcı çalışır.