XR_EXT_spatial_container

Name String

XR_EXT_spatial_container

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

811

Revisione

1

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

OpenXR 1.0

Data ultima modifica

2026-08-06

Stato IP

Nessuna rivendicazione di PI nota.

Collaboratori

Jared Finder, Google
Andreas Loeve Selvik, Meta Platforms
Lachlan Ford, Google
Cass Everitt, Meta Platforms
Adam Gousetis, Meta Platforms
Ankur Agrawal, Unity Technologies
Bjorn Swenson, LÖVR
Denny Rönngren, Varjo Technologies
Fredia Huya-Kouadio, Godot Engine
Guodong Rong, Meta Platforms
Jakob Bornecrantz, NVIDIA
Jian Zhang, ByteDance
John Kearney, Meta Platforms
Jonathan Wright, Meta Platforms
Junfeng She, ByteDance
Kenny Vercaemer, Google
Kurtis Eveleigh, Qualcomm
Mauricio Narvaez, Meta Platforms
Nathan Nuber, Valve Corporation
Nihav Jain, Google
Nikita Lutsenko, Meta Platforms
Praveen Babu J D, ByteDance
Rylie Pavlik, Collabora
Salar Khan, Google
Shuai Liu, ByteDance
Walter Luh, Meta Platforms
Yin Li, Microsoft
Zhipeng Liu, ByteDance

Panoramica

Questa estensione definisce una nuova classe di entità visualizzabili, chiamate "container spaziali", analoghe al concetto di "finestre" nei sistemi di finestre 2D per computer.

In OpenXR 1.x, le app hanno il controllo esclusivo di tutto ciò che l'utente vede e di come viene combinato con l'ambiente reale o virtuale dell'utente. I runtime apportano solo lievi modifiche a ciò che viene visualizzato per garantire la sicurezza degli utenti. Questo modello di app è ideale per immergere un utente in un'unica esperienza, ma non si estende a più esperienze simultanee. In particolare, negli ambienti AR e di realtà mista, gli utenti spesso vogliono utilizzare più app diverse contemporaneamente.

I container spaziali sono come finestre estese in 3D. L'utente può visualizzare più container spaziali contemporaneamente e fornire input a un sottoinsieme di questi. I container spaziali visibili possono appartenere ad app diverse e i runtime gestiscono le loro dimensioni e il loro posizionamento per conto dell'utente.

Questa estensione supporta questi nuovi tipi di esperienze spazialmente limitate, oltre alle esperienze OpenXR immersive esistenti. Le esperienze OpenXR limitate possono avere contenuti leggermente 3D (pannelli piatti con piccoli offset di profondità) o volumi che ospitano contenuti completamente 3D. Le esperienze OpenXR immersive sono le app immersive a schermo intero esistenti supportate da OpenXR 1.0. Le app possono passare da un tipo di contenuti all'altro, se lo desiderano.

Questa estensione non definisce alcun metodo per il rendering dei contenuti di un'app. La modalità di disegno dei contenuti è definita in altre estensioni: XR_EXT_spatial_container_self_rendering .

Utilizzo di container spaziali

Un XrSpatialContainerEXT è un handle che rappresenta un container spaziale.

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

Un'applicazione inizia il rendering tramite un container spaziale con i seguenti passaggi:

  1. Crea un container spaziale con xrCreateSpatialContainerEXT .
  2. Modifica qualsiasi stato del container per la presentazione iniziale, ad esempio la modalità dei limiti.
  3. Richiedi al runtime di mostrare il container con xrRequestSpatialContainerVisibleEXT .
  4. Attendi che il runtime sia pronto per mostrare il container. Quando il runtime è pronto, mette in coda un evento XrEventDataSpatialContainerVisibleChangedEXT con visible impostato su XR_TRUE .
  5. Inizia il rendering per il container spaziale.

Per eliminare un container spaziale:

  1. Richiedi al runtime di nascondere il container con xrRequestSpatialContainerVisibleEXT .
  2. Attendi che il runtime termini di nascondere il container. Quando il runtime ha nascosto completamente il container, mette in coda un evento XrEventDataSpatialContainerVisibleChangedEXT con visible impostato su XR_FALSE .
  3. Termina il rendering per il container spaziale.
  4. Elimina il container con xrDestroySpatialContainerEXT .

Nota

Per progettazione, questa estensione delega la gestione della visibilità e dello stato attivo ai singoli contenitori spaziali. Poiché la sessione nel suo complesso non rappresenta più un singolo oggetto visibile o attivo, la sessione non passa attraverso la macchina a stati OpenXR standard (READY, SYNCHRONIZED, VISIBLE, FOCUSED). La sessione rimane invece in XR_SESSION_STATE_IDLE per la sua durata attiva e le regole descritte in Modifiche allo stato della sessione specificano in che modo le operazioni principali di OpenXR vengono mappate a questa modalità.

Crea un container spaziale

La funzione xrCreateSpatialContainerEXT crea un nuovo container spaziale.

XrResult xrCreateSpatialContainerEXT(
    XrSession                                   session,
    const XrSpatialContainerCreateInfoEXT*      createInfo,
    XrSpatialContainerEXT*                      spatialContainer);

Descrizioni dei parametri

Un XrSpatialContainerEXT appena creato deve essere non visibile, non interattivo e in modalità limiti XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT . Un'app che vuole che un container spaziale venga avviato in modalità immersiva può richiedere una modalità di limiti di XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT prima di richiedere la visualizzazione di un container spaziale.

I runtime devono restituire XR_ERROR_VALIDATION_FAILURE se una dimensione di XrSpatialContainerCreateInfoEXT :: suggestedBounds è negativa, infinita o non è un numero. I runtime devono restituire XR_ERROR_LIMIT_REACHED se un'app tenta di creare più container spaziali di quelli specificati in XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount . Se i container spaziali non sono stati attivati per questa sessione , i runtime devono restituire XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT .

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerCreateInfoEXT viene passato a xrCreateSpatialContainerEXT per creare un container spaziale.

