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

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

將 3D 模型新增至應用程式後，您可以定義自訂材質屬性，並將紋理套用至物件，提升視覺體驗。Jetpack XR 的材質系統是以 glTF™ 2.0 規格為基礎，並使用以物理為基礎的算繪 (PBR) 算繪 3D 模型。這些開放式標準由 Khronos Group 維護。

您可以在執行階段調整材質屬性，根據使用者輸入內容或應用程式的目前狀態，動態變更物件外觀。

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

自訂 3D 模型的材質屬性

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

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

變更 3D 模型底色的範例

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

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

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

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

為 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")
)
MaterialOverride.kt

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

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

將材質和紋理套用至 3D 物件

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

gltfModelEntity.setMaterialOverride(
    material = pbrMaterial,
    nodeName = "Node Name"
)
MaterialOverride.kt

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

gltfModelEntity.clearMaterialOverride(
    nodeName = "Node Name"
)
MaterialOverride.kt

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