Jetpack SceneCore

Documentation de référence de l'API
androidx.xr.scenecore
androidx.xr.scenecore.testing

Créez et manipulez le graphe de scène Android XR avec du contenu 3D.

Dernière mise à jour	Version stable	Version finale	Version bêta	Version alpha
12 février 2025	-	-	-	1.0.0-alpha02

Déclarer des dépendances

Pour ajouter une dépendance à XR SceneCore, vous devez ajouter le dépôt Maven de Google à votre projet. Pour en savoir plus, consultez la section Dépôt Maven de Google.

Ajoutez les dépendances correspondant aux artefacts dont vous avez besoin dans le fichier build.gradle de votre application ou de votre module :

Groovy

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha01"
    // Required for Java
    implementation "com.google.guava:listenableFuture:1.0"
    // Required for Kotlin
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0"

    // Use to write unit tests
    testImplementation "androidx.xr.scenecore:scenecore-testing:1.0.0-alpha01"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha01")
    // Required for Java
    implementation("com.google.guava:listenableFuture:1.0")
    // Required for Kotlin
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0")

    // Use to write unit tests
    testImplementation("androidx.xr.scenecore:scenecore-testing:1.0.0-alpha01")
}

Pour en savoir plus sur les dépendances, consultez Ajouter des dépendances de compilation.

Commentaires

Vos commentaires nous aident à améliorer Jetpack. N'hésitez pas à nous contacter si vous découvrez de nouveaux problèmes ou si vous avez des idées pour améliorer cette bibliothèque. Veuillez consulter les problèmes existants de cette bibliothèque avant d'en signaler un nouveau. Vous pouvez ajouter votre vote à un problème existant en cliquant sur le bouton en forme d'étoile.

Signaler un nouveau problème

Pour en savoir plus, consultez la documentation sur l'outil Issue Tracker.

Version 1.0

Version 1.0.0-alpha02

12 février 2025

Publication d'androidx.xr.scenecore:scenecore:1.0.0-alpha02 et d'androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02. La version 1.0.0-alpha02 contient ces commits.

Modification destructive à venir affectant les applications créées avant la version 1.0.0-alpha02

Les méthodes de fabrique ont été déplacées de la classe Session vers une méthode associée pour chaque type respectif :
- Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) a été supprimé et remplacé par ActivityPanelEntity.create(Session, Dimensions, String, Pose)
- Session.createAnchorEntity(Anchor) a été supprimé et remplacé par AnchorEntity.create(Session, Anchor)
- Session.createAnchorEntity(Dimensions, Int, Int, Duration) a été supprimé et remplacé par AnchorEntity.create(Session, Dimensions, Int, Int, Duration)
- Session.createEntity(String, Pose) a été supprimé et remplacé par ContentlessEntity.create(Session, String, Pose)
- Session.createExrImageResource(String) a été supprimé et remplacé par ExrImage.create(Session, String)
- Session.createGltfEntity(GltfModel, Pose) a été supprimé et remplacé par GltfModelEntity.create(Session, GltfModel, Pose)
- Session.createGltfModelResource(String) a été supprimé et remplacé par GltfModel.create(Session, String)
- Session.createInteractableComponent(Executor, InputEventListener) a été supprimé et remplacé par InteractableComponent.create(Session, Executor, InputEventListener)
- Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) a été supprimé et remplacé par MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
- Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) a été supprimé et remplacé par PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose)
- Session.createResizableComponent(Dimensions, Dimensions) a été supprimé et remplacé par ResizableComponent.create(Session, Dimensions, Dimensions)
- Session.createStereoSurfaceEntity(Int, Dimensions, Pose) a été supprimé et remplacé par StereoSurface.create(Session, Int, Dimensions, Pose)
Les méthodes obsolètes suivantes ont été supprimées :
- Session.canEmbedActivityPanel(Activity) a été supprimé. Utilisez getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY) à la place.
- Session.hasSpatialCapability(Int) a été supprimé. Il a été remplacé par getSpatialCapabilities().hasCapability(), qui permet de vérifier la présence de fonctionnalités spatiales de manière plus compartimentée, car getSpatialCapabilities() renvoie un objet SpatialCapabilities.
- Session.requestFullSpaceMode() a été supprimé et remplacé par SpatialEnvironment.requestFullSpaceMode()
- Session.requestHomeSpaceMode() a été supprimé et remplacé par SpatialEnvironment.requestHomeSpaceMode()
Session.setFullSpaceMode(Bundle) et Session.setFullSpaceModeWithEnvironmentInherited(Bundle) ont été déplacés vers les fonctions d'extension. Les fichiers du développeur devront ajouter les nouvelles importations pour y accéder :
- import androidx.xr.scenecore.setFullSpaceMode
- import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
Session.setPreferredAspectRatio(Activity, Float) a été déplacé vers une fonction d'extension. Les fichiers du développeur devront ajouter la nouvelle importation pour y accéder :
- import androidx.xr.scenecore.setPreferredAspectRatio
Session.getEntitiesOfType(Class<out T>) et Session.getEntityForRtEntity(RtEntity) ont été déplacés vers les fonctions d'extension. Les fichiers du développeur devront ajouter les nouvelles importations pour y accéder :
- import androidx.xr.scenecore.getEntitiesOfType
- import androidx.xr.scenecore.getEntityForRtEntity
Session.unpersistAnchor(Anchor) a été supprimée
Session.createPersistedAnchorEntity(UUID) a été supprimée

