XGRIDS文檔

OpenXR 開發指南

OpenXR 是一個由 Khronos Group 制定並維護的開放、免版稅的 XR（VR/AR/MR）接口標準，核心目標是讓開發者「一次編寫，隨處運行」，解決過去不同設備各搞一套 API 的碎片化問題。LCC Unity SDK 現已支持 OpenXR 標準，無需特定 VR 設備廠商提供的 SDK，即可在支持 OpenXR 的設備上渲染 3DGS 數據。

版本要求

本指南使用的軟件及插件版本如下，建議使用相同版本開發，其他未經測試的版本可能存在兼容問題：

軟件 / 插件版本
Unityv6000.0.69f1
LCC Unity SDKv2.3.0 及以上

注意：

  1. OpenXR 是一個標準，各 VR 設備廠商可能支持其全部特性，也可能只支持一部分，因此使用前需要先查閱特定設備的支持情況。
  2. OpenXR 標準定義了通用的技術規範，但各廠商設備的特定特性仍需廠商 SDK 或廠商 OpenXR Extension 擴展支持，例如 ATW（Asynchronous Time Warp，異步時間扭曲）、PTW（Late Stage Reprojection，晚期階段重投影）等提高幀間平滑度的技術。
  3. 本指南主要演示 VR 設備真機的 OpenXR 開發，LCC Unity SDK 不支持 OpenXR 桌面端應用開發（除PCVR）。

開發流程

步驟 1：創建 URP 工程

在工程模板中選擇 Universal 3D（URP 渲染管線）類型，如下圖所示：

創建 Universal 3D 工程

創建 Universal 3D 工程

步驟 2：切換平台

工程創建完成後，在 Unity 菜單中選擇 File → Build Profiles 打開應用構建窗口，將平台切換為 Android，如下圖所示：

在 Build Profiles 中將平台切換為 Android

在 Build Profiles 中將平台切換為 Android

步驟 3：導入 Unity OpenXR

通過 Unity 菜單 Window → Package Manager 打開 UPM 窗口，在左側列表中選擇 Unity Registry，在搜索框中輸入 OpenXR，從檢索列表中選擇 OpenXR Plugin 並安裝，如下圖所示：

從 Unity Registry 安裝 OpenXR Plugin

從 Unity Registry 安裝 OpenXR Plugin

步驟 4：導入 XR Interaction Toolkit

在左側列表中選擇 Unity Registry，在搜索框中輸入 XR，從檢索列表中選擇 XR Interaction Toolkit 並安裝，如下圖所示：

從 Unity Registry 安裝 XR Interaction Toolkit

從 Unity Registry 安裝 XR Interaction Toolkit

步驟 5：導入 LCC Unity SDK

通過 Unity 菜單 Window → Package Manager 打開 UPM 窗口，單擊左側 ＋，在下拉菜單中選擇 Install package from disk，定位到 LCC Unity SDK，選擇 package.json 文件導入，如下圖所示：

通過 Install package from disk 導入 LCC Unity SDK

通過 Install package from disk 導入 LCC Unity SDK

步驟 6：設置 Unity 環境

配置 XR Plug-in Management（Android 平台）

在 Unity 菜單欄中選擇 File → Project Settings，在左側選擇 XR Plug-in Management，在 Android 平台選項卡下勾選 OpenXR，並勾選 Initialize XR on Startup，如下圖所示：

在 Android 平台勾選 OpenXR 與 Initialize XR on Startup

在 Android 平台勾選 OpenXR 與 Initialize XR on Startup

配置 XR Plug-in Management（Desktop 平台）

由於 LCC Unity SDK 不支持桌面端 OpenXR 開發，在 Desktop 平台下不勾選 OpenXR，也不勾選 Initialize XR on Startup，如下圖所示：

在 Desktop 平台不勾選 OpenXR 與 Initialize XR on Startup

在 Desktop 平台不勾選 OpenXR 與 Initialize XR on Startup

注意：桌面端PCVR請參考 PCVR串流。

配置 OpenXR 渲染模式與交互配置

選擇 XR Plug-in Management 下的 OpenXR 項，將 Android 平台的 Render Mode 設為 Single Pass Instanced 或 Multi-View。由於 OpenXR 必須設置 Interaction Profiles，通常選擇 Oculus Touch Controller Profile 或與設備性能特性相近的 Profile，如下圖所示：

設置 OpenXR 的 Render Mode 與 Interaction Profiles

設置 OpenXR 的 Render Mode 與 Interaction Profiles

Project Validation

選擇 XR Plug-in Management 下的 Project Validation 項，點擊 Fix All 完成必要設置（也可以先不處理，後續手動創建），如下圖所示：

