XR_EXT_spatial_container_self_rendering

Name String

XR_EXT_spatial_container_self_rendering

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

814

Revisione

1

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

XR_EXT_spatial_container

Data ultima modifica

2026-08-06

Stato IP

Nessuna rivendicazione di PI nota.

Collaboratori

Lachlan Ford, Google
Andreas Loeve Selvik, Meta Platforms
Adam Gousetis, Meta Platforms
Bjorn Swenson, LÖVR
Cass Everitt, Meta Platforms
Christian Kruse, Meta Platforms
Denny Rönngren, Varjo Technologies
Fredia Huya-Kouadio, Godot Engine
Jakob Bornecrantz, NVIDIA
Jared Finder, Google
Jonathan Wright, Meta Platforms
Jian Zhang, ByteDance
Kurtis Eveleigh, Qualcomm
Mauricio Narvaez, Meta Platforms
Nick Klingensmith, Qualcomm
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

Panoramica

Questa estensione definisce il "rendering autonomo" per i container spaziali. I pixel di un container spaziale con rendering autonomo vengono tutti generati da un'app e inviati al runtime utilizzando swapchain e livelli di composizione OpenXR standard. Poiché i container spaziali non occupano sempre tutti i pixel di uno schermo, il runtime informa le app della risoluzione e della configurazione di visualizzazione consigliate per ogni container spaziale, in modo da consentire alle app di eseguire il rendering in modo più efficiente.

Questa estensione, combinata con XR_EXT_spatial_container, ha lo scopo di offrire un superset delle funzionalità del rendering del livello di composizione principale di OpenXR 1.x convenzionale. I runtime OpenXR 1.x che supportano il rendering grafico e questa estensione devono impostare XrSystemSpatialContainerPropertiesEXT :: supportsImmersive su true per indicare che supportano i container spaziali immersivi.

Ciclo di vita del rendering dei container spaziali

Per utilizzare il rendering autonomo per un container spaziale, un'app imposta XrSpatialContainerCreateInfoEXT :: graphicsPresentation su XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT quando chiama xrCreateSpatialContainerEXT . L'app può quindi gestire se un container spaziale esegue attivamente il rendering chiamando le funzioni xrBeginSpatialContainerRenderingEXT e xrEndSpatialContainerRenderingEXT. Queste funzioni sostituiscono xrBeginSession e xrEndSession . Non sono operazioni per frame, come xrBeginFrame e xrEndFrame .

In ogni frame, un'app esegue i seguenti passaggi:

  • Chiama xrWaitFrame e xrBeginFrame . Queste funzioni non hanno strutture specifiche per i contenitori e funzionano come nella specifica di base.
  • Recupera le posizioni di visualizzazione, i parametri di proiezione e i suggerimenti di rendering per tutti i container spaziali che eseguono attivamente il rendering con xrLocateSpatialContainerViewsEXT . Per ogni container spaziale, il runtime segnala se i relativi livelli di composizione devono essere visualizzati e il modo consigliato per visualizzarli compilando XrSpatialContainerViewStateEXT .
  • Esegui il rendering dei pixel nei livelli di composizione normalmente. Queste operazioni non hanno strutture specifiche per i container.
  • Invia i livelli di composizione per tutti i container spaziali che eseguono attivamente il rendering chiamando xrEndFrame e concatenando XrSpatialContainerLayerFrameEndInfoEXT .

La distruzione di un handle XrSpatialContainerEXT lo rimuove implicitamente dal set di rendering attivo. Un'app può distruggere un container spaziale anche se ha effettuato una chiamata riuscita a xrBeginSpatialContainerRenderingEXT non associata a una chiamata corrispondente a xrEndSpatialContainerRenderingEXT . Il runtime deve comportarsi come se xrEndSpatialContainerRenderingEXT venisse chiamato implicitamente, se necessario, all'inizio dell'implementazione di xrDestroySpatialContainerEXT se viene restituito correttamente.

Quando un'app riceve un evento XrEventDataSpatialContainerClosedEXT per un container nel set di rendering attivo, l'app deve chiamare xrEndSpatialContainerRenderingEXT e distruggere l'handle XrSpatialContainerEXT.

La funzione xrBeginSpatialContainerRenderingEXT aggiunge il container spaziale al set di rendering attivo per sessione, consentendo a un'app di inviare livelli di composizione per il container spaziale a xrEndFrame .

XrResult xrBeginSpatialContainerRenderingEXT(
    XrSession                                   session,
    const XrSpatialContainerBeginInfoEXT*       beginInfo);

Descrizioni dei parametri

In genere, le app chiamano questo metodo in risposta a un evento visible-changed con XrEventDataSpatialContainerVisibleChangedEXT :: visible impostato su true.

