XR_EXT_spatial_container

Name String

XR_EXT_spatial_container

Tipo de extensión

Extensión de instancia

Número de extensión registrado

811

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

OpenXR 1.0

Fecha de la última modificación

2026-08-06

Estado de la IP

No hay reclamos de IP conocidos.

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

Descripción general

Esta extensión define una nueva clase de entidades que se pueden mostrar, llamadas "contenedores espaciales", que son análogas al concepto de "ventanas" en los sistemas de ventanas 2D de escritorio.

En OpenXR 1.x, las apps tienen control exclusivo de todo lo que ve el usuario y de cómo se combina sobre su entorno real o virtual. Los entornos de ejecución solo realizan modificaciones leves en lo que se muestra para garantizar la seguridad del usuario. Este modelo de app es bueno para sumergir al usuario en una sola experiencia, pero no se extiende a varias experiencias simultáneas. En particular, en los entornos de RA y realidad mixta, los usuarios suelen querer experimentar varias apps diferentes al mismo tiempo.

Los contenedores espaciales son como ventanas extendidas a 3D. El usuario puede ver varios contenedores espaciales de forma simultánea y proporciona entradas a un subconjunto de ellos. Los contenedores espaciales visibles pueden pertenecer a diferentes apps, y los entornos de ejecución administran su tamaño y ubicación en nombre del usuario.

Esta extensión admite estos nuevos tipos de experiencias con límites espaciales, además de las experiencias inmersivas de OpenXR existentes. Las experiencias de OpenXR limitadas pueden tener contenido ligeramente en 3D (paneles planos con compensaciones de profundidad menores) o volúmenes que alojan contenido completamente en 3D. Las experiencias envolventes de OpenXR son las apps envolventes de pantalla completa existentes que se admiten desde OpenXR 1.0. Las apps pueden cambiar entre los dos tipos de contenido si así lo desean.

Esta extensión no define ningún método para que una app renderice su contenido. La forma de dibujar contenido se define en otras extensiones: XR_EXT_spatial_container_self_rendering .

Usa contenedores espaciales

Un XrSpatialContainerEXT es un controlador que representa un contenedor espacial.

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

Una aplicación comienza a renderizarse a través de un contenedor espacial con los siguientes pasos:

  1. Crea un contenedor espacial con xrCreateSpatialContainerEXT .
  2. Modifica cualquier estado del contenedor para la presentación inicial, como su modo de límites.
  3. Solicita que el entorno de ejecución muestre el contenedor con xrRequestSpatialContainerVisibleEXT .
  4. Espera a que el entorno de ejecución esté listo para mostrar el contenedor. Cuando el entorno de ejecución está listo, pone en cola un evento XrEventDataSpatialContainerVisibleChangedEXT con visible establecido en XR_TRUE .
  5. Comienza a renderizar el contenedor espacial.

Y la eliminación de un contenedor espacial es la siguiente:

  1. Solicita que el entorno de ejecución oculte el contenedor con xrRequestSpatialContainerVisibleEXT .
  2. Espera a que el entorno de ejecución termine de ocultar el contenedor. Cuando el entorno de ejecución ocultó por completo el contenedor, pone en cola un evento XrEventDataSpatialContainerVisibleChangedEXT con visible establecido en XR_FALSE .
  3. Finaliza la renderización del contenedor espacial.
  4. Destruye el contenedor con xrDestroySpatialContainerEXT .

Nota

Por diseño, esta extensión delega la visibilidad y la administración del enfoque a contenedores espaciales individuales. Debido a que la sesión en su conjunto ya no representa un solo objeto visible o enfocado, la sesión no pasa por la máquina de estado estándar de OpenXR (READY, SYNCHRONIZED, VISIBLE, FOCUSED). En cambio, la sesión permanece en XR_SESSION_STATE_IDLE durante su ciclo de vida activo, y las reglas de Cambios en el estado de la sesión especifican cómo se asignan las operaciones principales de OpenXR a este modo.

Crea un contenedor espacial

La función xrCreateSpatialContainerEXT crea un nuevo contenedor espacial.

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

Descripciones de los parámetros

Un XrSpatialContainerEXT recién creado debe ser no visible, no interactivo y estar en modo de límites XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT . Una app que quiere que un contenedor espacial se inicie en modo envolvente puede solicitar un modo de límites de XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT antes de solicitar que se muestre un contenedor espacial.

Los entornos de ejecución deben mostrar XR_ERROR_VALIDATION_FAILURE si alguna dimensión de XrSpatialContainerCreateInfoEXT :: suggestedBounds es negativa, infinita o no es un número. Los entornos de ejecución deben devolver XR_ERROR_LIMIT_REACHED si una app intenta crear más contenedores espaciales que los especificados en XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount . Si los contenedores espaciales no se habilitaron para esta sesión , los entornos de ejecución deben devolver XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT .

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

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

XrSpatialContainerCreateInfoEXT se pasa a xrCreateSpatialContainerEXT para crear un contenedor espacial.

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • graphicsPresentation es un XrSpatialContainerGraphicsPresentationEXT que describe cómo este contenedor espacial presenta gráficos.
  • suggestedBounds es un XrExtent3Df que describe las dimensiones solicitadas del contenedor espacial en metros.

Una app que no tiene preferencia por su tamaño puede establecer suggestedBounds en {0, 0, 0}. Un entorno de ejecución puede ignorar el suggestedBounds solicitado.

Un entorno de ejecución que permite que los contenedores espaciales estén delimitados por formas que no sean cuadros orientados debe usar suggestedBounds como un cuadro delimitador alrededor de las otras formas. Las cajas orientadas están diseñadas para ser la forma de límite más común.

