XR_EXT_spatial_container_self_rendering

String de nome

XR_EXT_spatial_container_self_rendering

Tipo de extensão

Extensão de instância

Número de ramal registrado

814

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_EXT_spatial_container

Data da última modificação

2026-08-06

Status do IP

Nenhuma reivindicação de PI conhecida.

Colaboradores

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

Visão geral

Essa extensão define a "renderização automática" para contêineres espaciais. Os pixels de um contêiner espacial auto-renderizado são todos gerados por um app e enviados ao ambiente de execução usando swapchains e camadas de composição padrão do OpenXR. Como os contêineres espaciais nem sempre ocupam todos os pixels de uma tela, o ambiente de execução informa aos apps a resolução e a configuração de visualização recomendadas de cada contêiner espacial para que eles sejam renderizados com mais eficiência.

Essa extensão, combinada com XR_EXT_spatial_container, tem como objetivo oferecer um superconjunto dos recursos de renderização da camada de composição principal do OpenXR 1.x convencional. Os ambientes de execução do OpenXR 1.x que oferecem suporte à renderização gráfica e a essa extensão precisam definir XrSystemSpatialContainerPropertiesEXT :: supportsImmersive como verdadeiro para indicar que oferecem suporte a contêineres espaciais imersivos.

Ciclo de vida de renderização do contêiner espacial

Para usar a renderização automática em um contêiner espacial, um app define XrSpatialContainerCreateInfoEXT :: graphicsPresentation como XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT ao chamar xrCreateSpatialContainerEXT . Em seguida, esse app pode gerenciar se um contêiner espacial está sendo renderizado ativamente chamando as funções xrBeginSpatialContainerRenderingEXT e xrEndSpatialContainerRenderingEXT. Essas funções substituem xrBeginSession e xrEndSession . Elas não são operações por frame, como xrBeginFrame e xrEndFrame .

Em cada frame, um app passa pelas seguintes etapas:

  • Chame xrWaitFrame e xrBeginFrame . Essas funções não têm estruturas específicas de contêiner e funcionam como na especificação principal.
  • Recupere poses de visualização, parâmetros de projeção e recomendações de renderização para todos os contêineres espaciais que estão sendo renderizados ativamente com xrLocateSpatialContainerViewsEXT . Para cada contêiner espacial, o ambiente de execução informa se as camadas de composição precisam ser renderizadas e a maneira recomendada de renderizar as camadas preenchendo XrSpatialContainerViewStateEXT .
  • Renderize pixels em camadas de composição normalmente. Essas operações não têm estruturas específicas de contêiner.
  • Envie camadas de composição para todos os contêineres espaciais que estão sendo renderizados ativamente chamando xrEndFrame e encadeando XrSpatialContainerLayerFrameEndInfoEXT .

Destruir um identificador XrSpatialContainerEXT o remove implicitamente do conjunto de renderização ativo. Um app pode destruir um contêiner espacial mesmo que tenha feito uma chamada bem-sucedida para xrBeginSpatialContainerRenderingEXT não associada a uma chamada correspondente para xrEndSpatialContainerRenderingEXT . O ambiente de execução precisa se comportar como se xrEndSpatialContainerRenderingEXT fosse chamado implicitamente, se necessário, no início da implementação de xrDestroySpatialContainerEXT, se ele retornar com sucesso.

Quando um app recebe um evento XrEventDataSpatialContainerClosedEXT para um contêiner no conjunto de renderização ativo, ele precisa chamar xrEndSpatialContainerRenderingEXT e destruir o identificador XrSpatialContainerEXT.

A função xrBeginSpatialContainerRenderingEXT adiciona o contêiner espacial ao conjunto de renderização ativo por sessão, permitindo que um app envie camadas de composição do contêiner espacial para xrEndFrame .

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

Descrições dos parâmetros

Os apps normalmente chamam isso em resposta a um evento de mudança de visibilidade com XrEventDataSpatialContainerVisibleChangedEXT :: visible definido como verdadeiro.

Se o contêiner espacial não tiver sido criado com XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT ao chamar xrCreateSpatialContainerEXT , o ambiente de execução precisará retornar XR_ERROR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MISSING_EXT .

Se o contêiner espacial já estiver no conjunto de renderização ativo, o ambiente de execução precisa retornar XR_ERROR_SPATIAL_CONTAINER_IS_RENDERING_EXT .

