XR_EXT_spatial_container

String de nome

XR_EXT_spatial_container

Tipo de extensão

Extensão de instância

Número de ramal registrado

811

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

OpenXR 1.0

Data da última modificação

2026-08-06

Status do IP

Nenhuma reivindicação de PI conhecida.

Colaboradores

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

Visão geral

Essa extensão define uma nova classe de entidades exibíveis, chamadas de "contêineres espaciais", que são análogas ao conceito de "janelas" em sistemas de janelas 2D para computadores.

No OpenXR 1.x, os apps têm controle exclusivo sobre tudo o que o usuário vê e como isso é combinado com o ambiente real ou virtual do usuário. Os ambientes de execução fazem apenas pequenas modificações no que é exibido para garantir a segurança do usuário. Esse modelo de app é bom para imergir um usuário em uma única experiência, mas não se estende a várias experiências simultâneas. Em particular, em ambientes de RA e realidade mista, os usuários geralmente querem usar vários apps diferentes ao mesmo tempo.

Os contêineres espaciais são como janelas estendidas para 3D. O usuário pode ver vários contêineres espaciais simultaneamente e fornecer entrada para um subconjunto deles. Os contêineres espaciais visíveis podem pertencer a apps diferentes, e os ambientes de execução gerenciam o tamanho e o posicionamento deles em nome do usuário.

Essa extensão é compatível com esses novos tipos de experiências espacialmente limitadas, além das experiências imersivas do OpenXR. As experiências do OpenXR limitadas podem ter conteúdo ligeiramente 3D (painéis planos com pequenos deslocamentos de profundidade) ou volumes que hospedam conteúdo totalmente 3D. As experiências imersivas do OpenXR são os apps imersivos em tela cheia que têm suporte desde o OpenXR 1.0. Os apps podem alternar entre os dois tipos de conteúdo, se quiserem.

Essa extensão não define nenhum método para um app renderizar o conteúdo. Como desenhar conteúdo é definido em outras extensões: XR_EXT_spatial_container_self_rendering .

Como usar contêineres espaciais

Um XrSpatialContainerEXT é um identificador que representa um contêiner espacial.

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

Um aplicativo começa a ser renderizado por um contêiner espacial com as seguintes etapas:

  1. Crie um contêiner espacial com xrCreateSpatialContainerEXT .
  2. Modifique qualquer estado no contêiner para a apresentação inicial, como o modo de limites.
  3. Solicite que o ambiente de execução mostre o contêiner com xrRequestSpatialContainerVisibleEXT .
  4. Aguarde até que o ambiente de execução esteja pronto para mostrar o contêiner. Quando o ambiente de execução estiver pronto, ele vai colocar em fila um evento XrEventDataSpatialContainerVisibleChangedEXT com visible definido como XR_TRUE .
  5. Comece a renderizar o contêiner espacial.

E a remoção de um contêiner espacial é feita da seguinte maneira:

  1. Solicite que o ambiente de execução oculte o contêiner com xrRequestSpatialContainerVisibleEXT .
  2. Aguarde o ambiente de execução terminar de ocultar o contêiner. Quando o ambiente de execução oculta totalmente o contêiner, ele coloca em fila um evento XrEventDataSpatialContainerVisibleChangedEXT com visible definido como XR_FALSE .
  3. Encerra a renderização do contêiner espacial.
  4. Destrua o contêiner com xrDestroySpatialContainerEXT .

Observação

Por padrão, essa extensão delega o gerenciamento de visibilidade e foco a contêineres espaciais individuais. Como a sessão como um todo não representa mais um único objeto visível ou em foco, ela não passa pela máquina de estado padrão do OpenXR (READY, SYNCHRONIZED, VISIBLE, FOCUSED). Em vez disso, a sessão permanece em XR_SESSION_STATE_IDLE durante o ciclo de vida ativo, e as regras em Mudanças no estado da sessão especificam como as operações principais do OpenXR são mapeadas para esse modo.

Criar um contêiner espacial

A função xrCreateSpatialContainerEXT cria um novo contêiner espacial.

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

Descrições dos parâmetros

Um XrSpatialContainerEXT recém-criado não pode ser visível, interativo e estar no modo de limites XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT . Um app que quer que um contêiner espacial seja iniciado no modo imersivo pode solicitar um modo de limites de XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT antes de pedir para mostrar um contêiner espacial.

Os ambientes de execução precisam retornar XR_ERROR_VALIDATION_FAILURE se alguma dimensão de XrSpatialContainerCreateInfoEXT :: suggestedBounds for negativa, infinita ou não for um número. Os ambientes de execução precisam retornar XR_ERROR_LIMIT_REACHED se um app tentar criar mais contêineres espaciais do que o especificado em XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount . Se os contêineres espaciais não tiverem sido ativados para esta sessão , os ambientes de execução precisarão retornar XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT .

Uso válido (implícito)

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_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

O XrSpatialContainerCreateInfoEXT é transmitido para xrCreateSpatialContainerEXT para criar um contêiner espacial.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • graphicsPresentation é um XrSpatialContainerGraphicsPresentationEXT que descreve como esse contêiner espacial apresenta gráficos.
  • suggestedBounds é um XrExtent3Df que descreve as dimensões solicitadas do contêiner espacial em metros.

Um app que não tem preferência de tamanho pode definir suggestedBounds como {0, 0, 0}. Um ambiente de execução pode ignorar o suggestedBounds solicitado.

