Ajouter des environnements spatiaux à votre application

Dans le SDK Jetpack XR, les environnements spatiaux sont des environnements immersifs que vous pouvez ajouter à votre application pour personnaliser l'arrière-plan de la scène virtuelle. Les environnements spatiaux ne sont visibles que lorsque l'application est en mode d'affichage complet.

Présentation des environnements spatiaux

Un SpatialEnvironment permet de gérer les préférences d'environnement spatial d'une application. Il s'agit d'un composite d'une image de skybox autonome et d'une géométrie spécifiée par glTF. Vous ne pouvez définir qu'une seule image de ciel et un seul fichier de géométrie glTF à la fois.

Une skybox représente l'image que l'utilisateur voit autour de lui dans la scène virtuelle, créant l'illusion d'un environnement d'arrière-plan lointain, comme un ciel, des montagnes ou un paysage urbain. L'utilisateur ne peut pas interagir avec le skybox ni s'en approcher. Le SDK Jetpack XR est compatible avec les skyboxes sphériques dans la norme OpenEXR. En plus de fournir un arrière-plan immersif pour votre application, un skybox EXR fournit également un éclairage basé sur l'image (IBL) aux modèles 3D chargés par votre application. Pour en savoir plus, consultez le guide d'utilisation des modèles 3D.

Les environnements spatiaux peuvent également inclure du contenu de géométrie 3D dans la norme glTF. La géométrie de l'environnement chargée de cette manière sera automatiquement alignée sur le sol réel. La géométrie de l'environnement est un excellent moyen d'ajouter du réalisme à votre environnement grâce à des éléments de premier plan et d'arrière-plan qui se fondent dans le skybox avec l'effet de parallaxe.

Dans les conseils de conception pour les environnements spatiaux, vous pouvez découvrir les différents types d'assets que vous pouvez utiliser pour créer des environnements spatiaux, et comment créer des environnements spatiaux sûrs et agréables.

Vous pouvez définir l'environnement spatial de votre application sur l'une des trois configurations suivantes:

  • Combinaison d'une image de skybox et d'une géométrie glTF.
  • Surface de transmission, où l'environnement affiché est un flux en direct des caméras extérieures de l'appareil. À pleine opacité, cette surface de transmission masque complètement le skybox et la géométrie.
  • Configuration mixte, où la surface de transmission n'est pas à pleine opacité, ni à zéro opacité. Dans ce cas, la surface de transmission devient semi-transparente et l'alpha se mélange à la boîte de ciel et à la géométrie derrière elle.

Fonctionnalités spatiales pour les environnements spatiaux

Importer et charger des ressources d'environnement spatial

Les ressources glTF et EXR pour les environnements spatiaux sont chargées de manière asynchrone à l'aide de la classe Session.

Créer une ressource glTF

Une ressource glTF peut être créée en tant que GltfModel, où le glTF est chargé à partir d'un fichier local. Un GltfModel peut être utilisé dans un environnement d'application spatiale.

val environmentGeometryFuture = GltfModel.create(session, "DayGeometry.glb")
val environmentGeometry = environmentGeometryFuture.await()
Environments.kt

Créer une ressource image EXR

Une ressource d'image EXR peut être créée en tant que ExrImage, où l'EXR est chargé à partir d'un fichier local. Un ExrImage peut être utilisé avec cmgen pour créer un fichier ZIP de l'IBL pour vos skyboxes. Pour en savoir plus, consultez notre guide sur l'optimisation des composants d'environnement.

val lightingForSkybox = ExrImage.create(session, "BlueSkyboxLighting.zip")
Environments.kt

Définir la préférence SpatialEnvironment pour votre application

setSpatialEnvironmentPreference permet de définir l'environnement spatial préféré pour une application. Cette méthode ne définit qu'une préférence et ne provoque pas de changement immédiat, sauf si isSpatialEnvironmentPreferenceActive est déjà défini sur "true". Une fois que l'appareil est dans un état où l'arrière-plan XR peut être modifié et que la fonctionnalité SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT est disponible, l'environnement spatial préféré pour l'application s'affiche automatiquement.

