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 lorsqu'une application est en mode d'affichage complet.

Présentation des environnements spatiaux

Un SpatialEnvironment est utilisé pour gérer les préférences de l'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 au format glTF. Vous ne pouvez définir qu'une seule image de 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 lointain, 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 skyboxes 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 des images (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 standard 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 de plan intermédiaire qui se fondent dans la 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, ainsi que la façon de 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 skybox et d'une géométrie glTF.
  • Surface de transparence, où l'environnement affiché est un flux en direct des caméras orientées vers l'extérieur de l'appareil. À pleine opacité, cette surface de transfert occulte complètement la skybox et la géométrie.
  • Configuration mixte, où la surface de transmission n'est pas à pleine opacité ni à opacité nulle. Dans ce cas, la surface de transmission devient semi-transparente et se mélange à 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 à 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 environmentGeometry = GltfModel.create(session, Paths.get("DayGeometry.glb"))
Environments.kt

Créer une ressource d'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 éléments d'environnement.

val lightingForSkybox = ExrImage.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))
Environments.kt

Définir le SpatialEnvironmentPreference pour votre application

La propriété preferredSpatialEnvironment contrôle l'environnement spatial préféré pour une application. Lorsque cette propriété est utilisée pour définir une préférence, elle n'entraîne pas de changement immédiat, sauf si isPreferredSpatialEnvironmentActive 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é de l'application s'affiche automatiquement.

Si vous définissez la préférence sur null, l'environnement spatial préféré sera désactivé pour l'application, ce qui signifie que l'environnement système par défaut sera affiché à la place.

Si la SpatialEnvironmentPreference donnée n'est pas nulle, mais que toutes ses propriétés le sont, l'environnement spatial se composera d'une skybox noire et d'aucune géométrie.

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

Utilisation de base

Cet extrait de code crée les ressources de géométrie et de skybox de l'environnement, 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.
}
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'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 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 provenant des caméras orientées vers l'extérieur de l'appareil.

setPassthroughOpacityPreference permet de définir l'opacité préférée du mode Passthrough pour une application. Cette méthode ne définit qu'une préférence et n'entraîne 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é du mode Passthrough peut être modifiée et que la fonctionnalité SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL est disponible, l'opacité du mode Passthrough préférée pour l'application est automatiquement appliquée.

Les valeurs de préférence d'opacité de la vue traversante vont de 0.0f (opacité nulle, où la surface de la vue traversante n'est pas visible) à 1.0f (opacité totale, où la surface de la vue traversante masque l'environnement spatial). Le paramètre setPassthroughOpacityPreference est un float pouvant être une valeur nulle. Si vous définissez la valeur sur "null", cela indique que l'application n'a aucune préférence d'opacité pour la transparence et que le contrôle de la transparence sera renvoyé au système.

Utilisation de base

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

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.
}
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 l'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 sur l'optimisation des composants d'environnement.

Déterminer l'opacité de la transparence actuelle

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity
Environments.kt

Voir aussi