Um ambiente de execução que permite que os contêineres espaciais sejam limitados por formas diferentes de caixas orientadas precisa usar suggestedBounds como uma caixa delimitadora ao redor das outras formas. As caixas orientadas são o formato de limite mais comum.

Uso válido (implícito)

Quando um contêiner espacial não puder mais ser usado, os ambientes de execução precisam colocar um evento XrEventDataSpatialContainerClosedEXT na fila.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • spatialContainer é o XrSpatialContainerEXT a que este evento se destina.

O recebimento do evento XrEventDataSpatialContainerClosedEXT indica que o ambiente de execução não pode mais mostrar um contêiner espacial, por exemplo, porque o usuário clicou em um botão "Fechar" ou a sessão entrou no estado XR_SESSION_STATE_LOSS_PENDING.

Depois de receber o evento XrEventDataSpatialContainerClosedEXT, um app precisa parar de usar esse contêiner espacial, remover qualquer estado associado, como um loop de renderização, e destruir o contêiner. Os ambientes de execução precisam retornar XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT de todas as funções que operam nesse contêiner, exceto xrDestroySpatialContainerEXT .

Se um contêiner espacial estiver visível quando o ambiente de execução colocar um evento de fechamento na fila, os ambientes de execução precisam primeiro mudar o contêiner para não visível e colocar um evento XrEventDataSpatialContainerVisibleChangedEXT na fila.

Uso válido (implícito)

A função xrDestroySpatialContainerEXT destrói um contêiner espacial.

XrResult xrDestroySpatialContainerEXT(
    XrSpatialContainerEXT                       spatialContainer);

Descrições dos parâmetros

Depois que um contêiner espacial é destruído, os ambientes de execução não podem mais mostrar o conteúdo do contêiner nem colocar na fila outros eventos sobre ele.

Um app não deve destruir um contêiner espacial visível, porque isso pode resultar em artefatos gráficos. Em vez disso, um app deve solicitar que o contêiner espacial seja ocultado com xrRequestSpatialContainerVisibleEXT, aguardar um evento XrEventDataSpatialContainerVisibleChangedEXT e, em seguida, destruir o contêiner.

Uso válido (implícito)

Concorrência segura

  • O acesso a spatialContainer e a qualquer identificador filho precisa ser sincronizado externamente.

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

O espaço do contêiner espacial

A função xrCreateSpatialContainerSpaceEXT cria um identificador XrSpace para o espaço de um contêiner espacial específico.

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

Descrições dos parâmetros

O "espaço do contêiner espacial" para qualquer contêiner espacial é um sistema de coordenadas com origem no centro dos limites desse contêiner. Esse espaço normalmente é usado como base para funções como xrLocateSpace .

+X aponta para a face direita do contêiner, +Y aponta para a face superior do contêiner e +Z aponta para a face frontal do contêiner. Por exemplo, se um contêiner estiver alinhado à gravidade, na frente do espectador, e o espectador estiver na pose de identidade em relação ao espaço LOCAL , os ambientes de execução precisam orientar o espaço do contêiner com a orientação de identidade em relação ao espaço LOCAL . Os ambientes de execução podem definir a pose de um espaço de contêiner em relação ao espaço LOCAL como qualquer pose arbitrária quando esse contêiner se torna visível.

convenção de espaço do contêiner espacial externo

Figura 18. Convenção de eixos do espaço do contêiner espacial

O espaço do contêiner espacial é uma origem não bloqueada pelo mundo. Os apps que querem uma origem fixa no mundo no modo imersivo podem usar um espaço fixo no mundo, como XR_REFERENCE_SPACE_TYPE_LOCAL .

Os ambientes de execução podem mudar a pose de um espaço de contêiner espacial a qualquer momento, geralmente para permitir que um usuário mova um contêiner espacial para uma posição ou rotação diferente. Os ambientes de execução também podem mudar a pose ao fazer a transição entre os modos de limites XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT e XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT.

Um espaço de contêiner espacial precisa continuar sendo um identificador válido, mesmo que o contêiner espacial seja destruído com xrDestroySpatialContainerEXT . Enquanto um contêiner espacial não estiver visível ou for destruído, o espaço dele precisa ser não localizável em relação a outros espaços. XrSpaceLocation :: locationFlags e XrViewState ::viewStateFlags serão 0.

Uso válido (implícito)

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_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

O XrSpatialContainerSpaceCreateInfoEXT é usado com xrCreateSpatialContainerSpaceEXT para criar um identificador XrSpace.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • spatialContainer é um XrSpatialContainerEXT para criar um espaço.

Uso válido (implícito)

Como apresentar um contêiner espacial

O envio do conteúdo de um contêiner espacial para o OpenXR para exibição é processado por outras extensões: XR_EXT_spatial_container_self_rendering .

Para permitir que outras extensões especifiquem o método de apresentação de gráficos para um contêiner espacial, esta extensão define o tipo enumerado 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;

Descrição do tipo enumerado

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

O contêiner espacial usa camadas de composição do OpenXR (adicionadas pela extensão XR_EXT_spatial_container_self_rendering)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT

O contêiner espacial é criado para testes de conformidade e não tem um caminho de renderização (adicionado pela extensão XR_EXT_spatial_container_conformance_automation).

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1

O contêiner espacial usa a renderização do sistema OpenXR (adicionada pela extensão XR_EXTX1_system_renderer)

