3D‑Modelle in Ihre App einfügen

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-Datenbrille
Informationen zu XR-Gerätetypen →

Bei der Arbeit mit 3D-Modellen unterstützt das Jetpack XR SDK den offenen Standard glTF 2.0. Wenn Android XR Apps rendert, die mit dem Jetpack XR SDK erstellt wurden, werden 3D-Modelle mit physikalisch basierten Rendering-Techniken(PBR) gerendert, die im glTF 2.0-Standard (zusammen mit unterstützten Erweiterungen) angegeben sind. Die meisten Tools zur Erstellung digitaler Inhalte (Digital Content Creation, DCC) wie Autodesk Maya, Maxon ZBrush, Blender und Spline können 3D-Modelle in das glTF-Format (.gltf- oder .glb-Dateien) exportieren.

Wenn der Nutzer oder Ihre App eine SpatialEnvironment-Skybox angegeben hat, werden 3D-Modelle mit den Beleuchtungsinformationen der Umgebungs-Skybox beleuchtet. Reflektierende Materialien und Glanzlichter reflektieren auch die Skybox der Umgebung. Wenn Passthrough aktiviert ist, basieren die Beleuchtung, die Reflexionen und die Glanzlichter auf einem hellen Raum mit einer einzigen gerichteten Lichtquelle.

Eine kurze Übersicht über die unterstützten Materialien finden Sie auf der Khronos-Website unter glTF PBR Properties. Informationen zum Anpassen Ihrer 3D-Modelle mit diesen und anderen Attributen finden Sie unter 3D-Modelle in Ihrer App anpassen.

glTF-Datei zum Asset-Ordner hinzufügen

Sobald Sie die glTF-Datei haben, müssen Sie sie im nächsten Schritt dem Anlagenverzeichnis in Android Studio hinzufügen. Wir empfehlen, ein models-Verzeichnis zu erstellen, um Ihre Asset-Typen besser zu organisieren.

Beispiel für das Hinzufügen von Assets zum Verzeichnis „/models“

3D-Objekt mit SpatialGltfModel hinzufügen

Android XR unterstützt das glTF-Format für 3D-Modelle, die normalerweise als .glb-Dateien gespeichert werden. Verwenden Sie SpatialGltfModel, um diese Objekte Ihrem Layout hinzuzufügen. Ein SpatialGltfModel ist ein Subspace-Composable, mit dem Sie Ihrem räumlichen Layout 3D-Modelle im glTF-Format hinzufügen können. Diese API vereinfacht das Laden von Assets und die Verwaltung ihres Status.

Wenn Sie ein Modell anzeigen möchten, müssen Sie zuerst seine Quelle und seinen Status mit rememberSpatialGltfModelState definieren. Sie können Modelle aus dem Ordner assets Ihrer App, einem URI oder raw data laden.

val modelState = rememberSpatialGltfModelState(
    source = SpatialGltfModelSource.fromPath(
        Paths.get("models/model_name.glb")
    )
)

Nachdem der Status definiert wurde, verwenden Sie das Compose-Element SpatialGltfModel, um ihn in einem Subspace zu rendern:

SpatialGltfModel(state = modelState, modifier = SubspaceModifier)

Wichtige Punkte zum Code

  • Asynchrones Laden: Das Modell wird asynchron geladen. Während der ersten Komposition kann die intrinsische Größe null sein. Das Layout wird neu gemessen, sobald das Modell bereit ist.
  • Status steuern: Verwenden Sie SpatialGltfModelState.status, um den Ladestatus abzufragen oder Animationen zu steuern.
  • Größe und Skalierung: Standardmäßig entspricht die Layoutgröße dem Begrenzungsrahmen des Assets. Sie können dies mit einem SubspaceModifier.size überschreiben, um das Modell einheitlich so zu skalieren, dass es in die angegebenen Grenzen passt.

3D-Modell mit einer Compose SceneCoreEntity platzieren

Wenn Sie ein 3D-Modell mit SceneCoreEntity platzieren möchten, müssen Sie zuerst die glTF-Datei mit GltfModel.create() in den Arbeitsspeicher laden. Anschließend können Sie ein 3D-Modell in einem SceneCoreEntity platzieren, um SceneCore-Komponenten mit Compose for XR-Layouts zu verbinden. Weitere Informationen finden Sie unter SceneCoreEntity verwenden, um ein 3D-Objekt in Ihrem Layout zu platzieren.

3D-Modell mit Jetpack Scenecore platzieren

Rufen Sie GltfModel.create() auf, um das glTF-Modell zu laden.

val gltfModel = GltfModel.create(session, Paths.get("models", "saturn_rings.glb"))

An diesem Punkt wird das Modell in den Arbeitsspeicher geladen, aber noch nicht gerendert. Wenn Sie viele 3D-Modelle laden müssen oder Ihr Modell groß ist, sollten Sie sie im Voraus asynchron laden. So müssen Nutzer nicht warten, bis Ihre Modelle in den Arbeitsspeicher geladen wurden.

Fügen Sie die glTF-Datei dem ActivitySpace hinzu. Rufen Sie GltfModelEntity.create auf, um eine Entität zu erstellen und in ActivitySpace zu platzieren. Als Best Practice sollten Sie prüfen, ob sich die App in einem Zustand befindet, der räumliche Funktionen zulässt.

if (session.scene.spatialCapabilities.contains(SpatialCapability.SPATIAL_3D_CONTENT)) {
    val gltfEntity = GltfModelEntity.create(session, gltfModel)
}

Wenn Sie Ihre App ausführen, sollte jetzt das geladene 3D-Modell angezeigt werden.

Beispiel für das geladene 3D-Modell

3D-Modell mit Scene Viewer laden

Wenn Sie nach der einfachsten Möglichkeit suchen, ein 3D-Modell mit grundlegenden Interaktionsfunktionen zu laden, können Sie Scene Viewer wie auf Mobilgeräten verwenden. Ein wichtiger Unterschied zwischen dem Scene Viewer unter Android XR und auf Mobilgeräten besteht darin, dass der Scene Viewer nur den Datei-URI-Parameter unterstützt, der auf die glTF-Datei verweist. Alle anderen Parameter werden ignoriert.

Scene Viewer ist eine separate App, die über einen Intent aufgerufen wird und im Full Space-Modus ausgeführt wird. Wenn Sie Scene Viewer aufrufen, ist Ihre App nicht mehr sichtbar und Scene Viewer wird fokussiert. Alle Umgebungen, die Sie möglicherweise geändert haben, werden auf die Systemeinstellungen des Nutzers zurückgesetzt.

Hier ist ein Beispiel für die Verwendung eines Intent, um eine glTF-Datei im Scene Viewer unter Android XR anzusehen:

val url =
    "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf"
val sceneViewerIntent = Intent(Intent.ACTION_VIEW)
val intentUri =
    Uri.parse("https://arvr.google.com/scene-viewer/1.2")
        .buildUpon()
        .appendQueryParameter("file", url)
        .build()
sceneViewerIntent.setData(intentUri)
try {
    startActivity(sceneViewerIntent)
} catch (e: ActivityNotFoundException) {
    // There is no activity that could handle the intent.
}

Weitere Informationen zu den Interaktivitätsoptionen für Scene Viewer finden Sie in unserer Dokumentation zum Design von 3D-Modellen.

glTF-Erweiterungen

Das Jetpack XR SDK unterstützt mehrere glTF-Erweiterungen, die die Funktionen von 3D-Modellen erweitern. Diese Funktionen sind sowohl über die GltfModelEntity als auch über Scene Viewer verfügbar.