Aggiungere ambienti spaziali all'app

Nell'SDK Jetpack XR, gli ambienti spaziali sono ambienti immersivi che puoi aggiungere alla tua app per personalizzare lo sfondo della scena virtuale. Gli ambienti spatiali sono visibili solo quando un'app è in modalità Spazio intero.

Panoramica degli ambienti spaziali

Un SpatialEnvironment viene utilizzato per gestire le preferenze dell'ambiente spaziale di un'app. È un'immagine composita di uno skybox autonomo e di una geometria specificata da glTF. È possibile impostare una sola immagine skybox e un solo file di geometria glTF alla volta.

Uno skybox rappresenta l'immagine che un utente vede intorno a sé nella scena virtuale, creando l'illusione di un ambiente di sfondo lontano, come un cielo, montagne o un panorama urbano. L'utente non può interagire con la cupoletta o avvicinarsi. L'SDK Jetpack XR supporta gli skybox sferici nello standard OpenEXR. Oltre a fornire un sfondo immersivo per la tua app, una skybox EXR fornisce anche illuminazione basata su immagini (IBL) ai modelli 3D caricati dalla tua app. Per ulteriori informazioni, consulta la guida per lavorare con i modelli 3D.

Gli ambienti spaziali possono includere anche contenuti di geometria 3D nello standard glTF. La geometria dell'ambiente caricata in questo modo verrà allineata automaticamente al pavimento reale. La geometria dell'ambiente è un ottimo modo per aggiungere realismo all'ambiente tramite elementi in primo piano e in secondo piano che si fondono con la skybox con l'effetto parallasse.

Nelle linee guida per la progettazione di ambienti spaziali, puoi scoprire i diversi tipi di asset che puoi utilizzare per creare ambienti spaziali e come creare ambienti spaziali sicuri e piacevoli.

Puoi impostare l'ambiente spaziale della tua app su una di queste tre configurazioni:

  • Una combinazione di un'immagine skybox e della geometria glTF.
  • Una superficie di passaggio, in cui l'ambiente visualizzato è un feed in diretta proveniente dalle fotocamere esterne del dispositivo. A opacità massima, questa superficie di transizione occlude completamente la skybox e la geometria.
  • Una configurazione mista, in cui la superficie di transizione non è completamente opaca né completamente trasparente. In questo caso, la superficie di transizione diventa semitrasparente e l'alpha si fonde con la skybox e la geometria dietro.

Funzionalità spaziali per gli ambienti spaziali

Importa e carica le risorse dell'ambiente spaziale

Le risorse glTF ed EXR per gli ambienti spaziali vengono caricate in modo asincrono utilizzando la classe Session.

Crea una risorsa glTF

Una risorsa glTF può essere creata come GltfModel, in cui il modello glTF viene caricato da un file locale. Un GltfModel può essere utilizzato nell'ambito di un ambiente di app spaziali.

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

Crea una risorsa immagine EXR

Una risorsa immagine EXR può essere creata come ExrImage, in cui l'EXR viene caricato da un file locale. Un file ExrImage può essere utilizzato con cmgen per creare un file ZIP dell'IBL per le tue skybox. Per ulteriori dettagli, consulta la nostra guida sull'ottimizzazione degli asset dell'ambiente.

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

Impostare la preferenza di ambiente spaziale per l'app

setSpatialEnvironmentPreference viene utilizzato per impostare l'ambiente spaziale preferito per un'app. Questo metodo imposta solo una preferenza e non causa una modifica immediata, a meno che isSpatialEnvironmentPreferenceActive non sia già impostato su true. Quando il dispositivo entra in uno stato in cui lo sfondo XR può essere modificato e la funzionalità SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT è disponibile, viene visualizzato automaticamente l'ambiente spaziale preferito per l'applicazione.

Se imposti la preferenza su null, l'ambiente spaziale preferito per l'app verrà disattivato, il che significa che verrà visualizzato l'ambiente di sistema predefinito.

Se SpatialEnvironmentPreference specificato non è nullo, ma tutte le sue proprietà sono nulle, l'ambiente spaziale sarà costituito da un cielo nero e nessuna geometria.

Per ricevere una notifica delle modifiche allo stato SpatialEnvironment, utilizza addOnSpatialEnvironmentChangedListener.

Utilizzo di base

Questo snippet di codice crea le risorse della geometria e della skybox dell'ambiente e poi imposta la preferenza per l'ambiente spaziale. Questa preferenza verrà memorizzata e applicata quando l'app avrà la possibilità di impostare il proprio ambiente.

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

Utilizzo avanzato

Per casi d'uso più avanzati in cui hai bisogno di un controllo più preciso sull'ambiente, puoi incorporare i controlli SpatialCapabilities e implementare un addOnSpatialEnvironmentChangedListener per determinare quando impostare la preferenza per l'ambiente spaziale.

Imposta la PassthroughOpacityPreference per l'ambiente spaziale della tua app

Uno dei componenti dello sfondo virtuale immersivo di un'app è una superficie di transizione. In questo caso, lo sfondo visualizzato è un feed in diretta delle videocamere rivolte verso l'esterno del dispositivo.

setPassthroughOpacityPreference viene utilizzato per impostare l'opacità di transizione preferita per un'app. Questo metodo imposta solo una preferenza e non causa una modifica immediata, a meno che la funzionalità SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL non sia disponibile. Quando il dispositivo entra in uno stato in cui l'opacità di transizione può essere modificata e la funzionalità SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL è disponibile, l'opacità di transizione preferita per l'applicazione verrà applicata automaticamente.

I valori per la preferenza di opacità di transizione vanno da 0.0f (opacità zero, dove la superficie di transizione non è visibile) a 1.0f (opacità completa, dove la superficie di transizione nasconde l'ambiente spaziale). Il parametro setPassthroughOpacityPreference è un valore float con valori null. L'impostazione del valore su null indica che l'app non ha preferenze di opacità passthrough e restituisce il controllo passthrough al sistema.

Utilizzo di base

Questo snippet di codice imposta la preferenza di opacità di transizione. Questa preferenza verrà memorizzata e applicata quando l'app ha la possibilità di impostare l'opacità di transizione.

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

Utilizzo avanzato

Per casi d'uso più avanzati in cui hai bisogno di un controllo più preciso sull'opacità di transizione, puoi incorporare i controlli SpatialCapabilities e aggiungere un ascoltatore utilizzando addOnPassthroughOpacityChangedListener per determinare quando vuoi impostare la preferenza di opacità di transizione.

Ottimizzazione degli asset

Quando crei asset per impostare il SpatialEnvironment degli utenti, assicurati che raggiungano una risoluzione di alta qualità mantenendo al contempo dimensioni del file ragionevoli. Per saperne di più, consulta le nostre indicazioni sull'ottimizzazione degli asset ambiente.

Determina l'attuale opacità del passthrough

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

Vedi anche