Se xrBeginSpatialContainerRenderingEXT for chamada em um momento em que o app não puder chamar xrWaitFrame (ou seja, dentro da janela xrBeginFrame e xrEndFrame), o ambiente de execução precisará retornar XR_ERROR_CALL_ORDER_INVALID.

Uso válido (implícito)

Concorrência segura

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

A estrutura XrSpatialContainerBeginInfoEXT é usada para especificar os parâmetros para iniciar a renderização de um contêiner espacial.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • spatialContainer é o XrSpatialContainerEXT para iniciar a renderização.
  • primaryViewConfigurationType é o XrViewConfigurationType principal a ser usado para o contêiner espacial.

primaryViewConfigurationType é a configuração de visualização que o app pretende usar ao renderizar. O ambiente de execução pode reduzir a configuração de visualização para um tipo com menos visualizações para fins de otimização (por exemplo, um contêiner está muito distante e é pequeno, de modo que o estéreo é imperceptível). O ambiente de execução retorna detalhes sobre a configuração de visualização deteriorada de chamadas para xrLocateSpatialContainerViewsEXT .

Uso válido (implícito)

A função xrEndSpatialContainerRenderingEXT remove o contêiner espacial do conjunto de renderização ativo.

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

Descrições dos parâmetros

Os apps geralmente chamam isso em resposta a um evento de mudança de visibilidade com XrEventDataSpatialContainerVisibleChangedEXT :: visible definido como falso.

Se o contêiner espacial não estiver no conjunto de renderização ativo, o ambiente de execução precisa retornar XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT .

Se xrEndSpatialContainerRenderingEXT for chamada em um momento em que o app não pode chamar xrWaitFrame (ou seja, durante o período entre as chamadas xrBeginFrame e xrEndFrame), o ambiente de execução precisa retornar XR_ERROR_CALL_ORDER_INVALID.

Uso válido (implícito)

Concorrência segura

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

A estrutura XrSpatialContainerEndInfoEXT é usada para especificar os parâmetros para encerrar a renderização de um contêiner espacial.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • spatialContainer é o XrSpatialContainerEXT para encerrar a renderização.

Uso válido (implícito)

Como localizar visualizações usando xrLocateSpatialContainerViewsEXT

A função xrLocateSpatialContainerViewsEXT localiza visualizações para um conjunto de contêineres espaciais.

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

Descrições dos parâmetros

Essa função substitui xrLocateViews , permitindo que um app consulte visualizações de vários contêineres espaciais simultaneamente.

As visualizações de todos os contêineres espaciais são retornadas na matriz views única. As visualizações são ordenadas com base no índice do contêiner espacial na matriz XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfos e, em seguida, no índice de visualização desse contêiner.

Por exemplo, se um app fornecer três contêineres espaciais em XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfos :

  • Índice 0: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO (1 visualização)
  • Índice 1: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO (2 visualizações)
  • Índice 2: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO_WITH_FOVEATED_INSET (4 visualizações)

Em seguida, o ambiente de execução precisa preencher a matriz views com sete visualizações:

  • views [0] é a visualização do contêiner 0.
  • views [1] é a visualização do olho esquerdo para o contêiner 1.
  • views [2] é a visualização do olho direito para o contêiner 1.
  • views [3] é a visualização do olho esquerdo para o contêiner 2.
  • views [4] é a visualização do olho direito para o contêiner 2.
  • views [5] é a visualização de inserção do olho esquerdo para o contêiner 2.
  • views [6] é a visualização inserida do olho direito para o contêiner 2.

Se viewCount não for igual à soma das contagens de visualizações para cada tipo de configuração de visualização solicitada do contêiner espacial, o ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE .

O ambiente de execução pode reduzir a configuração de visualização para um tipo com menos visualizações para fins de otimização (por exemplo, um contêiner está muito distante e é pequeno, de modo que o estéreo é imperceptível). Se o ambiente de execução reduzir a configuração de visualização, ele precisará retornar o número original de visualizações para esse contêiner, preenchendo as visualizações extras com cópias das visualizações reduzidas. Por exemplo, se XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO for reduzido para XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO , os índices 0 e 1 vão conter a visualização mono única. Consequentemente, o número total de visualizações retornadas na matriz views é independente de o ambiente de execução ter decidido reduzir ou não as configurações de visualização.