Se il container spaziale non è stato creato con XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT quando viene chiamato xrCreateSpatialContainerEXT , il runtime deve restituire XR_ERROR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MISSING_EXT .

Se il contenitore spaziale è già nel set di rendering attivo, il runtime deve restituire XR_ERROR_SPATIAL_CONTAINER_IS_RENDERING_EXT .

Se xrBeginSpatialContainerRenderingEXT viene chiamata in un momento in cui l'app non può chiamare xrWaitFrame (ovvero all'interno della finestra xrBeginFrame e xrEndFrame), il runtime deve restituire XR_ERROR_CALL_ORDER_INVALID.

Utilizzo valido (implicito)

Thread safety

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MISSING_EXT
  • XR_ERROR_SPATIAL_CONTAINER_IS_RENDERING_EXT
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED

La struttura XrSpatialContainerBeginInfoEXT viene utilizzata per specificare i parametri per l'inizio del rendering di un container spaziale.

typedef struct XrSpatialContainerBeginInfoEXT {
    XrStructureType            type;
    const void*                next;
    XrSpatialContainerEXT      spatialContainer;
    XrViewConfigurationType    primaryViewConfigurationType;
} XrSpatialContainerBeginInfoEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • spatialContainer è l'XrSpatialContainerEXT per iniziare il rendering.
  • primaryViewConfigurationType è il valore XrViewConfigurationType principale da utilizzare per il contenitore spaziale.

primaryViewConfigurationType è la configurazione della visualizzazione che l'app intende utilizzare durante il rendering. Il runtime può ridurre la configurazione della visualizzazione a un tipo con meno visualizzazioni per scopi di ottimizzazione (ad esempio, un container è molto lontano e piccolo, per cui la stereofonia è impercettibile). Il runtime restituisce i dettagli sulla configurazione della visualizzazione decaduta dalle chiamate a xrLocateSpatialContainerViewsEXT .

Utilizzo valido (implicito)

La funzione xrEndSpatialContainerRenderingEXT rimuove il container spaziale dal set di rendering attivo.

XrResult xrEndSpatialContainerRenderingEXT(
    XrSession                                   session,
    const XrSpatialContainerEndInfoEXT*         endInfo);

Descrizioni dei parametri

In genere, le app chiamano questo metodo in risposta a un evento visible-changed con XrEventDataSpatialContainerVisibleChangedEXT :: visible impostato su false.

Se il contenitore spaziale non si trova nel set di rendering attivo, il runtime deve restituire XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT .

Se xrEndSpatialContainerRenderingEXT viene chiamata in un momento in cui l'app non può chiamare xrWaitFrame (ovvero durante il periodo tra le chiamate xrBeginFrame e xrEndFrame), il runtime deve restituire XR_ERROR_CALL_ORDER_INVALID.

Utilizzo valido (implicito)

Thread safety

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT
  • XR_ERROR_VALIDATION_FAILURE

La struttura XrSpatialContainerEndInfoEXT viene utilizzata per specificare i parametri per terminare il rendering di un contenitore spaziale.

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

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • spatialContainer è l'oggetto XrSpatialContainerEXT per terminare il rendering.

Utilizzo valido (implicito)

Individuazione delle visualizzazioni tramite xrLocateSpatialContainerViewsEXT

La funzione xrLocateSpatialContainerViewsEXT individua le visualizzazioni per un insieme di container spaziali.

XrResult xrLocateSpatialContainerViewsEXT(
    XrSession                                   session,
    const XrSpatialContainerViewsLocateInfoEXT* locateInfo,
    uint32_t                                    viewStateCount,
    XrSpatialContainerViewStateEXT*             viewStates,
    uint32_t                                    viewCount,
    XrView*                                     views);

Descrizioni dei parametri

Questa funzione sostituisce xrLocateViews , consentendo a un'app di eseguire query sulle visualizzazioni per più container spaziali contemporaneamente.

Le visualizzazioni per tutti i container spaziali vengono restituite nell'unico array views. Le visualizzazioni sono ordinate in base all'indice del container spaziale nell'array XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfos, quindi all'indice della visualizzazione per quel container.

Ad esempio, se un'app fornisce tre container spaziali in XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfos :

  • Indice 0: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO (1 visualizzazione)
  • Indice 1: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO (2 visualizzazioni)
  • Indice 2: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO_WITH_FOVEATED_INSET (4 visualizzazioni)

Il runtime deve quindi compilare l'array views con 7 visualizzazioni:

  • views [0] è la vista per il container 0.
  • views [1] è la vista dell'occhio sinistro per il contenitore 1.
  • views [2] è la visualizzazione dell'occhio destro per il container 1.
  • views [3] è la vista dell'occhio sinistro per il contenitore 2.
  • views [4] è la visualizzazione dell'occhio destro per il container 2.
  • views [5] è la visualizzazione dell'inserto dell'occhio sinistro per il contenitore 2.
  • views [6] è la visualizzazione dell'inserto dell'occhio destro per il container 2.

