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 spaziali sono visibili solo quando un'app è in modalità Spazio completo.

Panoramica degli ambienti spaziali

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

Una skybox rappresenta l'immagine che un utente vede intorno a sé nella scena virtuale, creando l'illusione di un ambiente di sfondo distante, come un cielo, montagne o un paesaggio urbano. L'utente non può interagire con la skybox né avvicinarsi. L'SDK Jetpack XR supporta le skybox sferiche nello standard OpenEXR. Oltre a fornire uno sfondo immersivo per la tua app, una skybox EXR fornisce anche l'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 del mondo reale. La geometria dell'ambiente è un ottimo modo per aggiungere realismo al tuo ambiente tramite elementi in primo piano e a metà piano che si fondono con la skybox con l'effetto parallasse.

Nella guida alla progettazione per gli 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 una geometria glTF.
  • Una superficie passthrough, in cui l'ambiente visualizzato è un feed in diretta delle videocamere rivolte verso l'esterno del dispositivo. A opacità completa, questa superficie passthrough occlude completamente la skybox e la geometria.
  • Una configurazione mista, in cui la superficie passthrough non è completamente opaca né completamente trasparente. In questo caso, la superficie passthrough diventa semitrasparente e si fonde con la skybox e la geometria dietro di essa.

Funzionalità spaziali per ambienti spaziali

Importare e caricare 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, dove glTF viene caricato da un file locale. Un GltfModel può essere utilizzato come parte di un ambiente di app spaziali.

val environmentGeometry = GltfModel.create(session, Paths.get("DayGeometry.glb"))
Environments.kt

Crea una risorsa immagine EXR

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

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

Imposta il SpatialEnvironmentPreference per la tua app

La proprietà preferredSpatialEnvironment controlla l'ambiente spaziale preferito per un'app. Quando questa proprietà viene utilizzata per impostare una preferenza, non causa una modifica immediata a meno che isPreferredSpatialEnvironmentActive non sia già true. Una volta che 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 viene visualizzato automaticamente.

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

Se il valore SpatialEnvironmentPreference specificato non è null, ma tutte le sue proprietà sono null, l'ambiente spaziale sarà costituito da una skybox nera e nessuna geometria.

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

Utilizzo di base

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

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

Utilizzo avanzato

Per casi d'uso più avanzati in cui è necessario un controllo più preciso sull'ambiente, puoi incorporare 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 passthrough. In questo caso, lo sfondo visualizzato è un feed in diretta delle videocamere esterne del dispositivo.

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

I valori per la preferenza di opacità passthrough vanno da 0.0f (opacità zero, dove la superficie passthrough non è visibile) a 1.0f (opacità completa, dove la superficie passthrough nasconde l'ambiente spaziale). Il parametro setPassthroughOpacityPreference è un float che ammette valori nulli. Se imposti il valore su null, 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à passthrough. Questa preferenza verrà memorizzata e applicata quando l'app avrà la possibilità di impostare l'opacità 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

Utilizzo avanzato

Per casi d'uso più avanzati in cui è necessario un controllo più preciso dell'opacità del passthrough, puoi incorporare i controlli SpatialCapabilities e aggiungere un listener utilizzando addOnPassthroughOpacityChangedListener per determinare quando impostare la preferenza di opacità del passthrough.

Ottimizzazione degli asset

Quando crei asset per impostare il SpatialEnvironment dei tuoi utenti, assicurati che gli asset raggiungano una risoluzione di alta qualità mantenendo una dimensione ragionevole del file. Per saperne di più, consulta le nostre indicazioni sull'ottimizzazione degli asset dell'ambiente.

Determinare l'opacità passthrough attuale

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

Vedi anche