在應用程式中自訂 3D 模型

適用的 XR 裝置
這份指南可協助您為這類 XR 裝置打造體驗。
瞭解 XR 裝置類型 →
XR 頭戴式裝置
有線 XR 眼鏡
瞭解 XR 裝置類型 →

在應用程式中加入 3D 模型後，即可自訂模型，提升視覺和互動體驗。舉例來說，您可以播放及控制內嵌的 glTF 動畫、定義自訂材質屬性 (例如基底顏色或金屬粗糙度)，以及將自訂紋理套用至 3D 模型。這些功能可讓您在執行階段動態變更物件的外觀和行為。

為 3D 模型製作動畫

根據 glTF 規格，3D 模型可以內嵌動畫。 Jetpack XR SDK 支援骨架 (綁定)、剛性及變形目標 (混合形狀) 動畫。系統也支援使用 KHR_animation_pointer glTF 擴充功能建立的 Material 動畫。

如要播放動畫，請從 animations 清單中指定特定軌道的名稱。撥打電話 GltfAnimation.start()即可開始播放。您可以選擇使用 GltfAnimationStartOptions 指定速度、搜尋時間，以及動畫是否應循環播放。

val animation = gltfEntity.animations.find { it.name == "Walk" }
animation?.start(GltfAnimationStartOptions(shouldLoop = true))

您也可以使用 pause()、resume() 和 stop() 動畫，以及使用 seekTo() 跳至動畫軌中的特定時間。如要查詢動畫的目前狀態，請使用 GltfAnimation.AnimationState。

自訂 3D 模型的材質屬性

Jetpack XR 的材質系統是以 glTF™ 2.0 規格為基礎，並使用以物理為基礎的算繪 (PBR) 算繪 3D 模型。您可以在執行階段調整材質屬性，根據使用者輸入內容或應用程式的目前狀態，動態變更物件的外觀。

Material 會定義物件表面的視覺屬性集，並決定該表面在場景中與光線的互動方式。

在 Jetpack XR 中，KhronosPbrMaterial 和 KhronosUnlitMaterial 類別用於建立及操控這些材質。顧名思義，KhronosUnlitMaterials 不會發光，也不會受到場景照明影響。KhronosPbrMaterial 可自訂更多屬性，例如光澤顏色、物件金屬感或粗糙程度，以及是否發光。

如要進一步瞭解 Android XR 中支援的各項屬性，以及可自訂的參數，請參閱參考文件。如要進一步瞭解這些屬性，請參閱 Khronos 詞彙表。

變更 3D 模型底色的範例

如要自訂 3D 模型的材質屬性，請先使用 KhronosPbrMaterial 建立新材質。您必須為要達成的視覺效果設定適當的 AlphaMode：

val pbrMaterial = KhronosPbrMaterial.create(
    session = xrSession,
    alphaMode = AlphaMode.OPAQUE
)

接著定義要修改的屬性。在本範例中，我們使用 setBaseColorFactor 變更基本顏色。這個方法需要 Vector4，其中 x、y、z 和 w 元件分別對應至 RGBA (紅、綠、藍和 Alpha) 值：

pbrMaterial.setBaseColorFactor(
    Vector4(
        x = 0.5f,
        y = 0.0f,
        z = 0.5f,
        w = 1.0f
    )
)

為 3D 模型建立自訂紋理

Texture 是可套用至 3D 模型表面的圖片素材資源，可提供顏色、細節或其他表面資訊。Jetpack XR Texture API 可讓您從應用程式的 /assets/ 資料夾非同步載入圖片資料，例如 PNG 檔案。

載入紋理時，您可以指定 TextureSampler，藉此控制紋理的算繪方式。取樣器會定義篩選屬性 (紋理小於或大於原始大小時) 和包裝模式 (用於處理標準 [0, 1] 範圍外的座標)。Texture 物件本身只是資料，必須指派給 Material，才能對 3D 模型產生視覺效果。

變更 3D 模型紋理的範例

如要建立自訂材質，請先將圖片檔儲存到 /assets/ 資料夾。最佳做法是在該資料夾中建立子目錄。textures

將檔案儲存到適當的目錄後，請使用 Texture API 建立紋理。如有需要，您也可以在此套用選用的 TextureSampler：

val texture = Texture.create(
    session = xrSession,
    path = Path("textures/texture_file.png")
)

接著定義紋理類型，並設定對應的參數。在本範例中，我們會套用遮蔽紋理並設定強度：

pbrMaterial.setOcclusionTexture(
    texture = texture,
    strength = 1.0f
)

為 3D 物件套用材質和紋理

如要套用新材質或紋理，請覆寫 glTF 節點上特定節點的現有材質。方法是在 GltfModelNode 上呼叫 setMaterialOverride：

gltfModelNode.setMaterialOverride(
    material = pbrMaterial
)

如要移除新建立的材質，請在先前覆寫的 GltfModelNode 節點上呼叫 clearMaterialOverride。這會將 3D 模型還原為預設狀態：

gltfModelNode.clearMaterialOverride()

glTF 和 glTF 標誌是 Khronos Group Inc. 的商標。