Estado do contêiner espacial

O estado do contêiner espacial é gerenciado por ambientes de execução com base nas solicitações do app e nas necessidades do usuário. Por isso, cada aspecto do estado do contêiner espacial documenta o seguinte:

  • Quando os ambientes de execução podem mudar o estado do contêiner espacial. Para a maioria dos estados de contêiner espacial, os ambientes de execução podem mudar o estado a qualquer momento.
  • Como um app solicita mudanças no estado. Os ambientes de execução podem adiar qualquer solicitação até que ela seja considerada adequada. Os ambientes de execução não colocam eventos em fila quando uma solicitação é adiada. Portanto, os apps não devem esperar por esse evento para uma lógica não relacionada.
  • Quais ambientes de execução de eventos são colocados na fila quando o estado do contêiner espacial muda. Os ambientes de execução colocam em fila os eventos de todas as mudanças, incluindo as solicitadas pelo app e as iniciadas pelo ambiente de execução. Os ambientes de execução não podem colocar em fila eventos de mudança de estado que não indicam uma mudança, como se um app fizesse duas solicitações para ocultar um contêiner em rápida sucessão.
  • O que os ambientes de execução de eventos colocam na fila ao negar uma solicitação de mudança de app. Os ambientes de execução podem negar uma solicitação por qualquer motivo, geralmente devido à política do sistema relacionada à manutenção de uma experiência do usuário de alta qualidade.

A função xrGetSpatialContainerStateEXT consulta o estado atual do contêiner espacial.

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

Descrições dos parâmetros

Uso válido (implícito)

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_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

O XrSpatialContainerStateGetInfoEXT é usado com xrGetSpatialContainerStateEXT para consultar um XrSpatialContainerStateEXT .

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.

Uso válido (implícito)

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • visible representa se um contêiner espacial está visível.
  • interactable representa se um contêiner espacial pode receber qualquer tipo de entrada no momento. É semelhante ao "foco" para sistemas de janelas 2D de computadores, com a diferença de que vários contêineres espaciais podem ser interativos ao mesmo tempo.
  • boundsMode é o XrSpatialContainerBoundsModeEXT atual do contêiner espacial.

As mudanças no estado de um contêiner espacial são comunicadas por eventos.

Evento de campo alterado

visible

XrEventDataSpatialContainerVisibleChangedEXT

interactable

XrEventDataSpatialContainerInteractableChangedEXT

boundsMode

XrEventDataSpatialContainerBoundsChangedEXT

Uso válido (implícito)

Visibilidade

Os apps solicitam que um contêiner espacial seja mostrado ou ocultado com xrRequestSpatialContainerVisibleEXT .

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

Descrições dos parâmetros

Mostrar ou ocultar um contêiner espacial é uma operação assíncrona.

Os apps precisam solicitar que um contêiner espacial seja ocultado antes de ser destruído, permitindo que os ambientes de execução mostrem uma transição suave. Os ambientes de execução precisam atender às solicitações para ocultar um contêiner espacial.

Um ambiente de execução pode negar solicitações para mostrar um contêiner espacial. Nesse caso, o ambiente de execução precisa colocar um evento XrEventDataSpatialContainerVisibleRequestDeniedEXT na fila. Por exemplo, alguns ambientes de execução vão negar uma solicitação para mostrar um contêiner espacial que o usuário ocultou ao interagir com um botão "minimizar" fornecido pelo sistema.

Os ambientes de execução não podem mostrar um contêiner espacial antes que o app solicite que ele seja mostrado pelo menos uma vez. Depois da primeira solicitação do app para mostrar um contêiner espacial, os ambientes de execução podem mudar a visibilidade desse contêiner, independentemente das solicitações do app. Isso permite que o app controle o estado inicial e o conteúdo de um contêiner espacial e que os ambientes de execução forneçam uma interface do sistema, como uma barra de tarefas, que permite ao usuário escolher quais contêineres espaciais ficam visíveis.

Os ambientes de execução precisam negar solicitações para mostrar um contêiner espacial em um modo de limites não compatível com base em XrSystemSpatialContainerPropertiesEXT :: supportsBounded e XrSystemSpatialContainerPropertiesEXT :: supportsImmersive . Isso é possível quando o modo de limites padrão, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT , não é compatível com um determinado sistema.

Observação

Em algumas implementações, mostrar ou ocultar um contêiner espacial requer comunicação com os serviços do sistema e pode ser adiado até que o usuário interaja com uma caixa de diálogo do sistema. O design assíncrono para solicitar mudanças no estado de visibilidade tem como objetivo dar aos ambientes de execução o tempo necessário para concluir as duas operações.

Uso válido (implícito)

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_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

O XrSpatialContainerVisibleRequestInfoEXT é usado com xrRequestSpatialContainerVisibleEXT para mudar a visibilidade de um contêiner espacial.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • visible indica se um contêiner espacial precisa ser mostrado ou ocultado.

Uso válido (implícito)

Sempre que um ambiente de execução mudar a visibilidade de um contêiner espacial, ele precisará colocar um evento XrEventDataSpatialContainerVisibleChangedEXT na fila com o novo estado.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • spatialContainer é o XrSpatialContainerEXT a que este evento se destina.
  • visible é o novo estado visível do contêiner espacial.

