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 plein écran.
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 marie avec le skybox et la géométrie derrière elle.
Fonctionnalités spatiales pour les environnements spatiaux
SpatialCapabilities: représente les fonctionnalités spatiales de la session en cours. Certaines fonctionnalités spatiales sont pertinentes pour les environnements spatiaux.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL: indique si l'activité peut activer ou désactiver le passthrough au moment actuel.SPATIAL_CAPABILITY_APP_ENVIRONMENT: indique si l'activité peut définir son propre environnement spatial au moment actuel.
Importer et charger des ressources d'environnement spatial
Les ressources glTF et EXR pour les environnements spatiaux sont chargées de manière asynchrone dans la classe Session. Ces fichiers doivent être stockés dans le dossier "assets".
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.
// assume that session is a Session that has been previously created
val environmentGeometryFuture = session.createGltfResourceAsync("DayGeometry.glb")
val environmentGeometry = environmentGeometryFuture.await()
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é dans un environnement d'application spatiale pour dessiner des skyboxes.
// assume that session is a Session that has been previously created
val skyboxExrFuture = session.createExrImageResourceAsync("BlueSkybox.exr")
val skyboxExr = skyboxExrFuture.await()
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 de modifications de 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.
// Assume that session is a Session that has been previously created
// Create a GLTFResource
val environmentGeometry = session.createGltfResourceAsync("DayGeometry.glb").await()
// Create an ExrImage for the skybox
val skyboxExr = session.createExrImageResourceAsync("BlueSkybox.exr").await()
val spatialEnvironmentPreference = SpatialEnvironmentPreference(skyboxExr, environmentGeometry)
val preferenceResult = session.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.
}
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.
// Assume that session is a Session that has been previously created
val preferenceResult = session.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
}
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 transmission, vous pouvez intégrer des vérifications SpatialCapabilities et implémenter un addOnPassthroughOpacityChangedListener pour déterminer quand vous souhaitez définir la préférence d'opacité de transmission.
Optimisation des composants
Lorsque vous créez des éléments pour définir les SpatialEnvironment de vos utilisateurs, vous devez vous assurer qu'ils offrent une résolution de haute qualité tout en conservant une taille de fichier raisonnable. Assurez-vous que votre glb utilise des mipmaps et des textures ktx2. Vous devez également être attentif au nombre de polygones dans vos fichiers glb, car un nombre élevé de polygones peut entraîner une consommation d'énergie inutile. La majeure partie de la taille de fichier de la plupart des instances SpatialEnvironment provient de l'image utilisée pour le skybox. Pour vous assurer que vos images sont optimisées, exécutez les composants via un outil d'optimisation (ktx, par exemple).
Déterminer l'opacité de transmission actuelle
val currentPassthroughOpacity = session.spatialEnvironment.getCurrentPassthroughOpacity()