Ajouter des modèles 3D à votre application

Appareils XR concernés
Ces conseils vous aident à créer des expériences pour ces types d'appareils XR.
En savoir plus sur les types d'appareils XR
Casques XR
Lunettes XR filaires
En savoir plus sur les types d'appareils XR

Lorsque vous travaillez avec des modèles 3D, le SDK Jetpack XR est compatible avec la norme ouverte glTF 2.0. Lorsque Android XR affiche des applications créées avec le SDK Jetpack XR, les modèles 3D sont rendus avec des techniques de rendu basées sur la physique(PBR) spécifiées dans la norme glTF 2.0 (ainsi que les extensions compatibles). La plupart des outils de création de contenu numérique (DCC), tels que Autodesk Maya, Maxon ZBrush, Blender et Spline, peuvent exporter des modèles 3D au format glTF (fichiers .gltf ou .glb).

Si une skybox SpatialEnvironment a été spécifiée par l'utilisateur ou par votre application, les modèles 3D seront éclairés avec les informations d'éclairage fournies par la skybox de l'environnement. Les matériaux réfléchissants et les reflets spéculaires refléteront également la skybox de l'environnement. Si le mode Passthrough est activé, l'éclairage, les reflets et les reflets spéculaires seront basés sur une pièce simple et lumineuse avec une seule lumière directionnelle.

Pour obtenir un aperçu rapide des matériaux compatibles, consultez les propriétés PBR glTF sur le site Khronos.

Il existe deux méthodes principales pour que les applications créées avec le SDK Jetpack XR chargent des modèles 3D.

Placer un modèle 3D dans l'ActivitySpace

Une fois que vous avez votre fichier glTF, l'étape suivante consiste à l'ajouter au répertoire des ressources dans Android Studio. Nous vous recommandons de créer un répertoire models pour mieux organiser vos types d'assets.

Exemple d'ajout de composants au répertoire /models

Pour charger le modèle glTF, appelez GltfModel.create().

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

À ce stade, le modèle est chargé en mémoire, mais il n'est pas encore rendu. Si vous avez de nombreux modèles 3D à charger ou si votre modèle est volumineux, il est judicieux de les charger de manière asynchrone à l'avance. Ainsi, les utilisateurs n'ont pas à attendre que vos modèles soient chargés en mémoire.

Nous devons ajouter le fichier glTF à ActivitySpace. Appelez GltfModelEntity.create pour créer une entité et la placer dans ActivitySpace. Il est recommandé de vérifier que l'application est dans un état qui permet les fonctionnalités spatiales.

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

Vous devriez maintenant voir le modèle 3D chargé lorsque vous exécutez votre application.

Exemple de modèle 3D chargé

Placer un modèle 3D dans une entité SceneCoreEntity Compose

Bien que vous deviez toujours charger le fichier glTF en mémoire à l'aide de GltfModel.create(), vous pouvez placer des modèles 3D dans un SceneCoreEntity si vous créez votre UI avec Jetpack Compose pour XR. Consultez Utiliser un SceneCoreEntity pour placer un objet 3D dans votre mise en page.

Animer des modèles 3D

Les modèles 3D peuvent contenir des animations intégrées, conformément à la spécification glTF. Les animations squelettiques (avec squelette), rigides et avec cibles de morphing (formes de mélange) sont toutes compatibles avec le SDK Jetpack XR. Les animations Material créées avec l'extension glTF KHR_animation_pointer sont également acceptées.

Pour lire une animation, appelez startAnimation() et spécifiez le nom de l'animation. Vous pouvez éventuellement spécifier si l'animation doit se répéter indéfiniment ou non.

gltfEntity.startAnimation(loop = true, animationName = "Walk")
GltfEntity.kt

Si vous appelez startAnimation une deuxième fois, l'animation en cours s'arrête et la nouvelle animation démarre.

Vous pouvez interroger l'état actuel de l'animation via getAnimationState().

Si le nom d'animation spécifié lors de l'appel de startAnimation() n'existe pas, l'appel échoue silencieusement, toutes les animations en cours s'arrêtent et getAnimationState() renvoie STOPPED.

Charger un modèle 3D à l'aide de Scene Viewer

Si vous recherchez le moyen le plus simple de charger un modèle 3D avec des fonctionnalités d'interaction de base, vous pouvez choisir d'utiliser Scene Viewer comme vous le feriez sur mobile. Une différence essentielle entre Scene Viewer sur Android XR et sur mobile est que Scene Viewer n'accepte que le paramètre URI de fichier pointant vers le fichier glTF. Tous les autres paramètres sont ignorés.

Scene Viewer est une application distincte qui est appelée à l'aide d'un intent et qui s'exécute en mode Full Space. Par conséquent, lorsque vous l'invoquez, votre application n'est plus visible et Scene Viewer est mis au premier plan. Tous les environnements que vous avez pu modifier seront réinitialisés sur les préférences système de l'utilisateur.

Voici un exemple d'utilisation d'un Intent pour afficher un fichier glTF dans Scene Viewer sur Android XR :

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.
}
GltfEntity.kt

Pour en savoir plus sur les options d'interactivité de Scene Viewer, consultez notre documentation sur la conception de modèles 3D.

Extensions glTF

Le SDK Jetpack XR est compatible avec plusieurs extensions gfTF qui étendent les capacités des modèles 3D. Ces fonctionnalités sont disponibles via GltfModelEntity et Scene Viewer.