在 Project Validation 中點擊 Fix All

在 Project Validation 中點擊 Fix All

設置 Player（Desktop 平台）

在 Project Settings 左側選中 Player，切換到 Desktop 平台，展開 Other Settings 卷展欄，取消勾選 Auto Graphics API，將 Graphics APIs 設為 Direct3D12、Vulkan、Direct3D11，並移除其它圖形 API；將 Color Space 設為 Gamma，如下圖所示：

Desktop 平台設置圖形 API 與 Gamma 顏色空間

Desktop 平台設置圖形 API 與 Gamma 顏色空間

注意：有的 VR 設備不支持 Gamma 顏色空間，此時只能選擇 Linear 線性顏色空間，LCC 場景在 Linear 顏色空間下渲染顏色會略微發白。

設置 Player（Android 平台）

在 Project Settings 左側選中 Player，切換到 Android 平台，展開 Other Settings 卷展欄，取消勾選 Auto Graphics API，將 Graphics APIs 設為 Vulkan，並移除其它圖形 API；將 Color Space 設為 Gamma，如下圖所示：

Android 平台設置圖形 API 為 Vulkan 與 Gamma 顏色空間

Android 平台設置圖形 API 為 Vulkan 與 Gamma 顏色空間

設置 Android 平台腳本後端與輸入

在 Android 平台的 Other Settings 選項卡中向下滑動，設置 Minimum API Level = Android 12L (API Level 32) 及以上、Scripting Backend = IL2CPP、Target Architectures = ARM64、Active Input Handling = Input System Package (New) 或 Both，如下圖所示：

設置 Minimum API Level、Scripting Backend、Target Architectures 與 Active Input Handling

設置 Minimum API Level、Scripting Backend、Target Architectures 與 Active Input Handling

檢查 Graphics 與 Quality

在 Project Settings 左側選中 Graphics 項，查看 Mobile 平台所使用的 Default Render Pipeline 對應的 Render Asset，本示例中為 Mobile_RPAsset，如下圖所示：

查看 Mobile 平台的 Default Render Pipeline Render Asset

查看 Mobile 平台的 Default Render Pipeline Render Asset

在 Project Settings 左側選中 Quality 項，查看 Mobile 平台所使用的 Default Render Pipeline 對應的 Render Asset（本示例中為 Mobile_RPAsset），設置 Resolution Scaling Fixed DPI Factor = 0.7、VSync Count = Don't Sync，如下圖所示：

在 Quality 中設置 DPI Factor 與垂直同步

在 Quality 中設置 DPI Factor 與垂直同步

配置 Render Asset

找到 Mobile 平台所使用的 Default Render Pipeline 對應的 Render Asset（本示例中為 Mobile_RPAsset），選中該 Asset，在屬性窗口（Inspector）中：取消勾選 Depth Texture、Opaque Texture、HDR，設置 Anti Aliasing (MSAA) = Disabled、Render Scale = 0.7、Upscaling Filter = Automatic，如下圖所示：

在 Render Asset 中關閉 Depth/Opaque Texture、HDR、MSAA 並設置超分

在 Render Asset 中關閉 Depth/Opaque Texture、HDR、MSAA 並設置 Render Scale = 0.7

找到該 Render Asset 的配套 Renderer，本示例中為 Mobile_Renderer（Universal Renderer Data），在屬性窗口（Inspector）中設置其相關屬性，如下圖所示：

配置 Mobile_Renderer（Universal Renderer Data）屬性

配置 Mobile_Renderer（Universal Renderer Data）屬性

步驟 7：創建場景

在 Unity 中創建一個全新的場景，刪除 Main Camera 和 Directional Light，在層級窗口（Hierarchy）空白處單擊鼠標右鍵，在彈出菜單中選擇 XR → XR Origin (VR)，創建必要的 XR 對象。

步驟 8：配置場景

在層級窗口（Hierarchy）中選中 XR Origin (VR) 遊戲對象，在屬性窗口（Inspector）的 XR Origin 組件中，將 Tracking Origin Mode 設為 Floor，其他相關屬性如下圖所示：

將 XR Origin 的 Tracking Origin Mode 設為 Floor

將 XR Origin 的 Tracking Origin Mode 設為 Floor

在層級窗口（Hierarchy）中選中 XR Origin (VR) 下的 Main Camera 遊戲對象，在屬性窗口（Inspector）中設置 Camera 組件相關屬性：Clipping Planes Near = 0.3、Far = 5000；Anti-aliasing = No Anti-aliasing；Opaque Texture = Off、Depth Texture = Off；Background Type = Solid Color、Background = 黑色；HDR = Off、MSAA = Off，其他屬性如下圖所示：

