3D-Modelle in Ihrer App anpassen

XR‑Geräte, für die der Leitfaden gilt
Dieser Leitfaden hilft Ihnen dabei, Erlebnisse für die folgenden Arten von XR-Geräten zu entwickeln.
Informationen zu XR‑Gerätetypen
XR‑Headsets
Kabelgebundene XR‑Brillen
Informationen zu XR‑Gerätetypen

Bevor Sie ein 3D‑Modell anpassen, müssen Sie es zuerst Ihrer App hinzufügen. Nachdem Sie ein 3D‑Modell hinzugefügt haben, können Sie das visuelle und interaktive Erlebnis verbessern, indem Sie das Aussehen und die Bewegung des 3D‑Modells anpassen.

Sie können beispielsweise eingebettete glTF‑Animationen abspielen und steuern, auf Knoten zugreifen und sie verschieben, aus denen Ihr Modell besteht, oder sogar benutzerdefinierte Texturen laden und Materialeigenschaften definieren, um interne Meshes zu überschreiben. Mit diesen Funktionen können Sie das Aussehen und Verhalten eines Objekts zur Laufzeit dynamisch ändern.

3D‑Objekte in Android XR

Das Jetpack XR SDK unterstützt den glTF 2.0 offenen Standard der Khronos Group für 3D-Modelle und rendert diese Objekte mit physikalisch basierten Rendering-Techniken (PBR) Techniken, die im glTF 2.0-Standard (zusammen mit unterstützten Erweiterungen) angegeben sind. glTF (Graphics Library Transmission Format) ist ein Standarddateiformat für die Übertragung und das Laden von 3D‑Szenen und ‑Modellen. Ein glTF‑Modell besteht aus einer hierarchischen Struktur interner Komponenten.

Hier sind die wichtigsten Komponenten:

  • Knoten: Diese definieren die Struktur und Hierarchie des Modells. Jeder Knoten kann eine eigene Position, Drehung und Skalierung haben.
  • Meshes: Die strukturelle 3D‑Geometrie, die die Form eines 3D‑Objekts bildet.
  • Materialien: Diese definieren das visuelle Erscheinungsbild der Meshes, z. B. ihre Farbe, Rauheit oder wie sie auf die Beleuchtung reagieren.
  • Texturen: Ein Bild-Asset, z. B. eine PNG‑Datei, das Sie auf die Oberfläche eines 3D‑Modells anwenden können, um benutzerdefinierte Muster, Farben, Details oder andere visuelle Effekte zu erstellen.

In Jetpack Compose für XR rendern Sie diese Dateien mit SpatialGltfModel und verfolgen den Ladestatus mit SpatialGltfModelState. Weitere Informationen finden Sie unter 3D‑Modelle zur App hinzufügen.

Knoten bearbeiten: Posen und Drehung

Wenn Sie bestimmte Teile eines Modells bearbeiten und seine Eigenschaften wie Drehung oder Pose ändern möchten, müssen Sie die internen nodes des glTF‑Modells mit SpatialGltfModelState abfragen.

// Retrieve the list of nodes (individual components/meshes) defined within the glTF model.
val entityNodes = modelState.nodes

// Find a specific node by name to apply modifications, such as material overrides.
val node = entityNodes.find { it.name == "node_name" }

Nachdem Sie den richtigen Knoten gefunden haben, können Sie seine localPose festlegen, um seine 3D Position und ‑Drehung relativ zum direkten übergeordneten Element GltfModelNode zu ändern, oder modelPose verwenden, um die Position relativ zum GltfModelEntity-Stamm festzulegen. Ebenso können Sie mit „localScale“/„modelScale“ die Skalierung des Modells relativ zum übergeordneten Element oder Stamm ändern.

LaunchedEffect(node, degrees) {
    val rotation = Quaternion.fromEulerAngles(degrees, 0f, degrees)
    node?.let {
        it.localPose = Pose(it.localPose.translation, rotation)
    }
}

Materialeigenschaften des 3D‑Modells anpassen

Sie können Materialattribute zur Laufzeit anpassen, um das Erscheinungsbild eines Objekts dynamisch basierend auf der Nutzereingabe oder dem aktuellen Status der App zu ändern.

In Jetpack XR werden die KhronosPbrMaterial und KhronosUnlitMaterial Klassen verwendet, um diese Materialien zu erstellen und zu bearbeiten. Wie der Name schon sagt, KhronosUnlitMaterials sind nicht beleuchtet und werden nicht von der Szenenbeleuchtung beeinflusst. KhronosPbrMaterial ermöglicht Ihnen, eine größere Auswahl an Eigenschaften anzupassen, z. B. die Farbe des Glanzes, wie metallisch oder rau ein Objekt ist und ob es Licht aussendet.

Weitere Informationen zu den einzelnen unterstützten Eigenschaften und den anpassbaren Parametern in Android XR finden Sie in unserer Referenzdokumentation. Ein besseres Verständnis dieser Eigenschaften erhalten Sie im Khronos-Glossar.

Abbildung 1. Beispiel für das Ändern der Grundfarben eines 3D‑Modells.