Uso válido (implícito)

Cuando un contenedor espacial ya no se pueda usar, los entornos de ejecución deben poner en cola un evento XrEventDataSpatialContainerClosedEXT.

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • spatialContainer es el XrSpatialContainerEXT para el que se genera este evento.

Recibir el evento XrEventDataSpatialContainerClosedEXT indica que el entorno de ejecución ya no puede mostrar un contenedor espacial, por ejemplo, porque el usuario hizo clic en un botón "Cerrar" o la sesión ingresó al estado XR_SESSION_STATE_LOSS_PENDING.

Después de recibir el evento XrEventDataSpatialContainerClosedEXT, una app debería dejar de usar ese contenedor espacial, anular cualquier estado asociado, como un bucle de renderización, y destruir el contenedor. Los entornos de ejecución deben devolver XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT de todas las funciones que operan en ese contenedor, excepto xrDestroySpatialContainerEXT .

Si un contenedor espacial está visible cuando el entorno de ejecución pone en cola un evento de cierre, los entornos de ejecución deben primero cambiar el contenedor a no visible y poner en cola un evento XrEventDataSpatialContainerVisibleChangedEXT.

Uso válido (implícito)

La función xrDestroySpatialContainerEXT destruye un contenedor espacial existente.

XrResult xrDestroySpatialContainerEXT(
    XrSpatialContainerEXT                       spatialContainer);

Descripciones de los parámetros

Después de que se destruye un contenedor espacial, los entornos de ejecución no deben mostrar más el contenido del contenedor y no deben poner en cola ningún evento adicional sobre el contenedor.

Una app no debería destruir un contenedor espacial que esté visible, ya que, si lo hace, podrían producirse artefactos gráficos. En su lugar, la app debería solicitar que se oculte el contenedor espacial con xrRequestSpatialContainerVisibleEXT, esperar un evento XrEventDataSpatialContainerVisibleChangedEXT y, luego, destruir el contenedor.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a spatialContainer y a cualquier controlador secundario debe sincronizarse de forma externa.

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

El espacio del contenedor espacial

La función xrCreateSpatialContainerSpaceEXT crea un controlador XrSpace para el espacio de contenedor espacial de un contenedor espacial específico.

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

Descripciones de los parámetros

El "espacio del contenedor espacial" para cualquier contenedor espacial determinado es un sistema de coordenadas con su origen en el centro de los límites de ese contenedor espacial. Este espacio se suele usar como el espacio base para funciones como xrLocateSpace .

+X apunta a la cara derecha del contenedor, +Y apunta a la cara superior del contenedor y +Z apunta a la cara frontal del contenedor. Por ejemplo, si un contenedor está alineado con la gravedad, frente al visor, y el visor está en la pose de identidad en relación con el espacio LOCAL , los entornos de ejecución deben orientar el espacio del contenedor con la orientación de identidad en relación con el espacio LOCAL . Los entornos de ejecución pueden establecer la pose de un espacio de contenedor en relación con el espacio LOCAL en cualquier pose arbitraria cuando ese contenedor se vuelve visible.

ext spatial container space convention

Figura 18: Convención de ejes del espacio del contenedor espacial

El espacio del contenedor espacial es un origen no bloqueado en el mundo. Las apps que quieren un origen bloqueado en el mundo mientras están en modo envolvente pueden usar un espacio bloqueado en el mundo, como XR_REFERENCE_SPACE_TYPE_LOCAL .

Los entornos de ejecución pueden cambiar la pose de un espacio de contenedor espacial en cualquier momento, por lo general, para permitir que un usuario mueva un contenedor espacial a una posición o rotación diferente. Los entornos de ejecución también pueden cambiar la postura cuando se realiza la transición entre los modos de límites XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT y XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT.

Un espacio de contenedor espacial debe seguir siendo un controlador válido, incluso si el contenedor espacial para el que se creó se destruye con xrDestroySpatialContainerEXT . Mientras un contenedor espacial no sea visible o se destruya, el espacio del contenedor espacial debe ser imposible de ubicar en relación con otros espacios. XrSpaceLocation :: locationFlags y XrViewState ::viewStateFlags serán 0.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

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

XrSpatialContainerSpaceCreateInfoEXT se usa con xrCreateSpatialContainerSpaceEXT para crear un controlador XrSpace.

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • spatialContainer es un XrSpatialContainerEXT para el que se creará un espacio.

Uso válido (implícito)

Presenta un contenedor espacial

Otras extensiones se encargan de enviar el contenido de un contenedor espacial a OpenXR para que se muestre: XR_EXT_spatial_container_self_rendering .

Para permitir que otras extensiones especifiquen el método de presentación de gráficos para un contenedor espacial, esta extensión define la enumeración 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;

Descripción de enum

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

El contenedor espacial usa capas de composición de OpenXR (agregadas por la extensión XR_EXT_spatial_container_self_rendering).

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT

El contenedor espacial se crea para las pruebas de conformidad y no tiene una ruta de renderización (agregado por la extensión XR_EXT_spatial_container_conformance_automation)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1

El contenedor espacial usa la renderización del sistema de OpenXR (agregado por la extensión XR_EXTX1_system_renderer)

Estado del contenedor espacial

