XR_EXT_spatial_container_self_rendering

Name String

XR_EXT_spatial_container_self_rendering

Tipo de extensión

Extensión de instancia

Número de extensión registrado

814

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

XR_EXT_spatial_container

Fecha de la última modificación

2026-08-06

Estado de la IP

No hay reclamos de IP conocidos.

Colaboradores

Lachlan Ford, Google
Andreas Loeve Selvik, Meta Platforms
Adam Gousetis, Meta Platforms
Bjorn Swenson, LÖVR
Cass Everitt, Meta Platforms
Christian Kruse, Meta Platforms
Denny Rönngren, Varjo Technologies
Fredia Huya-Kouadio, Godot Engine
Jakob Bornecrantz, NVIDIA
Jared Finder, Google
Jonathan Wright, Meta Platforms
Jian Zhang, ByteDance
Kurtis Eveleigh, Qualcomm
Mauricio Narvaez, Meta Platforms
Nick Klingensmith, Qualcomm
Nikita Lutsenko, Meta Platforms
Praveen Babu J D, ByteDance
Rylie Pavlik, Collabora
Salar Khan, Google
Shuai Liu, ByteDance
Walter Luh, Meta Platforms
Yin Li, Microsoft

Descripción general

Esta extensión define la "autorrenderización" para los contenedores espaciales. Todos los píxeles de un contenedor espacial renderizado por sí mismo se generan con una app y se envían al entorno de ejecución con cadenas de intercambio y capas de composición de OpenXR estándar. Como los contenedores espaciales no siempre ocupan todos los píxeles de una pantalla, el entorno de ejecución informa a las apps sobre la resolución y la configuración de vista recomendadas de cada contenedor espacial para que las apps puedan renderizar de manera más eficiente.

Esta extensión combinada con XR_EXT_spatial_container tiene como objetivo ofrecer un superconjunto de las capacidades de renderización de la capa de composición principal de OpenXR 1.x convencional. Los entornos de ejecución de OpenXR 1.x que admiten la renderización gráfica y esta extensión deben establecer XrSystemSpatialContainerPropertiesEXT :: supportsImmersive como verdadero para indicar que admiten contenedores espaciales envolventes.

Ciclo de vida de la renderización de contenedores espaciales

Para usar la renderización automática en un contenedor espacial, una app establece XrSpatialContainerCreateInfoEXT :: graphicsPresentation en XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT cuando llama a xrCreateSpatialContainerEXT . Luego, esa app puede administrar si un contenedor espacial se renderiza de forma activa llamando a las funciones xrBeginSpatialContainerRenderingEXT y xrEndSpatialContainerRenderingEXT. Estas funciones reemplazan a xrBeginSession y xrEndSession . No son operaciones por fotograma, como xrBeginFrame y xrEndFrame .

En cada fotograma, una app realiza los siguientes pasos:

  • Llama a xrWaitFrame y xrBeginFrame . Estas funciones no tienen estructuras específicas de contenedores y funcionan como lo hacen en la especificación principal.
  • Recupera las poses de vista, los parámetros de proyección y las recomendaciones de renderización para todos los contenedores espaciales que se renderizan de forma activa con xrLocateSpatialContainerViewsEXT . Para cada contenedor espacial, el entorno de ejecución informa si sus capas de composición deben renderizarse y la forma recomendada de renderizarlas completando XrSpatialContainerViewStateEXT .
  • Renderiza píxeles en capas de composición normalmente. Estas operaciones no tienen estructuras específicas de contenedores.
  • Envía capas de composición para todos los contenedores espaciales que se renderizan de forma activa llamando a xrEndFrame y encadenando XrSpatialContainerLayerFrameEndInfoEXT .