Wenn Sie die Materialeigenschaften Ihres 3D‑Modells anpassen möchten, erstellen Sie zuerst das neue Material mit KhronosPbrMaterial. Sie müssen den entsprechenden AlphaMode für das gewünschte Erscheinungsbild festlegen:

Definieren Sie als Nächstes die Eigenschaften, die Sie ändern möchten. In diesem Beispiel wird setBaseColorFactor verwendet, um die Grundfarbe des Mesh in Lila zu ändern. Für diese Methode ist ein Vector4 erforderlich, wobei die Komponenten x, y, z und w jeweils den RGBA‑Werten (Rot, Grün, Blau und Alpha) entsprechen:

// Maintain a reference to the custom material to avoid re-creating it on every recomposition.
var pbrMaterial by remember { mutableStateOf<KhronosPbrMaterial?>(null) }

// Create and apply the custom material once the session is ready and the target node is available.
LaunchedEffect(node) {
    val material = KhronosPbrMaterial.create(
        session = xrSession,
        alphaMode = AlphaMode.OPAQUE
    ).also {
        pbrMaterial = it
        // Apply a base color factor (RGBA) to change the color of the model.
        it.setBaseColorFactor(
            Vector4(
                x = 0.5f,
                y = 0.0f,
                z = 0.5f,
                w = 1.0f
            )
        )
    }

Benutzerdefinierte Texturen für das 3D‑Modell laden

Ein Texture ist ein Bild-Asset, das Sie auf die Oberfläche eines 3D Modells anwenden können, um Farbe, Details oder andere Oberflächeninformationen bereitzustellen. Mit der Jetpack XR Texture API können Sie Bilddaten wie PNG‑Dateien asynchron aus dem Ordner /assets/ Ihrer App laden.

Beim Laden einer Textur können Sie einen TextureSampler angeben, der steuert wie die Textur gerendert wird. Der Sampler definiert Filterungseigenschaften (wenn die Textur kleiner oder größer als ihre ursprüngliche Größe angezeigt wird) und Wrapping-Modi (für die Verarbeitung von Koordinaten außerhalb des Standardbereichs [0, 1] ). Ein Texture muss einem KhronosPbrMaterial zugewiesen werden, um einen visuellen Effekt auf ein 3D Modell zu haben.

Abbildung 2. Beispiel für das Ändern der Textur eines 3D‑Modells.

Wenn Sie eine benutzerdefinierte Textur laden möchten, müssen Sie zuerst die Bilddatei im Ordner /assets/ speichern. Als Best Practice empfiehlt es sich, in diesem Ordner auch ein Unterverzeichnis textures zu erstellen.

Nachdem Sie die Datei im entsprechenden Verzeichnis gespeichert haben, erstellen Sie die Textur mit der Texture API. Hier können Sie bei Bedarf auch einen optionalen TextureSampler anwenden.

In diesem Beispiel wird eine Okklusionstextur angewendet und die Okklusionsstärke festgelegt:

LaunchedEffect(node) {
    val material = KhronosPbrMaterial.create(
        session = xrSession,
        alphaMode = AlphaMode.OPAQUE
    ).also {
        pbrMaterial = it

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

        // Set the texture and configure occlusion to define how the material surface handles ambient lighting.
        it.setOcclusionTexture(
            texture = texture,
            strength = 1.0f
        )
    }
    node?.setMaterialOverride(
        material = material
    )
}

Materialien und Texturen auf 3D‑Objekte anwenden

Wenn Sie das neue Material oder die neue Textur anwenden möchten, überschreiben Sie das vorhandene Material für einen bestimmten Knoten in Ihrem glTF Knoten. Rufen Sie dazu setMaterialOverride auf:

node?.setMaterialOverride(
    material = material
)

Wenn Sie die neu erstellten Materialien entfernen möchten, rufen Sie clearMaterialOverride für den zuvor überschriebenen Knoten auf. Dadurch wird das 3D‑Modell auf den Standardzustand zurückgesetzt:

if (removeMaterial) {
    node?.clearMaterialOverride()
}

3D‑Modelle animieren

3D‑Modelle können eingebettete Animationen haben. Intern verwenden Animationen Sampler, um das Timing und die Werte einer Bewegung zu definieren, und Kanäle, um diese Bewegungen mit einzelnen Knoten und Meshes zu verbinden. Skelett- und Materialanimationen, die mit der KHR_animation_pointer glTF‑Erweiterung erstellt wurden, werden im Jetpack XR SDK unterstützt.

Animationen können nur mit GltfAnimation von SceneCore und einer GltfModelEntity gesteuert werden. Wenn Sie diese Entität einem Compose for XR‑Layout hinzufügen möchten, müssen Sie anstelle von SpatialGltfModel eine SceneCoreEntity verwenden.

Geben Sie den Namen des jeweiligen Tracks aus der Liste der animations in Ihrer GltfModelEntity an. Verwenden Sie GltfAnimationStartOptions, um die Animation abzuspielen. Optional können Sie die Geschwindigkeit, die Suchzeit und festlegen, ob die Animation wiederholt werden soll:

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

glTF und das glTF‑Logo sind Marken der Khronos Group Inc.