Los entornos de ejecución administran el estado del contenedor espacial según las solicitudes de la app y las necesidades del usuario. Por este motivo, cada aspecto del estado del contenedor espacial documenta lo siguiente:

  • Cuando se permite que los entornos de ejecución cambien el estado del contenedor espacial. En la mayoría de los estados de contenedores espaciales, los entornos de ejecución pueden cambiar el estado en cualquier momento.
  • Cómo una app solicita cambios en el estado Los entornos de ejecución pueden aplazar cualquier solicitud hasta que consideren que es adecuada. Los entornos de ejecución no ponen en cola los eventos cuando se aplaza una solicitud, por lo que las apps no deberían esperar un evento de ese tipo para una lógica no relacionada.
  • Qué tiempos de ejecución de eventos se ponen en cola cuando cambia el estado del contenedor espacial. Los entornos de ejecución ponen en cola los eventos de todos los cambios, incluidos los solicitados por la app y los iniciados por el entorno de ejecución. Los entornos de ejecución no deben poner en cola eventos de cambio de estado que no indiquen un cambio, como cuando una app realiza dos solicitudes para ocultar un contenedor en una sucesión rápida.
  • Qué entornos de ejecución de eventos se ponen en cola cuando se rechaza una solicitud de cambio de app. Los entornos de ejecución pueden rechazar una solicitud por cualquier motivo, por lo general, debido a la política del sistema relacionada con el mantenimiento de una experiencia del usuario de alta calidad.

La función xrGetSpatialContainerStateEXT consulta el estado actual del contenedor espacial.

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

Descripciones de los parámetros

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

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

XrSpatialContainerStateGetInfoEXT se usa con xrGetSpatialContainerStateEXT para consultar un XrSpatialContainerStateEXT .

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.

Uso válido (implícito)

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • visible representa si un contenedor espacial es visible.
  • interactable representa si un contenedor espacial puede recibir cualquier tipo de entrada en este momento. Es similar al "enfoque" de los sistemas de ventanas 2D de escritorio, con la diferencia de que puede haber varios contenedores espaciales interactivos a la vez.
  • boundsMode es el XrSpatialContainerBoundsModeEXT actual del contenedor espacial.

Los cambios en el estado de un contenedor espacial se comunican a través de eventos.

Evento Field Changed

visible

XrEventDataSpatialContainerVisibleChangedEXT

interactable

XrEventDataSpatialContainerInteractableChangedEXT

boundsMode

XrEventDataSpatialContainerBoundsChangedEXT

Uso válido (implícito)

Visibilidad

Las apps solicitan mostrar u ocultar un contenedor espacial con xrRequestSpatialContainerVisibleEXT .

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

Descripciones de los parámetros

Mostrar u ocultar un contenedor espacial es una operación asíncrona.

Las apps deben solicitar ocultar un contenedor espacial antes de destruirlo, lo que permite que los entornos de ejecución muestren una transición fluida. Los entornos de ejecución deben respetar las solicitudes para ocultar un contenedor espacial.

Un entorno de ejecución puede rechazar solicitudes para mostrar un contenedor espacial, en cuyo caso el entorno de ejecución debe poner en cola un evento XrEventDataSpatialContainerVisibleRequestDeniedEXT. Por ejemplo, algunos entornos de ejecución rechazarán una solicitud para mostrar un contenedor espacial que el usuario ocultó interactuando con un botón de "minimizar" proporcionado por el sistema.

Los entornos de ejecución no deben mostrar un contenedor espacial antes de que la app solicite mostrarlo al menos una vez. Después de la primera solicitud de la app para mostrar un contenedor espacial, los entornos de ejecución pueden cambiar la visibilidad de ese contenedor espacial independientemente de las solicitudes de la app. Esto permite que la app controle el estado inicial y el contenido de un contenedor espacial, y que los entornos de ejecución proporcionen una IU del sistema, como una barra de tareas, que permita al usuario elegir qué contenedores espaciales son visibles.

Los entornos de ejecución deben rechazar las solicitudes para mostrar un contenedor espacial en un modo de límites no admitido según XrSystemSpatialContainerPropertiesEXT :: supportsBounded y XrSystemSpatialContainerPropertiesEXT :: supportsImmersive . Esto es posible cuando el modo de límites predeterminado, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT , no es compatible con un sistema determinado.

Nota

En algunas implementaciones, mostrar u ocultar un contenedor espacial requiere comunicarse con los servicios del sistema y puede aplazarse hasta después de que el usuario interactúe con un diálogo del sistema. El diseño asíncrono para solicitar cambios en el estado de visibilidad tiene como objetivo permitir que los entornos de ejecución tengan tiempo para completar ambas operaciones.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

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

XrSpatialContainerVisibleRequestInfoEXT se usa con xrRequestSpatialContainerVisibleEXT para cambiar la visibilidad de un contenedor espacial.

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • visible representa si se solicita que se muestre o se oculte un contenedor espacial.

Uso válido (implícito)

Cada vez que un entorno de ejecución cambia la visibilidad de un contenedor espacial, el entorno de ejecución debe poner en cola un evento XrEventDataSpatialContainerVisibleChangedEXT con el estado nuevo.

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • spatialContainer es el XrSpatialContainerEXT para el que se genera este evento.
  • visible es el nuevo estado visible del contenedor espacial.

Este evento reemplaza a XR_SESSION_STATE_VISIBLE , lo que permite que el valor sea diferente para cada contenedor. El evento debe ponerse en cola para todos los cambios, incluidos los solicitados por la app y los iniciados en el entorno de ejecución.

Un entorno de ejecución puede retrasar la renderización de un contenedor durante algunos fotogramas después de poner en cola este evento con visible establecido en XR_TRUE para evitar que se muestre un contenedor vacío y darle tiempo a la app para que envíe su contenido inicial. Durante este tiempo, XrSpatialContainerStateEXT ::visible será XR_TRUE . Los entornos de ejecución no deberían retrasar la renderización de un contenedor por más de 0.5 segundos.