Cuando se destruye un controlador XrSpatialContainerEXT, se quita de forma implícita del conjunto de renderización activo. Una app puede destruir un contenedor espacial incluso si realizó una llamada exitosa a xrBeginSpatialContainerRenderingEXT que no está asociada con una llamada correspondiente a xrEndSpatialContainerRenderingEXT . El entorno de ejecución debe comportarse como si se llamara a xrEndSpatialContainerRenderingEXT de forma implícita si es necesario al principio de la implementación de xrDestroySpatialContainerEXT si se devuelve correctamente.

Cuando una app recibe un evento XrEventDataSpatialContainerClosedEXT para un contenedor en el conjunto de renderización activo, esa app debe llamar a xrEndSpatialContainerRenderingEXT y destruir el controlador XrSpatialContainerEXT.

La función xrBeginSpatialContainerRenderingEXT agrega el contenedor espacial al conjunto de renderización activo por sesión, lo que permite que una app envíe capas de composición para el contenedor espacial a xrEndFrame .

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

Descripciones de los parámetros

Por lo general, las apps llaman a esta función en respuesta a un evento de cambio de visibilidad con XrEventDataSpatialContainerVisibleChangedEXT :: visible establecido en verdadero.

Si el contenedor espacial no se creó con XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT cuando se llamó a xrCreateSpatialContainerEXT , el entorno de ejecución debe devolver XR_ERROR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MISSING_EXT .

Si el contenedor espacial ya está en el conjunto de renderización activo, el entorno de ejecución debe devolver XR_ERROR_SPATIAL_CONTAINER_IS_RENDERING_EXT .

Si se llama a xrBeginSpatialContainerRenderingEXT en un momento en el que la app no pudo llamar a xrWaitFrame (es decir, dentro de la ventana xrBeginFrame y xrEndFrame), el entorno de ejecución debe devolver XR_ERROR_CALL_ORDER_INVALID.

Uso válido (implícito)

Seguridad de subprocesos

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

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

La estructura XrSpatialContainerBeginInfoEXT se usa para especificar los parámetros que se usarán para comenzar a renderizar un contenedor espacial.

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

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.
  • spatialContainer es el XrSpatialContainerEXT para comenzar la renderización.
  • primaryViewConfigurationType es el XrViewConfigurationType principal que se usará para el contenedor espacial.

primaryViewConfigurationType es la configuración de vista que la app pretende usar cuando se renderiza. El entorno de ejecución puede reducir la configuración de la vista a un tipo con menos vistas para fines de optimización (p.ej., un contenedor está muy lejos y es pequeño, por lo que el estéreo es imperceptible). El entorno de ejecución devuelve detalles sobre la configuración de la vista deteriorada de las llamadas a xrLocateSpatialContainerViewsEXT .

Uso válido (implícito)

La función xrEndSpatialContainerRenderingEXT quita el contenedor espacial del conjunto de renderización activo.

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

Descripciones de los parámetros

Por lo general, las apps llaman a esta función en respuesta a un evento de cambio de visibilidad con XrEventDataSpatialContainerVisibleChangedEXT :: visible establecido en falso.

Si el contenedor espacial no está en el conjunto de renderización activo, el entorno de ejecución debe devolver XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT .

Si se llama a xrEndSpatialContainerRenderingEXT en un momento en el que la app no pudo llamar a xrWaitFrame (es decir, durante el período entre las llamadas a xrBeginFrame y xrEndFrame), el entorno de ejecución debe devolver XR_ERROR_CALL_ORDER_INVALID.

Uso válido (implícito)

Seguridad de subprocesos

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

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

La estructura XrSpatialContainerEndInfoEXT se usa para especificar los parámetros que finalizan la renderización de un contenedor espacial.

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

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.
  • spatialContainer es el XrSpatialContainerEXT para finalizar la renderización.

Uso válido (implícito)

Cómo ubicar vistas con xrLocateSpatialContainerViewsEXT

La función xrLocateSpatialContainerViewsEXT ubica vistas para un conjunto de contenedores espaciales.

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

Descripciones de los parámetros

Esta función reemplaza a xrLocateViews , lo que permite que una app consulte vistas de varios contenedores espaciales de forma simultánea.