Définir la préférence sur "null" désactive l'environnement spatial préféré pour l'application, ce qui signifie que l'environnement système par défaut s'affiche à la place.

Si l'élément SpatialEnvironmentPreference donné n'est pas nul, mais que toutes ses propriétés sont nulles, l'environnement spatial se compose d'un skybox noir et d'aucune géométrie.

Pour recevoir des notifications concernant les modifications apportées à l'état de SpatialEnvironment, utilisez addOnSpatialEnvironmentChangedListener.

Utilisation de base

Cet extrait de code crée la géométrie de l'environnement et les ressources de skybox, puis définit la préférence d'environnement spatial. Cette préférence sera mémorisée et appliquée lorsque l'application pourra définir son propre environnement.

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
val preferenceResult =
    session.scene.spatialEnvironment.setSpatialEnvironmentPreference(spatialEnvironmentPreference)
if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangeApplied()) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangePending()) {
    // The environment is in the process of being updated. Once visible, any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
}
Environments.kt

Utilisation avancée

Pour des cas d'utilisation plus avancés où vous avez besoin d'un contrôle plus précis de l'environnement, vous pouvez intégrer des vérifications SpatialCapabilities et implémenter un addOnSpatialEnvironmentChangedListener pour déterminer quand vous souhaitez définir la préférence d'environnement spatial.

Définir la préférence PassthroughOpacity pour l'environnement spatial de votre application

L'un des composants de l'arrière-plan virtuel immersif d'une application est une surface de passthrough. Dans ce cas, l'arrière-plan affiché est un flux en direct provenant des caméras extérieures de l'appareil.

setPassthroughOpacityPreference permet de définir l'opacité de transmission préférée pour une application. Cette méthode ne définit qu'une préférence et ne provoque pas de changement immédiat, sauf si la fonctionnalité SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL est disponible. Une fois que l'appareil est dans un état où l'opacité de la transparence peut être modifiée et que la fonctionnalité SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL est disponible, l'opacité de transparence préférée pour l'application est automatiquement appliquée.

Les valeurs de préférence d'opacité de la transparence varient de 0.0f (opacité nulle, où la surface de transparence n'est pas visible) à 1.0f (opacité totale, où la surface de transparence masque l'environnement spatial). Le paramètre setPassthroughOpacityPreference est un nombre à virgule flottante pouvant être nul. Définir la valeur sur "null" indique que l'application n'a aucune préférence d'opacité de passthrough et renverra le contrôle de passthrough au système.

Utilisation de base

Cet extrait de code définit la préférence d'opacité de la transparence. Cette préférence sera mémorisée et appliquée lorsque l'application pourra définir l'opacité de la transparence.

val preferenceResult = session.scene.spatialEnvironment.setPassthroughOpacityPreference(1.0f)
if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangeApplied()) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified
} else if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangePending()) {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the
    // SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL capability.
    // Then, any listeners specified using addOnPassthroughOpacityChangedListener
    // will be notified
}
Environments.kt

Utilisation avancée

Pour les cas d'utilisation plus avancés où vous avez besoin d'un contrôle plus précis de l'opacité de la transparence, vous pouvez intégrer des vérifications SpatialCapabilities et ajouter un écouteur à l'aide de addOnPassthroughOpacityChangedListener pour déterminer quand vous souhaitez définir la préférence d'opacité de la transparence.

Optimisation des composants

Lorsque vous créez des éléments pour définir les SpatialEnvironment de vos utilisateurs, assurez-vous qu'ils offrent une résolution de haute qualité tout en conservant une taille de fichier raisonnable. Pour en savoir plus, consultez nos conseils pour optimiser les composants d'environnement.

Déterminer l'opacité de transmission actuelle

val currentPassthroughOpacity = session.scene.spatialEnvironment.getCurrentPassthroughOpacity()
Environments.kt

Voir aussi