Aggiungere ambienti spaziali all'app

Dispositivi XR applicabili

Queste indicazioni ti aiutano a creare esperienze per questi tipi di dispositivi XR.

Scopri di più sui tipi di dispositivi XR →

Scopri di più sui tipi di dispositivi XR →

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

Panoramica degli ambienti spaziali

Un SpatialEnvironment gestisce le preferenze dell'ambiente spaziale di un'app. È una combinazione 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, delle montagne o un paesaggio urbano. L'utente non può interagire con la skybox o avvicinarsi ad essa. 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 all' utilizzo dei 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 in secondo piano che si fondono con la skybox con l'effetto di parallasse.

Nelle indicazioni di 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 di passthrough, in cui l'ambiente visualizzato è un feed in diretta delle videocamere rivolte verso l'esterno del dispositivo. Con opacità completa, questa superficie di passthrough occlude completamente la skybox e la geometria.
• Una configurazione mista, in cui la superficie di passthrough non è a opacità completa né a opacità zero. In questo caso, la superficie di passthrough diventa semitrasparente e si fonde con la skybox e la geometria dietro di essa.

Funzionalità spaziali per gli ambienti spaziali

• SpatialCapabilities: rappresenta le funzionalità spaziali della sessione corrente. Alcune funzionalità spaziali sono pertinenti agli ambienti spaziali.

• SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL: indica se l'attività può attivare o disattivare il passthrough al momento.

• SPATIAL_CAPABILITY_APP_ENVIRONMENT: indica se l'attività può impostare il proprio ambiente spaziale al momento.

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.

Creare una risorsa glTF

Una risorsa glTF può essere creata come GltfModel, in cui il glTF viene caricato da un file locale. Un GltfModel può essere utilizzato come parte di un ambiente di app spaziale.

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

Creare una risorsa di illuminazione basata su immagini

Una risorsa di illuminazione basata su immagini può essere creata come ImageBasedLightingAsset, in cui l'illuminazione viene caricata da un file locale. Un ImageBasedLightingAsset può essere utilizzato con cmgen per creare un file ZIP dell'IBL per le skybox. Per ulteriori dettagli, consulta la nostra guida all'ottimizzazione degli asset dell'ambiente.

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

Impostare SpatialEnvironmentPreference per l'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 SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT funzionalità è 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 e verrà visualizzato l'ambiente di sistema predefinito.

Se il valore di 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 della skybox, quindi imposta la preferenza dell'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)
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 dell'ambiente, puoi incorporare SpatialCapabilities controlli e implementare un addOnSpatialEnvironmentChangedListener per determinare quando vuoi impostare la preferenza dell'ambiente spaziale.

Impostare PassthroughOpacityPreference per l'ambiente spaziale dell'app

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

setPassthroughOpacityPreference viene utilizzato per impostare l'opacità di passthrough 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. Una volta che il dispositivo entra in uno stato in cui l'opacità di passthrough può essere modificata e la funzionalità SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL è disponibile, l'opacità di passthrough preferita per l'applicazione verrà applicata automaticamente.

I valori per la preferenza di opacità di passthrough vanno da 0.0f (opacità zero, in cui la superficie di passthrough non è visibile) a 1.0f (opacità completa, in cui la superficie di passthrough nasconde l'ambiente spaziale). Il parametro setPassthroughOpacityPreference è un float nullable. Se imposti il valore su null, indichi che l'app non ha una preferenza di opacità di passthrough e restituirà il controllo di passthrough al sistema.

Utilizzo di base

Questo snippet di codice imposta la preferenza di opacità di passthrough. Questa preferenza verrà memorizzata e applicata quando l'app avrà la possibilità di impostare l'opacità di 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à di passthrough, puoi incorporare i controlli SpatialCapabilities e aggiungere un listener utilizzando addOnPassthroughOpacityChangedListener per determinare quando vuoi impostare la preferenza di opacità di passthrough.

Ottimizzazione degli asset

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

Determinare l'opacità di passthrough corrente

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

Vedi anche

• Indicazioni di progettazione per gli ambienti spaziali