Problèmes connus

PanelEntity.setCornerRadius() et ActivityPanelEntity.setCornerRadius() ne seront peut-être pas appliqués avant le prochain déplacement du panneau. Pour y remédier, déplacez le panneau à sa position actuelle.
Lorsque BoundsChanged est appelé sur ActivitySpace, il est possible que certains ActivityPose n'aient pas été correctement mis à jour. Il sera mis à jour lors de l'appel OnSpaceUpdated suivant sur le ActivitySpace.

Modifications de comportement et de non-fonctionnement

Le rayon des coins de PanelEntity et ActivityPanelEntity est de 32 dp ou moins par défaut si la largeur ou la hauteur du panneau est inférieure à 32 dp.

Nouvelles API et fonctionnalités

Introduction de StereoSurface.CanvasShape, qui permet de créer des canevas Spherical et Hemispherical pour le rendu de contenus multimédias immersifs.
StereoSurfaceEntity.create() accepte désormais un paramètre CanvasShape. (Ce paramètre est actuellement ignoré, mais il sera utilisé dans une prochaine version)
StereoSurfaceEntity.create() n'accepte plus le paramètre Dimensions. Les applications doivent contrôler la taille du canevas en définissant CanvasShape.
StereoSurfaceEntity possède un membre CanvasShape qui peut être défini de manière dynamique.
StereoSurfaceEntity.dimensions est désormais une propriété en lecture seule. Les applications doivent définir CanvasShape pour modifier les dimensions.
StereoSurfaceEntity permet désormais de réinitialiser StereoMode après la compilation.

Autres modifications

Réduction de la version minimale du SDK au moment de la compilation à 24. Toutes les API Jetpack XR continuent de nécessiter l'API 34 au moment de l'exécution.
La fabrique de session (Session.create) de SceneCore ne lance plus d'intent pour acquérir l'autorisation SCENE_UNDERSTANDING. Au lieu de cela, l'application cliente doit demander explicitement les autorisations à l'utilisateur avant de tenter de créer les ancrages. La création d'une ancre échouera si l'utilisateur n'accorde pas l'autorisation.

Corrections de bugs

getActivitySpacePose() a été corrigé pour tenir compte de l'échelle ActivitySpace en renvoyant des valeurs de translation en mètres linéaires plutôt que toujours en mètres non linéaires. transformPoseTo utilise désormais également les unités appropriées pour calculer les changements de coordonnées lorsque le ActivitySpace est impliqué dans la source ou la destination.
La skybox sera désormais définie sur une skybox entièrement noire chaque fois qu'une préférence de skybox nulle sera transmise à l'aide de setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). Pour rétablir la géométrie et le skybox par défaut du système, utilisez setSpatialEnvironmentPreference(null)..

Version 1.0.0-alpha01

12 décembre 2024

Publication d'androidx.xr.scenecore:scenecore-* 1.0.0-alpha01.

Fonctionnalités de la version initiale Version initiale pour les développeurs de Jetpack SceneCore, une bibliothèque de graphes de scène 3D permettant de créer et de manipuler des scènes et des environnements immersifs. Cette bibliothèque vous permet de placer et d'organiser des modèles 3D et des panneaux de contenu les uns par rapport aux autres et par rapport à vos environnements virtuels ou réels.

