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 relative all'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.

Un'immagine satellitare 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à automaticamente allineata 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 ambienti spaziali

Importa e carica le risorse dell'ambiente spaziale

Le risorse glTF ed EXR per gli ambienti spaziali vengono caricate in modo asincrono nella classe Session. Questi file devono essere archiviati nella cartella degli asset.

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.

// assume that session is a Session that has been previously created
val environmentGeometryFuture = session.createGltfResourceAsync("DayGeometry.glb")

val environmentGeometry = environmentGeometryFuture.await()

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 ExrImage può essere utilizzato nell'ambito di un ambiente di app spaziali per disegnare skybox.

// assume that session is a Session that has been previously created
val skyboxExrFuture = session.createExrImageResourceAsync("BlueSkybox.exr")

val skyboxExr = skyboxExrFuture.await()

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, l'ambiente spaziale preferito per l'applicazione verrà visualizzato automaticamente.

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

// 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.
}

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 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, quando la superficie di transizione non è visibile) a 1.0f (opacità completa, quando 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.

// 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
}

Utilizzo avanzato

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

Ottimizzazione degli asset

Quando crei asset per impostare il SpatialEnvironment degli utenti, devi assicurarti che i tuoi asset raggiungano una risoluzione di alta qualità mantenendo dimensioni ragionevoli dei file. Assicurati che il file glb utilizzi mipmap e texture ktx2. Inoltre, tieni conto del numero di poligoni nei file glb, poiché un numero elevato di poligoni può comportare un consumo di energia non necessario. La maggior parte delle dimensioni del file per la maggior parte delle istanze di SpatialEnvironment proviene dall'immagine utilizzata per la sfera. Per assicurarti che le immagini siano ottimizzate, sottoponi gli asset a uno strumento di ottimizzazione (ad es. ktx).

Determina l'attuale opacità del passthrough

val currentPassthroughOpacity =  session.spatialEnvironment.getCurrentPassthroughOpacity()

Vedi anche