XR_EXT_spatial_container

Name String

XR_EXT_spatial_container

Type d'extension

Extension d'instance

Numéro d'extension enregistré

811

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

OpenXR 1.0

Date de dernière modification

2026-08-06

État de l'adresse IP

Aucune réclamation de propriété intellectuelle connue.

Participants

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

Présentation

Cette extension définit une nouvelle classe d'entités affichables, appelées "conteneurs spatiaux", qui sont analogues au concept de "fenêtres" dans les systèmes de fenêtrage 2D pour ordinateur.

Dans OpenXR 1.x, les applications ont un contrôle exclusif sur tout ce que l'utilisateur voit et sur la façon dont cela est superposé à l'environnement réel ou virtuel de l'utilisateur. Les environnements d'exécution n'apportent que de légères modifications à ce qui est affiché pour garantir la sécurité des utilisateurs. Ce modèle d'application est idéal pour plonger un utilisateur dans une expérience unique, mais il ne s'étend pas à plusieurs expériences simultanées. En particulier, dans les environnements de RA et de réalité mixte, les utilisateurs souhaitent souvent utiliser plusieurs applications différentes en même temps.

Les conteneurs spatiaux sont comme des fenêtres étendues à la 3D. L'utilisateur peut voir plusieurs conteneurs spatiaux simultanément et fournit des entrées à un sous-ensemble d'entre eux. Les conteneurs spatiaux visibles peuvent appartenir à différentes applications, et les environnements d'exécution gèrent leur taille et leur emplacement pour le compte de l'utilisateur.

Cette extension est compatible avec ces nouveaux types d'expériences spatialement limitées, en plus des expériences OpenXR immersives existantes. Les expériences OpenXR limitées peuvent comporter du contenu légèrement en 3D (panneaux plats avec de légers décalages de profondeur) ou des volumes hébergeant du contenu entièrement en 3D. Les expériences OpenXR immersives sont les applications immersives en plein écran existantes qui sont compatibles depuis OpenXR 1.0. Les applications peuvent basculer entre les deux types de contenus si elles le souhaitent.

Cette extension ne définit aucune méthode permettant à une application d'afficher son contenu. La façon de dessiner le contenu est définie dans d'autres extensions : XR_EXT_spatial_container_self_rendering .

Utiliser des conteneurs spatiaux

Un XrSpatialContainerEXT est un handle qui représente un conteneur spatial.

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

Une application commence à s'afficher via un conteneur spatial en procédant comme suit :

  1. Créez un conteneur spatial avec xrCreateSpatialContainerEXT .
  2. Modifiez n'importe quel état du conteneur pour la présentation initiale, comme son mode de limites.
  3. Demandez à l'environnement d'exécution d'afficher le conteneur avec xrRequestSpatialContainerVisibleEXT .
  4. Attendez que l'environnement d'exécution soit prêt à afficher le conteneur. Lorsque l'environnement d'exécution est prêt, il met en file d'attente un événement XrEventDataSpatialContainerVisibleChangedEXT avec visible défini sur XR_TRUE .
  5. Commencez l'affichage du conteneur spatial.

Pour supprimer un conteneur spatial :

  1. Demandez à l'environnement d'exécution de masquer le conteneur avec xrRequestSpatialContainerVisibleEXT .
  2. Attendez que l'environnement d'exécution ait fini de masquer le conteneur. Lorsque l'environnement d'exécution a complètement masqué le conteneur, il met en file d'attente un événement XrEventDataSpatialContainerVisibleChangedEXT avec visible défini sur XR_FALSE .
  3. Terminez l'affichage du conteneur spatial.
  4. Détruisez le conteneur avec xrDestroySpatialContainerEXT .

Remarque

Par défaut, cette extension délègue la gestion de la visibilité et de la sélection à des conteneurs spatiaux individuels. Étant donné que la session dans son ensemble ne représente plus un seul objet visible ou sélectionné, elle ne passe pas par la machine d'état OpenXR standard (READY, SYNCHRONIZED, VISIBLE, FOCUSED). Au lieu de cela, la session reste dans l'état XR_SESSION_STATE_IDLE pendant sa durée de vie active, et les règles de la section Modifications de l'état de la session spécifient comment les opérations OpenXR de base sont mappées à ce mode.

Créer un conteneur spatial

La fonction xrCreateSpatialContainerEXT crée un conteneur spatial.

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

Description des paramètres

  • session est l'XrSession qui crée le conteneur spatial.
  • createInfo est un pointeur vers un XrSpatialContainerCreateInfoEXT contenant les paramètres permettant de créer le conteneur spatial.
  • spatialContainer est un pointeur vers un handle dans lequel l'élément XrSpatialContainerEXT créé est renvoyé.

Un XrSpatialContainerEXT nouvellement créé doit être non visible, non interactif et en mode de limites XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT . Une application qui souhaite qu'un conteneur spatial démarre en mode immersif peut demander un mode de limites XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT avant de demander l'affichage d'un conteneur spatial.

Les environnements d'exécution doivent renvoyer XR_ERROR_VALIDATION_FAILURE si une dimension de XrSpatialContainerCreateInfoEXT :: suggestedBounds est négative, infinie ou n'est pas un nombre. Les environnements d'exécution doivent renvoyer XR_ERROR_LIMIT_REACHED si une application tente de créer plus de conteneurs spatiaux que ce qui est spécifié dans XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount . Si les conteneurs spatiaux n'ont pas été activés pour cette session , les environnements d'exécution doivent renvoyer XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT .

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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 est transmis à xrCreateSpatialContainerEXT pour créer un conteneur spatial.

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • graphicsPresentation est un XrSpatialContainerGraphicsPresentationEXT qui décrit comment ce conteneur spatial présente les graphismes.
  • suggestedBounds est un XrExtent3Df qui décrit les dimensions demandées du conteneur spatial en mètres.