Uso válido (implícito)

Cada vez que un entorno de ejecución rechaza una solicitud para mostrar un contenedor, debe poner en cola un evento XrEventDataSpatialContainerVisibleRequestDeniedEXT.

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • spatialContainer es el XrSpatialContainerEXT para el que se genera este evento.

Uso válido (implícito)

Interactable

Una app no puede solicitar que un contenedor espacial sea interactivo. Los entornos de ejecución controlan por completo qué contenedores espaciales son interactivos. Un contenedor espacial que sea interactivo también debe ser visible.

Cada vez que un entorno de ejecución cambia el estado interactivo de un contenedor espacial, el entorno de ejecución debe poner en cola un evento XrEventDataSpatialContainerInteractableChangedEXT con el estado nuevo.

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • spatialContainer es el XrSpatialContainerEXT para el que se genera este evento.
  • interactable es el nuevo estado interactivo del contenedor espacial.

Este evento reemplaza a XR_SESSION_STATE_FOCUSED , lo que permite que el valor sea diferente para cada contenedor. El evento se pone en cola para todos los cambios, incluidos los que se inician en el entorno de ejecución.

Los entornos de ejecución pueden habilitar o inhabilitar la interacción con un contenedor espacial en cualquier momento. Si un entorno de ejecución solo admite un contenedor espacial interactivo a la vez, cuando el entorno de ejecución cambia el contenedor espacial interactivo, debe poner en cola el evento para el contenedor espacial que deja de ser interactivo ( interactable establecido en falso) antes del evento para el contenedor que comienza a ser interactivo ( interactable establecido en verdadero).

Uso válido (implícito)

Límites

Un contenedor espacial tiene un modo de límites y un cuadro delimitador. El modo de límites de un contenedor espacial describe cómo se comportan los límites. Su cuadro delimitador es lo que dibuja el contenedor espacial en su interior.

La enumeración XrSpatialContainerBoundsModeEXT identifica los diferentes modos en los que pueden estar los límites de un contenedor espacial.

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;

Descripción de enum

XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT

El contenedor espacial está limitado. Los límites son un cuadro finito. El contenedor espacial solo aparecerá en esta región.

XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT

El contenedor espacial es envolvente y tiene límites infinitos. El contenedor espacial se muestra en toda la pantalla.

Los contenedores espaciales que están en el modo de límites XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT tienen requisitos adicionales:

  • Los entornos de ejecución deben tratar estos contenedores espaciales de la misma manera que una app inmersiva y de pantalla completa creada sin el uso de contenedores espaciales, excepto por los cambios de comportamiento que se indican en Cambios en el estado de la sesión .
  • Los entornos de ejecución pueden proporcionar extensiones adicionales que permitan que los contenedores espaciales envolventes se comporten de manera diferente a las apps envolventes y de pantalla completa creadas sin esta extensión.
  • Los entornos de ejecución deben informar límites infinitos para estos contenedores espaciales.
  • Los entornos de ejecución pueden ocultar otros contenedores espaciales mientras un contenedor espacial inmersivo está visible. Debido a que esto puede variar según el entorno de ejecución, las apps no deberían depender de que los contenedores espaciales se muestren o se oculten automáticamente según la visibilidad del contenedor espacial inmersivo. Al igual que todas las demás transiciones de estado visibles, los entornos de ejecución deben poner en cola un evento XrEventDataSpatialContainerVisibleChangedEXT cuando se oculta un contenedor espacial porque un contenedor envolvente está visible.

Nota

Los requisitos anteriores implican que todos los entornos de ejecución pueden implementar la ruta de acceso de OpenXR 1.x sin esta extensión creando de forma implícita un contenedor espacial, configurando el modo de límites del contenedor como envolvente y solicitando que sea visible.

Las apps solicitan cambiar el modo de límites de un contenedor espacial con xrRequestSpatialContainerBoundsModeEXT .

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

Descripciones de los parámetros

Cambiar el modo de límites de un contenedor espacial es una operación asíncrona, y los entornos de ejecución pueden poner en cola un evento de cambio o rechazo muchos segundos después de que la app solicite un cambio. Esto permite que los entornos de ejecución muestren la IU necesaria para que un usuario ingrese de forma segura a un modo envolvente.

Los entornos de ejecución deben respetar una solicitud para cambiar el modo de límites de un contenedor espacial no visible. Si un entorno de ejecución rechaza una solicitud de modo de límites para un contenedor no visible, puede rechazar o aplazar una solicitud para mostrar ese contenedor espacial. Esto permite que las apps inicien un contenedor como uno envolvente. Un entorno de ejecución puede rechazar las solicitudes para cambiar el modo de límites de un contenedor espacial visible, en cuyo caso el entorno de ejecución debe poner en cola un evento XrEventDataSpatialContainerBoundsModeRequestDeniedEXT. Por ejemplo, algunos entornos de ejecución rechazarán una solicitud para cambiar el modo de límites de un contenedor espacial visible con el que el usuario no interactúa de forma activa.

Los entornos de ejecución deben devolver XR_ERROR_VALIDATION_FAILURE si una app solicita un modo de límites no admitido según XrSystemSpatialContainerPropertiesEXT :: supportsBounded y XrSystemSpatialContainerPropertiesEXT :: supportsImmersive .

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

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

XrSpatialContainerBoundsModeRequestInfoEXT se usa con xrRequestSpatialContainerBoundsModeEXT para cambiar el modo de límites de un contenedor espacial.

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • boundsMode es el XrSpatialContainerBoundsModeEXT deseado para el contenedor espacial.