Las vistas de todos los contenedores espaciales se devuelven en el único array views. Las vistas se ordenan según el índice del contenedor espacial en el array XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfos y, luego, el índice de vista de ese contenedor.

Por ejemplo, si una app proporciona tres contenedores espaciales en XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfos :

  • Índice 0: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO (1 vista)
  • Índice 1: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO (2 vistas)
  • Índice 2: XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO_WITH_FOVEATED_INSET (4 vistas)

Luego, el entorno de ejecución debe completar el array views con 7 vistas:

  • views [0] es la vista del contenedor 0.
  • views[1] es la vista del ojo izquierdo para el contenedor 1.
  • views[2] es la vista del ojo derecho para el contenedor 1.
  • views[3] es la vista del ojo izquierdo para el contenedor 2.
  • views[4] es la vista del ojo derecho para el contenedor 2.
  • views [5] es la vista de inserción del ojo izquierdo para el contenedor 2.
  • views [6] es la vista de inserción del ojo derecho para el contenedor 2.

Si viewCount no es igual a la suma de los recuentos de vistas para cada tipo de configuración de vista solicitada del contenedor espacial, el entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .

El entorno de ejecución puede reducir la configuración de la vista a un tipo con menos vistas para fines de optimización (p.ej., un contenedor está muy lejos y es pequeño, por lo que el estéreo es imperceptible). Si el entorno de ejecución degrada la configuración de la vista, debe devolver la cantidad original de vistas para ese contenedor y propagar las vistas adicionales con duplicados de las vistas degradadas. Por ejemplo, si XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO se reduce a XR_VIEW_CONFIGURATION_TYPE_PRIMARY_MONO , tanto el índice 0 como el índice 1 contendrán la vista mono única. Por lo tanto, la cantidad total de vistas que se devuelven en el array views es independiente de si el entorno de ejecución decidió disminuir o no las configuraciones de las vistas.

El entorno de ejecución debe adaptar cada XrView :: fov que se devuelva de modo que el tronco sea lo más pequeño posible y, al mismo tiempo, contenga todos los límites del contenedor espacial correspondiente. Los entornos de ejecución pueden mostrar FOV no simétricos, por ejemplo, si un contenedor espacial está en un ángulo oblicuo con respecto a la vista del usuario o si otro objeto lo oculta parcialmente. Los entornos de ejecución pueden posicionar libremente la superficie de renderización de destino para el contenedor espacial. Debido a la naturaleza de la renderización de varias apps, en la que los contenedores espaciales se separan del usuario, el entorno de ejecución puede devolver valores de XrView que no son adecuados para la renderización de píxeles. Por ejemplo, si el contenedor espacial no es visible en la pantalla, no hay valores válidos para establecer XrView :: fov. En esos casos, los entornos de ejecución deben establecer XrSpatialContainerViewStateEXT :: shouldSubmitLayers como falso.

El entorno de ejecución devuelve información adicional sobre el estado de renderización por contenedor espacial en el array viewStates. Si viewStateCount no es igual a XrSpatialContainerViewsLocateInfoEXT :: viewLocateInfoCount , el entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .

Después de que el entorno de ejecución ponga en cola un evento XrEventDataSpatialContainerClosedEXT para un contenedor espacial, esta función debe devolver XR_FALSE en XrSpatialContainerViewStateEXT :: shouldSubmitLayers y 0 en XrSpatialContainerViewStateEXT :: viewStateFlags para el contenedor espacial correspondiente.

En el caso de los contenedores espaciales con ubicaciones que cambian activamente en el mundo real, el entorno de ejecución debería tener en cuenta el movimiento del contenedor cuando se completa views para minimizar los artefactos de reproyección.

Si se llama a xrLocateSpatialContainerViewsEXT para uno o más contenedores espaciales que no están actualmente en el conjunto de renderización activo, el entorno de ejecución debe devolver XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_VIEW_CONFIGURATION_TYPE_UNSUPPORTED

