Crea con i container spaziali

Dispositivi XR applicabili
Queste indicazioni ti aiutano a creare esperienze per questi tipi di dispositivi XR.
Scopri di più sui tipi di dispositivi XR →
Visori XR
Occhiali XR con cavo
Scopri di più sui tipi di dispositivi XR →

I contenitori spaziali portano il windowing volumetrico in OpenXR. Definito dalle estensioni XR_EXT_spatial_container e XR_EXT_spatial_container_self_rendering in OpenXR 1.1, un contenitore spaziale è una regione volumetrica 3D gestita dal sistema nello spazio dell'utente in cui l'app esegue il rendering dei contenuti 3D utilizzando i livelli di composizione OpenXR standard.

In genere, una sessione OpenXR richiede l'accesso esclusivo all'intero campo visivo dell'utente. I container spaziali consentono alla tua app di eseguire il rendering di contenuti OpenXR 3D all'interno di un riquadro 3D delimitato nell'ambiente dell'utente o di passare in qualsiasi momento a un'esperienza immersiva a schermo intero non delimitata.

Informazioni sui container spaziali

Un container spaziale è una regione 3D delimitata o non delimitata gestita dal sistema Android XR e sottoposta a rendering dalla tua app OpenXR:

  • Modalità delimitata: l'app suggerisce dimensioni 3D (larghezza, altezza e profondità in metri) e il sistema alloca un riquadro di delimitazione 3D nell'ambiente dell'utente. La tua app esegue il rendering di contenuti 3D stereo all'interno del volume e il sistema ritaglia i contenuti visualizzati in base ai confini della casella 3D.
  • Modalità immersiva: il contenitore spaziale si espande fino a limiti infiniti, offrendo alla tua app l'intero campo visivo dell'utente, come una sessione OpenXR tradizionale a schermo intero.
Tre container spaziali in esecuzione contemporaneamente in modalità spazio intero: un container arancione per il terreno 3D bloccato sul pavimento, un modello 3D blu di un'anatra con UI 2D collegata e un container verde per l'UI 2D.
Figura 1. Più container spaziali in modalità spazio intero: un volume di terreno 3D bloccato sul pavimento (a sinistra), un volume di papera 3D accoppiato con un'UI 2D (al centro) e un container UI 2D (a destra).

In che modo gli utenti interagiscono con i contenitori spaziali

Il sistema Android XR gestisce i controlli della finestra del contenitore spaziale e il posizionamento nello spazio fisico, fornendo un modello di interazione coerente tra le app:

  • Spostamento e riposizionamento: gli utenti possono afferrare l'handle di sistema di un contenitore spaziale utilizzando gesti con le mani (ad esempio pizzicando) o controller di movimento per riposizionarlo nello spazio 3D.
  • Riduzione a icona e chiusura: i controlli della finestra di sistema consentono agli utenti di ridurre a icona o chiudere singoli container spaziali. Quando un utente chiude un container, il sistema invia una notifica alla tua app in modo che possa liberare le risorse.
  • Blocco al pavimento con comprensione della scena: quando la tua app dichiara e richiede l'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE, il sistema attiva automaticamente l'aggancio alla superficie in modo che gli utenti possano posizionare e bloccare un contenitore spaziale al pavimento fisico senza ulteriori configurazioni dell'app, come mostrato dal contenitore arancione del terreno nella Figura 1.
  • Interazione 3D diretta: quando un container è attivo e interattivo, gli utenti possono interagire direttamente con i contenuti 3D all'interno del volume utilizzando il tracciamento delle mani, lo sguardo o i controller 6DoF.
Un utente che interagisce con un'anatra 3D all'interno di un contenitore spaziale blu delimitato utilizzando il tracciamento delle mani.
Figura 2. Un utente interagisce con contenuti 3D all'interno di un contenitore spaziale delimitato utilizzando il tracciamento delle mani.
  • Transizione tra le modalità limitata e immersiva: l'utente o la tua app possono passare da un container tra un riquadro 3D limitato e una visualizzazione immersiva a schermo intero non limitata senza riavviare la sessione OpenXR.
La scena con la papera in 3D dopo la transizione da un contenitore spaziale delimitato a una visualizzazione immersiva a schermo intero non delimitata.
Figura 3. Il contenitore spaziale dopo la transizione dalla modalità delimitata alla modalità immersiva, che riempie il campo visivo dell'utente.
  • Modalità Segui in movimento: poiché il sistema controlla la posa dello spazio delle coordinate di ogni contenitore spaziale (xrCreateSpatialContainerSpaceEXT), gli utenti possono attivare la modalità Segui dai controlli della finestra di sistema in modo che un contenitore 3D delimitato li segua automaticamente e rimanga nel loro campo visivo mentre camminano, senza richiedere alcuna configurazione aggiuntiva nella tua app.

Come utilizzare i container spaziali su Android XR

Quando crei un'app con i container spaziali, progetta la scena in base ai limiti, alle modifiche di stato e alla modalità di fusione dello sfondo del container.