Uso válido (implícito)

Cada vez que un entorno de ejecución cambia los límites o el modo de límites de un contenedor espacial, el entorno de ejecución debe poner en cola un evento XrEventDataSpatialContainerBoundsChangedEXT con la información de los límites nuevos.

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • spatialContainer es el XrSpatialContainerEXT para el que se genera este evento.
  • bounds es el nuevo ancho, la nueva altura y la nueva profundidad de los límites del contenedor espacial.
  • infiniteBounds es verdadero si el contenedor tiene límites infinitos.
  • boundsMode es el nuevo XrSpatialContainerBoundsModeEXT del contenedor espacial.

El evento se pone en cola para todos los cambios, incluidos los solicitados por la app y los iniciados en el entorno de ejecución.

Mientras un usuario cambia el tamaño de un contenedor espacial de forma interactiva, los entornos de ejecución deben comportarse de una de las siguientes maneras:

  • poner en cola muchos eventos, probablemente a la velocidad de fotogramas, mientras el usuario cambia el tamaño del contenedor espacial
  • poner en cola un solo evento al final del cambio de tamaño

Si un entorno de ejecución pone en cola solo un evento al final del cambio de tamaño, ese entorno de ejecución debe seguir informando los límites antiguos de xrGetSpatialContainerBoundsEXT hasta que el entorno de ejecución ponga en cola un evento de cambio de tamaño. Los entornos de ejecución deben fusionar varios eventos de cambio de límites no sondeados. En otras palabras, si los límites o el modo de límites cambian mientras hay un evento XrEventDataSpatialContainerBoundsChangedEXT en cola, los entornos de ejecución deben informar solo un evento que contenga el último cambio de límites que se produjo. Debido a que las apps también pueden sondear los límites de un contenedor espacial directamente con xrGetSpatialContainerBoundsEXT, la cantidad de cambios de límites de los eventos puede ser diferente de la cantidad de cambios del sondeo según el momento en que se generen los cambios de límites en el entorno de ejecución, las llamadas de la app a xrPollEvent y las llamadas de la app a xrGetSpatialContainerBoundsEXT .

Cuando cambian los límites de un contenedor espacial, el origen local del contenedor espacial puede cambiar también. Por ejemplo, si un entorno de ejecución permite que un usuario cambie el tamaño de los límites del contenedor espacial arrastrando uno de sus bordes, los límites y el origen local de ese contenedor cambiarán cuando el usuario arrastre un solo borde. En esas situaciones, el entorno de ejecución debe cambiar los límites y el origen local de forma simultánea.

Los entornos de ejecución deben establecer infiniteBounds en XR_TRUE y establecer el ancho, la altura y la profundidad en 0.0 para representar límites infinitos. Los entornos de ejecución deben establecer infiniteBounds en XR_FALSE y establecer el ancho, la altura y la profundidad en números positivos finitos para los límites finitos.

Los entornos de ejecución deben establecer bounds y infiniteBounds siguiendo las mismas reglas que para XrSpatialContainerBoundsEXT .

Uso válido (implícito)

Cada vez que un entorno de ejecución rechaza una solicitud para cambiar el modo de límites de un contenedor, el entorno de ejecución debe poner en cola un evento XrEventDataSpatialContainerBoundsModeRequestDeniedEXT.

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • spatialContainer es el XrSpatialContainerEXT para el que se genera este evento.

Uso válido (implícito)

La estructura XrSpatialContainerBoundsEXT describe el cuadro delimitador de un contenedor espacial.

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • bounds es el ancho, la altura y la profundidad de los límites del contenedor espacial. Los límites se expresan en metros.
  • infiniteBounds es verdadero si el contenedor tiene límites infinitos.

Los entornos de ejecución deben establecer infiniteBounds en XR_TRUE y establecer el ancho, la altura y la profundidad en 0.0 para representar límites infinitos. Los entornos de ejecución deben establecer infiniteBounds en XR_FALSE y establecer el ancho, la altura y la profundidad en números positivos finitos para los límites finitos.

Uso válido (implícito)

La función xrGetSpatialContainerBoundsEXT consulta los límites actuales de un contenedor espacial.

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

Descripciones de los parámetros

Mientras que un contenedor espacial está limitado, no debe tener límites infinitos, mientras que un contenedor espacial es inmersivo, debe tener límites infinitos.

Los entornos de ejecución pueden cambiar los límites de un contenedor espacial a cualquier valor finito positivo en cualquier momento mientras el contenedor espacial esté limitado. Los cambios en los límites de un contenedor espacial se comunican a través de XrEventDataSpatialContainerBoundsChangedEXT .

Con esta extensión, una app no puede solicitar cambios en los límites, excepto cambiar entre limitado e inmersivo con xrRequestSpatialContainerBoundsModeEXT . Es posible que otras extensiones proporcionen esa forma en el futuro.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

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

La estructura XrSpatialContainerBoundsGetInfoEXT es una estructura de entrada que existe para fines de extensión futuros.

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.

Uso válido (implícito)

La enumeración XrSpatialContainerVolumeClippingEXT identifica diferentes comportamientos de recorte de volumen para un contenedor 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;

Descripción de enum

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT

No se recorta ningún contenido para que se ajuste al volumen delimitador del contenedor espacial. El contenido se puede dibujar fuera de los límites del contenedor espacial.

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT

El contenido se recorta estrictamente al volumen delimitador del contenedor espacial.