La estructura XrSpatialContainerViewsLocateInfoEXT contiene los parámetros para ubicar vistas en una colección de contenedores espaciales.

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

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.
  • displayTime es el XrTime en el que se ubicarán las vistas.
  • viewLocateInfoCount es la cantidad de entradas en el array viewLocateInfos.
  • viewLocateInfos es un puntero a un array de estructuras XrSpatialContainerViewLocateInfoEXT.

Uso válido (implícito)

La estructura XrSpatialContainerViewLocateInfoEXT contiene los parámetros de un contenedor espacial individual para el que se ubicarán las vistas.

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

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.
  • viewConfigurationType es un XrViewConfigurationType que se usará para el contenedor espacial.
  • space es el XrSpace en el que se encuentran las vistas del contenedor espacial.
  • spatialContainer es el controlador XrSpatialContainerEXT.

La app puede proporcionar cualquier XrSpace válido en space. Sin embargo, se recomienda que proporcione el espacio del contenedor espacial para el XrSpatialContainerEXT correspondiente especificado dentro de la estructura XrSpatialContainerViewLocateInfoEXT.

Uso válido (implícito)

La estructura XrSpatialContainerViewStateEXT se propaga con llamadas a xrLocateSpatialContainerViewsEXT con información de idoneidad de renderización por contenedor espacial.

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

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.
  • viewStateFlags es una máscara de bits de XrViewStateFlags . Estas marcas tienen el mismo propósito que las viewStateFlags en la estructura principal de XrViewState.
  • viewConfigurationType es un XrViewConfigurationType que indica el tipo de configuración de vista que el entorno de ejecución usa para el contenedor espacial, que los entornos de ejecución pueden reducir a una configuración de vista con una cantidad de vistas inferior a la solicitada.
  • shouldSubmitLayers es un XrBool32 que devuelve el entorno de ejecución. Si es XR_FALSE, la app debería evitar enviar la composición para este contenedor espacial, ya que actualmente no es visible o se encuentra en un estado en el que no se requiere la renderización.
  • recommendedImageExtent es una estructura XrExtent2Di que representa la resolución recomendada para el contenedor espacial.

Al igual que con la ubicación de la vista principal de OpenXR, la app debe verificar XrSpatialContainerViewStateEXT :: viewStateFlags para asegurarse de que la posición y la orientación sean válidas y se les haga un seguimiento antes de usar los datos de la vista para la renderización.

La app debe verificar shouldSubmitLayers y viewConfigurationType para evitar renderizar más de lo que recomienda el entorno de ejecución. Cuando shouldSubmitLayers es falso, la app cambia su comportamiento de renderización de la siguiente manera:

  • La app no debe leer el XrView :: fov correspondiente.
  • La app no debe leer recommendedImageExtent .
  • La app debería evitar renderizar en cadenas de intercambio y enviar capas de composición para el contenedor espacial correspondiente.
  • La app debe establecer XrSpatialContainerLayerEXT :: retainPreviousSubmission en verdadero. Si la app decide enviar capas de todos modos, el entorno de ejecución determinará qué quiere hacer con ellas (p.ej., el entorno de ejecución puede optar por descartarlas).

recommendedImageExtent es explícitamente para las capas que se actualizarán según la posición del contenedor o la vista del usuario. Cuando se actualizan las capas con contenido que depende de la posición del contenedor espacial o de la vista del usuario (como el contenido 3D normal), la app debería renderizar en este viewport más pequeño en lugar del tamaño de vista recomendado predeterminado. Cuando se actualizan capas con contenido que no depende de la posición del contenedor espacial ni de la vista del usuario (como las capas de cuadrilátero estáticas), la app puede ignorar estos valores de forma segura. En el caso de las capas que dependen de la vista, recommendedImageExtent es una recomendación para la app desde el entorno de ejecución que tiene como objetivo minimizar el suavizado de líneas y mejorar el rendimiento de la renderización. La app puede enviar el contenido en resolución completa si lo desea.