Esse evento substitui XR_SESSION_STATE_VISIBLE , permitindo que o valor seja diferente para cada contêiner. O evento precisa ser colocado na fila para todas as mudanças, incluindo as solicitadas pelo app e as iniciadas pelo ambiente de execução.

Um ambiente de execução pode atrasar a renderização de um contêiner por alguns frames depois de colocar esse evento em fila com visible definido como XR_TRUE para evitar a exibição de um contêiner vazio e dar tempo para o app enviar o conteúdo inicial. Durante esse período, XrSpatialContainerStateEXT ::visible será XR_TRUE . Os ambientes de execução não devem atrasar a renderização de um contêiner por mais de 0,5 segundo.

Uso válido (implícito)

Sempre que um ambiente de execução negar uma solicitação para mostrar um contêiner, ele precisa colocar um evento XrEventDataSpatialContainerVisibleRequestDeniedEXT na fila.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • spatialContainer é o XrSpatialContainerEXT a que este evento se destina.

Uso válido (implícito)

Interativo

Um app não pode solicitar que um contêiner espacial seja interativo. Os ambientes de execução controlam totalmente quais contêineres espaciais são interativos. Um contêiner espacial interativo precisa estar visível.

Sempre que um ambiente de execução mudar o estado interativo de um contêiner espacial, ele precisará colocar um evento XrEventDataSpatialContainerInteractableChangedEXT na fila com o novo estado.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • spatialContainer é o XrSpatialContainerEXT a que este evento se destina.
  • interactable é o novo estado interativo do contêiner espacial.

Esse evento substitui XR_SESSION_STATE_FOCUSED , permitindo que o valor seja diferente para cada contêiner. O evento é colocado na fila para todas as mudanças, incluindo as iniciadas pelo ambiente de execução.

Os ambientes de execução podem ativar ou desativar a interação com um contêiner espacial a qualquer momento. Se um ambiente de execução só permitir que um contêiner espacial seja interativo por vez, quando o ambiente de execução mudar o contêiner espacial interativo, ele precisará colocar na fila o evento para o contêiner espacial que deixa de ser interativo ( interactable definido como falso) antes do evento para o contêiner que começa a ser interativo ( interactable definido como verdadeiro).

Uso válido (implícito)

Limites

Um contêiner espacial tem um modo de limites e uma caixa delimitadora. O modo de limites de um contêiner espacial descreve como os limites se comportam. A caixa delimitadora é o que o contêiner espacial desenha dentro.

A enumeração XrSpatialContainerBoundsModeEXT identifica diferentes modos em que os limites de um contêiner espacial podem estar.

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;

Descrição do tipo enumerado

XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT

O contêiner espacial é limitado. Os limites são uma caixa finita. O contêiner espacial só vai aparecer nessa região.

XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT

O contêiner espacial é imersivo e tem limites infinitos. O contêiner espacial é exibido em toda a tela.

Os contêineres espaciais que estão no modo de limites XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT têm requisitos adicionais:

  • Os ambientes de execução precisam tratar esses contêineres espaciais da mesma forma que um app imersivo e de tela cheia criado sem o uso de contêineres espaciais, exceto pelas mudanças de comportamento mencionadas em Mudanças no estado da sessão .
  • Os ambientes de execução podem fornecer outras extensões que permitem que os contêineres espaciais imersivos se comportem de maneira diferente dos apps imersivos e de tela cheia criados sem essa extensão.
  • Os ambientes de execução precisam informar limites infinitos para esses contêineres espaciais.
  • Os ambientes de execução podem ocultar outros contêineres espaciais enquanto um contêiner espacial imersivo estiver visível. Como isso pode variar de acordo com o ambiente de execução, os apps não devem depender da exibição ou ocultação automática de contêineres espaciais com base na visibilidade do contêiner espacial imersivo. Como todas as outras transições de estado visíveis, os ambientes de execução precisam colocar um evento XrEventDataSpatialContainerVisibleChangedEXT na fila quando um contêiner espacial é ocultado porque um contêiner imersivo está visível.

Observação

Os requisitos acima implicam que todos os ambientes de execução podem implementar o caminho do OpenXR 1.x sem essa extensão, criando implicitamente um contêiner espacial, definindo o modo de limites do contêiner como imersivo e solicitando que ele seja visível.

Os apps solicitam a mudança do modo de limites de um contêiner espacial com xrRequestSpatialContainerBoundsModeEXT .

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

Descrições dos parâmetros

Mudar o modo de limites de um contêiner espacial é uma operação assíncrona, e os ambientes de execução podem colocar um evento de mudança ou negação na fila muitos segundos depois que o app solicita uma mudança. Isso permite que os ambientes de execução mostrem a interface necessária para que o usuário entre com segurança em um modo imersivo.

Os ambientes de execução precisam atender a uma solicitação para mudar o modo de limites de um contêiner espacial não visível. Se um ambiente de execução negar uma solicitação de modo de limites para um contêiner não visível, ele poderá rejeitar ou adiar uma solicitação para mostrar esse contêiner espacial. Isso permite que os apps iniciem um contêiner como imersivo. Um ambiente de execução pode negar solicitações para mudar o modo de limites de um contêiner espacial visível. Nesse caso, o ambiente de execução precisa colocar um evento XrEventDataSpatialContainerBoundsModeRequestDeniedEXT na fila. Por exemplo, alguns ambientes de execução vão negar uma solicitação para mudar o modo de limites de um contêiner espacial visível com que o usuário não está interagindo ativamente.