typedef struct XrSpatialContainerCreateInfoEXT {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialContainerGraphicsPresentationEXT    graphicsPresentation;
    XrExtent3Df                                  suggestedBounds;
} XrSpatialContainerCreateInfoEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • graphicsPresentation è un XrSpatialContainerGraphicsPresentationEXT che descrive il modo in cui questo container spaziale presenta la grafica.
  • suggestedBounds è un XrExtent3Df che descrive le dimensioni richieste del container spaziale in metri.

Un'app che non ha preferenze per le sue dimensioni può impostare suggestedBounds su {0, 0, 0}. Un runtime può ignorare il valore suggestedBounds richiesto.

Un runtime che consente di delimitare i contenitori spaziali con forme diverse da riquadri orientati deve utilizzare suggestedBounds come riquadro di delimitazione attorno alle altre forme. Le caselle orientate sono pensate per essere la forma di delimitazione più comune.

Utilizzo valido (implicito)

Quando un contenitore spaziale non è più utilizzabile, i runtime devono mettere in coda un evento XrEventDataSpatialContainerClosedEXT.

typedef struct XrEventDataSpatialContainerClosedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerClosedEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • spatialContainer è l'XrSpatialContainerEXT a cui si riferisce questo evento.

La ricezione dell'evento XrEventDataSpatialContainerClosedEXT indica che il runtime non è più in grado di visualizzare un container spaziale, ad esempio perché l'utente ha fatto clic su un pulsante "Chiudi" o la sessione è entrata nello stato XR_SESSION_STATE_LOSS_PENDING.

Dopo aver ricevuto l'evento XrEventDataSpatialContainerClosedEXT, un'app deve interrompere l'utilizzo del container spaziale, eliminare qualsiasi stato associato, ad esempio un loop di rendering, e distruggere il container. I runtime devono restituire XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT da tutte le funzioni che operano su quel container, ad eccezione di xrDestroySpatialContainerEXT .

Se un container spaziale è visibile quando il runtime mette in coda un evento di chiusura, i runtime devono prima modificare il container in modo che non sia visibile e mettere in coda un evento XrEventDataSpatialContainerVisibleChangedEXT.

Utilizzo valido (implicito)

La funzione xrDestroySpatialContainerEXT elimina un container spaziale esistente.

XrResult xrDestroySpatialContainerEXT(
    XrSpatialContainerEXT                       spatialContainer);

Descrizioni dei parametri

Dopo la distruzione di un container spaziale, i runtime non devono più mostrare i contenuti del container e non devono mettere in coda altri eventi relativi al container.

Un'app non deve distruggere un container spaziale visibile, poiché ciò potrebbe causare artefatti grafici. Al contrario, un'app deve richiedere di nascondere il container spaziale con xrRequestSpatialContainerVisibleEXT, attendere un evento XrEventDataSpatialContainerVisibleChangedEXT e poi distruggere il container.

Utilizzo valido (implicito)

Thread safety

  • L'accesso a spatialContainer e a qualsiasi handle secondario deve essere sincronizzato esternamente

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Lo spazio del container spaziale

La funzione xrCreateSpatialContainerSpaceEXT crea un handle XrSpace per lo spazio del container spaziale di un container spaziale specifico.

XrResult xrCreateSpatialContainerSpaceEXT(
    XrSession                                   session,
    const XrSpatialContainerSpaceCreateInfoEXT* createInfo,
    XrSpace*                                    space);

Descrizioni dei parametri

Lo "spazio del contenitore spaziale" per un determinato contenitore spaziale è un sistema di coordinate con l'origine al centro dei limiti del contenitore spaziale. Questo spazio viene in genere utilizzato come spazio di base per funzioni come xrLocateSpace .

+X punta alla faccia destra del container, +Y punta alla faccia superiore del container e +Z punta alla faccia anteriore del container. Ad esempio, se un container è allineato alla gravità, davanti al visualizzatore e il visualizzatore si trova nella posizione di identità rispetto allo spazio LOCAL, i runtime devono orientare lo spazio del container con l'orientamento dell'identità rispetto allo spazio LOCAL . I runtime possono impostare la posa di uno spazio contenitore rispetto allo spazio LOCAL su qualsiasi posa arbitraria quando il contenitore diventa visibile.

ext spatial container space convention

Figura 18. Convenzione degli assi dello spazio del container spaziale

Lo spazio del contenitore spaziale è un'origine non bloccata nel mondo. Le app che vogliono un'origine bloccata nel mondo in modalità immersiva possono utilizzare uno spazio bloccato nel mondo come XR_REFERENCE_SPACE_TYPE_LOCAL .

I runtime possono modificare la posizione di uno spazio del contenitore spaziale in qualsiasi momento, in genere per consentire a un utente di spostare un contenitore spaziale in una posizione o rotazione diversa. I runtime possono anche modificare la posa durante la transizione tra le modalità di delimitazione XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT e XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT.

Uno spazio del contenitore spaziale deve continuare a essere un handle valido anche se il contenitore spaziale a cui è destinato viene eliminato con xrDestroySpatialContainerEXT . Quando un contenitore spaziale non è visibile o viene eliminato, lo spazio del contenitore spaziale deve essere non localizzabile rispetto ad altri spazi. XrSpaceLocation :: locationFlags e XrViewState ::viewStateFlags saranno pari a 0.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerSpaceCreateInfoEXT viene utilizzato con xrCreateSpatialContainerSpaceEXT per creare un handle XrSpace.

typedef struct XrSpatialContainerSpaceCreateInfoEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrSpatialContainerSpaceCreateInfoEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • spatialContainer è un XrSpatialContainerEXT per cui creare uno spazio.

Utilizzo valido (implicito)

Presentazione di un container spaziale

L'invio dei contenuti di un container spaziale a OpenXR per la visualizzazione è gestito da altre estensioni: XR_EXT_spatial_container_self_rendering .

Per consentire ad altre estensioni di specificare il metodo di presentazione grafica per un container spaziale, questa estensione definisce l'enum XrSpatialContainerGraphicsPresentationEXT.

