Jetpack SceneCore

Créez et manipulez le graphique 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 du retour fonctionne, vous devez spécifier android:enableOnBackInvokedCallback= "true" dans le fichier manifeste Android.
  • StereoSurfaceEntity est désormais compatible avec la lecture MV-HEVC grâce à 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 relatives à différents espaces. Les valeurs acceptées sont "Parent", "Activity" et "Real World". La valeur par défaut de ce paramètre est "Parent".
  • Des méthodes d'extension de rappel de visibilité spatiale ont été ajoutées à SessionExt.kt pour surveiller le moment où le contenu de la scène se déplace à l'intérieur ou à l'extérieur du champ de vision de l'utilisateur.
  • setPointSourceParams a été ajouté à SpatialAudioTrack, ce qui permet de mettre à jour les paramètres une fois la piste créée.
  • 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 à l'intérieur 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 de hitTest le contenu virtuel.
  • Ajout du nouveau type de composant SpatialPointerComponent, permettant 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 compte les dimensions du panneau en mètres ou en pixels. L'ancienne usine PanelEntity qui acceptait deux paramètres de type Dimension pour le panneau a été supprimée.

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 avec le niveau d'API 34 ou supérieur. (Iae0f8)
  • Les projets publiés avec Kotlin 2.0 nécessitent KGP 2.0.0 ou version ultérieure pour être utilisés (Idb6b5).
  • La classe PermissionHelper a été supprimée.
  • Abandon de PanelEntity.getPixelDensity.
  • PanelEntity.setPixelDimensions et PanelEntity.getPixelDimension sont supprimés et 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 ont été 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 à l'entité PointSourceParams est désormais interne au lieu d'être public.
  • AnchorEntity.create nécessite désormais la configuration de PlaneTrackingMode dans Session.configure().
  • Les API SpatialUser nécessitent désormais la configuration de HeadTrackingMode 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é concrète 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, de la meilleure façon possible, pour faciliter le débogage de l'application.

Correction de bugs

  • Une correction a été ajoutée pour éviter un plantage qui pouvait se produire lorsqu'un PanelEntity avec MovableComponent et AnchorPlacement était déplacé.
  • Correction d'un problème qui empêchait ResizableComponent de fournir des tailles obsolètes dans le rappel onResizeStart.
  • Correction du plantage 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 compatible avec le code Jetpack XR

Correction de bugs

  • Corrections supplémentaires pour la compatibilité de la minification Proguard pour Jetpack XR SceneCore (I4f47e)
  • Mise à jour de la règle Jetpack XR Scenecore ProGuard pour empêcher AbstractMethodError pour les clients minimisé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 sur 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 l'accès :
    • 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 l'accès :
    • 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 l'accès :
    • 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 prendront peut-être effet qu'au prochain déplacement du panneau. Pour éviter cela, 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 du prochain appel OnSpaceUpdated le ActivitySpace.

Modifications destructives et de comportement

  • PanelEntity et ActivityPanelEntity auront un rayon d'angle par défaut de 32 dp ou moins si le panneau a une largeur ou une hauteur inférieure à 32 dp.

Nouvelles API et fonctionnalités

  • Présentation 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 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 comporte 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 redéfinir StereoMode après la construction.

Autres modifications

  • La valeur minSDK de compilation est désormais de 24. Toutes les API Jetpack XR continueront de nécessiter l'API 34 au moment de l'exécution.
  • La fabrique de sessions de SceneCore (Session.create) 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 ancres. La création d'ancres é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 mis à l'échelle plutôt qu'en mètres non mis à l'échelle. transformPoseTo utilise désormais également les bonnes unités pour calculer les changements de coordonnées lorsque 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 est transmise à l'aide de setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). Pour rétablir la skybox et la géométrie 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 graphiques 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, ainsi que par rapport à vos environnements virtuels ou réels.

  • SpatialEnvironment : créez des expériences entièrement immersives avec une image skybox et/ou une géométrie de modèle 3D comme toile de fond pour la scène XR de votre environnement. Vous pouvez également activer le mode Passthrough pour que votre scène virtuelle s'intègre à 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 qui peuvent flotter ou être ancrés à des surfaces du monde réel.
  • GltfModelEntity : placez des modèles 3D dans votre scène, animez-les et interagissez avec eux. SceneCore est compatible avec le format de fichier glTF pour faciliter l'intégration aux modèles existants.
  • Son spatial : ajoutez des sources audio ambiantes et ponctuelles à votre scène 3D pour un son spatialisé totalement immersif.
  • StereoSurfaceEntity : SceneCore est compatible avec le routage du contenu rendu sur une surface Android pour l'œil gauche et l'œil droit. Il peut être utilisé pour afficher du contenu stéréoscopique au format côte à côte ou haut/bas, comme des photos stéréoscopiques, des vidéos 3D ou d'autres interfaces utilisateur rendues 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 associer des panneaux et des modèles à des surfaces réelles, ce qui permet aux utilisateurs d'intégrer facilement du contenu virtuel dans leur environnement réel.
  • Pose 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 capacités spatialisées lorsqu'elles sont disponibles, comme le positionnement 3D du contenu de l'UI. 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, un minSDK de 30 est requis pour utiliser Jetpack SceneCore. Pour contourner ce problème, ajoutez l'entrée de fichier manifeste suivante <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> afin de pouvoir compiler et exécuter avec un minSDK de 23.
  • Une session peut devenir non valide dans diverses situations qui recréent automatiquement l'activité, y compris le redimensionnement d'un panneau principal, la connexion de périphériques et le passage du mode clair au mode sombre. Si vous rencontrez des problèmes d'invalidation de session, vous pouvez, par exemple, rendre votre panneau principal non redimensionnable, utiliser une entité de panneau dynamique, désactiver la recréation d'activité pour des modifications de configuration spécifiques ou désactiver les changements de thème en mode clair/sombre.
  • Les composants déplaçables 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 RuntimeException.
  • Définir la skybox sur "null" via `SpatialEnvironment.setSpatialEnvironmentPreference()` ne produit pas une skybox noire unie comme indiqué dans la documentation. Il peut en résulter la skybox par défaut du système ou aucune modification de la skybox actuelle.
  • Les clients SceneCore doivent ajouter implementation(“com.google.guava:listenablefuture-1.0”) à la 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 à tort com.google.guava:guava-31.1-android et com.google.protobuf:protobuf-javalite en tant que dépendances transitives. Si cela entraîne des erreurs de classe en double dans votre build, ces deux dépendances peuvent être exclues sans problème.
  • 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.