Se viewCount non è uguale alla somma dei numeri di visualizzazioni per il tipo di configurazione della visualizzazione richiesto di ogni contenitore spaziale, il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

Il runtime può ridurre la configurazione della visualizzazione a un tipo con meno visualizzazioni per scopi di ottimizzazione (ad es. un container è molto lontano e piccolo, per cui lo stereo è impercettibile). Se il runtime riduce la configurazione delle visualizzazioni, deve comunque restituire il numero originale di visualizzazioni per quel container, compilando le visualizzazioni aggiuntive con duplicati delle visualizzazioni ridotte. Ad esempio, se XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO viene ridotto a XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO , sia l'indice 0 che l'indice 1 conterranno la singola visualizzazione mono. Di conseguenza, il numero totale di visualizzazioni restituite nell'array views è indipendente dal fatto che il runtime abbia deciso o meno di eseguire il decadimento di una configurazione di visualizzazione.

Il runtime dovrebbe adattare ogni XrView :: fov restituito in modo che il frustum sia il più piccolo possibile, pur contenendo l'intero limite del container spaziale corrispondente. I runtime possono restituire FOV non simmetrici, ad esempio se un contenitore spaziale si trova ad angolo obliquo rispetto alla visuale dell'utente o è parzialmente nascosto da un altro oggetto. I runtime possono posizionare liberamente la superficie di rendering di destinazione per il container spaziale. A causa della natura del rendering multi-app, in cui i container spaziali sono scollegati dall'utente, il runtime potrebbe restituire valori XrView non adatti al rendering dei pixel, ad esempio se il container spaziale non è visibile sullo schermo, non esistono valori validi per impostare XrView :: fov. In questi casi, i runtime devono impostare XrSpatialContainerViewStateEXT :: shouldSubmitLayers su false.

Il runtime restituisce ulteriori informazioni sullo stato di rendering del container per spazio nell'array viewStates. Se viewStateCount non è uguale a XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfoCount , il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

Dopo che il runtime ha inserito in coda un evento XrEventDataSpatialContainerClosedEXT per un container spaziale, questa funzione deve restituire XR_FALSE in XrSpatialContainerViewStateEXT :: shouldSubmitLayers e 0 in XrSpatialContainerViewStateEXT :: viewStateFlags per il container spaziale corrispondente.

Per i container spaziali con posizioni che cambiano attivamente nel mondo reale, il runtime dovrebbe tenere conto del movimento del container durante la compilazione di views per ridurre al minimo gli artefatti di riproiezione.

Se xrLocateSpatialContainerViewsEXT viene chiamato per uno o più container spaziali non attualmente nel set di rendering attivo, il runtime deve restituire XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED

La struttura XrSpatialContainerViewsLocateInfoEXT contiene i parametri per individuare le visualizzazioni in una raccolta di container spaziali.

typedef struct XrSpatialContainerViewsLocateInfoEXT {
    XrStructureType                               type;
    const void*                                   next;
    XrTime                                        displayTime;
    uint32_t                                      viewLocateInfoCount;
    const XrSpatialContainerViewLocateInfoEXT*    viewLocateInfos;
} XrSpatialContainerViewsLocateInfoEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • displayTime è la XrTime in cui si trovano le visualizzazioni.
  • viewLocateInfoCount è il numero di voci nell'array viewLocateInfos.
  • viewLocateInfos è un puntatore a un array di strutture XrSpatialContainerViewLocateInfoEXT.

Utilizzo valido (implicito)

La struttura XrSpatialContainerViewLocateInfoEXT contiene i parametri per un singolo container spaziale per cui individuare le visualizzazioni.

typedef struct XrSpatialContainerViewLocateInfoEXT {
    XrStructureType            type;
    const void*                next;
    XrViewConfigurationType    viewConfigurationType;
    XrSpace                    space;
    XrSpatialContainerEXT      spatialContainer;
} XrSpatialContainerViewLocateInfoEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • viewConfigurationType è un XrViewConfigurationType da utilizzare per il container spaziale.
  • space è l'XrSpace in cui si trovano le visualizzazioni del container spaziale.
  • spatialContainer è l'handle XrSpatialContainerEXT.

L'app può fornire qualsiasi XrSpace valido in space , tuttavia è consigliabile fornire lo spazio del container spaziale per il XrSpatialContainerEXT corrispondente specificato nella struttura XrSpatialContainerViewLocateInfoEXT.

Utilizzo valido (implicito)

La struttura XrSpatialContainerViewStateEXT viene compilata dalle chiamate a xrLocateSpatialContainerViewsEXT con informazioni sull'idoneità del rendering per contenitore spaziale.

