Ajouter des environnements spatiaux à 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 →

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 lorsqu'une application est en Full Space.

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'une combinaison d'une image skybox autonome et d'une géométrie spécifiée par glTF. Vous ne pouvez définir qu'une seule image skybox et un seul fichier de géométrie glTF à la fois.

Une skybox représente l'image qu'un utilisateur voit autour de lui dans la scène virtuelle, créant l'illusion d'un environnement d'arrière-plan distant, comme un ciel, des montagnes ou un paysage urbain. L'utilisateur ne peut pas interagir avec la skybox ni s'en approcher. Le SDK Jetpack XR est compatible avec les skybox sphériques au format OpenEXR. En plus de fournir un arrière-plan immersif à votre application, une 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 au format glTF standard. La géométrie d'environnement chargée de cette manière sera automatiquement alignée sur le sol du monde réel. La géométrie d'environnement est un excellent moyen d'ajouter du réalisme à votre environnement grâce à des éléments de premier et de deuxième plans qui se fondent dans la skybox avec l'effet de parallaxe.

Dans les conseils de conception pour les environnements spatiaux, vous découvrirez les différents types d'éléments que vous pouvez utiliser pour créer des environnements spatiaux, ainsi que 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 :

  • Une combinaison d'une image skybox et d'une géométrie glTF.
  • Une surface de transfert, où l'environnement affiché est un flux en direct des caméras externes de l'appareil. À pleine opacité, cette surface de transfert occulte complètement la skybox et la géométrie.
  • Une configuration mixte, où la surface de transfert n'est ni à pleine opacité ni à opacité nulle. Dans ce cas, la surface de transfert devient semi-transparente et se mélange alpha avec la skybox 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 par l'utilisation 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 environmentGeometry = GltfModel.create(session, Paths.get("DayGeometry.glb"))

Créer une ressource d'éclairage basée sur l'image

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

val lightingForSkybox = ImageBasedLightingAsset.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))

Définir la SpatialEnvironmentPreference pour votre application

La propriété preferredSpatialEnvironment contrôle l'environnement spatial préféré d'une application. Lorsque cette propriété est utilisée pour définir une préférence, elle n'entraîne pas de modification immédiate, sauf si isPreferredSpatialEnvironmentActive est déjà true. Une fois que l'appareil entre dans un état où l'arrière-plan XR peut être modifié et que la SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT fonctionnalité est disponible, l'environnement spatial préféré de l'application s'affiche automatiquement.

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

Si le SpatialEnvironmentPreference donné n'est pas nul, mais que toutes ses propriétés sont nulles, l'environnement spatial sera constitué d'une skybox noire et d'aucune géométrie.

Pour être informé des modifications apportées à l'état SpatialEnvironment, utilisez addOnSpatialEnvironmentChangedListener.

Utilisation de base

Cet extrait de code crée la géométrie de l'environnement et les ressources de la 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 aura la possibilité de définir son propre environnement.

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
session.scene.spatialEnvironment.preferredSpatialEnvironment = spatialEnvironmentPreference
if (session.scene.spatialEnvironment.isPreferredSpatialEnvironmentActive) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the SPATIAL_CAPABILITY_APP_ENVIRONMENT capability.
    // Then, any listeners specified using addOnSpatialEnvironmentChangedListener
    // will be notified.
}

Utilisation avancée

Pour les 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 PassthroughOpacityPreference 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 transfert. Dans ce cas, l'arrière-plan affiché est un flux en direct des caméras externes de l'appareil.

setPassthroughOpacityPreference permet de définir l'opacité de transfert préférée d'une application. Cette méthode ne définit qu'une préférence et n'entraîne pas de modification immédiate, sauf si la fonctionnalité SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL est disponible. Une fois que l'appareil entre dans un état où l'opacité de transfert peut être modifiée et que la fonctionnalité SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL est disponible, l'opacité de transfert préférée de l'application est automatiquement appliquée.

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

Utilisation de base

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

session.scene.spatialEnvironment.preferredPassthroughOpacity = 1.0f
if (session.scene.spatialEnvironment.currentPassthroughOpacity == 1.0f) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified.
} else {
    // 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.
}

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 transfert, 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 transfert.

Optimisation des composants

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

Déterminer l'opacité de transfert actuelle

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

Voir aussi