No se usa esta enumeración en esta extensión. Se define para permitir que otras extensiones especifiquen el comportamiento de recorte de volumen deseado. Por ejemplo, una app puede querer dibujar un fondo para un contenedor espacial limitado. Un mapa de cubo monocular es una forma conveniente de especificar un fondo; sin embargo, un mapa de cubo monocular se posiciona conceptualmente en el infinito, que está fuera del contenedor.

Funciones del sistema

Una app puede inspeccionar las capacidades del sistema encadenando una estructura XrSystemSpatialContainerPropertiesEXT a XrSystemProperties cuando se llama a xrGetSystemProperties .

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

Descripción del miembro

  • type es el XrStructureType de esta estructura.
  • next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
  • maxSpatialContainerCount es la cantidad máxima de contenedores espaciales que se pueden crear.
  • supportsBounded es verdadero si los contenedores espaciales se pueden delimitar.
  • supportsImmersive es verdadero si se permite que los contenedores espaciales sean envolventes.

Los entornos de ejecución que admiten esta extensión deberían admitir que una app cree muchos contenedores espaciales, solo limitados por la asignación de memoria. Un entorno de ejecución puede tener un límite diferente para la cantidad de contenedores espaciales que se muestran de forma simultánea. No hay forma de consultar la cantidad de contenedores que se muestran de forma simultánea en esta extensión, ya que un entorno de ejecución puede limitar las apps individuales según el estado de todas las apps en ejecución. Se supone que los dispositivos con muchas restricciones y los dispositivos con menos restricciones tendrán límites diferentes para la cantidad de contenedores que se muestran simultáneamente; los dispositivos con muchas restricciones pueden admitir que se muestre solo un contenedor espacial a la vez, y los dispositivos con menos restricciones pueden admitir que se muestre una gran cantidad de contenedores espaciales simultáneamente, sujeto a los límites de procesamiento de renderización.

Los entornos de ejecución que admiten esta extensión deben admitir, al menos, uno de los contenedores espaciales limitados o contenedores espaciales envolventes.

Uso válido (implícito)

La función xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT devuelve los métodos de presentación de gráficos admitidos en un sistema.

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

Descripciones de los parámetros

  • instance es la XrInstance de la que se recuperó systemId.
  • systemId es el XrSystemId que se consulta.
  • graphicsPresentationCapacityInput es la capacidad del array graphicsPresentations, o 0 para indicar una solicitud de recuperación de la capacidad requerida.
  • graphicsPresentationCountOutput es un puntero al recuento de presentaciones de gráficos escritas o un puntero a la capacidad requerida en caso de que graphicsPresentationCapacityInput sea 0.
  • graphicsPresentations es un puntero a un array de valores XrSpatialContainerGraphicsPresentationEXT, pero puede ser nulo si graphicsPresentationCapacityInput es 0.
  • Consulta la sección Parámetros de tamaño del búfer para obtener una descripción detallada de cómo recuperar el tamaño de graphicsPresentations requerido.

Los entornos de ejecución deben siempre devolver contenidos de búfer idénticos de esta enumeración para el systemId dado y durante la vida útil de la instancia.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • 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

Cambios en el estado de la sesión

La compatibilidad con contenedores espaciales se habilita para una sesión encadenando un XrSessionCreateInfoSpatialContainersEXT cuando se llama a xrCreateSession .

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

Cuando se habilita la compatibilidad con contenedores espaciales, una XrSession se comporta de manera diferente. Esto se debe a que, cuando se usan contenedores espaciales, la sesión ya no presenta contenido de imagen en las pantallas, sino que lo hacen los contenedores espaciales. Por lo tanto, cuando se habilita esta extensión, una sesión es, en efecto, "sin interfaz gráfica". A diferencia de otras extensiones sin interfaz gráfica, las apps pueden enviar datos de imágenes a través de los contenedores espaciales.

Habilitar la compatibilidad con contenedores espaciales altera las APIs principales de OpenXR de la siguiente manera.

tiempo de ejecución: pérdida del sistema o dispositivo

tiempo de ejecución: pérdida del sistema o dispositivo

xrDestroySession

xrDestroySession

IDLE
(en ejecución)

IDLE…

xrGetSystem
xrCreateSession

xrGetSystem...

xrCreateInstance

xrCreateIn...

xrDestroySession

xrDestroySession

LOSS_PENDING
(no se está ejecutando)

LOSS_PENDING...

xrDestroyInstance

xrDestroyInstance

app: opcionalmente,
reiniciar la RE

app: opcionalmente…

Figura 19. Nueva máquina de estado de sesión

  • La sesión nunca entra en los estados XR_SESSION_STATE_VISIBLE, XR_SESSION_STATE_FOCUSED ni XR_SESSION_STATE_EXITING . Los entornos de ejecución nunca deben poner en cola eventos para estos estados. Estos estados se reemplazan por los eventos de contenedor espacial XrEventDataSpatialContainerVisibleChangedEXT, XrEventDataSpatialContainerInteractableChangedEXT y XrEventDataSpatialContainerClosedEXT, respectivamente.
  • La sesión tampoco entra nunca en los estados XR_SESSION_STATE_READY, XR_SESSION_STATE_SYNCHRONIZED ni XR_SESSION_STATE_STOPPING . Los entornos de ejecución nunca deben poner en cola eventos para estos estados. No hay reemplazo para estos estados.
  • Los entornos de ejecución deben tratar la sesión como en ejecución cuando se encuentra en el estado XR_SESSION_STATE_IDLE .
  • Los entornos de ejecución deben tratar la sesión como enfocada cuando se encuentra en el estado XR_SESSION_STATE_IDLE y existe al menos un contenedor espacial con el que se puede interactuar.
  • Ya no se necesitan las funciones xrBeginSession ni xrEndSession. Los entornos de ejecución deben mostrar XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT cuando se llama a estas funciones. Otras extensiones pueden proporcionar reemplazos para estas funciones.
  • La función xrRequestExitSession tampoco es necesaria. Los entornos de ejecución deben mostrar XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT cuando se llama a esta función. Las apps que quieran salir de una sesión en ejecución pueden llamar a xrRequestSpatialContainerVisibleEXT para ocultar sus contenedores y destruir la sesión después de que todos los contenedores dejen de ser visibles.

  • Las extensiones que pondrían en cola eventos adicionales cuando la sesión comience a ejecutarse ahora deben poner en cola esos eventos después de la creación de la sesión. Estas extensiones se indican a continuación.

    Evento de extensión