O ambiente de execução precisa adaptar cada XrView :: fov retornado para que o tronco seja o menor possível, mas ainda contenha todos os limites do contêiner espacial correspondente. Os ambientes de execução podem retornar FOVs não simétricos, por exemplo, se um contêiner espacial estiver em um ângulo oblíquo em relação à visão do usuário ou estiver parcialmente oculto por outro objeto. Os ambientes de execução podem posicionar livremente a superfície de renderização de destino para o contêiner espacial. Devido à natureza da renderização de vários apps, em que os contêineres espaciais são separados do usuário, o ambiente de execução pode retornar valores de XrView que não são adequados para renderização de pixels. Por exemplo, se o contêiner espacial não estiver visível na tela, não haverá valores válidos para definir XrView :: fov. Nesses casos, os ambientes de execução precisam definir XrSpatialContainerViewStateEXT :: shouldSubmitLayers como falso.

O ambiente de execução retorna mais informações de estado de renderização por contêiner espacial na matriz viewStates. Se viewStateCount não for igual a XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfoCount , o ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE .

Depois que o ambiente de execução colocar um evento XrEventDataSpatialContainerClosedEXT em fila para um contêiner espacial, essa função precisa retornar XR_FALSE em XrSpatialContainerViewStateEXT :: shouldSubmitLayers e 0 em XrSpatialContainerViewStateEXT :: viewStateFlags para o contêiner espacial correspondente.

Para contêineres espaciais com locais que mudam ativamente no mundo real, o ambiente de execução precisa considerar o movimento do contêiner ao preencher views para minimizar artefatos de reprojeção.

Se xrLocateSpatialContainerViewsEXT for chamado para um ou mais contêineres espaciais que não estão no conjunto de renderização ativo, o ambiente de execução precisa retornar XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT .

Uso válido (implícito)

  • A extensão XR_EXT_spatial_container_self_rendering precisa ser ativada antes de chamar xrLocateSpatialContainerViewsEXT.
  • session precisa ser um identificador XrSession válido
  • locateInfo precisa ser um ponteiro para uma estrutura XrSpatialContainerViewsLocateInfoEXT válida
  • viewStates precisa ser um ponteiro para uma matriz de estruturas viewStateCount XrSpatialContainerViewStateEXT
  • views precisa ser um ponteiro para uma matriz de estruturas viewCount XrView.
  • O parâmetro viewStateCount precisa ser maior que 0.
  • O parâmetro viewCount precisa ser maior que 0.

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • 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

A estrutura XrSpatialContainerViewsLocateInfoEXT contém os parâmetros para localizar visualizações em uma coleção de contêineres espaciais.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • displayTime é o XrTime em que as visualizações estão localizadas.
  • viewLocateInfoCount é o número de entradas na matriz viewLocateInfos.
  • viewLocateInfos é um ponteiro para uma matriz de estruturas XrSpatialContainerViewLocateInfoEXT.

Uso válido (implícito)

A estrutura XrSpatialContainerViewLocateInfoEXT contém os parâmetros de um contêiner espacial individual para localizar visualizações.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • viewConfigurationType é um XrViewConfigurationType a ser usado para o contêiner espacial.
  • space é o XrSpace em que as visualizações do contêiner espacial estão localizadas.
  • spatialContainer é o identificador XrSpatialContainerEXT.

O app pode fornecer qualquer XrSpace válido em space , mas é recomendável que ele forneça o espaço do contêiner espacial para o XrSpatialContainerEXT correspondente especificado na estrutura XrSpatialContainerViewLocateInfoEXT.

Uso válido (implícito)

A estrutura XrSpatialContainerViewStateEXT é preenchida por chamadas para xrLocateSpatialContainerViewsEXT com informações de adequação de renderização por contêiner espacial.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • viewStateFlags é uma máscara de bits de XrViewStateFlags . Essas flags têm a mesma finalidade que as viewStateFlags na estrutura principal XrViewState.
  • viewConfigurationType é um XrViewConfigurationType que indica o tipo de configuração de visualização que o ambiente de execução está usando para o contêiner espacial, que os ambientes de execução podem reduzir para uma configuração de visualização com um número menor de visualizações do que o solicitado.
  • shouldSubmitLayers é um XrBool32 retornado pelo ambiente de execução. Se for XR_FALSE, o app precisa evitar o envio de composição para esse contêiner espacial, já que ele não está visível no momento ou está em um estado em que a renderização não é necessária.
  • recommendedImageExtent é uma estrutura XrExtent2Di que representa a resolução recomendada para o contêiner espacial.