typedef enum XrSpatialContainerGraphicsPresentationEXT {
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT = 1000813000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT = 1000814000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1 = 1000815000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerGraphicsPresentationEXT;

Descrizione enum

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

Il container spaziale utilizza i livelli di composizione OpenXR (aggiunti dall'estensione XR_EXT_spatial_container_self_rendering)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT

Il container spaziale viene creato per i test di conformità e non ha un percorso di rendering (aggiunto dall'estensione XR_EXT_spatial_container_conformance_automation)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1

Il container spaziale utilizza il rendering del sistema OpenXR (aggiunto dall'estensione XR_EXTX1_system_renderer)

Stato del contenitore spaziale

Lo stato del container spaziale è gestito dai runtime in base alle richieste dell'app e alle esigenze dell'utente. Per questo motivo, ogni aspetto dello stato del container spaziale documenta quanto segue:

  • Quando i runtime possono modificare lo stato del container spaziale. Per la maggior parte degli stati dei container spaziali, i runtime possono modificare lo stato in qualsiasi momento.
  • In che modo un'app richiede modifiche allo stato. I runtime possono rinviare qualsiasi richiesta finché non ritengono che sia idonea. I runtime non mettono in coda gli eventi quando una richiesta viene posticipata, quindi le app non devono attendere un evento di questo tipo per una logica non correlata.
  • Quali runtime di eventi vengono messi in coda quando lo stato del container spaziale cambia. I runtime mettono in coda gli eventi per tutte le modifiche, incluse quelle richieste dall'app e quelle avviate dal runtime. I runtime non devono mettere in coda eventi di modifica dello stato che non indicano una modifica, ad esempio se un'app effettua due richieste per nascondere un container in rapida successione.
  • Quali runtime di eventi vengono messi in coda quando viene rifiutata una richiesta di modifica dell'app. I runtime possono rifiutare una richiesta per qualsiasi motivo, in genere a causa di norme di sistema relative al mantenimento di un'esperienza utente di alta qualità.

La funzione xrGetSpatialContainerStateEXT esegue una query sullo stato attuale del container spaziale.

XrResult xrGetSpatialContainerStateEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerStateGetInfoEXT*    getInfo,
    XrSpatialContainerStateEXT*                 state);

Descrizioni dei parametri

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerStateGetInfoEXT viene utilizzato con xrGetSpatialContainerStateEXT per eseguire query su un XrSpatialContainerStateEXT .

typedef struct XrSpatialContainerStateGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerStateGetInfoEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.

Utilizzo valido (implicito)

typedef struct XrSpatialContainerStateEXT {
    XrStructureType                    type;
    void*                              next;
    XrBool32                           visible;
    XrBool32                           interactable;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerStateEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • visible indica se un contenitore spaziale è visibile.
  • interactable indica se un contenitore spaziale è attualmente in grado di ricevere qualsiasi tipo di input. È simile allo "stato attivo" per i sistemi di finestre 2D desktop, con la differenza che più container spaziali possono essere interattivi contemporaneamente.
  • boundsMode è l'attuale XrSpatialContainerBoundsModeEXT del container spaziale.

Le modifiche allo stato di un container spaziale vengono comunicate tramite eventi.

Evento Field Changed (Campo modificato)

visible

XrEventDataSpatialContainerVisibleChangedEXT

interactable

XrEventDataSpatialContainerInteractableChangedEXT

boundsMode

XrEventDataSpatialContainerBoundsChangedEXT

Utilizzo valido (implicito)

Visibilità

Le app richiedono di mostrare o nascondere un container spaziale con xrRequestSpatialContainerVisibleEXT .

XrResult xrRequestSpatialContainerVisibleEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerVisibleRequestInfoEXT* info);

Descrizioni dei parametri

La visualizzazione o l'occultamento di un contenitore spaziale è un'operazione asincrona.

Le app dovrebbero richiedere di nascondere un container spaziale prima di eliminarlo, consentendo ai runtime di mostrare una transizione fluida. I runtime devono rispettare le richieste di nascondere un contenitore spaziale.

Un runtime può rifiutare le richieste di visualizzazione di un container spaziale, nel qual caso il runtime deve mettere in coda un evento XrEventDataSpatialContainerVisibleRequestDeniedEXT. Ad esempio, alcuni runtime rifiuteranno una richiesta di visualizzazione di un contenitore spaziale che l'utente ha nascosto interagendo con un pulsante "Riduci a icona" fornito dal sistema.

I runtime non devono mostrare un container spaziale prima che l'app richieda di mostrarlo almeno una volta. Dopo la prima richiesta dell'app di mostrare un container spaziale, i runtime potrebbero modificare la visibilità del container spaziale indipendentemente dalle richieste dell'app. In questo modo, l'app può controllare lo stato iniziale e i contenuti di un container spaziale e i runtime possono fornire un'UI di sistema, ad esempio una barra delle app, che consente all'utente di scegliere quali container spaziali sono visibili.

I runtime devono rifiutare le richieste di visualizzazione di un container spaziale in una modalità di limiti non supportata in base a XrSystemSpatialContainerPropertiesEXT :: supportsBounded e XrSystemSpatialContainerPropertiesEXT :: supportsImmersive . Ciò è possibile quando la modalità di limiti predefinita, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT , non è supportata per un determinato sistema.

Nota

In alcune implementazioni, la visualizzazione o la scomparsa di un contenitore spaziale richiede la comunicazione con i servizi di sistema e potrebbe essere posticipata fino a quando l'utente non interagisce con una finestra di dialogo di sistema. Il design asincrono per la richiesta di modifiche dello stato di visibilità ha lo scopo di concedere ai runtime il tempo necessario per completare entrambe le operazioni.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerVisibleRequestInfoEXT viene utilizzato con xrRequestSpatialContainerVisibleEXT per modificare la visibilità di un container spaziale.

typedef struct XrSpatialContainerVisibleRequestInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           visible;
} XrSpatialContainerVisibleRequestInfoEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • visible indica se è stato richiesto di mostrare o nascondere un contenitore spaziale.

Utilizzo valido (implicito)

Ogni volta che un runtime modifica la visibilità di un container spaziale, il runtime deve mettere in coda un evento XrEventDataSpatialContainerVisibleChangedEXT con il nuovo stato.

typedef struct XrEventDataSpatialContainerVisibleChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 visible;
} XrEventDataSpatialContainerVisibleChangedEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • spatialContainer è l'XrSpatialContainerEXT a cui si riferisce questo evento.
  • visible è il nuovo stato visibile del container spaziale.

Questo evento sostituisce XR_SESSION_STATE_VISIBLE , consentendo di avere un valore diverso per ogni contenitore. L'evento deve essere messo in coda per tutte le modifiche, incluse quelle richieste dall'app e quelle avviate dal runtime.

Un runtime può ritardare il rendering di un contenitore per alcuni frame dopo aver messo in coda questo evento con visible impostato su XR_TRUE per evitare di visualizzare un contenitore vuoto e dare all'app il tempo di inviare i suoi contenuti iniziali. Durante questo periodo, XrSpatialContainerStateEXT ::visible sarà XR_TRUE . I runtime non devono ritardare il rendering di un contenitore per più di 0,5 secondi.

Utilizzo valido (implicito)

Ogni volta che un runtime rifiuta una richiesta di visualizzazione di un container, il runtime deve mettere in coda un evento XrEventDataSpatialContainerVisibleRequestDeniedEXT.

typedef struct XrEventDataSpatialContainerVisibleRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerVisibleRequestDeniedEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • spatialContainer è l'XrSpatialContainerEXT a cui si riferisce questo evento.

Utilizzo valido (implicito)

Interattivo

Un'app non può richiedere che un container spaziale sia interattivo. I container spaziali interattivi sono controllati completamente dai runtime. Un contenitore spaziale interattivo deve essere anche visibile.

Ogni volta che un runtime modifica lo stato di interazione di un container spaziale, il runtime deve mettere in coda un evento XrEventDataSpatialContainerInteractableChangedEXT con il nuovo stato.

typedef struct XrEventDataSpatialContainerInteractableChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 interactable;
} XrEventDataSpatialContainerInteractableChangedEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • spatialContainer è l'XrSpatialContainerEXT a cui si riferisce questo evento.
  • interactable è il nuovo stato interattivo del container spaziale.