XR_EXT_user_presence

XrEventDataUserPresenceChangedEXT

XR_META_boundary_visibility

XrEventDataBoundaryVisibilityChangedMETA

  • No es válido llamar a la función xrLocateViews para la sesión. Los entornos de ejecución deben devolver XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT desde xrLocateViews . Otras extensiones pueden proporcionar formas de ubicar las vistas de un contenedor espacial en particular.
  • La función xrWaitFrame debe establecer siempre XrFrameState :: shouldRender como falso. Otras extensiones pueden proporcionar formas de saber si un contenedor espacial en particular debe actualizar sus capas de composición.
  • La función xrEndFrame no es una forma válida de enviar capas de composición. Si una app establece XrFrameEndInfo :: layerCount en un valor distinto de cero, los entornos de ejecución deben devolver XR_ERROR_VALIDATION_FAILURE . Otras extensiones pueden proporcionar formas de enviar capas de composición para un contenedor espacial en particular.
  • Cuando se ingresa al estado XR_SESSION_STATE_LOSS_PENDING, también se cierran todos los contenedores espaciales. Los entornos de ejecución deben poner en cola un evento XrEventDataSpatialContainerClosedEXT para cada contenedor espacial activo antes de poner en cola un cambio de estado de sesión para XR_SESSION_STATE_LOSS_PENDING .
  • La función xrCreateSession ya no necesita una estructura de vinculación de la API de gráficos. Otras extensiones pueden requerir una vinculación de gráficos, por ejemplo, para que un contenedor espacial se renderice con una API de gráficos.

El comportamiento anterior es un poco diferente del comportamiento en XR_MND_headless . Los entornos de ejecución no deben habilitar el comportamiento de sesión sin interfaz gráfica de XR_MND_headless cuando la compatibilidad con contenedores espaciales está habilitada para esa sesión.

Nota

Cuando los contenedores espaciales están habilitados, una sesión solo cambia entre dos estados: XR_SESSION_STATE_IDLE (en ejecución) y XR_SESSION_STATE_LOSS_PENDING (no en ejecución). Como resultado, los entornos de ejecución ya no devuelven XR_ERROR_SESSION_RUNNING ni XR_ERROR_SESSION_NOT_RUNNING . En cambio, cuando no se está ejecutando una sesión, los entornos de ejecución devuelven XR_ERROR_SESSION_LOST o XR_SESSION_LOSS_PENDING según las reglas del núcleo de OpenXR. Además, xrBeginSession , la única función que devuelve XR_ERROR_SESSION_RUNNING , ahora siempre devolverá XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT .

Uso válido (implícito)

Entradas del manifiesto de Android

Los entornos de ejecución basados en AOSP pueden tener un comportamiento personalizado según el estado inicial del contenedor espacial que se inicia antes de ejecutar cualquier código de la app. Por ejemplo, un entorno de ejecución puede alterar los recursos asignados para la actividad, las animaciones de inicio o la visualización de la pantalla de presentación. Para ello, se proporcionan las siguientes propiedades. Reemplazan la etiqueta <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />, que las apps basadas en contenedores espaciales no deberían especificar, excepto por motivos de compatibilidad con entornos de ejecución anteriores basados en el AOSP.

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

Esta propiedad indica a los entornos de ejecución los modos de límites que usa una actividad. De forma predeterminada, es una lista vacía, lo que implica que no hay sugerencias.

Las siguientes cadenas son válidas para este atributo. Si hay más de un valor, se separan con |, como "bounded|immersive" .

Valor

Descripción

"2d_panel"

La actividad se muestra con el framework de vistas en 2D de Android.

"bounded"

La actividad usa XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT .

"immersive"

La actividad 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" />

Esta propiedad indica a los entornos de ejecución el XrSpatialContainerBoundsModeEXT inicial de la actividad cuando se crea por primera vez. De forma predeterminada, es la cadena XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED, que implica que no hay sugerencia.

Los entornos de ejecución no deben requerir que las apps tengan estas propiedades para comportarse de acuerdo con esta especificación. Los entornos de ejecución no deben alterar el comportamiento visible de la app en función de estas propiedades. Todos estos metadatos deben poder especificarse en el nivel <activity> o <application>. Si se especifica en el nivel <application>, se aplica a todas las actividades de la aplicación que no especifican sus propios valores.

Ejemplo de código

En el siguiente código, se muestra cómo usar esta extensión para casos de uso de solo percepción sin renderización.

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

Nuevos tipos de objetos

Comandos nuevos

Estructuras nuevas

Enums nuevas