設置 XR Origin (VR) 下 Main Camera 的 Camera 組件屬性

設置 XR Origin (VR) 下 Main Camera 的 Camera 組件屬性

步驟 9：編寫代碼，加載場景

在層級窗口（Hierarchy）中右鍵 Create Empty 創建一個空對象，命名為 LCCManager，將其 Transform 歸一，並通過 Add Component 為其掛載 LCCManager 腳本，如下圖所示：

創建 LCCManager 空對象並掛載 LCCManager 腳本

創建 LCCManager 空對象並掛載 LCCManager 腳本

在層級窗口（Hierarchy）中右鍵 Create Empty 創建另一個空對象，命名為 LCCRenderer，將其 Transform 設置 Rotation.x = -90、Scale.x = -1，如下圖所示：

創建 LCCRenderer 空對象並設置座標系對齊的 Transform

創建 LCCRenderer 空對象，設置 Rotation.x = -90、Scale.x = -1 以對齊座標系

Rotation.x = -90、Scale.x = -1 是 LCC 數據座標系（Z-up 右手）到 Unity 座標系（Y-up 左手）的對齊變換，詳見 Unity SDK 簡介 中的「LCC 數據座標系」。

此時層級窗口（Hierarchy）中的遊戲對象結構如下圖所示：

Hierarchy 窗口的結構

Hierarchy 窗口的結構

編寫一個 C# 腳本，命名為 LCCRenderer.cs，代碼如下：

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");
    }
}

將該腳本掛載到層級窗口（Hierarchy）中的 LCCRenderer 遊戲對象上，然後在屬性窗口（Inspector）中將 LCCManager 遊戲對象拖到腳本的 Manager 屬性上，最後填寫 LCC 文件的路徑地址。

為方便在 Unity Editor 中調試並直接打包到 Android 真機設備，代碼使用編譯宏區分運行環境：在 Unity Editor 中直接使用 m_FilePath 指定的地址；在 Android 設備上則使用設備本地的數據源。設備端數據的放置方式為：

  1. 先將打包好的應用在 VR 設備上運行一次。
  2. 應用安裝後，進入其數據目錄（一般為 設備存儲盤 → Android → data → 應用 BundleID → Files，具體目錄可查閱 Android 應用安裝路徑），在 Files 子目錄下創建 LccData 文件夾。
  3. 將 LCC 數據源全部拷貝到 LccData 文件夾下。

注意：實際使用中，建議將應用的數據源放在服務器上，而不是直接打包進應用。

優化實踐

按上述步驟可以在 VR 設備上正常渲染 LCC 數據，但會存在以下兩個主要問題：

2D 應用窗口顯示

按 OpenXR 標準開發且未引入設備廠商 SDK 的應用，在 VR 設備上不一定會被識別為 3D 應用，通常 VR 設備系統會將其看作 2D 應用，因此會顯示 2D 應用窗口。解決這個問題有兩個思路：

  • 引入設備廠商的 SDK 或設備廠商 OpenXR 擴展，此時設備廠商軟件會處理相關問題。
  • 自定義 AndroidManifest.xml。

自定義 Manifest 的具體操作為：在 Project Settings 左側選中 Player，切換到 Android 平台，展開 Publishing Settings 卷展欄，勾選 Custom Main Manifest，此時會生成自定義 Manifest 文件，如下圖所示：

勾選 Custom Main Manifest 生成自定義 Manifest 文件

勾選 Custom Main Manifest 生成自定義 Manifest 文件

找到 AndroidManifest.xml 文件，添加 VR 標識，讓 VR 設備識別這是一個 3D 沉浸式應用，啟動的應用將以 3D 空間的形式展示，示例如下：

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

渲染幀率不足 90FPS 的卡頓

OpenXR 標準本身並沒有定義插幀、平滑等相關內容，當幀率達不到 90FPS 時，旋轉頭部或移動時會有明顯的卡頓感。各設備廠商為了更好的體驗，特別是在有限的硬件性能條件下提高流暢度，通常會提供補間、插幀、平滑等技術，如 ATW（Asynchronous Time Warp，異步時間扭曲）、PTW（Late Stage Reprojection，晚期階段重投影）等。

如果設備支持 OpenXR，設備廠商通常都會提供 OpenXR Extension 擴展或直接支持 OpenXR 的 SDK，此時最好引入設備廠商 SDK，以獲得更流暢的體驗。

相關參考

  • 工程項目與性能優化，請參見工程設置優化指南、渲染性能參數設置指南 章節。
  • VR 設備端 3DGS 同屏渲染能力約為 70 萬高斯基元，渲染大場景時建議將 StartLOD 設為 2 並關閉環境數據顯示；大場景使用 PC 串流會更流暢。