遷移指南(nán)
雙渲染融合遷移指南(nán)
從 Snapdragon Spaces 版本 0.23.0 開始，雙渲染融合不再作爲單獨的(de) tarball 包提供。現在，樣本和(hé)插件組件已包含在 Snapdragon SDK 包中。請參考設置指南(nán)，了(le)解如何将樣本引入新項目或使用(yòng)舊(jiù)版雙渲染融合的(de)項目中。
遷移步驟
1、如果項目使用(yòng)的(de)是 0.13.0 至 0.19.1 版本中的(de)預制件，請确保這(zhè)些預制件已解包，并且不是樣本文件夾中預制件的(de)變體。
2、如果項目中已經導入了(le)樣本，請删除雙渲染融合樣本文件夾。
3、将新的(de) Snapdragon Spaces SDK 版本導入到現有項目中。
4、按照(zhào)設置指南(nán)中的(de)“導入樣本”部分(fēn)，導入新的(de)雙渲染融合樣本。
5、參考設置指南(nán)，添加場(chǎng)景中可(kě)能缺少的(de)組件，并特别關注故障排除部分(fēn)。
版本差異
| 0.13.0 至 0.19.1 版本 | 0.23.0 及以後版本 | |
| 屏幕方向 | Lifecycle.cs | FusionScreenSetup.cs |
| 場(chǎng)景邏輯功能（退出、切換或切換場(chǎng)景） | Lifecycle.cs | FusionSceneManager.cs |
| 自動啓動 XR 和(hé)管理(lǐ) XR 相機 | DynamicOpenXRLoader.cs | DynamicOpenXRLoader |
| OpenXR 生命周期事件 | DynamicOpenXRLoader.cs | FusionLifecycleEvents.cs |
| Spaces Glass 狀态 | - | SpacesGlassStatus.cs |
| Fusion Editor Simulator 組件 | FusionLogic.cs | FusionSimulator.cs |
版本0.13.0到0.21.0
舊(jiù)版本雙渲染融合
免責聲明(míng)
前提條件
安裝 Unity 編輯器時(shí)，必須添加 Android Build Support 模塊，以便能夠導出 .apk 文件。該模塊也(yě)可(kě)以在安裝後通(tōng)過 Unity Hub 添加。
開始新的(de) 3D Unity 項目
創建一個(gè)新的(de) 3D（或 3D URP）Unity 項目，或使用(yòng)現有的(de) Unity 項目。
導入 Snapdragon Spaces 包
Snapdragon Spaces for Unity SDK 以 tarball 文件形式提供。
請按照(zhào) Unity 的(de)說明(míng)，通(tōng)過 Unity 包管理(lǐ)器将 tarball (.tgz) 文件導入到項目中。該文件位于 Unity 包文件夾中。
| 注意！ 導入包後，Unity 可(kě)能會彈出提示以啓用(yòng)新的(de)輸入系統。點擊“是”以确保 OpenXR 和(hé) XR Interaction Toolkit 包的(de)完整功能。如果還(hái)需要使用(yòng)舊(jiù)的(de)輸入系統，可(kě)以在 Player > Other Settings > Configuration 中将 Active Input Handling 設置爲“Both”。 |
導入雙渲染融合包
在 Snapdragon Spaces SDK for Unity 版本 0.13.0 到 0.21.0 之間，雙渲染融合公測版作爲實驗性包提供。啓用(yòng)此功能的(de)文件以單獨的(de) Unity 包 tarball 形式提供，您可(kě)以在 Snapdragon Spaces for Unity SDK 下(xià)載頁面找到。
請按照(zhào) Unity 的(de)說明(míng)，通(tōng)過 Unity 包管理(lǐ)器将 tarball (.tgz) 文件導入項目。該文件可(kě)以在雙渲染融合包下(xià)載頁面找到。
建議(yì)同時(shí)通(tōng)過包管理(lǐ)器導入 Fusion Samples 示例包。
更改項目設置
要啓用(yòng) Snapdragon Spaces OpenXR 插件，請進入 Edit > Project Settings > XR Plug-in Management 下(xià)的(de)項目設置，打開 Android 标簽頁。
勾選 OpenXR 插件，但暫時(shí)不要勾選 Snapdragon Spaces 功能組。
接著(zhe)，點擊 OpenXR 菜單項以顯示不同的(de) OpenXR 功能選項。注意新的(de)“雙渲染融合功能”，勾選 Base Runtime Feature 和(hé) Dual Render Fusion Feature。點擊 Dual Render Fusion 旁邊的(de)紅色感歎号，以打開項目驗證器。
項目驗證器将顯示多(duō)個(gè)修複選項，用(yòng)于更新 Unity 項目和(hé)當前打開的(de)場(chǎng)景，因此請确保在項目中打開了(le)正确的(de)場(chǎng)景。
雙渲染融合功能驗證器
請注意驗證器中前綴爲 [Dual Render Fusion (Experimental)] 的(de)選項。應該首先解決這(zhè)些問題，以更新項目和(hé)當前場(chǎng)景，然後再選擇“全部修複”來(lái)處理(lǐ)項目中的(de)其他(tā)問題。（這(zhè)是因爲雙渲染融合的(de)驗證器選項可(kě)以解決一些其他(tā)默認的(de) Spaces 驗證器問題。）
完成雙渲染融合驗證後，點擊剩餘條目旁邊的(de)修複按鈕，以應用(yòng)所需的(de)項目設置。一些修複可(kě)能需要重新啓動編輯器，這(zhè)是正常的(de)。
此時(shí)，雙渲染融合應該已經正确啓用(yòng)，可(kě)以進行啓動。有關更多(duō)信息和(hé)高(gāo)級配置功能，請參見下(xià)文。
配置雙渲染融合設置
雙渲染融合功能的(de)可(kě)用(yòng)設置包括
1、驗證打開的(de)場(chǎng)景：啓用(yòng)此設置時(shí)，Unity 場(chǎng)景驗證器将檢查當前打開的(de)場(chǎng)景中是否正确配置了(le) XR 相機和(hé)智能手機相機。如果項目的(de)構建系統沒有完整的(de)功能場(chǎng)景（如附加場(chǎng)景），請禁用(yòng)此設置，以避免構建阻塞。
雙渲染融合示例
通(tōng)過包管理(lǐ)器可(kě)以獲取一系列示例場(chǎng)景和(hé)代碼腳本：
1、Controller Prefab Sample Scene：這(zhè)是一個(gè)示例場(chǎng)景，用(yòng)于将 Android Companion Controller 适配到 Unity Prefab 中，并完全控制設置和(hé)退出按鈕。有關更多(duō)詳細信息，請參見下(xià)文的(de) Companion Controller 部分(fēn)。
2、CubeManipulation：一個(gè)簡單的(de)場(chǎng)景，包含一個(gè)立方體，可(kě)以通(tōng)過一個(gè)、兩個(gè)或三個(gè)手指在觸控闆上移動，用(yòng)于創建響應式多(duō)點觸控界面。
3、LandscapeUISampleScene：一個(gè)簡單的(de)場(chǎng)景，包含一個(gè)橫向畫(huà)布，其中包含可(kě)交互的(de) UI 元素，用(yòng)于操作立方體。
4、OpenXRLoadingTest：一個(gè)演示如何在智能手機上立即啓動應用(yòng)程序，并在與眼鏡建立連接後啓用(yòng) OpenXR 的(de)場(chǎng)景。有關更多(duō)詳細信息，請參見下(xià)文的(de) Dynamic OpenXR Loader 部分(fēn)。
5、PortraitUISampleScene：一個(gè)簡單的(de)場(chǎng)景，包含一個(gè)縱向畫(huà)布，其中包含可(kě)交互的(de) UI 元素。
伴侶控制器
有些開發者可(kě)能希望将現有的(de) Snapdragon Spaces 項目遷移到雙渲染融合，并利用(yòng)伴侶控制器的(de)陀螺儀 3DOF 指向功能。請按照(zhào)以下(xià)步驟将其添加到項目中：
要在 Unity 中複制伴侶控制器，需要一些資産和(hé)腳本。
1、如果需要，請按照(zhào)提示導入 TextMeshPro。
2、将 CanvasControllerCompanion Prefab 從示例中拖到層級視圖中。
3、由于 Prefab 中不包含 XR 相機，需要将兩個(gè) GameObject 連接到 XR 相機。如果沒有設置，這(zhè)些對(duì)象會自動檢測 XR Origin 或 AR Session Origin 以使用(yòng)附加的(de)相機。也(yě)可(kě)以手動設置：
在 ControllerPositionHeadMirror 中設置 Ar Camera 字段。
在 GyroRotationReceiver 中設置 Ar Camera 字段。
确保将輸入系統設置爲“Both”，以啓用(yòng)陀螺儀控制。
5、将 ControllerPrefabInputActions 作爲附加的(de) Action Asset 添加到 Input Action Manager 中。如果層級視圖中沒有 Input Action Manager，請創建一個(gè) GameObject 并添加該組件。
6、要使用(yòng)菜單按鈕功能，可(kě)以直接使用(yòng)标準的(de) Unity 輸入系統，并在層級視圖中的(de)菜單按鈕對(duì)象上添加 On Click() 事件。
7、要在設置菜單中添加更多(duō)選項，請暫時(shí)啓用(yòng)“Settings Overlay” GameObject，并将菜單項添加到“Scroll Box”列表中。（目前，“About”按鈕沒有功能，僅作爲示例存在。）
動态 OpenXR 加載器
動态 OpenXR 加載器是一個(gè)實驗性示例腳本，允許應用(yòng)程序在眼鏡連接後加載 OpenXR，類似于耳機的(de)工作方式。此腳本會檢測第二個(gè)顯示器的(de)存在，并在配置時(shí)啓動 OpenXR。提供了(le)多(duō)個(gè)回調函數，用(yòng)于控制 OpenXR 開始連接時(shí)用(yòng)戶界面的(de)行爲。有關如何使用(yòng)此腳本的(de)示例，請參見 OpenXRLoadingTest 示例。
| 注意事項！ 1、目前不建議(yì)在啓用(yòng)手部跟蹤功能的(de)應用(yòng)程序中使用(yòng)此功能，由于動态 OpenXR 加載器與手部跟蹤功能存在并發兼容性問題，使用(yòng)此功能在應用(yòng)程序初始化(huà)過程之外啓動 OpenXR 可(kě)能會導緻應用(yòng)程序在嘗試加載時(shí)突然退出。此問題将在未來(lái)版本中修複。 2、當 OpenXR 開始連接時(shí)，主線程會短暫阻塞。建議(yì)顯示一些用(yòng)戶界面元素，以提示 OpenXR 正在連接，并在加載完成後顯示确認狀态。 |
功能驗證配置
雙渲染融合功能驗證器用(yòng)于輕松配置 Unity 項目和(hé)所選場(chǎng)景，以啓用(yòng)雙渲染融合。以下(xià)是驗證列表。
| 範圍 | 驗證項 | 描述 | 原因 |
| 項目 | 禁用(yòng)自定義啓動器 | 禁用(yòng)“Base Runtime Feature”中的(de)“Launch on Viewer”和(hé)“Launch Controller on Host”複選框 | 雙渲染融合需要禁用(yòng)自定義啓動器功能（參見頭戴式架構） |
| 場(chǎng)景 | 需要 AR 會話(huà)原點 | 确保場(chǎng)景中有 AR 會話(huà)原點（或 XR 原點）以及相關的(de) XR 攝像頭 | AR Foundation 需要一個(gè) XR 攝像頭 |
| 場(chǎng)景 | 需要 AR 會話(huà) | 确保場(chǎng)景中有 AR 會話(huà)和(hé) AR 輸入管理(lǐ)器 | AR Foundation 需要一個(gè) AR 會話(huà) |
| 場(chǎng)景 | 需要移動攝像頭 | 确保場(chǎng)景中有一個(gè)表示移動設備屏幕的(de) Unity 攝像頭 | 雙渲染融合需要一個(gè)移動顯示器進行渲染 |
| 場(chǎng)景 | 主攝像頭标簽 | 确保隻有 XR 攝像頭或其他(tā)非紋理(lǐ)渲染的(de)攝像頭被标記爲“主攝像頭”，而不是兩個(gè)都标記 | 如果有兩個(gè)攝像頭被标記爲“主攝像頭”，可(kě)能會導緻渲染錯誤或幹擾其他(tā)依賴項 |
| 場(chǎng)景 | 攝像頭渲染優先級 | 确保移動攝像頭的(de)渲染在 XR 攝像頭之後進行 | 如果 XR 攝像頭在移動攝像頭之前渲染，移動顯示器可(kě)能會被 XR 攝像頭的(de)圖像覆蓋 |
| 場(chǎng)景 | 攝像頭視角目标 | 确保 XR 攝像頭的(de)視角目标設置爲“Both”，而其他(tā)所有攝像頭設置爲“None” | 攝像頭視角目标決定了(le)每個(gè)攝像頭将渲染到哪個(gè)顯示器上 |
| 場(chǎng)景 | 移動攝像頭視角目标（URP） | 顯示警告，提醒檢查移動攝像頭的(de)視角目标是否設置爲“None” | URP 不能像内置渲染管線那樣程序化(huà)地設置視角目标，因此需要手動檢查 |
| 場(chǎng)景 | 攝像頭顯示目标 | 如果 XR 攝像頭的(de)目标顯示器不是顯示器 1，則建議(yì)添加一個(gè) Fusion Logic GameObject 和(hé)組件 | 爲了(le)使雙渲染融合能夠正确地渲染到兩個(gè)設備，兩個(gè)顯示目标必須設置爲顯示器 1。XR 攝像頭默認設置爲目标顯示器 2，而“Fusion Logic”會在運行時(shí)将目标設置爲正确的(de)顯示器 |
| 場(chǎng)景 | 音(yīn)頻(pín)監聽(tīng)器 | 如果場(chǎng)景中有多(duō)個(gè)音(yīn)頻(pín)監聽(tīng)器，建議(yì)關閉其中一個(gè) | 多(duō)個(gè)音(yīn)頻(pín)監聽(tīng)器同時(shí)存在會導緻 Unity 出現問題 |
| 場(chǎng)景 | 事件系統要求 | 如果場(chǎng)景中沒有事件系統，則需要添加一個(gè)事件系統和(hé)默認輸入模塊 | 這(zhè)是爲了(le)确保觸控 UI 能夠正确處理(lǐ) |
應用(yòng)程序在後台運行
雙渲染融合架構的(de)一個(gè)缺點是，應用(yòng)程序不能像頭戴式架構那樣在後台運行，同時(shí)其他(tā)應用(yòng)程序在前台運行。可(kě)以通(tōng)過使用(yòng) Android 的(de)畫(huà)中畫(huà)模式來(lái)克服這(zhè)一限制，這(zhè)種方式利用(yòng)了(le)标準的(de) Android 架構選項。
北京米浴科技有限公司