Assim como no local de visualização principal do OpenXR, o app precisa verificar o XrSpatialContainerViewStateEXT :: viewStateFlags para garantir que a posição e a orientação sejam válidas e rastreadas antes de usar os dados de visualização para renderização.

O app precisa verificar shouldSubmitLayers e viewConfigurationType para evitar renderizar mais do que o recomendado pelo ambiente de execução. Quando shouldSubmitLayers é falso, o app muda o comportamento de renderização da seguinte maneira:

  • O app não pode ler o XrView :: fov correspondente.
  • O app não pode ler recommendedImageExtent .
  • O app precisa evitar a renderização em swapchains e o envio de camadas de composição para o contêiner espacial correspondente.
  • O app precisa definir XrSpatialContainerLayerEXT :: retainPreviousSubmission como verdadeiro. Se o app optar por enviar camadas mesmo assim, o ambiente de execução vai determinar o que fazer com elas (por exemplo, o ambiente de execução pode optar por descartá-las).

recommendedImageExtent é explicitamente para camadas que serão atualizadas com base na posição do contêiner ou na visualização do usuário. Ao atualizar camadas com conteúdo que depende da posição do contêiner espacial ou da visualização do usuário (como conteúdo 3D normal), o app precisa renderizar para essa janela de visualização menor, em vez do tamanho de visualização recomendado padrão. Ao atualizar camadas com conteúdo que não depende da posição do contêiner espacial ou da visualização do usuário (como camadas quádruplas estáticas), o app pode ignorar esses valores com segurança. Para camadas dependentes de visualização, recommendedImageExtent é uma recomendação do ambiente de execução para o app que visa minimizar o aliasing e melhorar o desempenho de renderização. O app pode enviar em resolução máxima, se quiser.

O XrExtent2Di :: width e o XrExtent2Di :: height de recommendedImageExtent precisam ser sempre um número inteiro positivo menor ou igual ao XrViewConfigurationView :: recommendedImageRectWidth e ao XrViewConfigurationView :: recommendedImageRectHeight do XrViewConfigurationView para a configuração de visualização principal do contêiner espacial. Um app não deve recriar uma swapchain apenas porque recommendedImageExtent mudou, já que é uma dica dinâmica para o app que especifica o XrSwapchainSubImage :: imageRect a ser usado no XrSwapchainSubImage de qualquer camada de composição de resolução total que ele envia, e pode mudar a cada frame.

Uso válido (implícito)

Ver espaço de referência

O espaço de referência de visualização permanece inalterado, como está no núcleo do OpenXR. Assim como no núcleo, ele não se destina ao uso de renderização.

Como enviar camadas usando xrEndFrame

Para renderizar contêineres espaciais, o app precisa fornecer uma lista de camadas associadas aos respectivos contêineres espaciais para xrEndFrame . Isso é feito com a estrutura XrSpatialContainerLayerFrameEndInfoEXT.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • containerLayerCount é a contagem de elementos na matriz containerLayers.
  • containerLayers é um ponteiro para uma matriz de estruturas XrSpatialContainerLayerEXT.

A matriz containerLayers contém um XrSpatialContainerLayerEXT para cada contêiner espacial no conjunto de renderização ativo (os contêineres gerenciados por sessão por xrBeginSpatialContainerRenderingEXT e xrEndSpatialContainerRenderingEXT). Cada XrSpatialContainerLayerEXT contém uma lista de ponteiros XrCompositionLayerBaseHeader associados ao contêiner espacial em questão. Os ambientes de execução podem compor contêineres em qualquer ordem, independentemente da ordem do containerLayers . Por exemplo, os ambientes de execução podem compor contêineres com base na profundidade em relação ao usuário, fazer com que um contêiner espacial atue como uma camada de plano de fundo ou "fixar" um contêiner espacial para que ele esteja sempre no topo, independente da profundidade. Os ambientes de execução podem compor camadas usando estratégias diferentes para contêineres espaciais em modos limitados ou imersivos. Por exemplo, os ambientes de execução podem pré-compor as camadas de composição de cada contêiner espacial limitado em uma única camada estéreo quádrupla que é combinada com todos os outros contêineres em uma segunda etapa de composição.