Os ambientes de execução precisam retornar XR_ERROR_VALIDATION_FAILURE se um app solicitar um modo de limites não compatível com base em XrSystemSpatialContainerPropertiesEXT :: supportsBounded e XrSystemSpatialContainerPropertiesEXT :: supportsImmersive .

Uso válido (implícito)

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_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

O XrSpatialContainerBoundsModeRequestInfoEXT é usado com xrRequestSpatialContainerBoundsModeEXT para mudar o modo de limites de um contêiner espacial.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • boundsMode é o XrSpatialContainerBoundsModeEXT desejado para o contêiner espacial.

Uso válido (implícito)

Sempre que um ambiente de execução mudar os limites ou o modo de limites de um contêiner espacial, ele precisará colocar em fila um evento XrEventDataSpatialContainerBoundsChangedEXT com as novas informações de limites.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • spatialContainer é o XrSpatialContainerEXT a que este evento se destina.
  • bounds é a nova largura, altura e profundidade dos limites do contêiner espacial.
  • infiniteBounds será verdadeiro se o contêiner tiver limites infinitos.
  • boundsMode é o novo XrSpatialContainerBoundsModeEXT do contêiner espacial.

O evento é colocado na fila para todas as mudanças, incluindo as solicitadas pelo app e as iniciadas pelo ambiente de execução.

Enquanto um usuário está redimensionando um contêiner espacial de forma interativa, os ambientes de execução precisam se comportar de uma das seguintes maneiras:

  • enfileirar muitos eventos, provavelmente na taxa de frames, enquanto o usuário redimensiona o contêiner espacial
  • enfileirar um único evento no final do redimensionamento

Se um ambiente de execução colocar em fila apenas um evento no final do redimensionamento, ele precisará continuar informando os limites antigos de xrGetSpatialContainerBoundsEXT até que um evento de redimensionamento seja colocado em fila. Os ambientes de execução precisam agrupar vários eventos de mudança de limites não pesquisados. Em outras palavras, se os limites ou o modo de limites mudarem enquanto houver um evento XrEventDataSpatialContainerBoundsChangedEXT ainda na fila, os ambientes de execução precisam informar apenas um evento que contenha a última mudança de limites que ocorreu. Como os apps também podem consultar os limites de um contêiner espacial diretamente com xrGetSpatialContainerBoundsEXT, o número de mudanças de limites de eventos pode ser diferente do número de mudanças de consulta com base no momento das mudanças de limites geradas pelo ambiente de execução, nas chamadas do app para xrPollEvent e nas chamadas do app para xrGetSpatialContainerBoundsEXT .

Quando os limites de um contêiner espacial mudam, a origem local dele também pode mudar. Por exemplo, se um ambiente de execução permitir que um usuário redimensione os limites do contêiner espacial arrastando uma das bordas, os limites e a origem local desse contêiner vão mudar quando o usuário arrastar uma única borda. Nessas situações, o ambiente de execução precisa mudar os limites e a origem local simultaneamente.

Os ambientes de execução precisam definir infiniteBounds como XR_TRUE e definir a largura, a altura e a profundidade como 0.0 para representar limites infinitos. Os ambientes de execução precisam definir infiniteBounds como XR_FALSE e definir largura, altura e profundidade como números positivos finitos para limites finitos.

Os ambientes de execução precisam definir bounds e infiniteBounds seguindo as mesmas regras de XrSpatialContainerBoundsEXT .

Uso válido (implícito)

Sempre que um ambiente de execução negar uma solicitação para mudar o modo de limites de um contêiner, ele precisa colocar um evento XrEventDataSpatialContainerBoundsModeRequestDeniedEXT na fila.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • spatialContainer é o XrSpatialContainerEXT a que este evento se destina.

Uso válido (implícito)

A estrutura XrSpatialContainerBoundsEXT descreve a caixa delimitadora de um contêiner espacial.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • bounds é a largura, altura e profundidade dos limites do contêiner espacial. Os limites são em metros.
  • infiniteBounds será verdadeiro se o contêiner tiver limites infinitos.

Os ambientes de execução precisam definir infiniteBounds como XR_TRUE e definir a largura, a altura e a profundidade como 0.0 para representar limites infinitos. Os ambientes de execução precisam definir infiniteBounds como XR_FALSE e definir largura, altura e profundidade como números positivos finitos para limites finitos.

Uso válido (implícito)

A função xrGetSpatialContainerBoundsEXT consulta os limites atuais de um contêiner espacial.

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

Descrições dos parâmetros

Enquanto um contêiner espacial é limitado, ele não pode ter limites infinitos. Enquanto um contêiner espacial é imersivo, ele precisa ter limites infinitos.

Os ambientes de execução podem mudar os limites de um contêiner espacial para qualquer valor finito positivo a qualquer momento enquanto o contêiner espacial estiver limitado. As mudanças nos limites de um contêiner espacial são comunicadas por XrEventDataSpatialContainerBoundsChangedEXT .

Com essa extensão, um app não pode solicitar mudanças nos limites, exceto para alternar entre os modos limitado e imersivo com xrRequestSpatialContainerBoundsModeEXT . Outras extensões podem oferecer essa opção no futuro.

Uso válido (implícito)

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_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrSpatialContainerBoundsGetInfoEXT é uma estrutura de entrada que existe para fins de extensão futura.

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.

Uso válido (implícito)