Adatta i contenuti 3D ai limiti del contenitore

In modalità delimitata, l'origine (0, 0, 0) dello spazio del contenitore spaziale (xrCreateSpatialContainerSpaceEXT) si trova al centro del riquadro di delimitazione 3D. Poiché il sistema gestisce la posizione dello spazio del container nell'ambiente dell'utente, la tua app esegue il rendering dei contenuti 3D in relazione a (0, 0, 0), mentre il sistema gestisce il riposizionamento dell'utente e la modalità Segui. Il sistema ritaglia qualsiasi geometria eseguita al di fuori della larghezza, dell'altezza o della profondità della casella in modo che i contenuti rimangano all'interno del volume assegnato.

L'app deve ascoltare gli eventi di modifica dei limiti dal runtime e scalare o riposizionare la scena 3D in modo che i contenuti chiave rientrino nelle dimensioni attuali del container. Quando il container passa alla modalità immersiva, i limiti diventano infiniti e puoi ripristinare la scena alla scala reale 1:1.

Rispondi alle modifiche dello stato del container

Anziché gestire la visibilità e lo stato attivo solo a livello di applicazione, ogni container spaziale segnala il proprio stato in modo che l'app possa reagire di conseguenza:

  • Visibilità: indica se il contenitore è attualmente mostrato o nascosto. Metti in pausa le animazioni, l'audio o gli aggiornamenti della simulazione mentre il contenitore è nascosto. La tua app può anche richiedere di mostrare o nascondere un container.
  • Interattività: indica se il container è attivo e riceve l'input dell'utente dal tracciamento delle mani, dai controller o dallo sguardo. Attiva o disattiva l'evidenziazione interattiva e la gestione degli input quando lo stato attivo cambia.
  • Modalità limiti: indica se il container è attualmente in modalità XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT (ritagliato in un riquadro 3D) o XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT (schermo intero senza limiti). Aggiorna la scala della scena e attiva/disattiva gli elementi visivi dell'ambiente (come skybox o passthrough) quando cambia la modalità. L'app può anche richiedere transizioni tra le modalità limitata e immersiva in qualsiasi momento.

Utilizza la trasparenza con alpha blending in modalità limitata

In modalità delimitata, uno sfondo trasparente consente di mantenere visibili l'ambiente fisico dell'utente e altre finestre intorno ai modelli 3D. Configura la videocamera o l'area visibile con uno sfondo trasparente e utilizza la modalità di fusione dell'ambiente alpha-blend. Quando passi alla modalità immersiva, puoi mantenere il passthrough attivato o passare a un ambiente skybox opaco.

Verifica la disponibilità delle funzionalità e configura il manifest

I container spaziali richiedono un dispositivo Android XR che supporti il livello API spaziale 4 o versioni successive. Anziché controllare direttamente il livello API Android, esegui una query sul runtime OpenXR per determinare se i container spaziali sono supportati chiamando xrEnumerateInstanceExtensionProperties per verificare che XR_EXT_spatial_container e XR_EXT_spatial_container_self_rendering siano disponibili e chiamando xrGetSystemProperties con XrSystemSpatialContainerPropertiesEXT per ispezionare supportsBounded e supportsImmersive.

Prima di creare un'app che utilizza i container spaziali, configura la modalità di avvio dell'attività e le autorizzazioni specifiche per le funzionalità in AndroidManifest.xml.

Attiva la modalità Spazio intero in AndroidManifest.xml

I container spaziali richiedono la modalità spazio intero gestito, anche per le app OpenXR autonome. Le app OpenXR tradizionali a schermo intero dichiarano XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED per assumere il controllo esclusivo del display senza la gestione delle finestre di sistema. Al contrario, un'app che utilizza i container spaziali si affida al compositore di sistema Android XR per gestire i volumi delimitati 3D, i controlli delle finestre e il posizionamento spaziale in modalità spazio intero e deve impostare android.window.PROPERTY_XR_ACTIVITY_START_MODE su XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application ...>
        <!-- Spatial Containers require Full Space Managed mode -->
        <property
            android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
            android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED" />

        <activity android:name=".MainActivity" ...>
            <!-- Optional hint declaring which bounds modes the activity uses -->
            <property
                android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
                android:value="XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT|XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT" />
        </activity>
    </application>
</manifest>

Dichiara e richiedi autorizzazioni specifiche per le funzionalità

La creazione e il rendering di un container spaziale di base non richiedono autorizzazioni di runtime pericolose. Tuttavia, funzionalità specifiche richiedono la dichiarazione e la richiesta delle autorizzazioni Android XR corrispondenti:

  • Per bloccare e ancorare un container spaziale al pavimento fisico utilizzando la comprensione della scena, dichiara e richiedi l'autorizzazione pericolosa android.permission.SCENE_UNDERSTANDING_COARSE in fase di runtime.
  • Per monitorare la posizione della testa dell'utente in OpenXR, dichiara e richiedi android.permission.HEAD_TRACKING.