Une application qui n'a pas de préférence pour sa taille peut définir suggestedBounds sur {0, 0, 0}. Un environnement d'exécution peut ignorer le suggestedBounds demandé.

Un environnement d'exécution qui permet de délimiter les conteneurs spatiaux par des formes autres que des boîtes orientées doit utiliser suggestedBounds comme cadre de délimitation autour des autres formes. Les cadres orientés sont destinés à être la forme de délimitation la plus courante.

Utilisation valide (implicite)

Lorsqu'un conteneur spatial n'est plus utilisable, les environnements d'exécution doivent mettre en file d'attente un événement XrEventDataSpatialContainerClosedEXT.

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • spatialContainer est le XrSpatialContainerEXT auquel cet événement est destiné.

La réception de l'événement XrEventDataSpatialContainerClosedEXT indique que l'environnement d'exécution ne peut plus afficher de conteneur spatial, par exemple parce que l'utilisateur a cliqué sur un bouton "Fermer" ou que la session est passée à l'état XR_SESSION_STATE_LOSS_PENDING.

Après avoir reçu l'événement XrEventDataSpatialContainerClosedEXT, une application doit cesser d'utiliser ce conteneur spatial, supprimer tout état associé tel qu'une boucle de rendu et détruire le conteneur. Les environnements d'exécution doivent renvoyer XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT pour toutes les fonctions opérant sur ce conteneur, à l'exception de xrDestroySpatialContainerEXT .

Si un conteneur spatial est visible lorsque l'environnement d'exécution met en file d'attente un événement de fermeture, les environnements d'exécution doivent d'abord rendre le conteneur invisible et mettre en file d'attente un événement XrEventDataSpatialContainerVisibleChangedEXT.

Utilisation valide (implicite)

La fonction xrDestroySpatialContainerEXT détruit un conteneur spatial existant.

XrResult xrDestroySpatialContainerEXT(
    XrSpatialContainerEXT                       spatialContainer);

Description des paramètres

Une fois qu'un conteneur spatial est détruit, les environnements d'exécution ne doivent plus afficher le contenu du conteneur et ne doivent pas mettre en file d'attente d'autres événements concernant le conteneur.

Une application ne doit pas détruire un conteneur spatial visible, car cela peut entraîner des artefacts graphiques. À la place, une application doit demander à masquer le conteneur spatial avec xrRequestSpatialContainerVisibleEXT, attendre un événement XrEventDataSpatialContainerVisibleChangedEXT, puis détruire le conteneur.

Utilisation valide (implicite)

Thread safety

  • L'accès à spatialContainer et à tous les handles enfants doit être synchronisé en externe.

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Espace du conteneur spatial

La fonction xrCreateSpatialContainerSpaceEXT crée un handle XrSpace pour l'espace de conteneur spatial d'un conteneur spatial spécifique.

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

Description des paramètres

L'espace du conteneur spatial pour un conteneur spatial donné est un système de coordonnées dont l'origine se trouve au centre des limites de ce conteneur spatial. Cet espace est généralement utilisé comme espace de base pour des fonctions telles que xrLocateSpace .

+X pointe vers la face droite du conteneur, +Y pointe vers la face supérieure du conteneur et +Z pointe vers la face avant du conteneur. Par exemple, si un conteneur est aligné sur la gravité, devant l'utilisateur, et que l'utilisateur se trouve dans la pose d'identité par rapport à l'espace LOCAL , les environnements d'exécution doivent orienter l'espace du conteneur avec l'orientation d'identité par rapport à l'espace LOCAL . Les environnements d'exécution peuvent définir la position d'un espace de conteneur par rapport à l'espace LOCAL sur n'importe quelle position arbitraire lorsque ce conteneur devient visible.

ext spatial container space convention

Figure 18. Convention des axes de l'espace du conteneur spatial

L'espace du conteneur spatial est une origine non verrouillée dans le monde. Les applications qui souhaitent une origine verrouillée sur le monde en mode immersif peuvent utiliser un espace verrouillé sur le monde tel que XR_REFERENCE_SPACE_TYPE_LOCAL .

Les environnements d'exécution peuvent modifier la pose d'un espace de conteneur spatial à tout moment, généralement pour permettre à un utilisateur de déplacer un conteneur spatial vers une autre position ou rotation. Les environnements d'exécution peuvent également modifier la pose lors de la transition entre les modes de limites XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT et XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT.

Un espace de conteneur spatial doit continuer à être un handle valide même si le conteneur spatial auquel il est destiné est détruit avec xrDestroySpatialContainerEXT . Lorsqu'un conteneur spatial n'est pas visible ou est détruit, l'espace du conteneur spatial doit être introuvable par rapport aux autres espaces. XrSpaceLocation :: locationFlags et XrViewState ::viewStateFlags seront définis sur 0.

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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 est utilisé avec xrCreateSpatialContainerSpaceEXT pour créer un handle XrSpace.

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • spatialContainer est un XrSpatialContainerEXT pour lequel créer un espace.

Utilisation valide (implicite)

Présenter un conteneur spatial

L'envoi du contenu d'un conteneur spatial à OpenXR pour affichage est géré par d'autres extensions : XR_EXT_spatial_container_self_rendering .

Pour permettre à d'autres extensions de spécifier la méthode de présentation graphique d'un conteneur spatial, cette extension définit l'énumération 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;

Description de l'enum

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