Questo evento sostituisce XR_SESSION_STATE_FOCUSED , consentendo di avere un valore diverso per ogni contenitore. L'evento viene messo in coda per tutte le modifiche, incluse quelle avviate dal runtime.

I runtime possono attivare o disattivare l'interazione con un contenitore spaziale in qualsiasi momento. Se un runtime supporta al massimo un container spaziale interattivo alla volta, quando il runtime modifica il container spaziale interattivo, deve mettere in coda l'evento per il container spaziale che smette di essere interattivo ( interactable impostato su false) prima dell'evento per il container che inizia a essere interattivo ( interactable impostato su true).

Utilizzo valido (implicito)

Limiti

Un container spaziale ha una modalità di limiti e un riquadro di delimitazione. La modalità dei limiti di un container spaziale descrive il comportamento dei limiti. Il suo riquadro di delimitazione è l'area in cui il contenitore spaziale disegna.

L'enumerazione XrSpatialContainerBoundsModeEXT identifica le diverse modalità in cui possono trovarsi i limiti di un container spaziale.

typedef enum XrSpatialContainerBoundsModeEXT {
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT = 1,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT = 2,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerBoundsModeEXT;

Descrizione enum

XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT

Il container spaziale è delimitato. I limiti sono un riquadro finito. Il contenitore spaziale verrà visualizzato solo in questa regione.

XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT

Il contenitore spaziale è immersivo e ha limiti infiniti. Il contenitore spaziale viene visualizzato sull'intero schermo.

I container spaziali in modalità limiti XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT hanno requisiti aggiuntivi:

  • I runtime devono trattare questi container spaziali allo stesso modo di un'app immersiva a schermo intero creata senza l'utilizzo di container spaziali, ad eccezione delle modifiche al comportamento descritte in Modifiche allo stato della sessione .
  • I runtime possono fornire estensioni aggiuntive che consentono ai container spaziali immersivi di comportarsi in modo diverso dalle app immersive e a schermo intero create senza questa estensione.
  • I runtime devono segnalare limiti infiniti per questi contenitori spaziali.
  • I runtime possono nascondere altri container spaziali mentre è visibile un container spaziale immersivo. Poiché questo potrebbe essere diverso per ogni runtime, le app non devono fare affidamento sulla visualizzazione o sul nascondimento automatico dei container spaziali in base alla visibilità del container spaziale immersivo. Come per tutte le altre transizioni di stato visibili, i runtime devono mettere in coda un evento XrEventDataSpatialContainerVisibleChangedEXT quando un contenitore spaziale viene nascosto perché è visibile un contenitore immersivo.

Nota

I requisiti di cui sopra implicano che tutti i runtime possono implementare il percorso OpenXR 1.x senza questa estensione creando implicitamente un contenitore spaziale, impostando la modalità dei limiti del contenitore su immersiva e richiedendo che sia visibile.

Le app richiedono di modificare la modalità dei limiti di un contenitore spaziale con xrRequestSpatialContainerBoundsModeEXT .

XrResult xrRequestSpatialContainerBoundsModeEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsModeRequestInfoEXT* info);

Descrizioni dei parametri

La modifica della modalità dei limiti di un contenitore spaziale è un'operazione asincrona e i runtime potrebbero mettere in coda un evento modificato o negato molti secondi dopo che l'app ha richiesto una modifica. In questo modo, i runtime possono mostrare la UI necessaria per consentire a un utente di accedere in sicurezza a una modalità immersiva.

I runtime devono rispettare una richiesta di modifica della modalità dei limiti per un contenitore spaziale non visibile. Se un runtime rifiuta una richiesta di modalità di delimitazione per un contenitore non visibile, può rifiutare o posticipare una richiesta di visualizzazione di un contenitore spaziale di questo tipo. In questo modo, le app possono avviare un container come container immersivo. Un runtime può rifiutare le richieste di modifica della modalità dei limiti di un contenitore spaziale visibile, nel qual caso il runtime deve mettere in coda un evento XrEventDataSpatialContainerBoundsModeRequestDeniedEXT. Ad esempio, alcuni runtime negheranno una richiesta di modifica della modalità dei limiti di un contenitore spaziale visibile con cui l'utente non sta interagendo attivamente.

I runtime devono restituire XR_ERROR_VALIDATION_FAILURE se un'app richiede una modalità di limiti non supportata in base a XrSystemSpatialContainerPropertiesEXT :: supportsBounded e XrSystemSpatialContainerPropertiesEXT :: supportsImmersive .

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerBoundsModeRequestInfoEXT viene utilizzato con xrRequestSpatialContainerBoundsModeEXT per modificare la modalità dei limiti di un container spaziale.