<uses-permission android:name="android.permission.HEAD_TRACKING" />
<uses-permission android:name="android.permission.SCENE_UNDERSTANDING_COARSE" />

Per informazioni dettagliate sulla dichiarazione e sulla richiesta di autorizzazioni XR pericolose in fase di runtime, consulta Informazioni sulle autorizzazioni per XR.

Abilita i container spaziali nel tuo progetto

Puoi creare con Spatial Containers utilizzando Unity, Godot o direttamente con OpenXR in C++. Seleziona una scheda per visualizzare i prerequisiti, la configurazione dell'editor e l'esempio di codice per l'ambiente che preferisci:

Unità

Prerequisiti

Configura il progetto

  1. Vai a Edit > Impostazioni progetto > XR Plug-in Management > OpenXR.
  2. Fai clic su Impostazioni accanto ad Android XR (Extensions): Session Management e deseleziona Immersive XR.
  3. Nell'elenco OpenXR Feature Groups (Gruppi di funzionalità OpenXR), attiva Spatial Container (Container spaziale).

Utilizza XRSpatialContainerFeature in C# per eseguire query sui limiti, rispondere agli eventi del container e passare dalla modalità delimitata a quella immersiva e viceversa:

void OnEnable()
{
    XRSpatialContainerFeature.OnSpatialContainerBoundsChanged += OnBoundsChanged;
}

private void OnBoundsChanged(Vector3 bounds, bool infiniteBounds)
{
    float minScale = Mathf.Min(bounds.x, bounds.y, bounds.z);
    transform.localScale = infiniteBounds ? Vector3.one : Vector3.one * minScale;
}

public void SetImmersiveMode(bool immersive)
{
    XRSpatialContainerFeature.TryRequestBoundsMode(immersive);
}

Per i passaggi completi di configurazione del progetto, la configurazione del manifest e la gestione delle autorizzazioni, consulta Utilizza i container spaziali in Unity.

Godot

Prerequisiti

Configura il progetto

  1. Vai a Project > Project Settings (Progetto > Impostazioni progetto), attiva Advanced Settings (Impostazioni avanzate) e vai a General > XR > OpenXR > Extensions (Generali > XR > OpenXR > Estensioni).
  2. Nella sottosezione Contenitore spaziale, seleziona Attivato e configura Modalità limiti e Limiti.
  3. Vai a Progetto > Esporta… > Android e seleziona Usa funzionalità sperimentali in Funzionalità di Android XR.

Utilizza il singleton OpenXRSpatialContainerExtension in GDScript per rispondere alle modifiche dei limiti e della modalità del container:

func _ready() -> void:
    if OpenXRSpatialContainerExtension.is_enabled():
        OpenXRSpatialContainerExtension.spatial_container_bounds_changed.connect(
            _on_bounds_changed
        )

func _on_bounds_changed(_rid: RID, bounds: Vector3) -> void:
    scale = Vector3.ONE * min(bounds.x, bounds.y, bounds.z)

func set_immersive_mode() -> void:
    OpenXRSpatialContainerExtension.request_main_spatial_container_bounds_mode(
        OpenXRSpatialContainerState.IMMERSIVE
    )

Per le impostazioni progetto complete, le autorizzazioni di esportazione e gli esempi di GDScript, consulta Utilizza i container spaziali in Godot.

OpenXR

Prerequisiti

Attiva XR_EXT_spatial_container e XR_EXT_spatial_container_self_rendering quando crei XrInstance, quindi crea ed esegui il rendering del container spaziale:

// 1. Enable the Spatial Container extensions during xrCreateInstance
const char* enabledExtensions[] = {
    XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME,
    XR_EXT_SPATIAL_CONTAINER_SELF_RENDERING_EXTENSION_NAME,
};

// 2. Configure and create a self-rendering spatial container
XrSpatialContainerConfigurationSelfRenderingEXT selfRenderingConfig{
    .type = XR_TYPE_SPATIAL_CONTAINER_CONFIGURATION_SELF_RENDERING_EXT,
    .next = nullptr,
    .viewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
    .suggestedBounds = {1.5f, 1.5f, 1.5f}, // Width, height, depth in meters
};

XrSpatialContainerCreateInfoEXT createInfo{
    .type = XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT,
    .next = &selfRenderingConfig,
    .spatialContainerConfig =
        reinterpret_cast<const XrSpatialContainerConfigurationBaseHeaderEXT*>(
            &selfRenderingConfig),
};

XrSpatialContainerEXT spatialContainer = XR_NULL_HANDLE;
xrCreateSpatialContainerEXT(session, &createInfo, &spatialContainer);

// 3. Request bounded mode and make the container visible
xrRequestSpatialContainerBoundsModeEXT(
    spatialContainer, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT);
xrRequestSpatialContainerVisibilityEXT(spatialContainer, XR_TRUE);

Vedi anche

OpenXR™ e il logo OpenXR sono marchi di proprietà di The Khronos Group Inc. e sono registrati come marchi in Cina, nell'Unione Europea, in Giappone e nel Regno Unito.