アプリで 3D モデルをカスタマイズする

対象の XR デバイス
このガイダンスは、次のようなタイプの XR デバイスに対する経験を積むのに役立ちます。
XR デバイスの種類について →
XR ヘッドセット
有線 XR グラス
XR デバイスの種類について →

アプリに 3D モデルを追加したら、カスタム マテリアル プロパティを定義してオブジェクトにテクスチャを適用することで、視覚的なエクスペリエンスを強化できます。Jetpack XR のマテリアル システムは glTF™ 2.0 仕様に基づいており、3D モデルは物理ベース レンダリング（PBR）を使用してレンダリングされます。これらは、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（赤、緑、青、アルファ）の値に対応します。

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 オブジェクト自体は単なるデータです。3D モデルに視覚効果を与えるには、Material に割り当てる必要があります。

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. の商標です。