typedef struct XrSpatialContainerBoundsModeRequestInfoEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerBoundsModeRequestInfoEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • boundsMode è l'oggetto XrSpatialContainerBoundsModeEXT desiderato per il container spaziale.

Utilizzo valido (implicito)

Ogni volta che un runtime modifica i limiti o la modalità dei limiti di un contenitore spaziale, il runtime deve mettere in coda un evento XrEventDataSpatialContainerBoundsChangedEXT con le nuove informazioni sui limiti.

typedef struct XrEventDataSpatialContainerBoundsChangedEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerEXT              spatialContainer;
    XrExtent3Df                        bounds;
    XrBool32                           infiniteBounds;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrEventDataSpatialContainerBoundsChangedEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • spatialContainer è l'XrSpatialContainerEXT a cui si riferisce questo evento.
  • bounds è la nuova larghezza, altezza e profondità dei limiti del container spaziale.
  • infiniteBounds è true se il container ha limiti infiniti.
  • boundsMode è il nuovo XrSpatialContainerBoundsModeEXT del container spaziale.

L'evento viene inserito in coda per tutte le modifiche, incluse quelle richieste dall'app e quelle avviate dal runtime.

Mentre un utente ridimensiona in modo interattivo un contenitore spaziale, i runtime devono comportarsi in uno dei seguenti modi:

  • mettere in coda molti eventi, probabilmente alla frequenza fotogrammi, mentre l'utente ridimensiona il container spaziale
  • mettere in coda un singolo evento alla fine del ridimensionamento

Se un runtime mette in coda un solo evento alla fine del ridimensionamento, questo runtime deve continuare a segnalare i limiti precedenti da xrGetSpatialContainerBoundsEXT finché non mette in coda un evento di ridimensionamento. I runtime devono unire più eventi di modifica dei limiti non sottoposti a polling. In altre parole, se i limiti o la modalità dei limiti cambiano mentre un evento XrEventDataSpatialContainerBoundsChangedEXT è ancora in coda, i runtime devono segnalare un solo evento contenente l'ultima modifica dei limiti che si è verificata. Poiché le app possono anche eseguire il polling dei limiti di un contenitore spaziale direttamente con xrGetSpatialContainerBoundsEXT, il numero di modifiche ai limiti degli eventi può essere diverso dal numero di modifiche del polling in base alla tempistica delle modifiche ai limiti generate dal runtime, alle chiamate dell'app a xrPollEvent e alle chiamate dell'app a xrGetSpatialContainerBoundsEXT .

Quando i limiti di un contenitore spaziale cambiano, anche l'origine locale del contenitore spaziale potrebbe cambiare. Ad esempio, se un runtime consente a un utente di ridimensionare i limiti del contenitore spaziale trascinando uno dei bordi del contenitore, i limiti e l'origine locale di quel contenitore cambieranno quando l'utente trascina un singolo bordo. In questi casi, il runtime deve modificare contemporaneamente i limiti e l'origine locale.

I runtime devono impostare infiniteBounds su XR_TRUE e impostare larghezza, altezza e profondità su 0, 0 per rappresentare limiti infiniti. I runtime devono impostare infiniteBounds su XR_FALSE e impostare larghezza, altezza e profondità su numeri positivi finiti per i limiti finiti.

I runtime devono impostare bounds e infiniteBounds seguendo le stesse regole di XrSpatialContainerBoundsEXT .

Utilizzo valido (implicito)

Ogni volta che un runtime nega una richiesta di modifica della modalità dei limiti di un container, il runtime deve mettere in coda un evento XrEventDataSpatialContainerBoundsModeRequestDeniedEXT.

typedef struct XrEventDataSpatialContainerBoundsModeRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerBoundsModeRequestDeniedEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • spatialContainer è l'XrSpatialContainerEXT a cui si riferisce questo evento.

Utilizzo valido (implicito)

La struttura XrSpatialContainerBoundsEXT descrive il riquadro di delimitazione di un container spaziale.

typedef struct XrSpatialContainerBoundsEXT {
    XrStructureType    type;
    void*              next;
    XrExtent3Df        bounds;
    XrBool32           infiniteBounds;
} XrSpatialContainerBoundsEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • bounds è la larghezza, l'altezza e la profondità dei limiti del contenitore spaziale. I limiti sono espressi in metri.
  • infiniteBounds è true se il contenitore ha limiti infiniti.

I runtime devono impostare infiniteBounds su XR_TRUE e impostare larghezza, altezza e profondità su 0, 0 per rappresentare limiti infiniti. I runtime devono impostare infiniteBounds su XR_FALSE e impostare larghezza, altezza e profondità su numeri positivi finiti per i limiti finiti.

Utilizzo valido (implicito)

La funzione xrGetSpatialContainerBoundsEXT esegue una query sui limiti attuali di un container spaziale.

XrResult xrGetSpatialContainerBoundsEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsGetInfoEXT*   getInfo,
    XrSpatialContainerBoundsEXT*                bounds);

Descrizioni dei parametri

Un contenitore spaziale delimitato non deve avere limiti infiniti, mentre un contenitore spaziale immersivo deve avere limiti infiniti.

I runtime possono modificare i limiti di un container spaziale in qualsiasi valore finito positivo in qualsiasi momento mentre il container spaziale è limitato. Le modifiche ai limiti di un contenitore spaziale vengono comunicate tramite XrEventDataSpatialContainerBoundsChangedEXT .

Con questa estensione, un'app non può richiedere modifiche ai limiti, se non il passaggio tra limitato e immersivo con xrRequestSpatialContainerBoundsModeEXT . Altre estensioni potrebbero fornire questa funzionalità in futuro.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

La struttura XrSpatialContainerBoundsGetInfoEXT è una struttura di input che esiste per scopi di estensione futuri.

typedef struct XrSpatialContainerBoundsGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerBoundsGetInfoEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.

Utilizzo valido (implicito)

L'enumerazione XrSpatialContainerVolumeClippingEXT identifica diversi comportamenti di ritaglio del volume per un contenitore spaziale.