A enumeração XrSpatialContainerVolumeClippingEXT identifica diferentes comportamentos de corte de volume para um contêiner espacial.

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;

Descrição do tipo enumerado

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT

Nenhum conteúdo é cortado no volume delimitador do contêiner espacial. O conteúdo pode ser desenhado fora dos limites do contêiner espacial.

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT

O conteúdo é cortado estritamente no volume delimitador do contêiner espacial.

Essa enumeração não é usada nesta extensão. Ele é definido para permitir que outras extensões especifiquem o comportamento de corte de volume desejado. Por exemplo, um app pode querer desenhar um plano de fundo para um contêiner espacial limitado. Um mapa de cubo monocular é uma maneira conveniente de especificar um plano de fundo, mas ele é posicionado conceitualmente no infinito, que fica fora do contêiner.

Recursos do sistema

Um app pode inspecionar os recursos do sistema encadeando uma estrutura XrSystemSpatialContainerPropertiesEXT ao XrSystemProperties ao chamar xrGetSystemProperties .

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

Descrição do membro

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • maxSpatialContainerCount é o número máximo de contêineres espaciais que podem ser criados.
  • supportsBounded será verdadeiro se os contêineres espaciais puderem ser limitados.
  • supportsImmersive será verdadeiro se os contêineres espaciais puderem ser imersivos.

Os ambientes de execução compatíveis com essa extensão precisam permitir que um app crie muitos contêineres espaciais, limitados apenas pela alocação de memória. Um ambiente de execução pode ter um limite diferente para o número de contêineres espaciais exibidos simultaneamente. Não é possível consultar o número de contêineres exibidos simultaneamente nessa extensão porque um ambiente de execução pode limitar apps individuais com base no estado de todos os apps em execução. A premissa é que dispositivos com muitas restrições e dispositivos com menos restrições terão limites diferentes para o número de contêineres exibidos simultaneamente. Dispositivos com muitas restrições podem aceitar apenas um contêiner espacial exibido por vez, e dispositivos com menos restrições podem aceitar um grande número de contêineres espaciais exibidos simultaneamente, sujeito aos limites de computação de renderização.

Os ambientes de execução compatíveis com essa extensão precisam aceitar pelo menos um dos contêineres espaciais limitados ou imersivos.

Uso válido (implícito)

A função xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT retorna os métodos de apresentação de gráficos compatíveis com um sistema.

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

Descrições dos parâmetros

  • instance é a XrInstance de onde systemId foi recuperado.
  • systemId é o XrSystemId que está sendo consultado.
  • graphicsPresentationCapacityInput é a capacidade da matriz graphicsPresentations ou 0 para indicar uma solicitação de recuperação da capacidade necessária.
  • graphicsPresentationCountOutput é um ponteiro para a contagem de apresentações gráficas gravadas ou um ponteiro para a capacidade necessária caso graphicsPresentationCapacityInput seja 0.
  • graphicsPresentations é um ponteiro para uma matriz de valores XrSpatialContainerGraphicsPresentationEXT, mas pode ser nulo se graphicsPresentationCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de graphicsPresentations necessário.

Os ambientes de execução precisam sempre retornar conteúdos de buffer idênticos dessa enumeração para o systemId fornecido e durante o ciclo de vida da instância.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • 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

Mudanças no estado da sessão

O suporte a contêineres espaciais é ativado para uma sessão ao encadear um XrSessionCreateInfoSpatialContainersEXT ao chamar xrCreateSession .

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

Quando o suporte a contêineres espaciais está ativado, uma XrSession se comporta de maneira diferente. Isso ocorre porque, ao usar contêineres espaciais, a sessão não apresenta mais o conteúdo da imagem nas telas. Em vez disso, os contêineres espaciais fazem isso. Portanto, quando essa extensão é ativada, uma sessão é efetivamente "headless". Ao contrário de outras extensões headless, os apps podem enviar dados de imagem pelos contêineres espaciais.

Ativar o suporte a contêineres espaciais altera as principais APIs do OpenXR da seguinte maneira.

ambiente de execução: perda do sistema ou dispositivo

ambiente de execução: perda do sistema ou dispositivo

xrDestroySession

xrDestroySession

INATIVO
(em execução)

INATIVO...

xrGetSystem
xrCreateSession

xrGetSystem...

xrCreateInstance

xrCreateIn...

xrDestroySession

xrDestroySession

LOSS_PENDING
(não está em execução)

LOSS_PENDING...

xrDestroyInstance

xrDestroyInstance

app: opcionalmente,
reinicie o XR

app: opcionalmente...