XrExtent2Di :: width y XrExtent2Di :: height de recommendedImageExtent deben ser siempre un número entero positivo menor o igual que XrViewConfigurationView :: recommendedImageRectWidth y XrViewConfigurationView :: recommendedImageRectHeight de XrViewConfigurationView para la configuración de la vista principal del contenedor espacial. Una app no debería volver a crear una cadena de intercambio solo porque cambió recommendedImageExtent, ya que es una sugerencia dinámica para la app que especifica el XrSwapchainSubImage :: imageRect que se usará en el XrSwapchainSubImage de cualquier capa de composición de resolución completa que envíe, y puede cambiar cada fotograma.

Uso válido (implícito)

Ver el espacio de referencia

El espacio de referencia de la vista permanece sin cambios, ya que se encuentra en el núcleo de OpenXR. Al igual que en el núcleo, no está diseñada para usarse en la renderización.

Envía capas a través de xrEndFrame

Para renderizar contenedores espaciales, la app debe proporcionar una lista de capas asociadas con sus respectivos contenedores espaciales a xrEndFrame . Esto se logra a través de la estructura XrSpatialContainerLayerFrameEndInfoEXT.

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

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.
  • containerLayerCount es el recuento de elementos en el array containerLayers.
  • containerLayers es un puntero a un array de estructuras XrSpatialContainerLayerEXT.

El array containerLayers contiene un XrSpatialContainerLayerEXT para cada contenedor espacial en el conjunto de renderización activo (los contenedores administrados por sesión por xrBeginSpatialContainerRenderingEXT y xrEndSpatialContainerRenderingEXT). Cada XrSpatialContainerLayerEXT contiene una lista de punteros XrCompositionLayerBaseHeader asociados con el contenedor espacial determinado. Los entornos de ejecución pueden componer contenedores en cualquier orden que elijan, independientemente del orden de los containerLayers . Por ejemplo, los entornos de ejecución pueden componer contenedores según su profundidad en relación con el usuario, hacer que un contenedor espacial actúe como una capa de fondo o "fijar" un contenedor espacial para que siempre esté en la parte superior, independientemente de su profundidad. Los entornos de ejecución pueden componer capas con diferentes estrategias para los contenedores espaciales en modos limitados o envolventes. Por ejemplo, los entornos de ejecución pueden precomponer las capas de composición de cada contenedor espacial delimitado en una sola capa cuádruple estéreo que se combina con todos los demás contenedores en un segundo paso de composición.

XrFrameEndInfo :: displayTime y XrFrameEndInfo :: environmentBlendMode se aplicarán a todos los contenedores espaciales proporcionados en XrSpatialContainerLayerFrameEndInfoEXT .

Cuando esta estructura se pasa a xrEndFrame encadenándose a XrFrameEndInfo , se agregan los siguientes casos de error adicionales según el conjunto de renderización activo:

  • Si más de un elemento de containerLayers hace referencia a un contenedor espacial, los entornos de ejecución deben devolver XR_ERROR_SPATIAL_CONTAINER_DUPLICATE_EXT .
  • Si un elemento de containerLayers no hace referencia a un contenedor espacial en el conjunto de renderización activo, los entornos de ejecución deben devolver XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT .
  • Si un contenedor espacial al que hace referencia containerLayers no es miembro del conjunto de renderización activo, los entornos de ejecución deben devolver XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT .

Además, si hay contenedores espaciales en el conjunto de renderización activo y esta estructura no está encadenada a XrFrameEndInfo , los entornos de ejecución deben devolver XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT .

En cualquiera de los casos de error anteriores, el entorno de ejecución no debe renderizar ningún contenido para ningún contenedor espacial.

Si no hay contenedores espaciales en el conjunto de renderización activo, una app puede llamar a xrEndFrame siempre que no envíe ninguna capa de composición.