Le conteneur spatial utilise des couches de composition OpenXR (ajoutées par l'extension XR_EXT_spatial_container_self_rendering).

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT

Le conteneur spatial est créé pour les tests de conformité et ne comporte pas de chemin de rendu (ajouté par l'extension XR_EXT_spatial_container_conformance_automation).

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1

Le conteneur spatial utilise le rendu du système OpenXR (ajouté par l'extension XR_EXTX1_system_renderer)

État du conteneur spatial

L'état du conteneur spatial est géré par les environnements d'exécution en fonction des requêtes de l'application et des besoins de l'utilisateur. Par conséquent, chaque aspect de l'état du conteneur spatial documente les éléments suivants :

  • Lorsque les environnements d'exécution sont autorisés à modifier l'état du conteneur spatial. Pour la plupart des états de conteneur spatial, les environnements d'exécution peuvent modifier l'état à tout moment.
  • Comment une application demande des modifications de l'état. Les environnements d'exécution peuvent différer toute requête jusqu'à ce qu'ils estiment qu'elle est appropriée. Les environnements d'exécution ne mettent pas les événements en file d'attente lorsqu'une requête est différée. Les applications ne doivent donc pas attendre un tel événement pour une logique non liée.
  • Événements que les environnements d'exécution mettent en file d'attente lorsque l'état du conteneur spatial change. Les environnements d'exécution mettent en file d'attente les événements pour toutes les modifications, y compris celles demandées par l'application et celles initiées par l'environnement d'exécution. Les environnements d'exécution ne doivent pas mettre en file d'attente les événements de changement d'état qui n'indiquent pas de changement, par exemple si une application effectue deux requêtes pour masquer un conteneur à un intervalle très court.
  • File d'attente des environnements d'exécution d'événements lors du refus d'une demande de modification d'application. Les environnements d'exécution peuvent refuser une requête pour n'importe quelle raison, généralement en raison d'une règle système liée au maintien d'une expérience utilisateur de haute qualité.

La fonction xrGetSpatialContainerStateEXT interroge l'état actuel du conteneur spatial.

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

Description des paramètres

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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 est utilisé avec xrGetSpatialContainerStateEXT pour interroger un XrSpatialContainerStateEXT .

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.

Utilisation valide (implicite)

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • visible indique si un conteneur spatial est visible.
  • interactable indique si un conteneur spatial peut actuellement recevoir n'importe quel type d'entrée. Il est semblable au "focus" des systèmes de fenêtrage 2D pour ordinateur, à la différence que plusieurs conteneurs spatiaux peuvent être interactifs en même temps.
  • boundsMode est le XrSpatialContainerBoundsModeEXT actuel du conteneur spatial.

Les modifications apportées à l'état d'un conteneur spatial sont communiquées via des événements.

Événement "Champ modifié"

visible

XrEventDataSpatialContainerVisibleChangedEXT

interactable

XrEventDataSpatialContainerInteractableChangedEXT

boundsMode

XrEventDataSpatialContainerBoundsChangedEXT

Utilisation valide (implicite)

Visibilité

Les applications demandent à afficher ou à masquer un conteneur spatial avec xrRequestSpatialContainerVisibleEXT .

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

Description des paramètres

L'affichage ou le masquage d'un conteneur spatial est une opération asynchrone.

Les applications doivent demander à masquer un conteneur spatial avant de le détruire, ce qui permet aux environnements d'exécution d'afficher une transition fluide. Les environnements d'exécution doivent respecter les demandes de masquage d'un conteneur spatial.

Un environnement d'exécution peut refuser les requêtes d'affichage d'un conteneur spatial. Dans ce cas, l'environnement d'exécution doit mettre en file d'attente un événement XrEventDataSpatialContainerVisibleRequestDeniedEXT. Par exemple, certains environnements d'exécution refuseront une requête d'affichage d'un conteneur spatial que l'utilisateur a masqué en interagissant avec un bouton "Réduire" fourni par le système.

Les environnements d'exécution ne doivent pas afficher de conteneur spatial avant que l'application ne demande à l'afficher au moins une fois. Après la première demande de l'application d'afficher un conteneur spatial, les environnements d'exécution peuvent modifier la visibilité de ce conteneur spatial indépendamment des demandes de l'application. Cela permet à l'application de contrôler l'état initial et le contenu d'un conteneur spatial, et aux environnements d'exécution de fournir une UI système, comme une barre des tâches, qui permet à l'utilisateur de choisir les conteneurs spatiaux visibles.

Les environnements d'exécution doivent refuser les requêtes d'affichage d'un conteneur spatial dans un mode de limites non compatible en fonction de XrSystemSpatialContainerPropertiesEXT :: supportsBounded et XrSystemSpatialContainerPropertiesEXT :: supportsImmersive . Cela est possible lorsque le mode de limites par défaut, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT , n'est pas compatible avec un système donné.

Remarque

Sur certaines implémentations, l'affichage ou le masquage d'un conteneur spatial nécessite de communiquer avec les services système et peut être différé jusqu'à ce que l'utilisateur interagisse avec une boîte de dialogue système. La conception asynchrone pour demander des changements d'état de visibilité est destinée à donner aux environnements d'exécution le temps d'effectuer ces deux opérations.

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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 est utilisé avec xrRequestSpatialContainerVisibleEXT pour modifier la visibilité d'un conteneur spatial.

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • visible indique si un conteneur spatial doit être affiché ou masqué.

Utilisation valide (implicite)

Chaque fois qu'un environnement d'exécution modifie la visibilité d'un conteneur spatial, il doit mettre en file d'attente un événement XrEventDataSpatialContainerVisibleChangedEXT avec le nouvel état.

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • spatialContainer est le XrSpatialContainerEXT auquel cet événement est destiné.
  • visible est le nouvel état visible du conteneur spatial.

Cet événement remplace XR_SESSION_STATE_VISIBLE , ce qui permet d'avoir une valeur différente par conteneur. L'événement doit être mis en file d'attente pour toutes les modifications, y compris celles demandées par l'application et celles initiées par l'environnement d'exécution.

Un environnement d'exécution peut retarder l'affichage d'un conteneur de quelques images après avoir mis cet événement en file d'attente avec visible défini sur XR_TRUE pour éviter d'afficher un conteneur vide et laisser à l'application le temps d'envoyer son contenu initial. Pendant ce temps, XrSpatialContainerStateEXT ::visible sera XR_TRUE . Les environnements d'exécution ne doivent pas retarder l'affichage d'un conteneur de plus de 0,5 seconde.

Utilisation valide (implicite)

Chaque fois qu'un environnement d'exécution refuse une requête d'affichage d'un conteneur, il doit mettre en file d'attente un événement XrEventDataSpatialContainerVisibleRequestDeniedEXT.

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • spatialContainer est le XrSpatialContainerEXT auquel cet événement est destiné.

Utilisation valide (implicite)

Interactable

Une application ne peut pas demander qu'un conteneur spatial soit interactif. Les environnements d'exécution contrôlent entièrement les conteneurs spatiaux avec lesquels il est possible d'interagir. Un conteneur spatial interactif doit également être visible.

Chaque fois qu'un environnement d'exécution modifie l'état d'interaction d'un conteneur spatial, il doit mettre en file d'attente un événement XrEventDataSpatialContainerInteractableChangedEXT avec le nouvel état.

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • spatialContainer est le XrSpatialContainerEXT auquel cet événement est destiné.
  • interactable est le nouvel état d'interaction du conteneur spatial.

Cet événement remplace XR_SESSION_STATE_FOCUSED , ce qui permet d'avoir une valeur différente par conteneur. L'événement est mis en file d'attente pour toutes les modifications, y compris celles initiées par l'environnement d'exécution.

Les environnements d'exécution peuvent activer ou désactiver l'interaction avec un conteneur spatial à tout moment. Si un environnement d'exécution n'accepte qu'un seul conteneur spatial interactif à la fois, lorsqu'il modifie le conteneur spatial interactif, il doit mettre en file d'attente l'événement pour le conteneur spatial qui cesse d'être interactif ( interactable défini sur "false") avant l'événement pour le conteneur qui commence à être interactif ( interactable défini sur "true").

Utilisation valide (implicite)

Limites

Un conteneur spatial possède un mode de limites et un cadre de délimitation. Le mode de limites d'un conteneur spatial décrit le comportement des limites. Son cadre de délimitation est l'élément dans lequel le conteneur spatial dessine.

L'énumération XrSpatialContainerBoundsModeEXT identifie les différents modes dans lesquels les limites d'un conteneur spatial peuvent se trouver.

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;

Description de l'enum

XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT

Le conteneur spatial est limité. Les limites sont un cadre fini. Le conteneur spatial n'apparaîtra que dans cette région.

XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT

Le conteneur spatial est immersif et n'a pas de limites. Le conteneur spatial s'affiche sur tout l'écran.

Les conteneurs spatiaux en mode de limites XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT sont soumis à des exigences supplémentaires :

  • Les environnements d'exécution doivent traiter ces conteneurs spatiaux de la même manière qu'une application immersive en plein écran créée sans conteneur spatial, à l'exception des changements de comportement décrits dans Modifications de l'état de la session .
  • Les environnements d'exécution peuvent fournir des extensions supplémentaires qui permettent aux conteneurs spatiaux immersifs de se comporter différemment des applications plein écran et immersives créées sans cette extension.
  • Les environnements d'exécution doivent signaler des limites infinies pour ces conteneurs spatiaux.
  • Les environnements d'exécution peuvent masquer d'autres conteneurs spatiaux lorsqu'un conteneur spatial immersif est visible. Comme cela peut varier d'un environnement d'exécution à l'autre, les applications ne doivent pas compter sur l'affichage ou le masquage automatique des conteneurs spatiaux en fonction de la visibilité des conteneurs spatiaux immersifs. Comme pour toutes les autres transitions d'état visibles, les environnements d'exécution doivent mettre en file d'attente un événement XrEventDataSpatialContainerVisibleChangedEXT lorsqu'un conteneur spatial est masqué, car un conteneur immersif est visible.

Remarque

Les exigences ci-dessus impliquent que tous les environnements d'exécution peuvent implémenter le chemin d'accès OpenXR 1.x sans cette extension en créant implicitement un conteneur spatial, en définissant le mode de limites du conteneur sur immersif et en demandant qu'il soit visible.

Les applications demandent à modifier le mode de limites d'un conteneur spatial avec xrRequestSpatialContainerBoundsModeEXT .

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

Description des paramètres

La modification du mode de limites d'un conteneur spatial est une opération asynchrone, et les environnements d'exécution peuvent mettre en file d'attente un événement de modification ou de refus plusieurs secondes après que l'application a demandé une modification. Cela permet aux environnements d'exécution d'afficher l'interface utilisateur nécessaire pour permettre à un utilisateur d'accéder en toute sécurité à un mode immersif.

Les environnements d'exécution doivent honorer une requête de modification du mode de limites pour un conteneur spatial non visible. Si un environnement d'exécution refuse une requête de mode de limites pour un conteneur non visible, il peut rejeter ou différer une requête d'affichage d'un tel conteneur spatial. Cela permet aux applications de démarrer un conteneur en tant que conteneur immersif. Un environnement d'exécution peut refuser les requêtes de modification du mode de limites d'un conteneur spatial visible. Dans ce cas, l'environnement d'exécution doit mettre en file d'attente un événement XrEventDataSpatialContainerBoundsModeRequestDeniedEXT. Par exemple, certains environnements d'exécution refuseront une requête visant à modifier le mode de limites d'un conteneur spatial visible avec lequel l'utilisateur n'interagit pas activement.

Les environnements d'exécution doivent renvoyer XR_ERROR_VALIDATION_FAILURE si une application demande un mode de limites non compatible en fonction de XrSystemSpatialContainerPropertiesEXT :: supportsBounded et XrSystemSpatialContainerPropertiesEXT :: supportsImmersive .

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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 est utilisé avec xrRequestSpatialContainerBoundsModeEXT pour modifier le mode de limites d'un conteneur spatial.

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • boundsMode est le XrSpatialContainerBoundsModeEXT souhaité pour le conteneur spatial.

Utilisation valide (implicite)

Chaque fois qu'un environnement d'exécution modifie les limites ou le mode de limites d'un conteneur spatial, il doit mettre en file d'attente un événement XrEventDataSpatialContainerBoundsChangedEXT avec les nouvelles informations de limites.

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • spatialContainer est le XrSpatialContainerEXT auquel cet événement est destiné.
  • bounds correspond aux nouvelles largeur, hauteur et profondeur des limites du conteneur spatial.
  • infiniteBounds est défini sur "true" si le conteneur a des limites infinies.
  • boundsMode est le nouveau XrSpatialContainerBoundsModeEXT du conteneur spatial.

L'événement est mis en file d'attente pour toutes les modifications, y compris celles demandées par l'application et celles initiées par l'environnement d'exécution.

Lorsqu'un utilisateur redimensionne un conteneur spatial de manière interactive, les environnements d'exécution doivent se comporter de l'une des manières suivantes :

  • mettre en file d'attente de nombreux événements, probablement à la fréquence d'images, lorsque l'utilisateur redimensionne le conteneur spatial
  • mettre en file d'attente un seul événement à la fin du redimensionnement

Si un environnement d'exécution ne met en file d'attente qu'un seul événement à la fin du redimensionnement, cet environnement d'exécution doit continuer à signaler les anciennes limites de xrGetSpatialContainerBoundsEXT jusqu'à ce qu'il mette en file d'attente un événement de redimensionnement. Les environnements d'exécution doivent fusionner plusieurs événements de modification des limites non interrogés. En d'autres termes, si les limites ou le mode de limites changent alors qu'un événement XrEventDataSpatialContainerBoundsChangedEXT est toujours en file d'attente, les environnements d'exécution doivent ne signaler qu'un seul événement contenant la dernière modification de limites qui s'est produite. Étant donné que les applications peuvent également interroger directement les limites d'un conteneur spatial avec xrGetSpatialContainerBoundsEXT, le nombre de modifications de limites à partir d'événements peut être différent du nombre de modifications à partir de l'interrogation en fonction du moment où les modifications de limites générées par l'environnement d'exécution, les appels d'application à xrPollEvent et les appels d'application à xrGetSpatialContainerBoundsEXT sont effectués.

Lorsque les limites d'un conteneur spatial changent, l'origine locale du conteneur spatial peut également changer. Par exemple, si un environnement d'exécution permet à un utilisateur de redimensionner les limites du conteneur spatial en faisant glisser l'un de ses bords, les limites et l'origine locale de ce conteneur changeront lorsque l'utilisateur fera glisser un seul bord. Dans ce cas, l'environnement d'exécution doit modifier simultanément les limites et l'origine locale.

Les environnements d'exécution doivent définir infiniteBounds sur XR_TRUE, et définir la largeur, la hauteur et la profondeur sur 0,0 pour représenter des limites infinies. Les environnements d'exécution doivent définir infiniteBounds sur XR_FALSE, et définir la largeur, la hauteur et la profondeur sur des nombres positifs finis pour les limites finies.

Les environnements d'exécution doivent définir bounds et infiniteBounds en suivant les mêmes règles que pour XrSpatialContainerBoundsEXT .

Utilisation valide (implicite)

Chaque fois qu'un environnement d'exécution refuse une demande de modification du mode de limites d'un conteneur, il doit mettre en file d'attente un événement XrEventDataSpatialContainerBoundsModeRequestDeniedEXT.

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • spatialContainer est le XrSpatialContainerEXT auquel cet événement est destiné.

Utilisation valide (implicite)

La structure XrSpatialContainerBoundsEXT décrit le cadre de délimitation d'un conteneur spatial.

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • bounds correspond à la largeur, à la hauteur et à la profondeur des limites du conteneur spatial. Les limites sont exprimées en mètres.
  • infiniteBounds est défini sur "true" si le conteneur a des limites infinies.

Les environnements d'exécution doivent définir infiniteBounds sur XR_TRUE, et définir la largeur, la hauteur et la profondeur sur 0,0 pour représenter des limites infinies. Les environnements d'exécution doivent définir infiniteBounds sur XR_FALSE, et définir la largeur, la hauteur et la profondeur sur des nombres positifs finis pour les limites finies.

Utilisation valide (implicite)

La fonction xrGetSpatialContainerBoundsEXT interroge les limites actuelles d'un conteneur spatial.

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

Description des paramètres

Un conteneur spatial limité ne doit pas avoir de limites infinies, tandis qu'un conteneur spatial immersif doit avoir des limites infinies.

Les environnements d'exécution peuvent modifier les limites d'un conteneur spatial en n'importe quelle valeur finie positive à tout moment lorsque le conteneur spatial est limité. Les modifications apportées aux limites d'un conteneur spatial sont communiquées via XrEventDataSpatialContainerBoundsChangedEXT .

Avec cette extension, une application ne peut pas demander de modifications des limites, sauf pour passer d'un mode limité à un mode immersif avec xrRequestSpatialContainerBoundsModeEXT . D'autres extensions pourraient proposer une telle solution à l'avenir.

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • 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 structure XrSpatialContainerBoundsGetInfoEXT est une structure d'entrée qui existe à des fins d'extension future.

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.

Utilisation valide (implicite)

L'énumération XrSpatialContainerVolumeClippingEXT identifie différents comportements de découpage de volume pour un conteneur spatial.

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;

Description de l'enum

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT

Aucun contenu n'est découpé selon le volume de délimitation du conteneur spatial. Le contenu peut s'afficher en dehors des limites du conteneur spatial.

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT

Le contenu est strictement limité au volume de délimitation du conteneur spatial.

Cette énumération n'est pas utilisée dans cette extension. Il est défini pour permettre à d'autres extensions de spécifier le comportement de coupure de volume souhaité. Par exemple, une application peut vouloir dessiner un arrière-plan pour un conteneur spatial délimité. Un cubemap monoculaire est un moyen pratique de spécifier un arrière-plan. Toutefois, un cubemap monoculaire est conceptuellement positionné à l'infini, ce qui se trouve en dehors du conteneur.

Fonctionnalités du système

Une application peut inspecter les fonctionnalités du système en associant une structure XrSystemSpatialContainerPropertiesEXT à XrSystemProperties lors de l'appel de xrGetSystemProperties .

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

Description du membre

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
  • maxSpatialContainerCount est le nombre maximal de conteneurs spatiaux pouvant être créés.
  • supportsBounded est défini sur "true" si les conteneurs spatiaux peuvent être limités.
  • supportsImmersive est défini sur "true" si les conteneurs spatiaux sont autorisés à être immersifs.

Les environnements d'exécution compatibles avec cette extension devraient permettre à une application de créer de nombreux conteneurs spatiaux, limités uniquement par l'allocation de mémoire. Un environnement d'exécution peut avoir une limite différente pour le nombre de conteneurs spatiaux affichés simultanément. Il n'est pas possible d'interroger le nombre de conteneurs affichés simultanément dans cette extension, car un environnement d'exécution peut limiter les applications individuelles en fonction de l'état de toutes les applications en cours d'exécution. L'hypothèse est que les appareils très limités et les appareils moins limités auront des limites différentes pour le nombre de conteneurs affichés simultanément. Les appareils très limités peuvent n'accepter qu'un seul conteneur spatial affiché à la fois, et les appareils moins limités peuvent accepter un grand nombre de conteneurs spatiaux affichés simultanément, sous réserve des limites de calcul de rendu.

Les environnements d'exécution compatibles avec cette extension doivent prendre en charge au moins l'un des conteneurs spatiaux limités ou immersifs.

Utilisation valide (implicite)

La fonction xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT renvoie les méthodes de présentation graphique compatibles avec un système.

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

Description des paramètres

  • instance est l'XrInstance à partir de laquelle systemId a été récupéré.
  • systemId est l'élément XrSystemId interrogé.
  • graphicsPresentationCapacityInput est la capacité du tableau graphicsPresentations, ou 0 pour indiquer une requête de récupération de la capacité requise.
  • graphicsPresentationCountOutput est un pointeur vers le nombre de présentations graphiques écrites, ou un pointeur vers la capacité requise si graphicsPresentationCapacityInput est égal à 0.
  • graphicsPresentations est un pointeur vers un tableau de valeurs XrSpatialContainerGraphicsPresentationEXT, mais peut être nul si graphicsPresentationCapacityInput est égal à 0.
  • Consultez la section Paramètres de taille de la mémoire tampon pour obtenir une description détaillée de la récupération de la taille graphicsPresentations requise.

Les environnements d'exécution doivent toujours renvoyer un contenu de tampon identique à partir de cette énumération pour l'ID système donné et pendant la durée de vie de l'instance.

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • 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

Modifications apportées à l'état de la session

La compatibilité avec les conteneurs spatiaux est activée pour une session en associant un XrSessionCreateInfoSpatialContainersEXT lors de l'appel de xrCreateSession .

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

Lorsque la compatibilité avec les conteneurs spatiaux est activée, une XrSession se comporte différemment. En effet, lorsque vous utilisez des conteneurs spatiaux, la session ne présente plus le contenu de l'image sur les écrans. Ce sont les conteneurs spatiaux qui s'en chargent. Par conséquent, lorsque cette extension est activée, une session est effectivement "sans interface graphique". Contrairement aux autres extensions headless, les applications peuvent envoyer des données d'image via les conteneurs spatiaux.

L'activation de la compatibilité avec les conteneurs spatiaux modifie les API OpenXR de base de la manière suivante.

runtime: losing system or device

runtime: losing system or device

xrDestroySession

xrDestroySession

IDLE
(en cours d'exécution)

IDLE...

xrGetSystem
xrCreateSession

xrGetSystem...

xrCreateInstance

xrCreateIn...

xrDestroySession

xrDestroySession

LOSS_PENDING
(inactif)

LOSS_PENDING...

xrDestroyInstance

xrDestroyInstance

app : relancer XR (facultatif)

app : éventuellement...

Figure 19 : Machine à états de la nouvelle session

  • La session n'entre jamais dans les états XR_SESSION_STATE_VISIBLE, XR_SESSION_STATE_FOCUSED ou XR_SESSION_STATE_EXITING . Les environnements d'exécution ne doivent jamais mettre en file d'attente des événements pour ces états. Ces états sont remplacés par les événements par conteneur spatial XrEventDataSpatialContainerVisibleChangedEXT, XrEventDataSpatialContainerInteractableChangedEXT et XrEventDataSpatialContainerClosedEXT, respectivement.
  • La session n'entre jamais non plus dans les états XR_SESSION_STATE_READY, XR_SESSION_STATE_SYNCHRONIZED ou XR_SESSION_STATE_STOPPING . Les environnements d'exécution ne doivent jamais mettre en file d'attente des événements pour ces états. Il n'existe aucun remplacement pour ces états.
  • Les environnements d'exécution doivent traiter la session comme étant en cours d'exécution lorsqu'elle est à l'état XR_SESSION_STATE_IDLE .
  • Les environnements d'exécution doivent traiter la session comme étant active lorsqu'elle est à l'état XR_SESSION_STATE_IDLE et qu'au moins un conteneur spatial interactif existe.
  • Les fonctions xrBeginSession et xrEndSession ne sont plus nécessaires. Les environnements d'exécution doivent renvoyer XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT lorsque ces fonctions sont appelées. D'autres extensions peuvent fournir des remplacements pour ces fonctions.
  • La fonction xrRequestExitSession n'est plus nécessaire non plus. Les environnements d'exécution doivent renvoyer XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT lorsque cette fonction est appelée. Les applications qui souhaitent quitter une session en cours peuvent appeler xrRequestSpatialContainerVisibleEXT pour masquer leurs conteneurs, puis détruire la session une fois que tous les conteneurs ne sont plus visibles.

  • Les extensions qui mettaient en file d'attente des événements supplémentaires au démarrage de l'exécution de la session doivent désormais mettre ces événements en file d'attente après la création de la session. Ces extensions sont indiquées ci-dessous.

    Événement d'extension

XR_EXT_user_presence

XrEventDataUserPresenceChangedEXT

XR_META_boundary_visibility

XrEventDataBoundaryVisibilityChangedMETA

  • La fonction xrLocateViews n'est pas valide pour l'appel de la session. Les environnements d'exécution doivent renvoyer XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT à partir de xrLocateViews . D'autres extensions peuvent fournir des moyens de localiser les vues d'un conteneur spatial particulier.
  • La fonction xrWaitFrame doit toujours définir XrFrameState :: shouldRender sur "false". D'autres extensions peuvent fournir des moyens de savoir si un conteneur spatial particulier doit mettre à jour ses couches de composition.
  • La fonction xrEndFrame n'est pas un moyen valide d'envoyer des couches de composition. Si une application définit XrFrameEndInfo :: layerCount sur une valeur non nulle, les environnements d'exécution doivent renvoyer XR_ERROR_VALIDATION_FAILURE . D'autres extensions peuvent fournir des moyens d'envoyer des couches de composition pour un conteneur spatial particulier.
  • L'activation de l'état XR_SESSION_STATE_LOSS_PENDING ferme également tous les conteneurs spatiaux. Les environnements d'exécution doivent mettre en file d'attente un événement XrEventDataSpatialContainerClosedEXT pour chaque conteneur spatial actif avant de mettre en file d'attente un changement d'état de session pour XR_SESSION_STATE_LOSS_PENDING .
  • La fonction xrCreateSession n'a plus besoin d'une structure de liaison d'API graphique. D'autres extensions peuvent nécessiter une liaison graphique, par exemple pour qu'un conteneur spatial s'affiche à l'aide d'une API graphique.

Le comportement ci-dessus est légèrement différent de celui de XR_MND_headless . Les environnements d'exécution ne doivent pas activer le comportement de session sans interface graphique de XR_MND_headless lorsque la compatibilité avec les conteneurs spatiaux est activée pour cette session.

Remarque

Lorsque les conteneurs spatiaux sont activés, une session ne passe que par deux états : XR_SESSION_STATE_IDLE (en cours d'exécution) et XR_SESSION_STATE_LOSS_PENDING (pas en cours d'exécution). Par conséquent, les environnements d'exécution ne renvoient plus XR_ERROR_SESSION_RUNNING ni XR_ERROR_SESSION_NOT_RUNNING . Au lieu de cela, lorsqu'une session n'est pas en cours d'exécution, les environnements d'exécution renvoient XR_ERROR_SESSION_LOST ou XR_SESSION_LOSS_PENDING en suivant les règles du noyau OpenXR. De plus, xrBeginSession , la seule fonction qui renvoie XR_ERROR_SESSION_RUNNING , renverra désormais toujours XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT .

Utilisation valide (implicite)

Entrées du fichier manifeste Android

Les environnements d'exécution basés sur l'AOSP peuvent avoir un comportement personnalisé en fonction de l'état initial du conteneur spatial, qui est démarré avant l'exécution du code de l'application. Par exemple, un environnement d'exécution peut modifier les ressources allouées à l'activité, lancer des animations ou afficher un écran de démarrage. Les propriétés suivantes sont fournies à cette fin. Ils remplacent la balise <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />, que les applications basées sur des conteneurs spatiaux ne doivent pas spécifier, sauf pour assurer la compatibilité avec les environnements d'exécution basés sur l'AOSP antérieurs.

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

Cette propriété indique aux environnements d'exécution les modes de limites utilisés par une activité. Par défaut, il s'agit d'une liste vide, ce qui implique qu'il n'y a pas d'indice.

Les chaînes suivantes sont valides pour cet attribut. Plusieurs valeurs sont séparées par | (par exemple, "bounded|immersive").

Valeur

Description

"2d_panel"

L'activité s'affiche à l'aide du framework de vue 2D d'Android.

"bounded"

L'activité utilise XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT .

"immersive"

L'activité utilise 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" />

Cette propriété indique aux environnements d'exécution le XrSpatialContainerBoundsModeEXT initial de l'activité lors de sa création. Par défaut, il s'agit de la chaîne XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED, ce qui signifie qu'aucune indication n'est fournie.

Les environnements d'exécution ne doivent pas exiger que les applications disposent de ces propriétés pour se comporter conformément à cette spécification. Les environnements d'exécution ne doivent pas modifier le comportement visible de l'application en fonction de ces propriétés. Toutes ces métadonnées doivent pouvoir être spécifiées au niveau <activity> ou <application>. S'il est spécifié au niveau <application>, il s'applique à toutes les activités de l'application qui ne spécifient pas leurs propres valeurs.

Exemple de code

Le code suivant montre comment utiliser cette extension pour les cas d'utilisation de perception uniquement, sans aucun rendu.

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

Nouveaux types d'objets

Nouvelles commandes

Nouvelles structures

Nouvelles énumérations

Nouvelles constantes d'énumération

  • XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME
  • XR_EXT_spatial_container_SPEC_VERSION

  • Extension de XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTAINER_EXT

  • Extension de 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

  • Extension de 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

Problèmes

  • Comment gérer plusieurs requêtes visibles en attente ? L'application doit-elle recevoir un seul changement/refus ou plusieurs ? La réponse peut être différente si les appels sont répartis sur plusieurs frames. La réponse peut également être différente si les requêtes multiples n'ont aucun effet (par exemple, demander qu'un conteneur spatial soit visible, puis non visible pour un conteneur qui n'est pas visible au départ).

    • Résolu. Différents choix pour les événements de modification et les événements refusés. Les requêtes Noop ne mettent pas en file d'attente un événement de modification. Elles ne font que générer du bruit pour le développeur d'applications et sont faciles à filtrer pour les environnements d'exécution. Si plusieurs requêtes visibles sont refusées, les environnements d'exécution doivent générer un événement de refus correspondant pour chacune d'elles.

  • Comment une extension d'automatisation de la conformité doit-elle être définie pour que tout le texte de spécification facultatif pour les comportements des règles puisse toujours être testé par CTS ?

    • Résolu. Extension de test distincte. Un environnement d'exécution d'extension de test sera implémenté pour CTS uniquement, ce qui permettra à CTS de contrôler l'ensemble des règles système.

  • Avons-nous besoin d'un événement lorsque la position d'un conteneur spatial change ?

    • Résolu. Non. L'espace du conteneur spatial n'est pas verrouillé par rapport au monde, et d'autres espaces de ce type, comme XR_REFERENCE_SPACE_TYPE_VIEW, ne comportent pas d'événements lorsqu'ils changent.

  • Comment fonctionne xrSyncActions s'il existe plusieurs conteneurs spatiaux ?

    • Résolu. Aucune modification n'est nécessaire. xrSyncActions s'appliquerait à tous les conteneurs spatiaux de la session. Si une application souhaite diriger les actions de saisie vers un conteneur spatial particulier, elle peut examiner l'état interactif par conteneur pour choisir les conteneurs qui sont des cibles valides. Si une application souhaite synchroniser uniquement l'état de l'action d'entrée pour un seul conteneur spatial, une extension supplémentaire est nécessaire. Toutefois, nous prévoyons de nous concentrer plutôt sur une extension qui permet aux applications d'être entièrement basées sur des événements et d'éviter d'avoir à appeler xrSyncActions dans une boucle de frame.

  • Comment les applications peu fréquemment mises à jour gèrent-elles les entrées ?

    • Résolu. Aucune modification n'est nécessaire. Bien qu'elle soit utile pour EXT_spatial_container, elle l'est également en dehors des conteneurs spatiaux. Cela peut être géré via une extension de canal d'événement et fonctionner dans les deux cas. Pour les conteneurs spatiaux, nous ajouterons d'autres moyens de filtrer les événements pour un seul conteneur spatial.

  • Doit-on attendre pour limiter/contrôler le timing de la boucle d'entrée pour les applications avec des boucles d'entrée et de rendu dissociées ?

    • Résolu. Aucune modification n'est nécessaire. Cela devrait être géré via le canal d'événement et les extensions de requête actuelles. L'extension de requête Present permet d'effectuer un rendu basé sur des événements et dissocié d'une boucle de frame.

  • Un conteneur spatial peut-il obtenir sa pose par rapport à d'autres conteneurs spatiaux ? Points clés à prendre en compte : avons-nous un cas d'utilisation pour cela ? Si oui, comment les espaces de conteneur spatial se connectent-ils à LOCAL ?

    • Résolu. Oui. C'est déjà possible pour les conteneurs spatiaux d'une même session en passant par XR_REFERENCE_SPACE_TYPE_VIEW, et il est souhaitable de prendre en charge le contenu dépendant de la vue. Pour partager des positions de conteneurs spatiaux entre les sessions (par exemple, vers un autre processus), la méthode attendue consiste à exploiter XR_EXT_spatial_anchor et ses modèles de persistance et de partage existants.

  • L'espace d'un conteneur spatial est-il localisable s'il n'est pas visible ?

    • Résolu. Non. L'espace du conteneur spatial n'est pas localisable lorsque le conteneur spatial n'est pas visible. Cela implique qu'il n'y a pas de son spatialisé et que l'application ne peut pas "précharger" le contenu dépendant de la vue lorsque le spatial_container n'est pas visible. Ces deux options sont acceptables, car lorsqu'un conteneur spatial n'est pas visible, l'application est censée arrêter toute charge CPU/GPU utilisée pour ce conteneur spatial.

  • Où l'espace du conteneur spatial doit-il être placé dans le conteneur spatial ? Les suggestions ont été le centre ou le point minimal (minX, minY, minZ).

    • Résolu. Au centre. Il n'y a pas d'emplacement qui ne se déplace pas de la plupart des manières dont une UX de redimensionnement de conteneur spatial est censée se déplacer (bords mobiles). "Center" est couramment utilisé dans d'autres parties d'OpenXR. Nous ne nous sommes pas alignés sur les fenêtres de l'informatique 2D, qui utilisent la coordonnée minimale, car les visionneuses de modèles 3D ne suivent souvent pas cette convention.

  • Quand un environnement d'exécution doit-il créer des ressources sous-jacentes au conteneur spatial ? Cela implique parfois une communication interprocessus avec les services système.

    • Résolu. De manière synchrone dans le cadre de xrCreateSpatialContainerEXT . Bien qu'il puisse y avoir des communications interprocessus, la création d'un conteneur est généralement peu coûteuse. Certains fournisseurs disposent de mutex globaux pour la gestion des conteneurs, mais ils ne devraient pas entraîner de longs temps d'attente. Les problèmes de conflit de mutex sont des bugs spécifiques au fournisseur qui doivent être résolus par chaque fournisseur.

  • Avons-nous besoin d'un signal indiquant qu'une XrSession va créer des conteneurs spatiaux et ne sera donc pas compatible avec l'ancien chemin de rendu ?

    • Résolu. Oui. Nous modifions fondamentalement la machine d'état de la session.

Historique des versions

  • Révision 1, 06/08/2026 (Jared Finder, Google)

    • Description initiale de l'extension