typedef enum XrSpatialContainerVolumeClippingEXT {
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT = 0,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT = 1,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerVolumeClippingEXT;

Descrizione enum

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT

Nessun contenuto viene ritagliato in base al volume di delimitazione del contenitore spaziale. I contenuti possono essere visualizzati al di fuori dei limiti del contenitore spaziale.

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT

I contenuti vengono ritagliati rigorosamente in base al volume di delimitazione del contenitore spaziale.

Questa enumerazione non viene utilizzata in questa estensione. È definito per consentire ad altre estensioni di specificare il comportamento di clipping del volume desiderato. Ad esempio, un'app potrebbe voler disegnare uno sfondo per un contenitore spaziale delimitato. Una mappa cubica monoculare è un modo pratico per specificare uno sfondo, ma concettualmente è posizionata all'infinito, ovvero all'esterno del container.

Funzionalità del sistema

Un'app può ispezionare le funzionalità del sistema concatenando una struttura XrSystemSpatialContainerPropertiesEXT a XrSystemProperties quando chiama xrGetSystemProperties .

typedef struct XrSystemSpatialContainerPropertiesEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSpatialContainerCount;
    XrBool32           supportsBounded;
    XrBool32           supportsImmersive;
} XrSystemSpatialContainerPropertiesEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • maxSpatialContainerCount è il numero massimo di container spaziali che è possibile creare.
  • supportsBounded è true se i container spaziali possono essere delimitati.
  • supportsImmersive è true se i container spaziali possono essere immersivi.

I runtime che supportano questa estensione dovrebbero supportare un'app che crea molti container spaziali, limitati solo dall'allocazione della memoria. Un runtime potrebbe avere un limite diverso per il numero di contenitori spaziali visualizzati contemporaneamente. Non è possibile eseguire query sul numero di container visualizzati contemporaneamente in questa estensione perché un runtime potrebbe limitare le singole app in base allo stato di tutte le app in esecuzione. Si presume che i dispositivi con vincoli elevati e quelli con vincoli meno elevati abbiano limiti diversi per il numero di container visualizzati contemporaneamente; i dispositivi con vincoli elevati potrebbero supportare la visualizzazione di un solo container spaziale alla volta, mentre i dispositivi con vincoli meno elevati potrebbero supportare la visualizzazione simultanea di un numero elevato di container spaziali, in base ai limiti di calcolo del rendering.

I runtime che supportano questa estensione devono supportare almeno uno dei container spaziali limitati o dei container spaziali immersivi.

Utilizzo valido (implicito)

La funzione xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT restituisce i metodi di presentazione grafica supportati su un sistema.

XrResult xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    graphicsPresentationCapacityInput,
    uint32_t*                                   graphicsPresentationCountOutput,
    XrSpatialContainerGraphicsPresentationEXT*  graphicsPresentations);

Descrizioni dei parametri

  • instance è l'XrInstance da cui è stato recuperato systemId.
  • systemId è l'XrSystemId su cui viene eseguita la query.
  • graphicsPresentationCapacityInput è la capacità dell'array graphicsPresentations o 0 per indicare una richiesta di recupero della capacità richiesta.
  • graphicsPresentationCountOutput è un puntatore al conteggio delle presentazioni grafiche scritte o un puntatore alla capacità richiesta nel caso in cui graphicsPresentationCapacityInput sia 0.
  • graphicsPresentations è un puntatore a un array di valori XrSpatialContainerGraphicsPresentationEXT, ma può essere null se graphicsPresentationCapacityInput è 0.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione graphicsPresentations richiesta.

I runtime devono sempre restituire contenuti del buffer identici da questa enumerazione per il systemId specificato e per la durata dell'istanza.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Modifiche allo stato della sessione

Il supporto dei container spaziali viene attivato per una sessione concatenando un XrSessionCreateInfoSpatialContainersEXT quando si chiama xrCreateSession .

typedef struct XrSessionCreateInfoSpatialContainersEXT {
    XrStructureType    type;
    const void*        next;
} XrSessionCreateInfoSpatialContainersEXT;

Quando il supporto dei container spaziali è attivo, un XrSession si comporta in modo diverso. Questo perché, quando si utilizzano i container spaziali, la sessione non presenta più i contenuti delle immagini sui display, ma lo fanno i container spaziali. Pertanto, quando questa estensione è attiva, una sessione è effettivamente "headless". A differenza di altre estensioni headless, le app possono inviare dati di immagini tramite i container spaziali.

L'attivazione del supporto dei container spaziali modifica le API OpenXR principali nel seguente modo.

runtime: perdita del sistema o del dispositivo

runtime: losing system or device

xrDestroySession

xrDestroySession

IDLE
(in esecuzione)

IDLE…

xrGetSystem
xrCreateSession

xrGetSystem…

xrCreateInstance

xrCreateIn…

xrDestroySession

xrDestroySession

LOSS_PENDING
(non in esecuzione)

LOSS_PENDING…

xrDestroyInstance

xrDestroyInstance

app: facoltativamente
riavvia XR

app: facoltativamente…

Figura 19. Nuova macchina a stati della sessione

  • La sessione non entra mai negli stati XR_SESSION_STATE_VISIBLE, XR_SESSION_STATE_FOCUSED o XR_SESSION_STATE_EXITING . I runtime non devono mai mettere in coda gli eventi per questi stati. Questi stati vengono sostituiti rispettivamente dagli eventi del container per spazio XrEventDataSpatialContainerVisibleChangedEXT, XrEventDataSpatialContainerInteractableChangedEXT e XrEventDataSpatialContainerClosedEXT.
  • Inoltre, la sessione non entra mai negli stati XR_SESSION_STATE_READY, XR_SESSION_STATE_SYNCHRONIZED, XR_SESSION_STATE_STOPPING . I runtime non devono mai mettere in coda gli eventi per questi stati. Non sono previste sostituzioni per questi stati.
  • I runtime devono considerare la sessione come in esecuzione quando si trova nello stato XR_SESSION_STATE_IDLE .
  • I runtime devono trattare la sessione come attiva quando si trova nello stato XR_SESSION_STATE_IDLE ed esiste almeno un container spaziale interattivo.
  • Le funzioni xrBeginSession e xrEndSession non sono più necessarie. I runtime devono restituire XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT quando vengono chiamate queste funzioni. Altre estensioni potrebbero fornire sostituzioni per queste funzionalità.
  • Anche la funzione xrRequestExitSession non è più necessaria. I runtime devono restituire XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT quando viene chiamata questa funzione. Le app che vogliono uscire da una sessione in esecuzione possono chiamare xrRequestSpatialContainerVisibleEXT per nascondere i propri container e distruggere la sessione dopo che tutti i container non sono più visibili.

  • Le estensioni che mettono in coda eventi aggiuntivi all'inizio dell'esecuzione della sessione ora devono mettere in coda questi eventi dopo la creazione della sessione. Queste estensioni sono indicate di seguito.

    Evento di estensione