Ten en cuenta que las cadenas de intercambio individuales pueden enviarse para varios contenedores a través de capas en una estructura válida, p.ej., una capa cuádruple renderizada a través de una sola cadena de intercambio enviada a varios contenedores espaciales. Este caso se controla de manera uniforme con otras renderizaciones: el entorno de ejecución debe renderizar el cuadrilátero en todos esos contenedores espaciales.

Uso válido (implícito)

La estructura XrSpatialContainerLayerEXT agrupa las capas de composición estándar y las asocia con un contenedor espacial específico.

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

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.
  • spatialContainer es el XrSpatialContainerEXT que identifica el contenedor de destino.
  • retainPreviousSubmission es un XrBool32 . Si es XR_TRUE , el entorno de ejecución conservará el último fotograma enviado para este contenedor espacial.
  • layerCount es la cantidad de capas de composición en el array layers.
  • layers es un puntero a un array de punteros XrCompositionLayerBaseHeader.

Cuando retainPreviousSubmission es XR_TRUE , el entorno de ejecución debe volver a usar las capas de composición y el contenido de la imagen de la cadena de intercambio como se bloqueó durante la llamada a xrEndFrame más reciente en la que retainPreviousSubmission era XR_FALSE . Las modificaciones posteriores de las cadenas de intercambio que usen las capas retenidas no deben reflejarse en el resultado renderizado.

En el caso de las capas enviadas para un contenedor espacial individual (renderización dentro del contenedor), el entorno de ejecución debe seguir las reglas ya especificadas para el orden de composición de las capas. Es decir, las capas dentro de los contenedores deben dibujarse en el mismo orden en que se especifican, compuestas a través del algoritmo del pintor.

"Borrar" un contenedor espacial se refiere a quitar todo el contenido de un contenedor espacial, lo que hace que no se renderice nada para ese contenedor en el fotograma actual. Los entornos de ejecución deben tratar esto como equivalente a que la app envíe negro transparente (todos los bits en 0) para cada píxel dentro del contenedor. "Retener" un contenedor espacial se refiere a que el entorno de ejecución sigue mostrando el conjunto de capas enviado más recientemente para ese contenedor.

Para cada contenedor espacial, la app puede especificar si se deben enviar capas nuevas, conservar el envío anterior o borrar el contenedor espacial:

  • Para enviar capas nuevas, la app proporciona un layerCount que no es cero y un puntero layers válido.
  • Para borrar un contenedor espacial, el layerCount de su entrada debe ser 0 y retainPreviousSubmission debe ser XR_FALSE .
  • Para conservar las últimas capas enviadas y las imágenes de la cadena de intercambio (conservación), el layerCount de su entrada debe ser 0 y retainPreviousSubmission debe ser XR_TRUE .

Este control explícito por contenedor garantiza que el intent de la app se comunique con claridad en cada fotograma.

Si retainPreviousSubmission es XR_TRUE y layerCount no es 0, el entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .

Si XrSpatialContainerCompositionLayerViewConfigurationEXT no está encadenado a un XrCompositionLayerProjection que forma parte de un contenedor espacial, el entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE . Esta estructura solo se aplica a las capas XrCompositionLayerProjection. Si está encadenada a otros tipos de capas (p.ej., capas cuadradas o cilíndricas), el entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .

Uso válido (implícito)

Especifica la configuración de la vista para las capas de proyección

La estructura XrSpatialContainerCompositionLayerViewConfigurationEXT se usa para especificar la configuración de vista que se utiliza para renderizar una capa de proyección para un contenedor espacial.

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

Descripción del miembro

Cuando se envía un XrCompositionLayerProjection para un contenedor espacial, la app debe especificar qué configuración de vista se usó para renderizar la capa. Esto es necesario porque la app puede elegir cada fotograma si se renderiza con la configuración de vista principal del contenedor espacial o con la configuración de vista degradada sugerida del entorno de ejecución, si la hay.