Figura 19. Nova máquina de estados da sessão

  • A sessão nunca entra nos estados XR_SESSION_STATE_VISIBLE, XR_SESSION_STATE_FOCUSED ou XR_SESSION_STATE_EXITING . Os ambientes de execução nunca podem colocar eventos em fila para esses estados. Esses estados são substituídos por eventos de contêiner espacial XrEventDataSpatialContainerVisibleChangedEXT, XrEventDataSpatialContainerInteractableChangedEXT e XrEventDataSpatialContainerClosedEXT, respectivamente.
  • A sessão também nunca entra nos estados XR_SESSION_STATE_READY , XR_SESSION_STATE_SYNCHRONIZED , XR_SESSION_STATE_STOPPING . Os ambientes de execução nunca podem colocar eventos em fila para esses estados. Não há substituição para esses estados.
  • Os ambientes de execução precisam tratar a sessão como em execução quando ela estiver no estado XR_SESSION_STATE_IDLE .
  • Os ambientes de execução precisam tratar a sessão como em foco quando ela está no estado XR_SESSION_STATE_IDLE e há pelo menos um contêiner espacial interativo.
  • As funções xrBeginSession e xrEndSession não são mais necessárias. Os ambientes de execução precisam retornar XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT quando essas funções são chamadas. Outras extensões podem oferecer substituições para essas funções.
  • A função xrRequestExitSession também não é mais necessária. Os ambientes de execução precisam retornar XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT quando essa função é chamada. Os apps que querem sair de uma sessão em execução podem chamar xrRequestSpatialContainerVisibleEXT para ocultar os contêineres e destruir a sessão depois que todos os contêineres não estiverem mais visíveis.

  • As extensões que colocavam outros eventos em fila quando a sessão começava a ser executada agora precisam fazer isso após a criação da sessão. Essas extensões são descritas abaixo.

    Evento de extensão

XR_EXT_user_presence

XrEventDataUserPresenceChangedEXT

XR_META_boundary_visibility

XrEventDataBoundaryVisibilityChangedMETA

  • A função xrLocateViews não é válida para chamada na sessão. Os ambientes de execução precisam retornar XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT de xrLocateViews . Outras extensões podem oferecer maneiras de localizar as visualizações de um contêiner espacial específico.
  • A função xrWaitFrame precisa sempre definir XrFrameState :: shouldRender como falso. Outras extensões podem fornecer maneiras de saber se um contêiner espacial específico precisa atualizar as camadas de composição.
  • A função xrEndFrame não é uma maneira válida de enviar camadas de composição. Se um app definir XrFrameEndInfo :: layerCount como um valor diferente de zero, os ambientes de execução precisam retornar XR_ERROR_VALIDATION_FAILURE . Outras extensões podem oferecer maneiras de enviar camadas de composição para um contêiner espacial específico.
  • Entrar no estado XR_SESSION_STATE_LOSS_PENDING também fecha todos os contêineres espaciais. Os ambientes de execução precisam colocar um evento XrEventDataSpatialContainerClosedEXT na fila para cada contêiner espacial ativo antes de colocar uma mudança de estado de sessão na fila para XR_SESSION_STATE_LOSS_PENDING .
  • A função xrCreateSession não precisa mais de uma estrutura de vinculação da API de gráficos. Outras extensões podem exigir uma vinculação de gráficos, por exemplo, para que um contêiner espacial seja renderizado usando uma API de gráficos.

O comportamento acima é um pouco diferente do comportamento em XR_MND_headless . Os ambientes de execução não podem ativar o comportamento de sessão headless de XR_MND_headless quando o suporte ao contêiner espacial está ativado para essa sessão.

Observação

Quando os contêineres espaciais estão ativados, uma sessão transita entre apenas dois estados: XR_SESSION_STATE_IDLE (em execução) e XR_SESSION_STATE_LOSS_PENDING (não em execução). Como resultado, os ambientes de execução não retornam mais XR_ERROR_SESSION_RUNNING ou XR_ERROR_SESSION_NOT_RUNNING . Em vez disso, quando uma sessão não está em execução, os ambientes de execução retornam XR_ERROR_SESSION_LOST ou XR_SESSION_LOSS_PENDING seguindo as regras do núcleo do OpenXR. Além disso, xrBeginSession , a única função que retorna XR_ERROR_SESSION_RUNNING , agora sempre vai retornar XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT .

Uso válido (implícito)

Entradas do manifesto do Android

Os ambientes de execução baseados no AOSP podem ter um comportamento personalizado com base no estado inicial do contêiner espacial que é iniciado antes da execução de qualquer código do app. Por exemplo, um ambiente de execução pode alterar os recursos alocados para a atividade, as animações de inicialização ou a exibição da tela de apresentação. As propriedades a seguir são fornecidas para essa finalidade. Elas substituem a tag <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />, que os apps baseados em contêineres espaciais não devem especificar, exceto para compatibilidade com ambientes de execução anteriores baseados no AOSP.

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

Essa propriedade indica aos ambientes de execução os modos de limites usados por uma atividade. Por padrão, é uma lista vazia, o que significa que não há dicas.

As strings a seguir são válidas para esse atributo. Vários valores são separados por | , como "bounded|immersive" .

Valor

Descrição

"2d_panel"

A atividade é mostrada usando o framework de visualização 2D do Android.

"bounded"

A atividade usa XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT .

"immersive"

A atividade usa 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" />

Essa propriedade indica aos ambientes de execução o XrSpatialContainerBoundsModeEXT inicial da atividade quando ela é criada. Por padrão, é a string XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED, o que significa que não há dica.

Os ambientes de execução não podem exigir que os apps tenham essas propriedades para se comportar de acordo com essa especificação. Os ambientes de execução não podem alterar o comportamento visível do app com base nessas propriedades. Todos esses metadados precisam ser especificáveis no nível <activity> ou <application>. Se especificado no nível <application>, ele se aplica a todas as atividades no aplicativo que não especificam os próprios valores.

Exemplo de código

O código a seguir mostra como usar essa extensão para casos de uso somente de percepção sem renderização.

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

Novos tipos de objeto

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas constantes de tipo enumerado

  • XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME
  • XR_EXT_spatial_container_SPEC_VERSION

  • Estendendo XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTAINER_EXT

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

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