typedef struct XrSpatialContainerViewStateEXT {
    XrStructureType            type;
    void*                      next;
    XrViewStateFlags           viewStateFlags;
    XrViewConfigurationType    viewConfigurationType;
    XrBool32                   shouldSubmitLayers;
    XrExtent2Di                recommendedImageExtent;
} XrSpatialContainerViewStateEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • viewStateFlags è una bitmask di XrViewStateFlags . Questi flag hanno lo stesso scopo dei viewStateFlags nella struttura principale XrViewState.
  • viewConfigurationType è un XrViewConfigurationType che indica il tipo di configurazione della visualizzazione utilizzato dal runtime per il container spaziale, che i runtime potrebbero ridurre a una configurazione della visualizzazione con un numero di visualizzazioni inferiore a quello richiesto.
  • shouldSubmitLayers è un XrBool32 restituito dal runtime. Se XR_FALSE, l'app dovrebbe evitare di inviare la composizione per questo contenitore spaziale, poiché al momento non è visibile o si trova in uno stato in cui il rendering non è richiesto.
  • recommendedImageExtent è una struttura XrExtent2Di che rappresenta la risoluzione consigliata per il container spaziale.

Come per la posizione della visualizzazione OpenXR di base, l'app deve controllare XrSpatialContainerViewStateEXT :: viewStateFlags per assicurarsi che la posizione e l'orientamento siano validi e monitorati prima di utilizzare i dati della visualizzazione per il rendering.

L'app dovrebbe controllare shouldSubmitLayers e viewConfigurationType per evitare di eseguire il rendering di un numero di elementi superiore a quello consigliato dal runtime. Quando shouldSubmitLayers è false, l'app modifica il comportamento di rendering come segue:

  • L'app non deve leggere il corrispondente XrView :: fov .
  • L'app non deve leggere recommendedImageExtent .
  • L'app deve evitare il rendering in swapchain e l'invio di livelli di composizione per il container spaziale corrispondente.
  • L'app deve impostare XrSpatialContainerLayerEXT :: retainPreviousSubmission su true. Se l'app sceglie comunque di inviare i livelli, spetta al runtime determinare cosa fare con i livelli (ad esempio, il runtime potrebbe scegliere di eliminarli).

recommendedImageExtent è destinato esplicitamente ai livelli che verranno aggiornati in base alla posizione del contenitore o alla visualizzazione dell'utente. Quando aggiorna i livelli con contenuti che dipendono dalla posizione del contenitore spaziale o dalla visualizzazione dell'utente (ad esempio i normali contenuti 3D), l'app deve eseguire il rendering in questa area visibile più piccola anziché nelle dimensioni di visualizzazione consigliate predefinite. Quando aggiorna i livelli con contenuti che non dipendono dalla posizione del contenitore spaziale o dalla visuale dell'utente (come i livelli quad statici), l'app può ignorare questi valori in sicurezza. Per i livelli dipendenti dalla visualizzazione, recommendedImageExtent è un suggerimento per l'app dal runtime destinato a ridurre al minimo l'aliasing e migliorare le prestazioni di rendering. Se lo desidera, l'app può inviare i contenuti alla risoluzione completa senza costi.

XrExtent2Di :: width e XrExtent2Di :: height di recommendedImageExtent devono essere sempre un numero intero positivo inferiore o uguale a XrViewConfigurationView :: recommendedImageRectWidth e XrViewConfigurationView :: recommendedImageRectHeight di XrViewConfigurationView per la configurazione della visualizzazione principale del container spaziale. Un'app non deve ricreare una catena di scambio solo perché recommendedImageExtent è cambiato, in quanto si tratta di un suggerimento dinamico per l'app che specifica l'XrSwapchainSubImage :: imageRect da utilizzare nell'XrSwapchainSubImage di qualsiasi livello di composizione a risoluzione piena che invia e può cambiare ogni frame.

Utilizzo valido (implicito)

Visualizza spazio di riferimento

Lo spazio di riferimento della visualizzazione rimane invariato rispetto a quello di OpenXR core. Come in Core, non è destinato al rendering.

Invio di livelli tramite xrEndFrame

Per eseguire il rendering dei contenitori spaziali, l'app deve fornire un elenco di livelli associati ai rispettivi contenitori spaziali a xrEndFrame . Questo viene fatto tramite la struttura XrSpatialContainerLayerFrameEndInfoEXT.

typedef struct XrSpatialContainerLayerFrameEndInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             containerLayerCount;
    const XrSpatialContainerLayerEXT*    containerLayers;
} XrSpatialContainerLayerFrameEndInfoEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • containerLayerCount è il numero di elementi nell'array containerLayers.
  • containerLayers è un puntatore a un array di strutture XrSpatialContainerLayerEXT.

