{ } { }

Jetpack SceneCore

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
7 mai 2025 - - - 1.0.0-alpha04

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-alpha04"
    // 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-alpha04"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha04")
    // 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-alpha04")
}

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-alpha04

7 mai 2025

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

Nouvelles fonctionnalités

  • La gestion du Retour fonctionne désormais sur les entités de panneau sans activités intégrées. Pour que la gestion des retours fonctionne, vous devez spécifier android:enableOnBackInvokedCallback= "true" dans le fichier manifeste Android.
  • StereoSurfaceEntity est désormais compatible avec la lecture MV-HEVC via deux nouvelles valeurs StereoMode: MULTIVIEW_LEFT_PRIMARY et MULTIVIEW_RIGHT_PRIMARY.
  • PanelEntity.setSize et PanelEntity.getSize renvoient désormais des tailles dans l'espace parent.
  • Entity.setPose, Entity.getPose, Entity.setScale, Entity.getScale, Entity.setAlpha et Entity.getAlpha acceptent désormais un nouveau paramètre relativeTo, qui permet d'obtenir/de définir des valeurs par rapport à différents espaces. Les valeurs acceptées sont "Parent", "Activity" et "Real World". La valeur par défaut de ce paramètre est "Parent".
  • Méthodes d'extension du rappel de visibilité spatiale ajoutées à SessionExt.kt pour surveiller le moment où le contenu de la scène se déplace dans ou en dehors du champ de vision de l'utilisateur.
  • setPointSourceParams a été ajouté à SpatialAudioTrack, ce qui permet de mettre à jour les paramètres après la compilation du canal.
  • Ajout d'une nouvelle classe, Scene, avec des références aux API Scenecore. La scène sera accessible en tant que propriété d'extension de la session. Les fonctions de SessionExt ont été déplacées vers Scene. Les importations devront donc être ajustées (par exemple, SessionExt.getScene(session)).addSpatialCapababilitiesChangedListener contre SessionExt.addSpatialCapabilitiesChangedListener.
  • ActivityPose.hitTestAsync a été ajouté, ce qui permet d'utiliser hitTest pour les contenus virtuels.
  • Ajout du nouveau type de composant SpatialPointerComponent, qui permet aux clients de spécifier l'icône affichée pour le pointeur ou de la désactiver. Ce composant ne peut actuellement être associé qu'à des instances PanelEntity.
  • Présentation de la nouvelle usine PanelEntity, qui prend en charge les dimensions du panneau en mètres ou en pixels. Suppression de l'ancienne usine PanelEntity qui utilisait deux paramètres de type de dimension pour le panneau.

Modifications apportées à l'API

  • Suppression de la restriction RequiresApi(34) sur tous les packages Jetpack XR. Cette restriction était redondante, car Jetpack XR n'est actuellement disponible que sur les appareils équipés d'un niveau d'API 34 ou supérieur. (Iae0f8)
  • Les projets publiés avec Kotlin 2.0 nécessitent KGP 2.0.0 ou une version ultérieure pour être consommés (Idb6b5)
  • La classe PermissionHelper a été supprimée.
  • Abandon de PanelEntity.getPixelDensity.
  • PanelEntity.setPixelDimensions et PanelEntity.getPixelDimension sont supprimés, remplacés par setSizeInPixels et getSizeInPixels.
  • Entity.getActivitySpaceAlpha supprimé. Peut être remplacé par Entity.getAlpha(Space.Activity).
  • Entity.getWorldSpaceScale supprimé. Peut être remplacé par Entity.getScale(Space.REAL\_WORLD).
  • La classe Session dans SceneCore a été supprimée au profit de la session dans XR Runtime.
  • Le compte de service (StereoSurfaceEntity) a été renommé SurfaceEntity.
  • Entity.setSize et Entity.getSize sont supprimés, et les mêmes méthodes ont été ajoutées à PanelEntity.
  • Le compte de service (PointSourceAttributes) a été renommé PointSourceParams.
  • Le compte de service (SpatializerConstants.SOURCE\_TYPE\_BYPASS) a été renommé SpatializerConstants.SOURCE\_TYPE\_DEFAULT.
  • L'accès public de l'entité PointSourceParams a été modifié pour passer à un accès interne.
  • AnchorEntity.create nécessite désormais que PlaneTrackingMode soit configuré dans Session.configure().
  • Les API SpatialUser nécessitent désormais que HeadTrackingMode soit configuré dans Session.configure().
  • Lorsque ResizableComponent n'est pas associé, un journal de niveau INFO est généré au lieu d'un journal de niveau ERROR.
  • La classe Fov est désormais une classe Kotlin standard.
  • Divisez Entity.kt pour placer chaque type d'entité concret dans son propre fichier.
  • Lorsque vous créez un PanelEntity, la plupart des vues sont reparentées à un FrameLayout. Cela facilite l'utilisation de LayoutInspector avec les panneaux spatiaux.
  • L'instance XrExtensions actuellement utilisée est désormais enregistrée auprès de la plate-forme, dans la mesure du possible, pour faciliter le débogage de l'application.

Correction de bugs

  • Un correctif a été ajouté pour éviter un plantage pouvant se produire lors du déplacement d'un PanelEntity avec MovableComponent et AnchorPlacement.
  • Correction d'un problème qui entraînait la fourniture de tailles obsolètes dans le rappel onResizeStart.ResizableComponent
  • Correction du plantage qui se produisait lorsque dispose() de JxrPlatformAdapterAxr était appelé plusieurs fois.

Version 1.0.0-alpha03

26 février 2025

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

Nouvelles fonctionnalités

  • La minification Proguard est désormais prise en charge pour le code Jetpack XR

Correction de bugs

  • Corrections supplémentaires pour la prise en charge de la minification Proguard pour Jetpack XR SceneCore (I4f47e)
  • Mise à jour de la règle ProGuard de Scenecore Jetpack XR pour empêcher AbstractMethodError pour les clients minifiés. (I91a01)

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 par défaut ou inférieur 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 les 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 min 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 autre qu'Android XR, 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.