Nuevas constantes de enum

  • XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME
  • XR_EXT_spatial_container_SPEC_VERSION

  • Extiende XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTAINER_EXT

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

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

  • ¿Cómo manejamos varias solicitudes visibles pendientes? ¿La app debería recibir un cambio o un rechazo, o varios? La respuesta podría ser diferente si las llamadas se realizan en varios fotogramas. La respuesta también podría ser diferente si las múltiples solicitudes dan como resultado una operación noop, es decir, solicitar que un contenedor espacial sea visible y, luego, no visible para un contenedor que comienza como no visible.

    • Se resolvió el problema. Diferentes opciones para los eventos de cambio y los eventos rechazados Las solicitudes noop no ponen en cola un evento de cambio, solo generan ruido para el desarrollador de apps y son fáciles de filtrar para los entornos de ejecución. Si se rechazan varias solicitudes visibles, los entornos de ejecución deben generar un evento de rechazo correspondiente para cada una.

  • ¿Cómo se espera que se defina una extensión de automatización de conformidad para que el CTS pueda probar todo el texto de especificación opcional para los comportamientos de las políticas?

    • Se resolvió el problema. Extensión de prueba independiente Habrá un entorno de ejecución de extensiones de prueba que se implementará solo para el CTS, lo que permitirá que el CTS controle toda la política del sistema.

  • ¿Necesitamos un evento para cuando cambia la posición de un contenedor espacial?

    • Se resolvió el problema. No. El espacio del contenedor espacial no está bloqueado en el mundo, y otros espacios similares, como XR_REFERENCE_SPACE_TYPE_VIEW, no tienen eventos cuando cambian.

  • ¿Cómo funciona xrSyncActions si hay varios contenedores espaciales?

    • Se resolvió el problema. No se necesita ningún cambio. xrSyncActions se aplicaría a todos los contenedores espaciales de la sesión. Si una app quiere dirigir las acciones de entrada a un contenedor espacial en particular, puede consultar el estado interactivo por contenedor para elegir qué contenedores son destinos válidos. Si una app solo quiere sincronizar el estado de la acción de entrada para un solo contenedor espacial, se necesitaría una extensión adicional. Sin embargo, esperamos enfocarnos en una extensión que permita que las apps se basen completamente en eventos y eviten la necesidad de una llamada a xrSyncActions en un bucle de fotogramas.

  • ¿Cómo manejan las entradas las apps que se actualizan con poca frecuencia?

    • Se resolvió el problema. No se necesitan cambios. Si bien es valioso para EXT_spatial_container, también lo es fuera de los contenedores espaciales. Esto se puede controlar a través de una extensión de canal de eventos y funcionar en ambos casos. En el caso de los contenedores espaciales, agregaremos formas adicionales de filtrar eventos para un solo contenedor espacial.

  • ¿Necesitamos una espera para limitar o controlar el tiempo del bucle de entrada para las apps con bucles de entrada y renderización desacoplados?

    • Se resolvió el problema. No se necesitan cambios. Se espera que esto se controle a través del canal de eventos y las extensiones de solicitud presentes. La extensión de solicitud de presentación permite que la renderización se base en eventos y se desvincule de un bucle de fotogramas.

  • ¿Puede un contenedor espacial obtener su pose en relación con otros contenedores espaciales? Consideraciones clave: ¿Tenemos un caso de uso para esto? Y, si es así, ¿cómo se conectan los espacios de contenedores espaciales con LOCAL?

    • Se resolvió el problema. Sí. Esto ya es posible para los contenedores espaciales dentro de la misma sesión si se pasa por XR_REFERENCE_SPACE_TYPE_VIEW, y es conveniente admitir contenido que dependa de la vista. Para compartir poses de contenedores espaciales entre sesiones (como en otro proceso), la ruta esperada es aprovechar XR_EXT_spatial_anchor y sus patrones de persistencia y uso compartido existentes.

  • ¿Se puede ubicar el espacio de un contenedor espacial si no es visible?

    • Se resolvió el problema. No. No se puede ubicar el espacio del contenedor espacial cuando este no está visible. Esto implica que no tiene audio espacializado ni la app puede "preparar" el contenido dependiente de la vista cuando el spatial_container no está visible. Ambas opciones son correctas porque, cuando un contenedor espacial no está visible, se espera que la app detenga cualquier carga de CPU o GPU que se use para ese contenedor espacial.

  • ¿Dónde se espera que se coloque el espacio del contenedor espacial en el contenedor espacial? Las sugerencias han sido el centro o el punto mínimo (minX, minY, minZ).

    • Se resolvió el problema. En el centro. No hay ninguna ubicación que no se mueva de la mayoría de las formas en que se espera que se mueva la UX de cambio de tamaño de un contenedor espacial (bordes en movimiento). Center se usa comúnmente en otras partes de OpenXR. No nos alineamos con las ventanas en la computación en 2D, que usan la coordenada mínima, porque los visores de modelos 3D no suelen seguir esta convención.

  • ¿Cuándo se espera que un entorno de ejecución cree recursos subyacentes al contenedor espacial? A veces, esto implica la IPC con servicios del sistema.

    • Se resolvió el problema. De forma síncrona como parte de xrCreateSpatialContainerEXT . Si bien puede haber IPC involucrada, se espera que la creación real de un contenedor sea económica. Algunos proveedores tienen mutex globales para administrar contenedores, pero no se espera que, por lo general, haya una espera prolongada. Los problemas con la contención de mutex son errores específicos del proveedor que se espera que cada proveedor solucione.

  • ¿Necesitamos un indicador de que una XrSession creará contenedores espaciales y, por lo tanto, no admitirá la ruta de renderización heredada?

    • Se resolvió el problema. Sí. Cambiamos la máquina de estado de la sesión de una manera fundamental.

Historial de versiones

  • Revisión 1, 6 de agosto de 2026 (Jared Finder, Google)

    • Descripción inicial de la extensión