L'array containerLayers contiene un XrSpatialContainerLayerEXT per ogni container spaziale nel set di rendering attivo (i container gestiti per sessione da xrBeginSpatialContainerRenderingEXT e xrEndSpatialContainerRenderingEXT). Ogni XrSpatialContainerLayerEXT contiene un elenco di puntatori XrCompositionLayerBaseHeader associati al container spaziale specificato. I runtime possono comporre i container in qualsiasi ordine scelgano, indipendentemente dall'ordine di containerLayers . Ad esempio, i runtime possono comporre container in base alla loro profondità rispetto all'utente, fare in modo che un container spaziale funga da livello di sfondo o "bloccare" un container spaziale in modo che sia sempre in primo piano, indipendentemente dalla sua profondità. I runtime possono comporre i livelli utilizzando strategie diverse per i container spaziali in modalità limitata o immersiva. Ad esempio, i runtime possono precomporre i livelli di composizione di ogni contenitore spaziale limitato in un unico livello stereo quad che viene combinato con tutti gli altri contenitori in un secondo passaggio di composizione.

XrFrameEndInfo :: displayTime e XrFrameEndInfo :: environmentBlendMode verranno applicati a tutti i container spaziali forniti in XrSpatialContainerLayerFrameEndInfoEXT .

Quando questa struttura viene passata a xrEndFrame concatenandola a XrFrameEndInfo , vengono aggiunti i seguenti casi di errore aggiuntivi in base al set di rendering attivo:

  • Se un contenitore spaziale è referenziato da più di un elemento di containerLayers , i runtime devono restituire XR_ERROR_SPATIAL_CONTAINER_DUPLICATE_EXT .
  • Se un container spaziale nel set di rendering attivo non è referenziato da un elemento di containerLayers , i runtime devono restituire XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT .
  • Se un contenitore spaziale a cui fa riferimento containerLayers non è un membro del set di rendering attivo, i runtime devono restituire XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT .

Inoltre, se nel set di rendering attivo sono presenti container spaziali e questa struttura non è concatenata a XrFrameEndInfo , i runtime devono restituire XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT .

In tutti i casi di errore sopra indicati, il runtime non deve eseguire il rendering di alcun contenuto per nessun contenitore spaziale.

Se nel set di rendering attivo non sono presenti container spaziali, un'app può chiamare xrEndFrame, a condizione che non invii livelli di composizione.

Tieni presente che le singole catene di scambio possono essere inviate per più contenitori tramite livelli in una struttura valida, ad esempio un livello quad di cui viene eseguito il rendering tramite una singola catena di scambio inviata a più contenitori spaziali. Questo caso viene gestito in modo uniforme con gli altri rendering: il runtime deve eseguire il rendering del quad in tutti questi contenitori spaziali.

Utilizzo valido (implicito)

La struttura XrSpatialContainerLayerEXT raggruppa i livelli di composizione standard e li associa a un contenitore spaziale specifico.

typedef struct XrSpatialContainerLayerEXT {
    XrStructureType                               type;
    const void*                                   next;
    XrSpatialContainerEXT                         spatialContainer;
    XrBool32                                      retainPreviousSubmission;
    uint32_t                                      layerCount;
    const XrCompositionLayerBaseHeader* const*    layers;
} XrSpatialContainerLayerEXT;

Descrizione membro

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • spatialContainer è l'oggetto XrSpatialContainerEXT che identifica il container di destinazione.
  • retainPreviousSubmission è un XrBool32 . Se XR_TRUE , il runtime manterrà l'ultimo frame inviato per questo contenitore spaziale.
  • layerCount è il numero di livelli di composizione nell'array layers.
  • layers è un puntatore a un array di puntatori XrCompositionLayerBaseHeader.

Quando retainPreviousSubmission è XR_TRUE , il runtime deve riutilizzare i livelli di composizione e i contenuti delle immagini della catena di scambio così come sono stati bloccati durante la chiamata xrEndFrame più recente in cui retainPreviousSubmission era XR_FALSE . Eventuali modifiche successive alle catene di scambio utilizzate dai livelli conservati non devono essere applicate all'output sottoposto a rendering.