SpatialEnvironment: créez des expériences entièrement immersives avec une image de ciel et/ou une géométrie de modèle 3D comme toile de fond pour votre scène XR de votre environnement. Vous pouvez également activer le passthrough pour que votre scène virtuelle puisse s'intégrer à l'environnement réel de l'utilisateur.
PanelEntity: ajoutez du contenu 2D à vos scènes 3D en intégrant des mises en page et des activités Android standards dans des panneaux spatialisés pouvant flotter ou être ancrés à des surfaces réelles.
GltfModelEntity: placez, animez et interagissez avec des modèles 3D dans votre scène. SceneCore est compatible avec le format de fichier glTF pour faciliter l'intégration aux modèles existants.
SpatialAudio: ajoutez des sources audio ambiantes et ponctuelles à votre scène 3D pour un son spatialisé et immersif.
StereoSurfaceEntity: SceneCore prend en charge le routage des contenus affichés sur une surface Android pour les yeux gauche et droit. Vous pouvez l'utiliser pour afficher du contenu stéréoscopique dans un format côte à côte ou haut/bas, comme des photos stéréo, des vidéos 3D ou d'autres UI affichées de manière dynamique. Les applications doivent utiliser MediaPlayer ou ExoPlayer pour le décodage vidéo.
Système de composants: SceneCore propose un système de composants robuste et flexible pour ajouter des fonctionnalités à votre contenu XR, y compris des affordances permettant aux utilisateurs de déplacer, redimensionner et interagir avec des modèles et des panneaux.
Ancrage: lorsque le passthrough est activé, vous pouvez attacher des panneaux et des modèles à des surfaces réelles, ce qui permet aux utilisateurs d'intégrer facilement des contenus virtuels à leur environnement réel.
Posture de l'utilisateur: accédez à la position de l'utilisateur dans la scène virtuelle pour orienter votre contenu en fonction de sa position.
SpatialCapabilities: créez des applications entièrement adaptatives qui exploitent les fonctionnalités spatialisées lorsqu'elles sont disponibles, comme le positionnement 3D du contenu de l'interface utilisateur. De plus, votre application peut surveiller les modifications apportées aux fonctionnalités pendant son exécution afin de modifier l'expérience en fonction de la façon dont l'utilisateur utilise son appareil Android XR.

Problèmes connus

Actuellement, une version minimale du SDK 30 est requise pour utiliser Jetpack SceneCore. Pour contourner ce problème, ajoutez l'entrée de fichier manifeste <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> suivante afin de pouvoir compiler et exécuter avec un SDK minimal de 23.
La session peut devenir non valide dans diverses situations qui recréent automatiquement l'activité, y compris en redimensionnant un panneau principal, en connectant des périphériques et en passant du mode clair au mode sombre. Si vous rencontrez des problèmes d'invalidation de session, vous pouvez contourner le problème en rendant votre panneau principal non redimensionnable, en utilisant une entité de panneau dynamique, en désactivant la recréation d'activité pour des modifications de configuration spécifiques ou en désactivant les modifications de thème en mode clair/sombre.
Les composants mobiles et redimensionnables ne sont pas compatibles avec GltfEntity.
Entity.getSize() n'est pas compatible avec GltfEntity.
Les applications Jetpack XR doivent demander l'autorisation android.permission.SCENE_UNDERSTANDING dans AndroidManifest.
La création d'une session n'est possible que sur un appareil Android XR. Pour le moment, si vous créez une session et que vous essayez de l'utiliser sur un appareil XR autre qu'Android, vous obtiendrez une exception RuntimeException.
Définir la skybox sur "null" via "SpatialEnvironment.setSpatialEnvironmentPreference()" ne génère pas de skybox noire unie, comme indiqué dans la documentation. Il est possible que le ciel par défaut du système soit utilisé ou qu'aucune modification ne soit apportée au ciel actuel.
Les clients SceneCore doivent ajouter implementation(“com.google.guava:listenablefuture-1.0”) à leur configuration Gradle pour les dépendances de leur application. Dans une prochaine version, Scenecore inclura cette bibliothèque en tant que dépendance api. Les clients n'auront donc pas besoin de la déclarer explicitement.
SceneCore inclut par erreur com.google.guava:guava-31.1-android et com.google.protobuf:protobuf-javalite comme dépendances transitives. Si cela entraîne des erreurs de classe en double dans votre compilation, ces deux dépendances peuvent être exclues en toute sécurité.
Si votre application utilise SceneCore et active ProGuard, elle plantera lorsque vous créerez une session. Pour contourner ce problème, désactivez ProGuard. Pour savoir comment activer ProGuard, consultez ce guide.