XR_EXT_user_presence

XrEventDataUserPresenceChangedEXT

XR_META_boundary_visibility

XrEventDataBoundaryVisibilityChangedMETA

  • La funzione xrLocateViews non è valida per la chiamata della sessione. I runtime devono restituire XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT da xrLocateViews . Altre estensioni potrebbero fornire modi per individuare le visualizzazioni per un particolare contenitore spaziale.
  • La funzione xrWaitFrame deve sempre impostare XrFrameState :: shouldRender su false. Altre estensioni potrebbero fornire modi per sapere se un particolare contenitore spaziale deve aggiornare i propri livelli di composizione.
  • La funzione xrEndFrame non è un modo valido per inviare i livelli di composizione. Se un'app imposta XrFrameEndInfo :: layerCount su un valore diverso da zero, i runtime devono restituire XR_ERROR_VALIDATION_FAILURE . Altre estensioni potrebbero fornire modi per inviare livelli di composizione per un determinato contenitore spaziale.
  • L'attivazione dello stato XR_SESSION_STATE_LOSS_PENDING chiude anche tutti i contenitori spaziali. I runtime devono mettere in coda un evento XrEventDataSpatialContainerClosedEXT per ogni container spaziale attivo prima di mettere in coda una modifica dello stato della sessione per XR_SESSION_STATE_LOSS_PENDING .
  • La funzione xrCreateSession non richiede più una struttura di associazione dell'API grafica. Altre estensioni potrebbero richiedere un'associazione grafica, ad esempio per il rendering di un contenitore spaziale utilizzando un'API grafica.

Il comportamento descritto sopra è leggermente diverso da quello in XR_MND_headless . I runtime non devono attivare il comportamento della sessione headless da XR_MND_headless quando il supporto del container spaziale è abilitato per la sessione.

Nota

Quando i container spaziali sono attivati, una sessione passa solo tra due stati: XR_SESSION_STATE_IDLE (in esecuzione) e XR_SESSION_STATE_LOSS_PENDING (non in esecuzione). Di conseguenza, i runtime non restituiscono più XR_ERROR_SESSION_RUNNING o XR_ERROR_SESSION_NOT_RUNNING . Invece, quando una sessione non è in esecuzione, i runtime restituiscono XR_ERROR_SESSION_LOST o XR_SESSION_LOSS_PENDING seguendo le regole di OpenXR core. Inoltre, xrBeginSession , l'unica funzione che restituisce XR_ERROR_SESSION_RUNNING , ora restituirà sempre XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT .

Utilizzo valido (implicito)

Voci del manifest Android

I runtime basati su AOSP potrebbero avere un comportamento personalizzato in base allo stato iniziale del container spaziale avviato prima di eseguire qualsiasi codice dell'app. Ad esempio, un runtime potrebbe alterare le risorse allocate per l'attività, avviare animazioni o visualizzare la schermata iniziale. A questo scopo vengono fornite le seguenti proprietà. Sostituiscono il tag <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />, che le app basate su container spaziali non devono specificare, ad eccezione della compatibilità con i runtime basati su AOSP precedenti.

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
          android:value="list of modes" />

Questa proprietà indica ai runtime le modalità dei limiti utilizzate da un'attività. Per impostazione predefinita, l'elenco è vuoto, il che significa che non viene fornito alcun suggerimento.

Le seguenti stringhe sono valide per questo attributo. I valori multipli sono separati da | , ad esempio "bounded|immersive" .

Valore

Descrizione

"2d_panel"

L'attività viene visualizzata utilizzando il framework di visualizzazione 2D di Android.

"bounded"

L'attività utilizza XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT .

"immersive"

L'attività utilizza XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT .

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
          android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED" />

Questa proprietà suggerisce ai runtime l'XrSpatialContainerBoundsModeEXT iniziale dell'attività quando viene creata per la prima volta. Per impostazione predefinita, è la stringa XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED, che non implica alcun suggerimento.

I runtime non devono richiedere alle app di avere queste proprietà per comportarsi in altro modo in base a questa specifica. I runtime non devono alterare il comportamento visibile dell'app in base a queste proprietà. Tutti questi metadati devono essere specificabili a livello di <activity> o di <application>. Se specificato a livello di <application>, si applica a tutte le attività dell'applicazione che non specificano i propri valori.

Esempio di codice

Il seguente codice mostra come utilizzare questa estensione per casi d'uso di sola percezione senza rendering.

XrInstance instance;    // Already initialized


// Create the session with spatial containers enabled
XrSession session;

XrSessionCreateInfoSpatialContainersEXT spatialContainerCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT,
};
XrSessionCreateInfo sessionCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO,
  .next = &spatialContainerCreateInfo,   // Enable spatial containers
};
(void)sessionCreateInfo.systemId;                             // Other create fields set in usual way

CHK_XR(xrCreateSession(instance, &sessionCreateInfo, &session));


// Because spatial containers are enabled, the session is considered
// running. App is able to query perception data such as head poses and hand
// poses.


// Based on app logic or when a system lost event happens, destroy the
// session
CHK_XR(xrDestroySession(session));

Nuovi tipi di oggetti

Nuovi comandi

Nuove strutture

Nuovi enum