Per i livelli inviati per un singolo contenitore spaziale (rendering all'interno del contenitore), il runtime deve seguire le regole già specificate per l'ordine di composizione dei livelli. In altre parole, i livelli all'interno dei container devono essere disegnati nello stesso ordine in cui sono specificati, composti tramite l'algoritmo del pittore.

"Cancellare" un contenitore spaziale significa rimuovere tutti i contenuti da un contenitore spaziale, in modo che non venga eseguito il rendering di nulla per quel contenitore nel frame corrente. I runtime devono trattare questo valore come equivalente all'invio da parte dell'app di un nero trasparente (tutti i bit 0) per ogni pixel all'interno del container. "Conservare" un container spaziale significa che il runtime continua a visualizzare l'insieme di livelli inviato più di recente per quel container.

Per ogni contenitore spaziale, l'app può specificare se inviare nuovi livelli, conservare l'invio precedente o cancellare il contenitore spaziale:

  • Per inviare nuovi livelli, l'app fornisce un valore layerCount diverso da zero e un puntatore layers valido.
  • Per cancellare un contenitore spaziale, il valore layerCount per la sua voce deve essere 0 e il valore retainPreviousSubmission deve essere XR_FALSE .
  • Per conservare gli ultimi livelli e le immagini della catena di scambio inviati (conservazione), il valore layerCount per la relativa voce deve essere 0 e retainPreviousSubmission deve essere XR_TRUE .

Questo controllo esplicito per container garantisce che l'intent dell'app venga comunicato chiaramente in ogni frame.

Se retainPreviousSubmission è XR_TRUE e layerCount non è 0, il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

Se XrSpatialContainerCompositionLayerViewConfigurationEXT non è concatenato a un XrCompositionLayerProjection che fa parte di un container spaziale, il runtime deve restituire XR_ERROR_VALIDATION_FAILURE . Questa struttura è applicabile solo ai livelli XrCompositionLayerProjection. Se è concatenato ad altri tipi di livelli (ad es. livelli quad o cilindrici), il runtime deve restituire XR_ERROR_VALIDATION_FAILURE.

Utilizzo valido (implicito)

Specifica della configurazione di visualizzazione per i livelli di proiezione

La struttura XrSpatialContainerCompositionLayerViewConfigurationEXT viene utilizzata per specificare la configurazione della visualizzazione utilizzata per eseguire il rendering di un livello di proiezione per un container spaziale.

typedef struct XrSpatialContainerCompositionLayerViewConfigurationEXT {
    XrStructureType            type;
    const void*                next;
    XrViewConfigurationType    viewConfigurationType;
} XrSpatialContainerCompositionLayerViewConfigurationEXT;

Descrizione membro

Quando invia un XrCompositionLayerProjection per un container spaziale, l'app deve specificare quale configurazione di visualizzazione è stata utilizzata per eseguire il rendering del livello. Questo è necessario perché l'app può scegliere per ogni frame se eseguire il rendering con la configurazione di visualizzazione principale del container spaziale o con la configurazione di visualizzazione decaduta suggerita dal runtime, se presente.

Quando XrSpatialContainerCompositionLayerViewConfigurationEXT è concatenato, l'app deve assicurarsi che XrCompositionLayerProjection :: viewCount sia un numero di visualizzazioni valido per XrViewConfigurationType specificato nella struttura concatenata. Il viewConfigurationType specificato nella struttura concatenata deve essere il XrSpatialContainerBeginInfoEXT :: primaryViewConfigurationType specificato all'avvio del container o il tipo di configurazione della visualizzazione decaduta restituito dal runtime in XrSpatialContainerViewStateEXT o valori aggiuntivi abilitati tramite un'estensione.

Utilizzo valido (implicito)

Comportamento di clipping dei pixel

Le app devono informare il runtime se eseguono o meno il rendering dei pixel al di fuori dei limiti di un container spaziale concatenando XrSpatialContainerLayerVolumeClippingEXT durante l'invio dei livelli di composizione.

typedef struct XrSpatialContainerLayerVolumeClippingEXT {
    XrStructureType                        type;
    const void*                            next;
    XrSpatialContainerVolumeClippingEXT    volumeClipping;
} XrSpatialContainerLayerVolumeClippingEXT;

Descrizione membro

Questa struttura funge da suggerimento per indicare se l'app esegue il rendering dei pixel al di fuori dei limiti di un container spaziale. Quando un container spaziale è in modalità immersiva, questo suggerimento non ha alcun significato perché i limiti sono infiniti.

Per i contenitori spaziali limitati che utilizzano il rendering autonomo, il runtime deve ragionare sia sui limiti del volume 3D sia sui limiti dei pixel 2D. I limiti del volume 3D vengono restituiti da xrGetSpatialContainerBoundsEXT . I limiti dei pixel 2D sono la proiezione dei limiti del volume 3D su ogni display del sistema.

I runtime devono ignorare i pixel delle immagini della catena di scambio al di fuori dei limiti dei pixel 2D, ma non devono ignorare i pixel che si trovano all'interno dei limiti dei pixel 2D, ma al di fuori dei limiti del volume 3D. Sono possibili effetti stereo in cui i contenuti sembrano estendersi oltre o davanti ai limiti del volume 3D del container. Le app possono eliminare i pixel al di fuori dei limiti del volume 3D di un contenitore spaziale limitato per ridurre i paradossi di profondità e devono impostare volumeClipping in base a come lo fanno. I paradossi di profondità spesso causano affaticamento degli occhi e disagio per l'utente.

I runtime possono utilizzare volumeClipping per regolare il modo in cui mostrano un determinato contenitore spaziale. Ad esempio, se impostato su XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT, un runtime potrebbe eseguire il rendering delle facce posteriori dei limiti del volume 3D che causerebbero paradossi di profondità se il contenitore spaziale disegnasse pixel dietro i limiti del volume 3D del contenitore.

Le estensioni future potrebbero consentire il ritaglio in base ai limiti del volume 3D se vengono inviate informazioni sulla profondità.

Utilizzo valido (implicito)

Nuovi comandi

Nuove strutture

Nuove costanti enum

  • XR_EXT_SPATIAL_CONTAINER_SELF_RENDERING_EXTENSION_NAME
  • XR_EXT_spatial_container_self_rendering_SPEC_VERSION

  • Estensione di XrResult :

    • XR_ERROR_SPATIAL_CONTAINER_DUPLICATE_EXT
    • XR_ERROR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINER_IS_RENDERING_EXT
    • XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT

  • Estensione di XrSpatialContainerGraphicsPresentationEXT :

    • XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

  • Estensione di XrStructureType :

    • XR_TYPE_SPATIAL_CONTAINER_BEGIN_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_COMPOSITION_LAYER_VIEW_CONFIGURATION_EXT
    • XR_TYPE_SPATIAL_CONTAINER_END_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_LAYER_EXT
    • XR_TYPE_SPATIAL_CONTAINER_LAYER_FRAME_END_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_LAYER_VOLUME_CLIPPING_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VIEWS_LOCATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VIEW_LOCATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VIEW_STATE_EXT

Esempi di codice

// Example: Complete lifecycle, view location, and frame submission for spatial containers
PFN_xrBeginSpatialContainerRenderingEXT xrBeginSpatialContainerRenderingEXT; // previously initialized
PFN_xrEndSpatialContainerRenderingEXT xrEndSpatialContainerRenderingEXT; // previously initialized
PFN_xrLocateSpatialContainerViewsEXT xrLocateSpatialContainerViewsEXT; // previously initialized

XrSession session; // previously initialized

// We want to update this container
XrSpatialContainerEXT containerA; // previously initialized with XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT
XrSpace containerASpace; // previously initialized

// We want to retain this container
XrSpatialContainerEXT containerB; // previously initialized with XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT
XrSpace containerBSpace; // previously initialized

// 1. Add to active render set when the app is ready to start submitting layers
XrSpatialContainerBeginInfoEXT beginInfoA {
  .type = XR_TYPE_SPATIAL_CONTAINER_BEGIN_INFO_EXT,
  .spatialContainer = containerA,
  .primaryViewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
};
CHK_XR(xrBeginSpatialContainerRenderingEXT(session, &beginInfoA));

XrSpatialContainerBeginInfoEXT beginInfoB {
  .type = XR_TYPE_SPATIAL_CONTAINER_BEGIN_INFO_EXT,
  .spatialContainer = containerB,
  .primaryViewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
};
CHK_XR(xrBeginSpatialContainerRenderingEXT(session, &beginInfoB));

// ... Frame Loop ...


XrTime displayTime; // returned from xrWaitFrame

const std::vector<XrSpatialContainerEXT> containers = {containerA, containerB};
const std::vector<XrSpace> containerSpaces = {containerASpace, containerBSpace};
uint32_t containerCount = static_cast<uint32_t>(containers.size());

// 2. Setup individual locate info for each container
std::vector<XrSpatialContainerViewLocateInfoEXT> containerLocateInfos(containerCount, {
  .type = XR_TYPE_SPATIAL_CONTAINER_VIEW_LOCATE_INFO_EXT,
});

for (uint32_t i = 0; i < containerCount; ++i) {
    containerLocateInfos[i].viewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO;
    containerLocateInfos[i].space = containerSpaces[i]; // Recommended to use container's own space
    containerLocateInfos[i].spatialContainer = containers[i];
}

// Setup bulk locate info
XrSpatialContainerViewsLocateInfoEXT locateInfo {
  .type = XR_TYPE_SPATIAL_CONTAINER_VIEWS_LOCATE_INFO_EXT,
  .displayTime = displayTime,
  .viewLocateInfoCount = containerCount,
  .viewLocateInfos = containerLocateInfos.data(),
};

// Prepare states to be populated by the runtime
std::vector<XrSpatialContainerViewStateEXT> viewStates(containerCount, {
  .type = XR_TYPE_SPATIAL_CONTAINER_VIEW_STATE_EXT,
});

// Call the dedicated locate views function
// We know the required view count is 2 per container for STEREO
const uint32_t viewsPerConfig = 2;
uint32_t totalViewCount = containerCount * viewsPerConfig;
std::vector<XrView> views(totalViewCount, {.type = XR_TYPE_VIEW});

CHK_XR(xrLocateSpatialContainerViewsEXT(session, &locateInfo, containerCount, viewStates.data(), totalViewCount, views.data()));

// Process results
for (uint32_t i = 0; i < containerCount; ++i) {
    XrBool32 shouldSubmitLayers = viewStates[i].shouldSubmitLayers;
    XrExtent2Di recommendedImageExtent = viewStates[i].recommendedImageExtent;
    XrViewConfigurationType viewConfigurationType = viewStates[i].viewConfigurationType;
    bool isDecayedToMono = (viewConfigurationType == XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO);
    if (shouldSubmitLayers) {
        // App is expected to also verify viewStates[i].viewStateFlags has valid orientation/position bits before rendering
        XrView& leftView = views[i * viewsPerConfig];
        XrView& rightView = views[i * viewsPerConfig + 1];
        // If isDecayedToMono is true, left and right will be identical.
    } else {
        // Skip layer submission but retain previous submission when calling
        // xrEndFrame.
    }
}

// 3. Setup projection layer for container A
XrCompositionLayerProjection projectionLayer = {.type = XR_TYPE_COMPOSITION_LAYER_PROJECTION};
// ... standard projection layer setup (space, viewCount, views, etc.) ...

// Specify which view configuration was used to render this specific layer
XrSpatialContainerCompositionLayerViewConfigurationEXT containerViewConfig {
  .type = XR_TYPE_SPATIAL_CONTAINER_COMPOSITION_LAYER_VIEW_CONFIGURATION_EXT,
  // Even if the runtime decayed to MONO, we indicate what we actually rendered
  .viewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
};

// Chain it to the projection layer
projectionLayer.next = &containerViewConfig;
const XrCompositionLayerBaseHeader* layersA[1] = {reinterpret_cast<const XrCompositionLayerBaseHeader*>(&projectionLayer)};

// Note: In a real app, you are required to submit ALL active containers in the render set.

XrSpatialContainerLayerVolumeClippingEXT containerClippingA = {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_VOLUME_CLIPPING_EXT,
  // Set volumeClipping appropriately for the rendering done.
  .volumeClipping = XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT,
};

// Setup container A (Update with new pixels)
XrSpatialContainerLayerEXT containerLayerA {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_EXT,
  .next = &containerClippingA,
  .spatialContainer = containerA,
  .retainPreviousSubmission = XR_FALSE,
  .layerCount = 1,
  .layers = layersA,
};

XrSpatialContainerLayerVolumeClippingEXT containerClippingB {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_VOLUME_CLIPPING_EXT,
  // Set volumeClipping appropriately for the rendering done.
  .volumeClipping = XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT,
};

// Setup container B (Explicitly retain previous frame)
XrSpatialContainerLayerEXT containerLayerB {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_EXT,
  .next = &containerClippingB,
  .spatialContainer = containerB,
  .retainPreviousSubmission = XR_TRUE,
  .layerCount = 0, // Required to be 0 when retaining
  .layers = nullptr,
};

// Aggregate all container layers
XrSpatialContainerLayerEXT containerLayers[] = { containerLayerA, containerLayerB };

XrSpatialContainerLayerFrameEndInfoEXT spatialEndInfo {
  .type = XR_TYPE_SPATIAL_CONTAINER_LAYER_FRAME_END_INFO_EXT,
  .containerLayerCount = 2, // Must equal the number of active containers
  .containerLayers = containerLayers,
};

XrFrameEndInfo frameEndInfo {
  .type = XR_TYPE_FRAME_END_INFO,
  .next = &spatialEndInfo,
  .displayTime = displayTime,
  .environmentBlendMode = XR_ENVIRONMENT_BLEND_MODE_ALPHA_BLEND,
  .layerCount = 0, // MANDATORY: Must be 0 for self rendering extension
};

CHK_XR(xrEndFrame(session, &frameEndInfo));

// ... End Frame Loop ...

// 4. Remove from active render set when the container is destroyed or no longer needs rendering
XrSpatialContainerEndInfoEXT endInfoA {
  .type = XR_TYPE_SPATIAL_CONTAINER_END_INFO_EXT,
  .spatialContainer = containerA,
};
CHK_XR(xrEndSpatialContainerRenderingEXT(session, &endInfoA));

XrSpatialContainerEndInfoEXT endInfoB {
  .type = XR_TYPE_SPATIAL_CONTAINER_END_INFO_EXT,
  .spatialContainer = containerB,
};
CHK_XR(xrEndSpatialContainerRenderingEXT(session, &endInfoB));

Cronologia delle versioni

  • Revisione 1, 6 agosto 2026 (Lachlan Ford)

    • Descrizione iniziale dell'estensione