XrFrameEndInfo :: displayTime e XrFrameEndInfo :: environmentBlendMode serão aplicados a todos os contêineres espaciais fornecidos em XrSpatialContainerLayerFrameEndInfoEXT .

Quando essa estrutura é transmitida para xrEndFrame ao ser encadeada em XrFrameEndInfo , os seguintes casos de erro adicionais são adicionados com base no conjunto de renderização ativo:

  • Se um contêiner espacial for referenciado por mais de um elemento de containerLayers , os ambientes de execução precisam retornar XR_ERROR_SPATIAL_CONTAINER_DUPLICATE_EXT .
  • Se um contêiner espacial no conjunto de renderização ativo não for referenciado por um elemento de containerLayers , os ambientes de execução precisam retornar XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT .
  • Se um contêiner espacial referenciado por containerLayers não for membro do conjunto de renderização ativo, os ambientes de execução precisam retornar XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT .

Além disso, se houver contêineres espaciais no conjunto de renderização ativo e essa estrutura não estiver encadeada em XrFrameEndInfo , os ambientes de execução precisam retornar XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT .

Em qualquer um dos casos de erro acima, o ambiente de execução não pode renderizar nenhum conteúdo para nenhum contêiner espacial.

Se não houver contêineres espaciais no conjunto de renderização ativo, um app pode chamar xrEndFrame, desde que não esteja enviando camadas de composição.

As swapchains individuais podem ser enviadas para vários contêineres usando camadas em uma estrutura válida, por exemplo, uma camada quádrupla renderizada por uma única swapchain enviada para vários contêineres espaciais. Esse caso é tratado de maneira uniforme com outras renderizações: o ambiente de execução precisa renderizar o quad em todos esses contêineres espaciais.

Uso válido (implícito)

A estrutura XrSpatialContainerLayerEXT agrupa camadas de composição padrão e as associa a um contêiner espacial específico.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • spatialContainer é o XrSpatialContainerEXT que identifica o contêiner de destino.
  • retainPreviousSubmission é um XrBool32 . Se for XR_TRUE , o ambiente de execução vai reter o último frame enviado para esse contêiner espacial.
  • layerCount é o número de camadas de composição na matriz layers.
  • layers é um ponteiro para uma matriz de ponteiros XrCompositionLayerBaseHeader.

Quando retainPreviousSubmission é XR_TRUE, o ambiente de execução precisa reutilizar as camadas de composição e o conteúdo da imagem da swapchain, conforme travado durante a chamada mais recente de xrEndFrame em que retainPreviousSubmission era XR_FALSE . As modificações subsequentes nas swapchains usadas pelas camadas retidas não podem ser refletidas na saída renderizada.

Para camadas enviadas para um contêiner espacial individual (renderização dentro do contêiner), o ambiente de execução precisa seguir as regras já especificadas para a ordem de composição de camadas. Ou seja, as camadas dentro dos contêineres precisam ser desenhadas na mesma ordem em que são especificadas, compostas pelo algoritmo do pintor.

"Limpar" um contêiner espacial significa remover todo o conteúdo dele, o que resulta em nada sendo renderizado para esse contêiner no frame atual. Os ambientes de execução precisam tratar isso como equivalente ao app que envia preto transparente (todos os bits 0) para cada pixel dentro do contêiner. "Reter" um contêiner espacial significa que o ambiente de execução continua mostrando o conjunto de camadas enviado mais recentemente para esse contêiner.

Para cada contêiner espacial, o app pode especificar se quer enviar novas camadas, manter o envio anterior ou limpar o contêiner espacial:

  • Para enviar novas camadas, o app fornece um layerCount diferente de zero e um ponteiro layers válido.
  • Para limpar um contêiner espacial, o layerCount da entrada precisa ser 0 e o retainPreviousSubmission precisa ser XR_FALSE .
  • Para reter as últimas camadas enviadas e as imagens da swapchain (retenção), o layerCount da entrada precisa ser 0 e o retainPreviousSubmission precisa ser XR_TRUE .