Nuove costanti enum

  • XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME
  • XR_EXT_spatial_container_SPEC_VERSION

  • Estensione di XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTAINER_EXT

  • Estensione di XrResult :

    • XR_ERROR_COMPATIBLE_SPATIAL_CONTAINER_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT
    • XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT

  • Estensione di XrStructureType :

    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_DENIED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_CLOSED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_INTERACTABLE_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_REQUEST_DENIED_EXT
    • XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_SPACE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_STATE_EXT
    • XR_TYPE_SPATIAL_CONTAINER_STATE_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VISIBLE_REQUEST_INFO_EXT
    • XR_TYPE_SYSTEM_SPATIAL_CONTAINER_PROPERTIES_EXT

Problemi

  • Come gestiamo più richieste visibili in sospeso? L'app deve ricevere una modifica/un rifiuto o più? La risposta potrebbe essere diversa se le chiamate vengono effettuate su più frame. La risposta potrebbe anche essere diversa se le richieste multiple generano un'operazione noop, ad esempio la richiesta di rendere visibile un contenitore spaziale, quindi non visibile per un contenitore che inizia non visibile.

    • Risolto. Scelte diverse per gli eventi di modifica e gli eventi negati. Le richieste Noop non mettono in coda un evento di modifica, ma generano solo rumore per lo sviluppatore di app e sono facili da filtrare per i runtime. Se vengono rifiutate più richieste visibili, i runtime devono generare ciascuno un evento di rifiuto corrispondente.

  • Come deve essere definita un'estensione di automazione della conformità in modo che tutto il testo facoltativo delle specifiche per i comportamenti delle policy sia ancora testabile da CTS?

    • Risolto. Estensione di test separata. Verrà implementato un runtime di estensione di test solo per CTS, consentendo a CTS di controllare tutte le policy di sistema.

  • Abbiamo bisogno di un evento per quando cambia la posizione di un container spaziale?

    • Risolto. No. Lo spazio del container spaziale non è bloccato nel mondo e altri spazi simili, come XR_REFERENCE_SPACE_TYPE_VIEW , non hanno eventi quando cambiano.

  • Come funziona xrSyncActions se sono presenti più container spaziali?

    • Risolto. Non è necessaria alcuna modifica. xrSyncActions si applica a tutti i contenitori spaziali della sessione. Se un'app vuole indirizzare le azioni di input a un particolare contenitore spaziale, può esaminare lo stato interattivo per contenitore per scegliere quali contenitori sono target validi. Se un'app vuole sincronizzare solo lo stato dell'azione di input per un singolo contenitore spaziale, è necessaria un'estensione aggiuntiva. Tuttavia, prevediamo di concentrarci su un'estensione che consenta alle app di essere completamente basate sugli eventi ed evitare la necessità di una chiamata xrSyncActions in un loop di frame.

  • In che modo le app aggiornate di rado gestiscono l'input?

    • Risolto. Nessuna modifica necessaria. Sebbene sia utile per EXT_spatial_container, è utile anche al di fuori dei contenitori spaziali. Questo può essere gestito tramite un'estensione del canale degli eventi e funziona in entrambi i casi. Per i container spaziali, aggiungeremo altri modi per filtrare gli eventi per un singolo container spaziale.

  • È necessario un tempo di attesa per limitare/controllare i tempi del loop di input per le app con loop di input e rendering disaccoppiati?

    • Risolto. Nessuna modifica necessaria. Questo dovrebbe essere gestito tramite il canale degli eventi e le estensioni di richiesta presenti. L'estensione della richiesta di presentazione consente di basare il rendering sugli eventi e di disaccoppiarlo da un loop di frame.

  • Un contenitore spaziale può ottenere la sua posa rispetto ad altri contenitori spaziali? Considerazioni chiave: abbiamo un caso d'uso per questo? In questo caso, in che modo gli spazi del container spaziale si collegano a LOCAL?

    • Risolto. Sì. Questo è già possibile per i contenitori spaziali all'interno della stessa sessione tramite XR_REFERENCE_SPACE_TYPE_VIEW ed è auspicabile supportare i contenuti dipendenti dalla visualizzazione. Per condividere le posizioni dei container spaziali tra le sessioni (ad esempio con un altro processo), il percorso previsto è quello di sfruttare XR_EXT_spatial_anchor e i suoi pattern di persistenza e condivisione esistenti.

  • Lo spazio di un contenitore spaziale è localizzabile se non è visibile?

    • Risolto. No. Lo spazio del contenitore spaziale non è localizzabile quando il contenitore spaziale non è visibile. Ciò significa che non dispone di audio spazializzato e che l'app non è in grado di "preparare" i contenuti dipendenti dalla visualizzazione quando lo spatial_container non è visibile. Entrambe le opzioni sono accettabili perché, quando un container spaziale non è visibile, l'app deve interrompere qualsiasi carico della CPU/GPU utilizzato per quel container spaziale.

  • Dove deve essere posizionato lo spazio del contenitore spaziale nel contenitore spaziale? I suggerimenti sono stati il centro o il punto minimo (minX, minY, minZ).

    • Risolto. Al centro. Non esiste una posizione che non si muova nella maggior parte dei modi in cui è prevista l'UX di ridimensionamento di un contenitore spaziale (bordi in movimento). Il centro è di uso comune in altre parti di OpenXR. Non abbiamo utilizzato l'allineamento con le finestre nel computing 2D, che utilizzano la coordinata minima, perché i visualizzatori di modelli 3D spesso non seguono questa convenzione.

  • Quando è previsto che un runtime crei le risorse alla base del container spaziale? A volte questo comporta l'IPC con i servizi di sistema.

    • Risolto. In modo sincrono nell'ambito di xrCreateSpatialContainerEXT . Anche se potrebbe essere coinvolta l'IPC, la creazione effettiva di un container è generalmente considerata un'operazione economica. Alcuni fornitori hanno mutex globali per la gestione dei container, ma non si prevede che l'attesa sia lunga. I problemi relativi alla contesa dei mutex sono bug specifici del fornitore che dovrebbero essere risolti da ciascun fornitore.

  • Abbiamo bisogno di un segnale che indichi che un XrSession creerà container spaziali e, di conseguenza, non supporterà il percorso di rendering precedente?

    • Risolto. Sì. Modifichiamo la macchina a stati della sessione in modo fondamentale.

Cronologia delle versioni

  • Revisione 1, 6/08/2026 (Jared Finder, Google)

    • Descrizione iniziale dell'estensione