Problemas

  • Como lidamos com várias solicitações visíveis pendentes? O app deve receber uma mudança / negação ou várias? A resposta pode ser diferente se as chamadas forem feitas em vários frames. A resposta também pode ser diferente se as várias solicitações resultarem em uma operação nula, ou seja, solicitar que um contêiner espacial fique visível e, em seguida, não visível para um contêiner que começa não visível.

    • Resolvido. Opções diferentes para eventos de mudança e eventos negados. As solicitações Noop não colocam um evento de mudança na fila. Elas apenas geram ruído para o desenvolvedor de apps e são fáceis de filtrar pelos ambientes de execução. Se várias solicitações visíveis forem negadas, os ambientes de execução precisam gerar um evento negado correspondente.

  • Como uma extensão de automação de conformidade deve ser definida para que todo o texto de especificação opcional para comportamentos de política ainda possa ser testado pelo CTS?

    • Resolvido. Extensão de teste separada. Haverá uma implementação de ambientes de execução de extensão de teste apenas para o CTS, permitindo que ele controle toda a política do sistema.

  • Precisamos de um evento para quando a posição de um contêiner espacial muda?

    • Resolvido. Não. O espaço do contêiner espacial não é bloqueado pelo mundo, e outros espaços desse tipo, como XR_REFERENCE_SPACE_TYPE_VIEW, não têm eventos quando mudam.

  • Como o xrSyncActions funciona se houver vários contêineres espaciais?

    • Resolvido. Nenhuma mudança é necessária. xrSyncActions se aplicaria a todos os contêineres espaciais na sessão. Se um app quiser direcionar as ações de entrada para um contêiner espacial específico, ele pode analisar o estado interativo por contêiner para escolher quais contêineres são destinos válidos. Se um app quiser sincronizar apenas o estado da ação de entrada para um único contêiner espacial, será necessária uma extensão adicional. No entanto, esperamos focar em uma extensão que permita que os apps sejam totalmente baseados em eventos e evitem a necessidade de uma chamada xrSyncActions em um loop de frame.

  • Como os apps atualizados com pouca frequência lidam com entradas?

    • Resolvido. Nenhuma mudança é necessária. Embora seja valioso para EXT_spatial_container, ele também é valioso fora dos contêineres espaciais. Isso pode ser feito por uma extensão de canal de eventos e funciona nos dois casos. Para contêineres espaciais, vamos adicionar outras maneiras de filtrar eventos para um único contêiner espacial.

  • Precisamos de uma espera para limitar/controlar o tempo do loop de entrada para apps com loops de entrada e renderização desacoplados?

    • Resolvido. Nenhuma mudança é necessária. Isso deve ser processado pelo canal de eventos e pelas extensões de solicitação atuais. A extensão de solicitação de apresentação permite que a renderização seja baseada em eventos e dissociada de um loop de frame.

  • Um contêiner espacial pode receber a pose em relação a outros contêineres espaciais? Principais considerações: temos um caso de uso para isso? Se sim, como os espaços do contêiner espacial se conectam ao LOCAL?

    • Resolvido. Sim. Isso já é possível para contêineres espaciais na mesma sessão usando XR_REFERENCE_SPACE_TYPE_VIEW, e é recomendável oferecer suporte a conteúdo dependente da visualização. Para compartilhar poses de contêineres espaciais entre sessões (como para outro processo), o caminho esperado é usar XR_EXT_spatial_anchor e os padrões de persistência e compartilhamento atuais.

  • O espaço de um contêiner espacial é localizável se não estiver visível?

    • Resolvido. Não. O espaço do contêiner espacial não pode ser localizado quando o contêiner não está visível. Isso significa que ele não tem áudio espacializado e que o app não pode "aquecer" o conteúdo dependente da visualização quando o spatial_container não está visível. As duas opções são aceitáveis porque, quando um contêiner espacial não está visível, o app precisa interromper qualquer carga de CPU / GPU usada para esse contêiner.

  • Onde o espaço do contêiner espacial deve ser colocado no contêiner espacial? As sugestões têm sido o centro ou o ponto mínimo (minX, minY, minZ).

    • Resolvido. No centro. Não há um local que não se mova da maioria das maneiras esperadas para uma UX de redimensionamento de contêiner espacial (bordas em movimento). O centro é usado com frequência em outras partes do OpenXR. Não alinhamos com janelas na computação 2D, que usam a coordenada mínima, porque os visualizadores de modelos 3D geralmente não seguem essa convenção.

  • Quando um ambiente de execução deve criar recursos subjacentes ao contêiner espacial? Às vezes, isso envolve a IPC com serviços do sistema.

    • Resolvido. De forma síncrona como parte de xrCreateSpatialContainerEXT . Embora possa haver IPC envolvida, a criação real de um contêiner geralmente é barata. Alguns fornecedores têm mutexes globais para gerenciar contêineres, mas não é comum que isso cause uma longa espera. Os problemas com contenção de mutex são bugs específicos do fornecedor que devem ser resolvidos por cada fornecedor.

  • Precisamos de um indicador de que uma XrSession vai criar contêineres espaciais e, portanto, não será compatível com o caminho de renderização legado?

    • Resolvido. Sim. Mudamos a máquina de estado da sessão de forma fundamental.

Histórico de versões

  • Revisão 1, 06/08/2026 (Jared Finder, Google)

    • Descrição inicial da extensão