Cuando se encadena XrSpatialContainerCompositionLayerViewConfigurationEXT, la app debe asegurarse de que XrCompositionLayerProjection :: viewCount sea un recuento de vistas válido para el XrViewConfigurationType especificado en la estructura encadenada. El viewConfigurationType especificado en la estructura encadenada debe ser el XrSpatialContainerBeginInfoEXT :: primaryViewConfigurationType especificado cuando se inició el contenedor, o el tipo de configuración de vista degradada que muestra el entorno de ejecución en XrSpatialContainerViewStateEXT , o bien valores adicionales habilitados a través de una extensión.

Uso válido (implícito)

Comportamiento de recorte de píxeles

Las apps deben informar al entorno de ejecución si renderizan píxeles fuera de los límites de un contenedor espacial o no encadenando XrSpatialContainerLayerVolumeClippingEXT cuando envían capas de composición.

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

Descripción del miembro

Esta estructura sirve como sugerencia para saber si la app renderiza píxeles fuera de los límites de un contenedor espacial. Cuando un contenedor espacial está en modo envolvente, debido a que los límites son infinitos, esta sugerencia no tiene sentido.

En el caso de los contenedores espaciales limitados que usan la renderización automática, el entorno de ejecución debe razonar sobre los límites de volumen 3D y los límites de píxeles 2D. Los límites del volumen 3D se devuelven desde xrGetSpatialContainerBoundsEXT . Los límites de píxeles en 2D son la proyección de los límites de volumen en 3D en cada pantalla del sistema.

Los entornos de ejecución deben descartar los píxeles de las imágenes de la cadena de intercambio que estén fuera de los límites de píxeles 2D. Sin embargo, los entornos de ejecución no deben descartar los píxeles que estén dentro de los límites de píxeles 2D, pero fuera de los límites de volumen 3D. Es posible que se produzcan efectos estéreo en los que el contenido parezca extenderse más allá o delante de los límites de volumen 3D del contenedor. Las apps pueden descartar píxeles fuera de los límites de volumen 3D de un contenedor espacial limitado para reducir las paradojas de profundidad y deben establecer volumeClipping en función de cómo lo hagan. Las paradojas de profundidad suelen causar fatiga ocular y molestias al usuario.

Los entornos de ejecución pueden usar volumeClipping para ajustar cómo muestran un contenedor espacial en particular. Por ejemplo, cuando se establece en XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT, un entorno de ejecución podría renderizar las caras posteriores de los límites del volumen 3D, lo que causaría paradojas de profundidad si el contenedor espacial dibujara píxeles detrás de los límites del volumen 3D del contenedor.

Las extensiones futuras pueden permitir el recorte en función de los límites del volumen 3D si se envía información de profundidad.

Uso válido (implícito)

Comandos nuevos

Estructuras nuevas

Nuevas constantes de enum

  • XR_EXT_SPATIAL_CONTAINER_SELF_RENDERING_EXTENSION_NAME
  • XR_EXT_spatial_container_self_rendering_SPEC_VERSION

  • Extiende XrResult :

    • XR_ERROR_SPATIAL_CONTAINER_DUPLICATE_EXT
    • XR_ERROR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINER_IS_RENDERING_EXT
    • XR_ERROR_SPATIAL_CONTAINER_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINER_NOT_RENDERING_EXT

  • Extiende XrSpatialContainerGraphicsPresentationEXT :

    • XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

  • Extiende XrStructureType :

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

Muestras de código

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

XrSession session; // previously initialized

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

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

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

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

// ... Frame Loop ...


XrTime displayTime; // returned from xrWaitFrame

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

CHK_XR(xrEndFrame(session, &frameEndInfo));

// ... End Frame Loop ...

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

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

Historial de versiones

  • Revisión 1, 6 de agosto de 2026 (Lachlan Ford)

    • Descripción inicial de la extensión