Esse controle explícito por contêiner garante que a intenção do app seja comunicada de forma clara em cada frame.

Se retainPreviousSubmission for XR_TRUE e layerCount não for 0, o ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE .

Se XrSpatialContainerCompositionLayerViewConfigurationEXT não estiver encadeado a um XrCompositionLayerProjection que faz parte de um contêiner espacial, o ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE . Essa estrutura só é aplicável a camadas XrCompositionLayerProjection. Se ela estiver encadeada com outros tipos de camada (por exemplo, camadas quádruplas ou cilíndricas), o ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE.

Uso válido (implícito)

Como especificar a configuração de visualização para camadas de projeção

A estrutura XrSpatialContainerCompositionLayerViewConfigurationEXT é usada para especificar a configuração de visualização usada para renderizar uma camada de projeção para um contêiner espacial.

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

Descrição do membro

Ao enviar uma XrCompositionLayerProjection para um contêiner espacial, o app precisa especificar qual configuração de visualização foi usada para renderizar a camada. Isso é necessário porque o app pode escolher cada frame para renderizar com a configuração de visualização principal do contêiner espacial ou com a configuração de visualização reduzida sugerida pelo ambiente de execução, se houver.

Quando XrSpatialContainerCompositionLayerViewConfigurationEXT é encadeado, o app precisa garantir que XrCompositionLayerProjection :: viewCount seja uma contagem de visualizações válida para o XrViewConfigurationType especificado na estrutura encadeada. O viewConfigurationType especificado na estrutura encadeada precisa ser o XrSpatialContainerBeginInfoEXT :: primaryViewConfigurationType especificado quando o contêiner foi iniciado, o tipo de configuração de visualização decaída retornado pelo ambiente de execução em XrSpatialContainerViewStateEXT ou valores adicionais ativados por uma extensão.

Uso válido (implícito)

Comportamento de corte de pixel

Os apps precisam informar ao ambiente de execução se renderizam pixels fora dos limites de um contêiner espacial ou não, encadeando XrSpatialContainerLayerVolumeClippingEXT ao enviar camadas de composição.

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

Descrição do membro

Essa estrutura serve como uma dica para saber se o app renderiza pixels fora dos limites de um contêiner espacial. Quando um contêiner espacial está no modo imersivo, como os limites são infinitos, essa dica não tem significado.

Para contêineres espaciais limitados que usam renderização própria, o ambiente de execução precisa considerar os limites de volume 3D e de pixel 2D. Os limites de volume 3D são retornados de xrGetSpatialContainerBoundsEXT . Os limites de pixel 2D são a projeção dos limites de volume 3D em cada tela do sistema.

Os ambientes de execução precisam descartar pixels de imagens de swapchain fora dos limites de pixels 2D, mas não podem descartar pixels que estão dentro dos limites de pixels 2D, mas fora dos limites de volume 3D. É possível usar efeitos estéreo em que o conteúdo parece se estender além ou na frente dos limites de volume 3D do contêiner. Os apps podem descartar pixels fora dos limites de volume 3D de um contêiner espacial limitado para reduzir paradoxos de profundidade e precisam definir volumeClipping com base em como fazem isso. Os paradoxos de profundidade geralmente causam cansaço visual e desconforto ao usuário.

Os ambientes de execução podem usar volumeClipping para ajustar como mostram um contêiner espacial específico. Por exemplo, quando definido como XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT, um ambiente de execução pode renderizar as faces traseiras dos limites de volume 3D que causariam paradoxos de profundidade se o contêiner espacial desenhasse pixels atrás dos limites de volume 3D do contêiner.

Extensões futuras podem permitir o recorte com base nos limites de volume 3D se as informações de profundidade forem enviadas.

Uso válido (implícito)

Novos comandos

Novas estruturas

Novas constantes de tipo enumerado

  • XR_EXT_SPATIAL_CONTAINER_SELF_RENDERING_EXTENSION_NAME
  • XR_EXT_spatial_container_self_rendering_SPEC_VERSION

  • Estendendo 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

  • Estendendo XrSpatialContainerGraphicsPresentationEXT :

    • XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

  • Estendendo 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

Exemplos de código

// 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));

Histórico de versões

  • Revisão 1, 06/08/2026 (Lachlan Ford)

    • Descrição inicial da extensão