XR_EXT_spatial_entity

Chaîne de nom

XR_EXT_spatial_entity

Type d'extension

Extension d'instance

Numéro d'extension enregistré

741

Révision

1

État de ratification

Ratifié

Dépendances des extensions et des versions

XR_EXT_future

Participants

Nihav Jain, Google
Jared Finder, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Karthik Kadappan, Magic Leap
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Présentation

Cette extension présente les concepts et les bases de la compréhension des scènes et du raisonnement spatial dans OpenXR. Cela unifie plusieurs domaines de fonctionnalités distincts, mais connexes, qui sont énumérés, configurés et avec lesquels il est possible d'interagir de manière largement uniforme, comme défini par cette extension. Comme cette extension ne comporte pas de définitions concrètes pour aucun de ces domaines fonctionnels, le texte de la spécification formelle a tendance à être quelque peu abstrait. Les exemples inclus dans le texte de spécification de cette extension font parfois référence à des fonctionnalités définies dans une extension associée à venir ou hypothétique à des fins d'illustration, sans limiter ni spécifier intrinsèquement ces fonctionnalités supplémentaires.

Voici les principaux éléments de cette extension :

  • Entités spatiales : la fonctionnalité est axée sur les entités , qui offrent très peu de fonctionnalités en elles-mêmes.
  • Composants spatiaux : ces entités sont associées à des composants qui fournissent des données et des comportements.
  • Types de composants spatiaux : chaque composant spatial est d'un type de composant spécifique , et une entité donnée ne peut comporter qu'un seul composant d'un type de composant donné .
  • Contexte spatial : toutes les interactions avec des entités spatiales se produisent dans un contexte après une phase d'initialisation et de configuration.
  • Capacités spatiales : la manipulation des entités spatiales est largement assurée par les capacités . Une capacité est une unité de fonctionnalité, par exemple (sans s'y limiter) les ancres définies par l'application, la détection de plans ou le suivi d'images. Chaque capacité est généralement définie dans une extension distincte (activée lors de la création de l'instance comme d'habitude) et est activée pour un contexte spécifique au moment de la création.
  • Chaque capacité est associée à un ensemble de types de composants pour lesquels des composants sont présents sur chaque entité exposée par cette capacité . L'extension définissant une fonctionnalité spécifie les types de composants obligatoires pour la fonctionnalité ("garantis"), tandis que cette même extension ou d'autres peuvent spécifier les types de composants facultatifs fournis par certaines implémentations potentielles. Un nombre quelconque de capacités peut fournir aux entités des composants d'un type de composant donné, qui sont utilisables de manière uniforme, quelle que soit la capacité qui les a produits.
  • Fonctionnalités de capacité spatiale : de plus, certaines capacités nécessitent une configuration et sont donc paramétrées par des fonctionnalités de capacité .

Cette extension fournit un mécanisme permettant d'énumérer les composants fournis par chaque fonctionnalité prise en charge sur le système actuel, à la fois les composants obligatoires et les composants facultatifs .

Étant donné que certaines implémentations peuvent nécessiter différents degrés de paramétrisation pour les capacités , cette extension fournit un mécanisme permettant d'énumérer les fonctionnalités de capacité compatibles associées à une capacité donnée dans le système actuel.

Cette extension définit également plusieurs composants courants qui devraient être utilisés dans un large éventail de fonctionnalités .

Entité spatiale

Les entités spatiales sont des entités qui existent dans un espace et qui comportent diverses données associées organisées en composants. Ils peuvent correspondre à l'un des éléments suivants :

  • Physiques (par exemple, les surfaces planes comme les murs et les sols, les objets comme les chaises et les bibliothèques, etc.)
  • virtuels (par exemple, contenus placés et partagés par une autre application ou un autre utilisateur) ;
  • Défini par l'application (par exemple, l'application marque une zone comme "salon" ou "cuisine", ou marque un point comme emplacement pour placer le téléviseur, etc.)

Les éléments exposés via le système d'actions, comme les contrôleurs ou le regard, ne sont pas destinés à être modélisés en tant qu'entités spatiales.

Les entités spatiales dans OpenXR sont modélisées en tant que système entité-composant . Chaque entité spatiale possède un ensemble de composants, et chaque composant fournit un ensemble unique de données et de comportements pour cette entité.

Les entités spatiales sont représentées par un atome XrSpatialEntityIdEXT ou un handle XrSpatialEntityEXT. Pour en savoir plus, consultez la section Représentations d'entités spatiales.

Types de composants spatiaux

Une entité spatiale comporte un ou plusieurs composants qui fournissent des données ou des comportements pour cette entité. Pour découvrir certains composants courants définis par cette extension, consultez Composants courants.

typedef enum XrSpatialComponentTypeEXT {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT = 1,
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT = 2,
    XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT = 3,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT = 4,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT = 1000741000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT = 1000741001,
    XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT = 1000741002,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT = 1000741003,
    XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT = 1000743000,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT = 1000744000,
    XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT = 1000744001,
    XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT = 1000744002,
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT = 1000763000,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT = 1000782000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT = 1000783000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT = 1000783001,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT = 1000783002,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID = 1000785000,
    XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID = 1000786000,
    XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID = 1000791000,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS = 1000792002,
    XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS = 1000792003,
    XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS = 1000792004,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS = 1000792005,
    XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1 = 1000793000,
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID = 1000794000,
    XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2 = 1000798000,
    XR_SPATIAL_COMPONENT_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

L'énumération XrSpatialComponentTypeEXT identifie les différents types de composants que le moteur d'exécution peut prendre en charge.

Tous les types de composants listés ne sont pas fournis par cette extension seule : certains nécessitent l'activation d'extensions supplémentaires au moment de la création de l'instance, comme indiqué dans la documentation.

Les énumérants ont les valeurs suivantes :

Description de l'enum

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Composant qui fournit les limites 2D d'une entité spatiale. La structure de liste correspondante est XrSpatialComponentBounded2DListEXT et la structure de données correspondante est XrSpatialBounded2DDataEXT.

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

Composant qui fournit les limites 3D d'une entité spatiale. La structure de liste correspondante est XrSpatialComponentBounded3DListEXT. La structure de données correspondante est XrBoxf.

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

Composant qui fournit le XrSpatialEntityIdEXT du parent pour une entité spatiale. La structure de liste correspondante est XrSpatialComponentParentListEXT ; la structure de données correspondante est XrSpatialEntityIdEXT

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

Composant qui fournit un maillage 3D pour une entité spatiale. La structure de liste correspondante est XrSpatialComponentMesh3DListEXT. La structure de données correspondante est XrSpatialMeshDataEXT.

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

Composant qui fournit l'énumération d'alignement du plan pour une entité spatiale. La structure de liste correspondante est XrSpatialComponentPlaneAlignmentListEXT. La structure de données correspondante est XrSpatialPlaneAlignmentEXT (ajoutée par l'extension XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

Composant qui fournit un maillage 2D pour une entité spatiale. La structure de liste correspondante est XrSpatialComponentMesh2DListEXT. La structure de données correspondante est XrSpatialMeshDataEXT (ajoutée par l'extension XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

Composant qui fournit un polygone de délimitation 2D pour une entité spatiale. La structure de liste correspondante est XrSpatialComponentPolygon2DListEXT. La structure de données correspondante est XrSpatialPolygon2DDataEXT (ajoutée par l'extension XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

Composant qui fournit un libellé sémantique pour un plan. La structure de liste correspondante est XrSpatialComponentPlaneSemanticLabelListEXT. La structure de données correspondante est XrSpatialPlaneSemanticLabelEXT (ajoutée par l'extension XR_EXT_spatial_plane_tracking).

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

Composant décrivant le type, l'ID et l'emplacement du repère. La structure de liste correspondante est XrSpatialComponentMarkerListEXT. La structure de données correspondante est XrSpatialMarkerDataEXT (ajoutée par l'extension XR_EXT_spatial_marker_tracking).

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

Composant qui fournit un libellé sémantique pour une scène. La structure de liste correspondante est XrSpatialComponentObjectSemanticLabelListEXT. La structure de données correspondante est XrSpatialObjectSemanticLabelEXT . (Ajouté par l'extension XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

Composant qui fournit un libellé sémantique pour un clavier. La structure de liste correspondante est XrSpatialComponentKeyboardSemanticLabelListEXT. La structure de données correspondante est XrSpatialKeyboardSemanticLabelEXT (ajoutée par l'extension XR_EXT_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

Composant qui fournit un libellé sémantique pour une souris. La structure de liste correspondante est XrSpatialComponentMouseSemanticLabelListEXT. La structure de données correspondante est XrSpatialMouseSemanticLabelEXT (ajoutée par l'extension XR_EXT_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

Composant qui fournit l'emplacement d'une ancre. La structure de liste correspondante est XrSpatialComponentAnchorListEXT. La structure de données correspondante est XrPosef (ajoutée par l'extension XR_EXT_spatial_anchor).

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

Composant qui fournit l'UUID persistant pour une entité spatiale. La structure de liste correspondante est XrSpatialComponentPersistenceListEXT. La structure de données correspondante est XrSpatialPersistenceDataEXT (ajoutée par l'extension XR_EXT_spatial_persistence).

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

Composant décrivant le type d'image plane. La structure de liste correspondante est XrSpatialComponentImage2DListEXT et la structure de données correspondante est XrSpatialImageSizeEXT . (Ajouté par l'extension XR_EXT_spatial_image_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

Composant qui fournit les normales pour le maillage 3D d'une entité spatiale. La structure de liste correspondante est XrSpatialComponentMesh3DNormalsListEXT. La structure de données correspondante est XrSpatialBufferEXT (ajoutée par l'extension XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

Composant qui fournit les libellés sémantiques par vertex pour le maillage 3D d'une entité spatiale. La structure de liste correspondante est XrSpatialComponentMesh3DVertexSemanticLabelsListEXT. La structure de données correspondante est XrSpatialBufferEXT. Les données du tampon sont mappées sur XrSpatialMeshSemanticLabelEXT (ajouté par l'extension XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

Composant qui fournit les libellés sémantiques par face de triangle pour le maillage 3D d'une entité spatiale. La structure de liste correspondante est XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT. La structure de données correspondante est XrSpatialBufferEXT. Les données du tampon sont mappées sur XrSpatialMeshSemanticLabelEXT (ajouté par l'extension XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

Composant qui fournit un libellé sémantique pour un objet. La structure de liste correspondante est XrSpatialComponentObjectSemanticLabelListANDROID. La structure de données correspondante est XrSpatialObjectSemanticLabelANDROID (ajoutée par l'extension XR_ANDROID_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Composant qui fournit la pose d'un impact de raycast sur une entité. La structure de liste correspondante est XrSpatialComponentRaycastResultListANDROID. La structure de données correspondante est XrSpatialRaycastResultDataANDROID (ajoutée par l'extension XR_ANDROID_spatial_discovery_raycast).

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

Composant qui fournit l'ID d'entité de l'entité englobant l'entité associée. La structure de liste correspondante est XrSpatialComponentSubsumedByListANDROID. La structure de données correspondante est XrSpatialEntityIdEXT (ajoutée par l'extension XR_ANDROID_spatial_component_subsumed_by).

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

Composant qui fournit les dimensions et le type de pièce d'une boîte à chaussures. La structure de liste correspondante est XrSpatialComponentRoomListANDROIDSYS. La structure de données correspondante est XrSpatialRoomDataANDROIDSYS (ajoutée par l'extension XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

Composant qui fournit le type de matériau d'une surface limite. La structure de liste correspondante est XrSpatialComponentMaterialTypeListANDROIDSYS. La structure de données correspondante est XrSpatialMaterialTypeANDROIDSYS (ajoutée par l'extension XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

Composant qui fournit la confiance d'un élément pouvant être suivi. La structure de liste correspondante est XrSpatialComponentConfidenceListANDROIDSYS. La structure de données correspondante est float (ajoutée par l'extension XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

Composant qui indique si une pièce est vide ou non. La structure de liste correspondante est XrSpatialComponentRoomEmptinessListANDROIDSYS. La structure de données correspondante est float (ajoutée par l'extension XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

Composant qui fournit des informations sur la grille d'occupation de l'entité associée. La structure de liste correspondante est XrSpatialComponentOccupancyGridListANDROIDX1. La structure de données correspondante est XrSpatialOccupancyGridDataANDROIDX1 (ajoutée par l'extension XR_ANDROIDX1_spatial_occupancy_grid).

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Composant décrivant une annotation de quad. La structure de liste correspondante est XrSpatialComponentAnnotationQuadListANDROID. La structure de données correspondante est XrSpatialAnnotationQuadDataANDROID (ajoutée par l'extension XR_ANDROID_spatial_annotation_tracking).

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

Composant qui fournit les métadonnées d'une géométrie Streetscape. La structure de liste correspondante est XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2. La structure de données correspondante est XrSpatialStreetscapeGeometryMetadataANDROIDX2 (ajoutée par l'extension XR_ANDROIDX2_geospatial_streetscape).

Fonctionnalités et configuration spatiales

Les capacités spatiales définissent les capacités d'un moteur d'exécution à découvrir des entités qui comportent un ensemble garanti de composants. Les applications activent les composants d'une fonctionnalité spatiale lors de la création de XrSpatialContextEXT, et le runtime doit à son tour fournir uniquement les composants activés sur les entités découvertes. Par exemple, si un runtime indique que l'un des composants d'une fonctionnalité donnée est "libellés sémantiques", cela signifie que l'application peut activer les libellés sémantiques via la configuration de cette fonctionnalité et que le runtime doit uniquement fournir le composant de libellé sémantique s'il est configuré.

typedef enum XrSpatialCapabilityEXT {
    XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT = 1000741000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT = 1000743002,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT = 1000743003,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID = 1000785000,
    XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID = 1000786000,
    XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS = 1000792000,
    XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS = 1000792001,
    XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID = 1000794000,
    XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2 = 1000798000,
    XR_SPATIAL_CAPABILITY_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityEXT;

L'énumération XrSpatialCapabilityEXT identifie les différents types de capacités que le moteur d'exécution peut prendre en charge.

Les énumérants ont les valeurs suivantes :

Description de l'enum

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

Suivi des avions (ajouté par l'extension XR_EXT_spatial_plane_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

Capacité à détecter et suivre les codes QR. (Ajouté par l'extension XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

Possibilité de détecter et de suivre les microcodes QR. (Ajouté par l'extension XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

Capacité à détecter et à suivre les marqueurs Aruco. (Ajouté par l'extension XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

Capacité à détecter et suivre les AprilTags. (Ajouté par l'extension XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

Suivi des objets (ajouté par l'extension XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

Possibilité de créer des ancres spatiales (ajoutée par l'extension XR_EXT_spatial_anchor)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Capacité à détecter et à suivre des images de référence planes. (Ajouté par l'extension XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

Possibilité de suivre le maillage d'un environnement. (Ajouté par l'extension XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

Suivi des objets (ajouté par l'extension XR_ANDROID_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

Raycast contre le tampon de profondeur (ajouté par l'extension XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

Possibilité de suivre une salle (ajoutée par l'extension XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

Possibilité de suivre la limite d'une pièce (ajoutée par l'extension XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Suivi des annotations (ajouté par l'extension XR_ANDROID_spatial_annotation_tracking)

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

Géométrie du paysage urbain (ajoutée par l'extension XR_ANDROIDX2_geospatial_streetscape)

La fonction xrEnumerateSpatialCapabilitiesEXT est définie comme suit :

XrResult xrEnumerateSpatialCapabilitiesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    capabilityCapacityInput,
    uint32_t*                                   capabilityCountOutput,
    XrSpatialCapabilityEXT*                     capabilities);

Descriptions des paramètres

  • instance est un handle vers une XrInstance .
  • systemId est le XrSystemId dont les capacités spatiales seront énumérées.
  • capabilityCapacityInput correspond à la capacité du tableau capabilities ou à 0 pour indiquer une demande de récupération de la capacité requise.
  • capabilityCountOutput correspond au nombre de capacités ou à la capacité requise si capabilityCapacityInput est insuffisant.
  • capabilities est un tableau de XrSpatialCapabilityEXT . Elle peut être NULL si capabilityCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille capabilities requise, consultez la section Paramètres de taille du tampon.

L'application peut énumérer la liste des capacités spatiales prises en charge par un XrSystemId donné à l'aide de xrEnumerateSpatialCapabilitiesEXT .

L'exécution ne doit pas énumérer les fonctionnalités spatiales dont l'extension n'est pas activée pour instance .

Utilisation valide (implicite)

  •  L'extension XR_EXT_spatial_entity doit être activée avant d'appeler xrEnumerateSpatialCapabilitiesEXT.
  • instance doit être un handle XrInstance valide
  • capabilityCountOutput must être un pointeur vers une valeur uint32_t
  •  Si capabilityCapacityInput n'est pas 0 , capabilities doit être un pointeur vers un tableau de valeurs XrSpatialCapabilityEXT capabilityCapacityInput.

Codes de retour

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

La fonction xrEnumerateSpatialCapabilityComponentTypesEXT est définie comme suit :

XrResult xrEnumerateSpatialCapabilityComponentTypesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    XrSpatialCapabilityComponentTypesEXT*       capabilityComponents);

Descriptions des paramètres

  • instance est un handle vers une XrInstance .
  • systemId est le XrSystemId dont les composants de capacité spatiale seront énumérés.
  • capability est l'XrSpatialCapabilityEXT pour lequel les composants seront énumérés.
  • capabilityComponents est un pointeur vers un XrSpatialCapabilityComponentTypesEXT , qui est une structure d'entrée/sortie dans laquelle un tableau alloué à l'application est renseigné.

Cette fonction énumère les types de composants que la fonctionnalité donnée fournit sur ses entités dans le système tel qu'il est configuré.

L'application peut utiliser les types de composants énumérés dans XrSpatialCapabilityComponentTypesEXT :: componentTypes pour comprendre l'ensemble des composants que systemId prend en charge pour capability et peut utiliser cette liste pour déterminer ce qu'est une configuration valide pour capability lors de la création d'un XrSpatialContextEXT pour celui-ci.

L'exécution doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT si capability n'est pas énuméré par xrEnumerateSpatialCapabilitiesEXT .

Le runtime ne doit pas énumérer les types de composants spatiaux dont l'extension n'est pas activée pour instance .

Utilisation valide (implicite)

Codes de retour

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_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La structure XrSpatialCapabilityComponentTypesEXT est définie comme suit :

typedef struct XrSpatialCapabilityComponentTypesEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      componentTypeCapacityInput;
    uint32_t                      componentTypeCountOutput;
    XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialCapabilityComponentTypesEXT;

Descriptions des membres

  • 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 l'extension ni dans le cœur d'OpenXR.
  • componentTypeCapacityInput correspond à la capacité du tableau ou à 0 pour indiquer une demande de récupération de la capacité requise.
  • componentTypeCountOutput correspond au nombre de types de composants ou à la capacité requise si componentTypeCapacityInput est insuffisant.
  • componentTypes est un tableau de XrSpatialComponentTypeEXT . Elle peut être NULL si componentTypeCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille componentTypes requise, consultez la section Paramètres de taille du tampon.

Utilisation valide (implicite)

Fonctionnalités de capacité spatiale

typedef enum XrSpatialCapabilityFeatureEXT {
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID = 1000761000,
    XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID = 1000761001,
    XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID = 1000761002,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT = 1000782001,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT = 1000782002,
    XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_FEATURE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityFeatureEXT;

Certaines fonctionnalités ont des paramètres exposés à l'application pour configurer la façon dont les données des composants sont calculées par le runtime. Ces dimensions de paramétrisation/configurabilité sont appelées "fonctionnalités de capacité". Par exemple, pour une fonctionnalité de suivi d'images, un runtime peut permettre à l'application de spécifier si les images suivies sont fixes ou non.

Le fait de fournir ces informations au runtime via une structure de configuration ne doit pas modifier l'ensemble des types de composants présents sur les entités associées, par exemple sur l'image suivie. Toutefois, le runtime peut être en mesure d'optimiser, par exemple, les capacités de suivi de la fonctionnalité de suivi d'image et d'offrir une meilleure expérience à l'application.

Ces fonctionnalités sont représentées par XrSpatialCapabilityFeatureEXT et l'application les énumère à l'aide de xrEnumerateSpatialCapabilityFeaturesEXT .

Chaque fonctionnalité de capacité possède une structure de configuration correspondante pour l'activer. Ces structures de configuration doivent être chaînées à XrSpatialCapabilityConfigurationBaseHeaderEXT :: next de la fonctionnalité correspondante.

Les énumérants ont les valeurs suivantes :

Description de l'enum

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

Fonctionnalité permettant aux applications de spécifier la taille des repères. La structure de configuration correspondante est XrSpatialMarkerSizeEXT (ajoutée par l'extension XR_EXT_spatial_marker_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

Fonctionnalité permettant aux applications d'indiquer si les repères sont statiques. La structure de configuration correspondante est XrSpatialMarkerStaticOptimizationEXT (ajoutée par l'extension XR_EXT_spatial_marker_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

Fonctionnalité spatiale permettant aux applications de spécifier un sous-ensemble de libellés à partir de XrSpatialObjectSemanticLabelEXT pour que le runtime puisse les suivre. La structure de configuration correspondante est XrSpatialFeatureObjectSemanticLabelSubsetEXT . (Ajouté par l'extension XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

Le runtime est compatible avec le filtre XrSpatialBoundsSpherefANDROID pour XrSpatialDiscoverySnapshotCreateInfoEXT. Aucune structure de configuration n'est requise lors de la création du contexte spatial. (Ajouté par l'extension XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

Le runtime est compatible avec le filtre XrSpatialBoundsBoxfANDROID pour XrSpatialDiscoverySnapshotCreateInfoEXT. Aucune structure de configuration n'est requise lors de la création du contexte spatial. (Ajouté par l'extension XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

Le runtime est compatible avec le filtre XrSpatialBoundsFrustumfANDROID pour XrSpatialDiscoverySnapshotCreateInfoEXT. Aucune structure de configuration n'est requise lors de la création du contexte spatial. (Ajouté par l'extension XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

Le runtime permet de déduire automatiquement la taille physique des images détectées et suivies. La structure de configuration correspondante est XrSpatialImageSizeEXT (ajoutée par l'extension XR_EXT_spatial_image_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

L'environnement d'exécution est compatible avec XrSpatialImageStaticOptimizationEXT . La structure de configuration correspondante est XrSpatialImageStaticOptimizationEXT . (Ajouté par l'extension XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

L'environnement d'exécution est compatible avec XrSpatialImageSizeEXT . La structure de configuration correspondante est XrSpatialImageSizeEXT (ajoutée par l'extension XR_EXT_spatial_image_tracking).

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

Fonctionnalité permettant de suivre un maillage étanche de l'environnement. La structure de configuration correspondante est XrSpatialFeatureTrackWatertightMeshEXT . (Ajouté par l'extension XR_EXT_spatial_mesh_tracking)

La fonction xrEnumerateSpatialCapabilityFeaturesEXT est définie comme suit :

XrResult xrEnumerateSpatialCapabilityFeaturesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    capabilityFeatureCapacityInput,
    uint32_t*                                   capabilityFeatureCountOutput,
    XrSpatialCapabilityFeatureEXT*              capabilityFeatures);

Descriptions des paramètres

  • instance est un handle vers une XrInstance .
  • systemId est le XrSystemId dont les fonctionnalités de capacité spatiale seront énumérées.
  • capability est l'XrSpatialCapabilityEXT pour lequel les fonctionnalités seront énumérées.
  • capabilityFeatureCapacityInput correspond à la capacité du tableau ou à 0 pour indiquer une demande de récupération de la capacité requise.
  • capabilityFeatureCountOutput correspond au nombre de fonctionnalités ou à la capacité requise si capabilityFeatureCapacityInput est insuffisant.
  • capabilityFeatures est un tableau de XrSpatialCapabilityFeatureEXT . Elle peut être NULL si capabilityFeatureCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille capabilityFeatures requise, consultez la section Paramètres de taille du tampon.

L'application découvre les fonctionnalités compatibles avec un système donné pour un XrSpatialCapabilityEXT à l'aide de xrEnumerateSpatialCapabilityFeaturesEXT .

Pour les capacités dont les fonctionnalités sont exposées, l'application sélectionne la ou les fonctionnalités à activer et fournit la structure de configuration correspondante dans la chaîne suivante des structures de configuration des capacités dans XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Si capability n'est pas une fonctionnalité énumérée par xrEnumerateSpatialCapabilitiesEXT , le runtime doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

L'exécution ne doit pas énumérer les fonctionnalités de capacité spatiale dont l'extension n'est pas activée pour instance .

Utilisation valide (implicite)

Codes de retour

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_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Contexte spatial

Créer un contexte spatial

XR_DEFINE_HANDLE(XrSpatialContextEXT)

Le handle XrSpatialContextEXT représente les ressources permettant de découvrir et de mettre à jour un certain nombre d'entités spatiales dans l'environnement de l'utilisateur. L'application peut utiliser ce handle pour découvrir et mettre à jour les entités spatiales à l'aide d'autres fonctions de cette extension.

La fonction xrCreateSpatialContextAsyncEXT est définie comme suit :

XrResult xrCreateSpatialContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialContextCreateInfoEXT*        createInfo,
    XrFutureEXT*                                future);

Descriptions des paramètres

  • session est une XrSession dans laquelle le contexte spatial sera actif.
  • createInfo est le XrSpatialContextCreateInfoEXT utilisé pour spécifier les paramètres du contexte spatial.
  • future est un pointeur vers un XrFutureEXT .

L'application peut créer un handle XrSpatialContextEXT en procédant comme suit :

L'exécution doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT si XrSpatialContextCreateInfoEXT ::capabilityConfigCount est défini sur 0. Un handle de contexte spatial doit disposer d'au moins une fonctionnalité.

L'exécution doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT si une fonctionnalité du tableau capabilityConfigs de XrSpatialContextCreateInfoEXT n'est pas énumérée par xrEnumerateSpatialCapabilitiesEXT .

L'exécution doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT si XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount dans XrSpatialContextCreateInfoEXT :: capabilityConfigs est défini sur 0. Une configuration de fonctionnalité est incomplète sans liste des types de composants à activer pour cette fonctionnalité.

Le runtime doit renvoyer XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT si un type de composant listé dans XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents n'est pas énuméré pour XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability dans xrEnumerateSpatialCapabilityComponentTypesEXT .

Si l'une des structures de la chaîne suivante de XrSpatialContextCreateInfoEXT :: capabilityConfigs correspond à une XrSpatialCapabilityFeatureEXT qui n'est pas énumérée pour cette fonctionnalité dans xrEnumerateSpatialCapabilityFeaturesEXT , le runtime doit ignorer cette structure XrSpatialCapabilityFeatureEXT.

L'environnement d'exécution doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT si XrSpatialContextCreateInfoEXT :: capabilityConfigs contient plusieurs structures avec le même XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability .

Pour garantir une utilisation optimale des ressources système, l'environnement d'exécution peut utiliser les configurations fournies dans le tableau XrSpatialContextCreateInfoEXT pour se préparer aux futures requêtes spatiales. Par exemple, un environnement d'exécution compatible avec la fonctionnalité de suivi des plans peut ne démarrer son pipeline de suivi des plans que si un handle de contexte spatial contenant la fonctionnalité de suivi des plans est créé par l'application. Si les fonctionnalités configurées ont un long temps de préchauffage, les appels à xrCreateSpatialDiscoverySnapshotAsyncEXT peuvent entraîner un instantané vide. L'application peut attendre XrEventDataSpatialDiscoveryRecommendedEXT avant d'utiliser xrCreateSpatialDiscoverySnapshotAsyncEXT pour s'assurer que les services de suivi sous-jacents sont prêts.

Si un moteur d'exécution applique un système d'autorisations pour contrôler l'accès des applications aux fonctionnalités spatiales configurées pour XrSpatialContextEXT , il doit renvoyer XR_ERROR_PERMISSION_INSUFFICIENT si ces autorisations n'ont pas été accordées à cette application.

Cette fonction lance une opération asynchrone et crée un XrFutureEXT correspondant , utilisable avec xrPollFutureEXT et les fonctions associées. La valeur renvoyée par cette fonction indique uniquement si les paramètres étaient acceptables pour planifier l'opération asynchrone. La fonction d'achèvement correspondante est xrCreateSpatialContextCompleteEXT , utilisable lorsqu'un avenir de cette fonction est à l'état READY, avec des sorties renseignées par cette fonction dans la structure d'achèvement XrCreateSpatialContextCompletionEXT .

Utilisation valide (implicite)

Codes de retour

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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
  • XR_ERROR_VALIDATION_FAILURE

La structure XrSpatialContextCreateInfoEXT est définie comme suit :

typedef struct XrSpatialContextCreateInfoEXT {
    XrStructureType                                                type;
    const void*                                                    next;
    uint32_t                                                       capabilityConfigCount;
    const XrSpatialCapabilityConfigurationBaseHeaderEXT* const*    capabilityConfigs;
} XrSpatialContextCreateInfoEXT;

Descriptions des membres

  • 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 l'extension ni dans le cœur d'OpenXR.
  • capabilityConfigCount est un uint32_t décrivant le nombre d'éléments dans le tableau capabilityConfigs.
  • capabilityConfigs est un pointeur vers un tableau de pointeurs XrSpatialCapabilityConfigurationBaseHeaderEXT.

La structure XrSpatialContextCreateInfoEXT décrit les informations permettant de créer un handle XrSpatialContextEXT.

Utilisation valide (implicite)

La structure XrSpatialCapabilityConfigurationBaseHeaderEXT est définie comme suit :

typedef struct XrSpatialCapabilityConfigurationBaseHeaderEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationBaseHeaderEXT;

Cette structure n'est pas directement utilisée dans l'API, mais ses structures enfants peuvent être utilisées avec XrSpatialContextCreateInfoEXT pour configurer les capacités spatiales.

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • capability est une XrSpatialCapabilityEXT .
  • enabledComponentCount est un uint32_t décrivant le nombre d'éléments dans le tableau enabledComponents.
  • enabledComponents est un pointeur vers un tableau de XrSpatialComponentTypeEXT .

L'exécution doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT si capability n'est pas énuméré par xrEnumerateSpatialCapabilitiesEXT . L'environnement d'exécution doit renvoyer XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT si un type de composant listé dans enabledComponents n'est pas énuméré pour capability dans xrEnumerateSpatialCapabilityComponentTypesEXT .

Utilisation valide (implicite)

La fonction xrCreateSpatialContextCompleteEXT est définie comme suit :

XrResult xrCreateSpatialContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialContextCompletionEXT*        completion);

Descriptions des paramètres

xrCreateSpatialContextCompleteEXT termine l'opération asynchrone lancée par xrCreateSpatialContextAsyncEXT . L'environnement d'exécution doit renvoyer XR_ERROR_FUTURE_PENDING_EXT si future n'est pas prêt. L'environnement d'exécution doit renvoyer XR_ERROR_FUTURE_INVALID_EXT si future a déjà été effectué ou annulé.

Utilisation valide (implicite)

Codes de retour

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • 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_VALIDATION_FAILURE

La structure XrCreateSpatialContextCompletionEXT est définie comme suit :

typedef struct XrCreateSpatialContextCompletionEXT {
    XrStructureType        type;
    void*                  next;
    XrResult               futureResult;
    XrSpatialContextEXT    spatialContext;
} XrCreateSpatialContextCompletionEXT;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • futureResult correspond à XrResult de l'opération de création du contexte spatial.
  • spatialContext est un XrSpatialContextEXT créé à l'aide des données et de la configuration dans xrCreateSpatialContextAsyncEXT :: createInfo .

Codes de retour futurs

Valeurs futureResult :

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT

Si futureResult est un code de réussite, spatialContext doit être valide. Si spatialContext est valide, il ne le reste que pendant le cycle de vie de xrCreateSpatialContextAsyncEXT :: session ou jusqu'à ce que l'application détruise spatialContext avec xrDestroySpatialContextEXT , selon la première éventualité.

Utilisation valide (implicite)

Détruire le contexte spatial

La fonction xrDestroySpatialContextEXT est définie comme suit :

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

Descriptions des paramètres

L'application peut appeler la fonction xrDestroySpatialContextEXT pour libérer le handle spatialContext et les ressources sous-jacentes une fois les tâches de découverte et de mise à jour des entités spatiales terminées. S'il n'existe aucune autre XrSpatialContextEXT valide créée avec les mêmes capacités spatiales que spatialContext , cet appel sert de suggestion au moteur d'exécution pour désactiver les services de suivi requis pour ces capacités afin d'économiser les ressources système.

Utilisation valide (implicite)

Sécurité des threads

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

Codes de retour

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Représentations d'entités spatiales

ID d'entité spatiale

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT est utilisé pour représenter tout type d'entité découvert par le runtime dans l'environnement spatial de l'utilisateur. Un XrSpatialEntityIdEXT est valide pour le XrSpatialContextEXT dans lequel il est découvert, et le runtime ne doit pas réutiliser le même XrSpatialEntityIdEXT pour différentes entités au sein du même XrSpatialContextEXT . De plus, le runtime ne doit pas réutiliser le même XrSpatialEntityIdEXT pour plusieurs XrSpatialContextEXT au sein de la même XrSession, qu'il représente la même entité ou des entités différentes.

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT est une valeur réservée représentant un XrSpatialEntityIdEXT non valide . Il peut être transmis aux fonctions d'API et renvoyé par celles-ci uniquement lorsque cela est spécifiquement autorisé.

Handle d'entité spatiale

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

Le handle XrSpatialEntityEXT représente une entité spatiale. Une application peut créer un tel handle pour exprimer son intérêt pour une entité spécifique au moment de l'exécution.

Créer un handle d'entité spatiale à partir d'un ID

La fonction xrCreateSpatialEntityFromIdEXT est définie comme suit :

XrResult xrCreateSpatialEntityFromIdEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialEntityFromIdCreateInfoEXT*   createInfo,
    XrSpatialEntityEXT*                         spatialEntity);

Descriptions des paramètres

L'application peut utiliser xrCreateSpatialEntityFromIdEXT pour créer un handle XrSpatialEntityEXT qui fait référence à une entité existant dans l'environnement de l'utilisateur.

L'exécution doit renvoyer XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT si XrSpatialEntityFromIdCreateInfoEXT::entityId n'est pas un ID valide pour spatialContext .

Utilisation valide (implicite)

Codes de retour

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

La structure XrSpatialEntityFromIdCreateInfoEXT est définie comme suit :

typedef struct XrSpatialEntityFromIdCreateInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    entityId;
} XrSpatialEntityFromIdCreateInfoEXT;

Descriptions des membres

  • 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 l'extension ni dans le cœur d'OpenXR.
  • entityId correspond au XrSpatialEntityIdEXT de l'entité pour laquelle l'application souhaite créer un handle.

Utilisation valide (implicite)

Détruire le handle d'entité spatiale

La fonction xrDestroySpatialEntityEXT est définie comme suit :

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

Descriptions des paramètres

L'application peut utiliser xrDestroySpatialEntityEXT pour libérer le handle spatialEntity lorsqu'elle n'est plus intéressée par l'entité référencée par ce handle.

Utilisation valide (implicite)

Sécurité des threads

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

Codes de retour

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Instantané spatial

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

L'application peut créer des instantanés spatiaux pour découvrir des entités spatiales ou mettre à jour ses informations sur les entités spatiales connues. Le handle XrSpatialSnapshotEXT représente les données immuables des entités spatiales découvertes ou mises à jour, ainsi qu'un sous-ensemble de leurs composants sélectionnés par l'application. L'instantané spatial représente une vue cohérente des entités et de leurs données composantes. Une fois l'instantané créé, les données de l'instantané doivent rester constantes tant que l'instantané est valide.

L'application peut créer autant d'instantanés qu'elle le souhaite, mais elle doit tenir compte de la mémoire allouée à chaque nouvel instantané et doit détruire les instantanés une fois qu'elle n'en a plus besoin.

Créer un instantané de découverte

La fonction xrCreateSpatialDiscoverySnapshotAsyncEXT est définie comme suit :

XrResult xrCreateSpatialDiscoverySnapshotAsyncEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialDiscoverySnapshotCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Descriptions des paramètres

L'application peut découvrir des entités spatiales en créant un instantané de découverte à l'aide de xrCreateSpatialDiscoverySnapshotAsyncEXT .

Cette fonction lance une opération asynchrone et crée un XrFutureEXT correspondant , utilisable avec xrPollFutureEXT et les fonctions associées. La valeur renvoyée par cette fonction indique uniquement si les paramètres étaient acceptables pour planifier l'opération asynchrone. La fonction de finalisation correspondante est xrCreateSpatialDiscoverySnapshotCompleteEXT , utilisable lorsqu'un futur de cette fonction est à l'état READY, avec des sorties renseignées par cette fonction dans la structure de finalisation XrCreateSpatialDiscoverySnapshotCompletionEXT .

L'application peut envoyer plusieurs demandes de création d'instantanés de découverte sans avoir à attendre que la précédente soit terminée. L'environnement d'exécution peut traiter et finaliser la création de l'instantané dans n'importe quel ordre. Le runtime peut retarder la création de l'instantané de découverte pour limiter l'application si elle doit réduire l'utilisation des ressources système en raison de la batterie, de la température ou d'autres règles de l'appareil.

L'application peut utiliser XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes pour filtrer la liste des entités et des composants dont les données doivent être incluses dans l'instantané par le moteur d'exécution. Si l'application fournit une liste valide de types de composants spatiaux dans XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , le runtime doit uniquement inclure dans le snapshot les entités spatiales qui comportent au moins l'un des composants fournis dans XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . De plus, le runtime ne doit inclure que les données des composants présents dans l'instantané.

L'exécution doit renvoyer XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT si l'un des XrSpatialComponentTypeEXT dans XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes n'est pas activé pour les capacités spatiales transmises à XrSpatialContextCreateInfoEXT :: capabilityConfigs lors de la création de spatialContext .

Si l'application ne fournit pas de liste de types de composants spatiaux dans XrSpatialDiscoverySnapshotCreateInfoEXT::componentTypes , le runtime doit inclure toutes les entités spatiales de l'instantané qui possèdent l'ensemble de composants énumérés dans XrSpatialCapabilityConfigurationBaseHeaderEXT::enabledComponents pour les capacités configurées pour spatialContext . L'exécution doit inclure les données de tous les composants activés des fonctionnalités configurées pour spatialContext .

Si XrEventDataReferenceSpaceChangePending est mis en file d'attente avant la fin de future et que XrEventDataReferenceSpaceChangePending :: poseValid est défini sur "false", le runtime peut créer un XrSpatialSnapshotEXT sans entités ou définir XrSpatialEntityTrackingStateEXT des entités qui ne sont plus localisables dans XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace à XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time sur XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT ou XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . Le runtime ne doit pas définir XrCreateSpatialContextCompletionEXT :: futureResult sur un code d'erreur en raison de XrEventDataReferenceSpaceChangePending .

Utilisation valide (implicite)

Codes de retour

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

La structure XrSpatialDiscoverySnapshotCreateInfoEXT est définie comme suit :

typedef struct XrSpatialDiscoverySnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialDiscoverySnapshotCreateInfoEXT;

Descriptions des membres

  • 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 l'extension ni dans le cœur d'OpenXR.
  • componentTypeCount est un uint32_t décrivant le nombre d'éléments dans le tableau componentTypes.
  • componentTypes est un tableau de XrSpatialComponentTypeEXT .

La structure XrSpatialDiscoverySnapshotCreateInfoEXT décrit les informations permettant de créer un handle XrSpatialSnapshotEXT lors de la découverte d'entités spatiales.

Utilisation valide (implicite)

La fonction xrCreateSpatialDiscoverySnapshotCompleteEXT est définie comme suit :

XrResult xrCreateSpatialDiscoverySnapshotCompleteEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrCreateSpatialDiscoverySnapshotCompletionInfoEXT* createSnapshotCompletionInfo,
    XrCreateSpatialDiscoverySnapshotCompletionEXT* completion);

Descriptions des paramètres

xrCreateSpatialDiscoverySnapshotCompleteEXT termine l'opération asynchrone lancée par xrCreateSpatialDiscoverySnapshotAsyncEXT . L'exécution doit renvoyer XR_ERROR_FUTURE_PENDING_EXT si XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future n'est pas à l'état prêt. Le runtime doit renvoyer XR_ERROR_FUTURE_INVALID_EXT si XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future a déjà été terminé ou annulé.

Utilisation valide (implicite)

Codes de retour

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • 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_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La structure XrCreateSpatialDiscoverySnapshotCompletionInfoEXT est définie comme suit :

typedef struct XrCreateSpatialDiscoverySnapshotCompletionInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrFutureEXT        future;
} XrCreateSpatialDiscoverySnapshotCompletionInfoEXT;

Descriptions des membres

Les emplacements des différentes données de composants incluses dans l'instantané créé seront représentés dans baseSpace , situé à time .

Utilisation valide (implicite)

La structure XrCreateSpatialDiscoverySnapshotCompletionEXT est définie comme suit :

typedef struct XrCreateSpatialDiscoverySnapshotCompletionEXT {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialSnapshotEXT    snapshot;
} XrCreateSpatialDiscoverySnapshotCompletionEXT;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • futureResult correspond à XrResult de l'opération de création d'instantané de découverte spatiale.
  • snapshot est un XrSpatialSnapshotEXT qui peut être utilisé pour interroger les données des composants des entités spatiales découvertes.

Codes de retour futurs

Valeurs futureResult :

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Utilisation valide (implicite)

Événement de recommandation de découverte

La structure XrEventDataSpatialDiscoveryRecommendedEXT est définie comme suit :

typedef struct XrEventDataSpatialDiscoveryRecommendedEXT {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
} XrEventDataSpatialDiscoveryRecommendedEXT;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • spatialContext est l'XrSpatialContextEXT pour lequel l'exécution recommande la découverte.

L'application peut récupérer cet événement à l'aide de xrPollEvent . L'application peut éviter les appels excessifs à xrCreateSpatialDiscoverySnapshotAsyncEXT pour découvrir les entités spatiales en attendant cet événement. Si l'application crée plusieurs instantanés de découverte avec le même XrSpatialDiscoverySnapshotCreateInfoEXT entre deux événements XrEventDataSpatialDiscoveryRecommendedEXT, les instantanés résultants peuvent contenir les mêmes entités. La création d'instantanés et les requêtes de données seraient donc inutiles.

L'attente de cet événement pour créer un instantané de découverte garantit que l'application ne surcharge pas le système avec des requêtes de découverte pour lesquelles le runtime peut ne renvoyer aucune nouvelle donnée. Cela permet également d'éviter le risque de surutilisation des ressources système et de limitation en raison des règles d'alimentation ou thermiques de l'appareil. Cela permet également de créer une parité entre les runtimes qui découvrent des entités spatiales à la volée avec le suivi en direct et les runtimes qui fournissent des entités spatiales à partir d'un état précédemment enregistré (où le runtime peut mettre en file d'attente l'événement de recommandation de découverte une seule fois pour chaque XrSpatialContextEXT).

L'exécution ne doit pas mettre en file d'attente cet événement pour informer l'application des modifications ou ajustements apportés aux données des composants des entités spatiales existantes. L'application peut utiliser xrCreateSpatialUpdateSnapshotEXT pour suivre les mises à jour des données de composants pour les entités spatiales qui l'intéressent.

Un runtime peut mettre en file d'attente un événement de recommandation de découverte sans attendre que l'application appelle d'abord xrCreateSpatialDiscoverySnapshotAsyncEXT . Par exemple, un environnement d'exécution peut baser la décision de mise en file d'attente de l'événement de recommandation de découverte sur la configuration de XrSpatialContextEXT , sa propre compréhension de l'environnement autour de l'utilisateur (découverte de nouvelles entités ou perte d'entités existantes), ou pour suggérer une cadence de demande de découverte appropriée à l'application afin de ne pas surcharger les ressources système. Le runtime peut choisir de ne jamais mettre en file d'attente cet événement pour un XrSpatialContextEXT si aucune entité n'est trouvée dans l'environnement de l'utilisateur pendant toute la durée de vie de cet XrSpatialContextEXT .

L'exécution ne doit pas mettre en file d'attente cet événement pour un spatialContext donné tant que l'application n'a pas terminé sa création à l'aide de xrCreateSpatialContextCompleteEXT .

Une fois que l'application a appelé xrDestroySpatialContextEXT , le moteur d'exécution ne doit pas mettre en file d'attente d'autres événements de recommandation de découverte pour ce contexte spatial ni renvoyer de tels événements pour ce contexte à partir de xrPollEvent .

Utilisation valide (implicite)

Interroger les données des composants

La fonction xrQuerySpatialComponentDataEXT est définie comme suit :

XrResult xrQuerySpatialComponentDataEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialComponentDataQueryConditionEXT* queryCondition,
    XrSpatialComponentDataQueryResultEXT*       queryResult);

Descriptions des paramètres

L'application peut utiliser xrQuerySpatialComponentDataEXT pour interroger les données de composant des entités dans l'instantané en associant une structure de liste à XrSpatialComponentDataQueryResultEXT :: next correspondant à chaque XrSpatialComponentTypeEXT dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Si l'application associe une structure de liste à XrSpatialComponentDataQueryResultEXT :: next qui ne correspond à aucun des composants listés dans XrSpatialComponentDataQueryConditionEXT :: componentTypes , le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE .

L'application peut choisir de joindre les structures de liste correspondant uniquement à un sous-ensemble de composants listés dans XrSpatialComponentDataQueryConditionEXT :: componentTypes . L'application peut choisir d'omettre complètement les structures de liste si elle ne souhaite connaître que les ID et l'état de suivi des entités spatiales qui satisfont queryCondition . L'exécution ne doit pas traiter l'absence de structures de liste de la chaîne XrSpatialComponentDataQueryResultEXT :: next comme un échec.

Si XrEventDataReferenceSpaceChangePending est mis en file d'attente et que XrEventDataReferenceSpaceChangePending :: changeTime s'est écoulé pendant que l'application interroge les données des composants à partir d'un XrSpatialSnapshotEXT , l'application peut utiliser les données d'événement pour ajuster les poses en conséquence.

L'exécution doit remplir XrSpatialComponentDataQueryResultEXT :: entityIds uniquement avec les entités qui comportent tous les composants spécifiés dans XrSpatialComponentDataQueryConditionEXT :: componentTypes . Si XrSpatialComponentDataQueryConditionEXT :: componentTypeCount est défini sur 0, l'environnement d'exécution doit remplir queryResult avec toutes les entités (et leurs états de suivi) qui se trouvent dans l'instantané. Si des conditions de requête supplémentaires sont ajoutées à XrSpatialComponentDataQueryConditionEXT :: next, le runtime doit les traiter comme un "AND" avec la disponibilité des types de composants, c'est-à-dire que le runtime doit remplir XrSpatialComponentDataQueryResultEXT ::entityIds uniquement avec les entités qui remplissent toutes les conditions fournies. L'exécution doit remplir les données du composant dans les structures de liste dans le même ordre que les entités dans XrSpatialComponentDataQueryResultEXT :: entityIds, c'est-à-dire que les données du composant à un index donné dans le tableau de structure de liste doivent correspondre à l'entité au même index.

Si l'état de suivi d'une entité n'est pas XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT , le runtime ne doit pas modifier les données à l'index correspondant à cette entité dans le tableau contenu dans les structures de liste associées à XrSpatialComponentDataQueryResultEXT .

Utilisation valide (implicite)

Codes de retour

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

Par exemple, l'application crée un XrSpatialSnapshotEXT qui contient cinq entités, où :

  • Les entités 1 et 2 ont des composants XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT et XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT.
  • Les entités 3 et 4 comportent les composants XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT et XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT.
  • L'entité 5 comporte les composants XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT et XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT .

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

3

3

4

4

5

5

Bounded2D

Bounded2D

Oui

Oui

Oui

Oui

Non

Non

Non

Non

Oui

Oui

Parent

Parent

Oui

Oui

Oui

Oui

Non

Non

Non

Non

Non

Non

Mesh3D

Mesh3D

Non

Non

Non

Non

Oui

Oui

Oui

Oui

Oui

Oui

Bounded3D

Bounded3D

Non

Non

Non

Non

Oui

Oui

Oui

Oui

Non

Le texte n'est pas au format SVG et ne peut pas être affiché

Figure 20. Exemple d'instantané

xrQuerySpatialComponentDataEXT sur l'instantané ci-dessus avec XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT listé dans la condition de requête renverra les entités 1, 2 et 5 à l'application, et l'application peut joindre un tableau de XrSpatialBounded2DDataEXT dans la structure XrSpatialComponentBounded2DListEXT à la chaîne suivante de XrSpatialComponentDataQueryResultEXT pour obtenir les données bounded2D.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

5

5

Bounded2D

Bounded2D

Données pour l'entityId 1

Données pour l'entité…

Données pour l'entityId 2

Données pour les entités…

Données pour l'entityId 5

Données pour l'entité…

entityIds

entityIds

suivant

suivant

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

limites

limites

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou... Le texte n'est pas au format SVG et ne peut pas s'afficher

Figure 21. Exemple de résultat de requête

xrQuerySpatialComponentDataEXT sur l'instantané ci-dessus avec les composants XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT et XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT listés dans la condition de requête renverra les entités 3 et 4 à l'application, et l'application peut joindre des tableaux de XrBoxf et XrSpatialMeshDataEXT dans le cadre des structures XrSpatialComponentBounded3DListEXT et XrSpatialComponentMesh3DListEXT respectivement à la prochaine chaîne de XrSpatialComponentDataQueryResultEXT pour obtenir les données du composant.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

Données pour l'entityId 3

Données pour les entités…

Données pour l'entityId 4

Données pour les entités…

Mesh3D

Mesh3D

Données pour l'entityId 3

Données pour les entités…

Données pour l'entityId 4

Données pour les entités…

entityIds

entityIds

suivant

suivant

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

limites

limites

suivant

suivant

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

mailles

meshes Text is not SVG - cannot display

Figure 22. Exemple de résultat de requête

La structure XrSpatialComponentDataQueryConditionEXT est définie comme suit :

typedef struct XrSpatialComponentDataQueryConditionEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialComponentDataQueryConditionEXT;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • componentTypeCount est un uint32_t décrivant le nombre d'éléments dans le tableau componentTypes.
  • componentTypes est un tableau de XrSpatialComponentTypeEXT pour lequel obtenir les données de l'instantané.

Utilisation valide (implicite)

La structure XrSpatialComponentDataQueryResultEXT est définie comme suit :

typedef struct XrSpatialComponentDataQueryResultEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            entityIdCapacityInput;
    uint32_t                            entityIdCountOutput;
    XrSpatialEntityIdEXT*               entityIds;
    uint32_t                            entityStateCapacityInput;
    uint32_t                            entityStateCountOutput;
    XrSpatialEntityTrackingStateEXT*    entityStates;
} XrSpatialComponentDataQueryResultEXT;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • entityIdCapacityInput correspond à la capacité du tableau entityIds ou à 0 pour indiquer une demande de récupération de la capacité requise.
  • entityIdCountOutput correspond au nombre de XrSpatialEntityIdEXT dans entityIds ou à la capacité requise si entityIdCapacityInput est insuffisant.
  • entityIds est un tableau de XrSpatialEntityIdEXT . Elle peut être NULL si entityIdCapacityInput est défini sur 0.
  • entityStateCapacityInput correspond à la capacité du tableau entityStates ou à 0 pour indiquer une demande de récupération de la capacité requise.
  • entityStateCountOutput correspond au nombre de XrSpatialEntityTrackingStateEXT dans entityStates ou à la capacité requise si entityStateCapacityInput est insuffisant. Cette valeur doit toujours être identique à entityIdCountOutput .
  • entityStates est un tableau de XrSpatialEntityTrackingStateEXT . Elle peut être NULL si entityStateCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille entityIds requise, consultez la section Paramètres de taille du tampon.

Une application peut utiliser entityIds avec xrCreateSpatialEntityFromIdEXT pour créer des handles XrSpatialEntityEXT pour les entités pour lesquelles elle souhaite recevoir des mises à jour régulières. L'application peut ensuite utiliser ces handles XrSpatialEntityEXT avec xrCreateSpatialUpdateSnapshotEXT pour créer un instantané de mise à jour contenant les dernières données connues du runtime concernant les composants des entités fournies.

Utilisation valide (implicite)

typedef enum XrSpatialEntityTrackingStateEXT {
    XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT = 1,
    XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT = 2,
    XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT = 3,
    XR_SPATIAL_ENTITY_TRACKING_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialEntityTrackingStateEXT;

L'énumération XrSpatialEntityTrackingStateEXT liste les états de suivi des entités spatiales possibles :

Les énumérations ont les significations suivantes :

Description de l'enum

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

L'exécution a cessé de suivre cette entité et ne reprendra jamais le suivi.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

L'exécution a suspendu le suivi de cette entité, mais pourrait le reprendre à l'avenir.

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

Le runtime suit actuellement cette entité et les données de ses composants sont valides.

SUIVI

MISE EN VEILLE

ARRÊTÉ

Figure 23. XrSpatialEntityTrackingStateEXT

  • Le runtime peut modifier l'état de l'entité spatiale de XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT à XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT s'il suspend le suivi de cette entité spatiale, mais qu'il a la possibilité de le reprendre à l'avenir. Voici quelques exemples de cas où le runtime peut le faire (sans s'y limiter) : si l'application perd le focus d'entrée, si l'entité spatiale donnée est trop éloignée de l'utilisateur pour être suivie avec précision ou si le nombre d'entités suivies est trop élevé et que le runtime souhaite réduire le coût du suivi. XrSpatialEntityTrackingStateEXT aide l'application à s'isoler des différentes stratégies de suivi de chaque environnement d'exécution.
  • L'exécution peut modifier l'état d'une entité de XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT à XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT ou XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT .
  • L'exécution doit modifier l'état de l'entité spatiale de XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT ou XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT à XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT si l'entité spatiale est perdue et que son suivi ne sera jamais récupéré ni repris. Par exemple, si l'appareil perd le suivi, redémarre sa session de suivi, mais ne parvient pas à se relocaliser dans son environnement, il traite les entités découvertes lors de cette session de suivi comme de nouvelles entités.
  • Une fois l'état de suivi d'une entité défini sur XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , le runtime ne doit jamais le modifier pour un autre état.
  • Lors de l'interrogation des données de composant d'une entité spatiale à l'aide de xrQuerySpatialComponentDataEXT , le runtime doit définir des données valides dans le contenu des tampons fournis par l'application dans la chaîne suivante de XrSpatialComponentDataQueryResultEXT si l'état de l'entité est XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . Si l'état de l'entité est XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT ou XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT , le runtime ne doit pas modifier le contenu des tampons.

Expression à deux appels pour les données de composants

La structure XrSpatialBufferEXT est définie comme suit :

typedef struct XrSpatialBufferEXT {
    XrSpatialBufferIdEXT      bufferId;
    XrSpatialBufferTypeEXT    bufferType;
} XrSpatialBufferEXT;

Descriptions des membres

  • bufferId : XrSpatialBufferIdEXT des données du tampon.
  • bufferType est XrSpatialBufferTypeEXT pour indiquer le type de données dans bufferId . L'application peut utiliser bufferType pour déterminer la fonction à utiliser pour récupérer les données réelles du tampon.

Certains composants spatiaux contiennent des données de taille variable et nécessitent donc l'utilisation de l'idiome à deux appels pour récupérer leurs données. Dans ce cas, la structure de données du composant spatial fournit un XrSpatialBufferEXT pour chaque tampon de taille variable nécessaire dans les données de ce composant.

Pour le même bufferId , le runtime doit fournir les mêmes données d'une requête de données de composant à une autre, même d'un instantané à un autre. Un bufferId différent entre les appels de requête de données de composants indique à l'application que les données de ce composant peuvent avoir changé.

Utilisation valide (implicite)

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT permet de représenter n'importe quel type de données de taille variable pour un composant spatial.

L'exécution doit conserver XrSpatialBufferIdEXT et ses données en mémoire pendant au moins le cycle de vie de XrSpatialSnapshotEXT qui le contient. Le runtime peut conserver le XrSpatialBufferIdEXT et ses données en mémoire plus longtemps que le cycle de vie de XrSpatialSnapshotEXT afin de renvoyer le même ID que celui des instantanés créés ultérieurement par l'application. Pour le même XrSpatialBufferIdEXT , le runtime doit toujours renvoyer les mêmes données via la fonction xrGetSpatialBuffer* appropriée.

typedef enum XrSpatialBufferTypeEXT {
    XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT = 0,
    XR_SPATIAL_BUFFER_TYPE_STRING_EXT = 1,
    XR_SPATIAL_BUFFER_TYPE_UINT8_EXT = 2,
    XR_SPATIAL_BUFFER_TYPE_UINT16_EXT = 3,
    XR_SPATIAL_BUFFER_TYPE_UINT32_EXT = 4,
    XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT = 5,
    XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT = 6,
    XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT = 7,
    XR_SPATIAL_BUFFER_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialBufferTypeEXT;

L'énumération XrSpatialBufferTypeEXT identifie les différents types de données du tampon représenté par XrSpatialBufferIdEXT .

Descriptions des énumérants

  • XR_SPATIAL_BUFFER_TYPE_STRING_EXT . Le can XrSpatialBufferIdEXT peut être transmis à xrGetSpatialBufferStringEXT pour récupérer un tampon de chaîne.
  • XR_SPATIAL_BUFFER_TYPE_UINT8_EXT . Le can XrSpatialBufferIdEXT peut être transmis à xrGetSpatialBufferUint8EXT pour récupérer un tampon uint8_t.
  • XR_SPATIAL_BUFFER_TYPE_UINT16_EXT . Le can XrSpatialBufferIdEXT peut être transmis à xrGetSpatialBufferUint16EXT pour récupérer un tampon uint16_t.
  • XR_SPATIAL_BUFFER_TYPE_UINT32_EXT . Le can XrSpatialBufferIdEXT peut être transmis à xrGetSpatialBufferUint32EXT pour récupérer un tampon uint32_t.
  • XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT . Le XrSpatialBufferIdEXT peut être transmis à xrGetSpatialBufferFloatEXT pour récupérer un tampon float.
  • XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT . Le XrSpatialBufferIdEXT can peut être transmis à xrGetSpatialBufferVector2fEXT pour récupérer un tampon XrVector2f.
  • XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT . Le XrSpatialBufferIdEXT peut être transmis à xrGetSpatialBufferVector3fEXT pour récupérer un tampon XrVector3f.

La fonction xrGetSpatialBufferStringEXT est définie comme suit :

XrResult xrGetSpatialBufferStringEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Descriptions des paramètres

  • snapshot est un handle pour un XrSpatialSnapshotEXT .
  • info contient les informations sur la mémoire tampon à interroger.
  • bufferCapacityInput correspond à la capacité du tableau ou à 0 pour indiquer une demande de récupération de la capacité requise.
  • bufferCountOutput correspond au nombre de caractères ou à la capacité requise si bufferCapacityInput est insuffisant.
  • buffer est un tableau de char . Elle peut être NULL si bufferCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille buffer requise, consultez la section Paramètres de taille du tampon.

L'application peut obtenir les données d'un XrSpatialBufferEXT fourni par un composant, où XrSpatialBufferEXT :: bufferType est XR_SPATIAL_BUFFER_TYPE_STRING_EXT en utilisant xrGetSpatialBufferStringEXT .

L'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE si XrSpatialBufferTypeEXT pour XrSpatialBufferGetInfoEXT :: bufferId n'est pas XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

L'exécution doit renvoyer XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId n'appartient pas à snapshot .

buffer rempli par le runtime doit être une chaîne UTF-8 terminée par un caractère nul.

Utilisation valide (implicite)

  •  L'extension XR_EXT_spatial_entity doit être activée avant d'appeler xrGetSpatialBufferStringEXT.
  • snapshot doit être un handle XrSpatialSnapshotEXT valide
  • info must être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput must être un pointeur vers une valeur uint32_t
  •  Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de valeurs char bufferCapacityInput.

Codes de retour

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

La fonction xrGetSpatialBufferUint8EXT est définie comme suit :

XrResult xrGetSpatialBufferUint8EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

Descriptions des paramètres

  • snapshot est un handle pour un XrSpatialSnapshotEXT .
  • info contient les informations sur la mémoire tampon à interroger.
  • bufferCapacityInput correspond à la capacité du tableau ou à 0 pour indiquer une demande de récupération de la capacité requise.
  • bufferCountOutput correspond au nombre d'éléments du tableau buffer ou à la capacité requise si bufferCapacityInput est insuffisant.
  • buffer est un tableau de uint8_t . Elle peut être NULL si bufferCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille buffer requise, consultez la section Paramètres de taille du tampon.

L'application peut obtenir les données d'un XrSpatialBufferEXT fourni par un composant, où XrSpatialBufferEXT :: bufferType est XR_SPATIAL_BUFFER_TYPE_UINT8_EXT en utilisant xrGetSpatialBufferUint8EXT .

L'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE si XrSpatialBufferTypeEXT pour XrSpatialBufferGetInfoEXT :: bufferId n'est pas XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

L'exécution doit renvoyer XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId n'appartient pas à snapshot .

Utilisation valide (implicite)

  •  L'extension XR_EXT_spatial_entity doit être activée avant d'appeler xrGetSpatialBufferUint8EXT.
  • snapshot doit être un handle XrSpatialSnapshotEXT valide
  • info must être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput must être un pointeur vers une valeur uint32_t
  •  Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de valeurs uint8_t de type bufferCapacityInput.

Codes de retour

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

La fonction xrGetSpatialBufferUint16EXT est définie comme suit :

XrResult xrGetSpatialBufferUint16EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint16_t*                                   buffer);

Descriptions des paramètres

  • snapshot est un handle vers un XrSpatialSnapshotEXT .
  • info contient les informations sur la mémoire tampon à interroger.
  • bufferCapacityInput correspond à la capacité du tableau ou à 0 pour indiquer une demande de récupération de la capacité requise.
  • bufferCountOutput correspond au nombre d'éléments du tableau buffer ou à la capacité requise si bufferCapacityInput est insuffisant.
  • buffer est un tableau de uint16_t . Elle peut être NULL si bufferCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille buffer requise, consultez la section Paramètres de taille du tampon.

L'application peut obtenir les données d'un XrSpatialBufferEXT fourni par un composant, où XrSpatialBufferEXT :: bufferType est XR_SPATIAL_BUFFER_TYPE_UINT16_EXT en utilisant xrGetSpatialBufferUint16EXT .

L'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE si XrSpatialBufferTypeEXT pour XrSpatialBufferGetInfoEXT :: bufferId n'est pas XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

L'exécution doit renvoyer XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId n'appartient pas à snapshot .

Utilisation valide (implicite)

  •  L'extension XR_EXT_spatial_entity doit être activée avant d'appeler xrGetSpatialBufferUint16EXT.
  • snapshot doit être un handle XrSpatialSnapshotEXT valide
  • info must être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput must être un pointeur vers une valeur uint32_t
  •  Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de valeurs uint16_t de type bufferCapacityInput.

Codes de retour

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

La fonction xrGetSpatialBufferUint32EXT est définie comme suit :

XrResult xrGetSpatialBufferUint32EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint32_t*                                   buffer);

Descriptions des paramètres

  • snapshot est un handle pour un XrSpatialSnapshotEXT .
  • info contient les informations sur la mémoire tampon à interroger.
  • bufferCapacityInput correspond à la capacité du tableau ou à 0 pour indiquer une demande de récupération de la capacité requise.
  • bufferCountOutput correspond au nombre d'éléments du tableau buffer ou à la capacité requise si bufferCapacityInput est insuffisant.
  • buffer est un tableau de uint32_t . Elle peut être NULL si bufferCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille buffer requise, consultez la section Paramètres de taille du tampon.

L'application peut obtenir les données d'un XrSpatialBufferEXT fourni par un composant, où XrSpatialBufferEXT :: bufferType est XR_SPATIAL_BUFFER_TYPE_UINT32_EXT en utilisant xrGetSpatialBufferUint32EXT .

L'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE si XrSpatialBufferTypeEXT pour XrSpatialBufferGetInfoEXT :: bufferId n'est pas XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

L'exécution doit renvoyer XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId n'appartient pas à snapshot .

Utilisation valide (implicite)

  •  L'extension XR_EXT_spatial_entity doit être activée avant d'appeler xrGetSpatialBufferUint32EXT.
  • snapshot doit être un handle XrSpatialSnapshotEXT valide
  • info must être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput must être un pointeur vers une valeur uint32_t
  •  Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de valeurs uint32_t de type bufferCapacityInput.

Codes de retour

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

La fonction xrGetSpatialBufferFloatEXT est définie comme suit :

XrResult xrGetSpatialBufferFloatEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    float*                                      buffer);

Descriptions des paramètres

  • snapshot est un handle pour un XrSpatialSnapshotEXT .
  • info contient les informations sur la mémoire tampon à interroger.
  • bufferCapacityInput correspond à la capacité du tableau ou à 0 pour indiquer une demande de récupération de la capacité requise.
  • bufferCountOutput correspond au nombre d'éléments du tableau buffer ou à la capacité requise si bufferCapacityInput est insuffisant.
  • buffer est un tableau de float . Elle peut être NULL si bufferCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille buffer requise, consultez la section Paramètres de taille du tampon.

L'application peut obtenir les données d'un XrSpatialBufferEXT fourni par un composant, où XrSpatialBufferEXT :: bufferType est XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT en utilisant xrGetSpatialBufferFloatEXT .

L'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE si XrSpatialBufferTypeEXT pour XrSpatialBufferGetInfoEXT :: bufferId n'est pas XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

L'exécution doit renvoyer XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId n'appartient pas à snapshot .

Utilisation valide (implicite)

  •  L'extension XR_EXT_spatial_entity doit être activée avant d'appeler xrGetSpatialBufferFloatEXT.
  • snapshot doit être un handle XrSpatialSnapshotEXT valide
  • info must être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput must être un pointeur vers une valeur uint32_t
  •  Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de valeurs float de type bufferCapacityInput.

Codes de retour

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

La fonction xrGetSpatialBufferVector2fEXT est définie comme suit :

XrResult xrGetSpatialBufferVector2fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector2f*                                 buffer);

Descriptions des paramètres

  • snapshot est un handle pour un XrSpatialSnapshotEXT .
  • info contient les informations sur la mémoire tampon à interroger.
  • bufferCapacityInput correspond à la capacité du tableau ou à 0 pour indiquer une demande de récupération de la capacité requise.
  • bufferCountOutput correspond au nombre d'éléments du tableau buffer ou à la capacité requise si bufferCapacityInput est insuffisant.
  • buffer est un tableau de XrVector2f . Elle peut être NULL si bufferCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille buffer requise, consultez la section Paramètres de taille du tampon.

L'application peut obtenir les données d'un XrSpatialBufferEXT fourni par un composant, où XrSpatialBufferEXT :: bufferType est XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT en utilisant xrGetSpatialBufferVector2fEXT .

L'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE si XrSpatialBufferTypeEXT pour XrSpatialBufferGetInfoEXT :: bufferId n'est pas XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

L'exécution doit renvoyer XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId n'appartient pas à snapshot .

Utilisation valide (implicite)

  •  L'extension XR_EXT_spatial_entity doit être activée avant d'appeler xrGetSpatialBufferVector2fEXT.
  • snapshot doit être un handle XrSpatialSnapshotEXT valide
  • info must être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput must être un pointeur vers une valeur uint32_t
  •  Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de structures XrVector2f bufferCapacityInput.

Codes de retour

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

La fonction xrGetSpatialBufferVector3fEXT est définie comme suit :

XrResult xrGetSpatialBufferVector3fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector3f*                                 buffer);

Descriptions des paramètres

  • snapshot est un handle vers un XrSpatialSnapshotEXT .
  • info contient les informations sur la mémoire tampon à interroger.
  • bufferCapacityInput correspond à la capacité du tableau ou à 0 pour indiquer une demande de récupération de la capacité requise.
  • bufferCountOutput correspond au nombre d'éléments du tableau buffer ou à la capacité requise si bufferCapacityInput est insuffisant.
  • buffer est un tableau de XrVector3f . Elle peut être NULL si bufferCapacityInput est défini sur 0.
  • Pour obtenir une description détaillée de la récupération de la taille buffer requise, consultez la section Paramètres de taille du tampon.

L'application peut obtenir les données d'un XrSpatialBufferEXT fourni par un composant, où XrSpatialBufferEXT :: bufferType est XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT en utilisant xrGetSpatialBufferVector3fEXT .

L'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE si XrSpatialBufferTypeEXT pour XrSpatialBufferGetInfoEXT :: bufferId n'est pas XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

L'exécution doit renvoyer XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT si XrSpatialBufferGetInfoEXT :: bufferId n'appartient pas à snapshot .

Utilisation valide (implicite)

  •  L'extension XR_EXT_spatial_entity doit être activée avant d'appeler xrGetSpatialBufferVector3fEXT.
  • snapshot doit être un handle XrSpatialSnapshotEXT valide
  • info must être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput must être un pointeur vers une valeur uint32_t
  •  Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de structures XrVector3f de bufferCapacityInput.

Codes de retour

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

La structure XrSpatialBufferGetInfoEXT est définie comme suit :

typedef struct XrSpatialBufferGetInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialBufferIdEXT    bufferId;
} XrSpatialBufferGetInfoEXT;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • bufferId : XrSpatialBufferIdEXT pour le tampon dont les données doivent être récupérées.

Utilisation valide (implicite)

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT est une valeur réservée représentant un XrSpatialBufferIdEXT non valide . Il peut être transmis aux fonctions d'API et renvoyé par celles-ci uniquement lorsque cela est spécifiquement autorisé.

Créer un instantané de mise à jour

La fonction xrCreateSpatialUpdateSnapshotEXT est définie comme suit :

XrResult xrCreateSpatialUpdateSnapshotEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialUpdateSnapshotCreateInfoEXT* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

Descriptions des paramètres

L'application peut utiliser xrCreateSpatialUpdateSnapshotEXT pour créer un instantané et obtenir les dernières données de composants pour des entités spécifiques telles qu'elles sont connues par le moteur d'exécution. Les applications peuvent fournir les handles XrSpatialEntityEXT et les types de composants qui les intéressent lors de la création de l'instantané.

L'application peut utiliser XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes pour filtrer la liste des composants dont les données doivent être incluses dans l'instantané. Si l'application fournit une liste valide de types de composants spatiaux dans XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , le runtime doit uniquement inclure dans le snapshot les entités spatiales qui comportent au moins l'un des composants fournis dans XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . De plus, le runtime doit uniquement inclure les données de ces composants dans l'instantané.

L'exécution doit renvoyer XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT si l'un des XrSpatialComponentTypeEXT dans XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes n'est pas activé pour les capacités spatiales transmises à XrSpatialContextCreateInfoEXT :: capabilityConfigs lors de la création de spatialContext .

Si l'application ne fournit pas de liste de types de composants spatiaux dans XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , le runtime doit inclure toutes les entités spatiales listées dans XrSpatialUpdateSnapshotCreateInfoEXT :: entities dans le snapshot et doit inclure les données de tous les composants activés des fonctionnalités configurées pour spatialContext .

L'exécution ne doit pas inclure d'entités spatiales qui ne sont pas listées dans XrSpatialUpdateSnapshotCreateInfoEXT :: entities dans snapshot .

L'application peut créer autant d'instantanés qu'elle le souhaite, mais elle doit tenir compte de la mémoire allouée à chaque nouvel instantané et doit détruire les instantanés une fois qu'elle n'en a plus besoin.

Utilisation valide (implicite)

Codes de retour

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_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La structure XrSpatialUpdateSnapshotCreateInfoEXT est définie comme suit :

typedef struct XrSpatialUpdateSnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            entityCount;
    const XrSpatialEntityEXT*           entities;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
    XrSpace                             baseSpace;
    XrTime                              time;
} XrSpatialUpdateSnapshotCreateInfoEXT;

Descriptions des membres

  • 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 l'extension ni dans le cœur d'OpenXR.
  • entityCount est un uint32_t décrivant le nombre d'éléments dans le tableau entities.
  • entities est un tableau de XrSpatialEntityEXT pour lequel le runtime doit inclure les données du composant dans l'instantané.
  • componentTypeCount est un uint32_t décrivant le nombre d'éléments dans le tableau componentTypes.
  • componentTypes est un tableau de XrSpatialComponentTypeEXT pour lequel le runtime doit inclure les données dans l'instantané.
  • baseSpace est le XrSpace par rapport auquel tous les emplacements de la mise à jour XrSpatialSnapshotEXT seront situés.
  • time est le XrTime dans lequel se trouveront tous les emplacements de la mise à jour XrSpatialSnapshotEXT.

Utilisation valide (implicite)

  •  L'extension XR_EXT_spatial_entity doit être activée avant d'utiliser XrSpatialUpdateSnapshotCreateInfoEXT.
  • type doit être XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT.
  • next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.
  • entities doit être un pointeur vers un tableau de entityCount descripteurs XrSpatialEntityEXT valides.
  •  Si componentTypeCount n'est pas 0 , componentTypes doit être un pointeur vers un tableau de componentTypeCount valeurs XrSpatialComponentTypeEXT valides.
  • baseSpace doit être un handle XrSpace valide
  •  Le paramètre entityCount doit être supérieur à 0
  •  baseSpace et les éléments de entities doivent avoir été créés, alloués ou récupérés à partir de la même XrSession.

Détruire un instantané

La fonction xrDestroySpatialSnapshotEXT est définie comme suit :

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

Descriptions des paramètres

L'application peut appeler xrDestroySpatialSnapshotEXT pour détruire le handle XrSpatialSnapshotEXT et les ressources qui y sont associées.

Utilisation valide (implicite)

Sécurité des threads

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

Codes de retour

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Composants courants

2D limitée

Données des composants

La structure XrSpatialBounded2DDataEXT est définie comme suit :

typedef struct XrSpatialBounded2DDataEXT {
    XrPosef        center;
    XrExtent2Df    extents;
} XrSpatialBounded2DDataEXT;

Descriptions des membres

  • center est une XrPosef qui définit le centre géométrique du composant 2D limité.
  • extents correspond aux limites du composant 2D limité le long de l'axe X (extents.width) et de l'axe Y (extents.height), centré sur center .

Les extents de XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT font référence à la taille de l'entité dans le plan x-y du système de coordonnées du plan. Un plan avec une position de {0, 0, 0}, une rotation de {0, 0, 0, 1} (aucune rotation) et une étendue de {1, 1} fait référence à un plan de 1 mètre x 1 mètre centré sur {0, 0, 0} avec son vecteur normal de face avant pointant vers la direction +Z dans l'espace du composant.

X X Y Y Z Z Hauteur Hauteur Y Y Z Z X X Plan vertical Plan vertical Plan horizontal Plan horizontal Largeur Largeur Largeur Largeur Hauteur Hauteur

Figure 24. Système de coordonnées du composant Bounded2D

Remarque

OpenXR utilise un plan X-Y avec +Z comme normale du plan, mais d'autres API peuvent utiliser un plan X-Z avec +Y comme normale du plan. Le plan X-Y peut être converti en plan X-Z en effectuant une rotation de -π/2 radians autour de l'axe X positif.

Utilisation valide (implicite)

Structure de la liste des composants pour interroger les données

La structure XrSpatialComponentBounded2DListEXT est définie comme suit :

typedef struct XrSpatialComponentBounded2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      boundCount;
    XrSpatialBounded2DDataEXT*    bounds;
} XrSpatialComponentBounded2DListEXT;

Descriptions des membres

  • 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 l'extension ni dans le cœur d'OpenXR.
  • boundCount est un uint32_t décrivant le nombre d'éléments dans le tableau bounds.
  • bounds est un tableau de XrSpatialBounded2DDataEXT .

Le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrQuerySpatialComponentDataEXT si XrSpatialComponentBounded2DListEXT se trouve dans la chaîne suivante de XrSpatialComponentDataQueryResultEXT :: next, mais que XrSpatialComponentDataQueryConditionEXT ::componentTypeCount n'est pas nul et que XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Le runtime doit renvoyer XR_ERROR_SIZE_INSUFFICIENT à partir de xrQuerySpatialComponentDataEXT si boundCount est inférieur à XrSpatialComponentDataQueryResultEXT::entityIdCountOutput .

Si xrQuerySpatialComponentDataEXT :: snapshot a été créé à partir de xrCreateSpatialDiscoverySnapshotCompleteEXT , le runtime doit fournir XrSpatialBounded2DDataEXT :: center dans XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace et XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Si xrQuerySpatialComponentDataEXT :: snapshot a été créé à partir de xrCreateSpatialUpdateSnapshotEXT , le runtime doit fournir XrSpatialBounded2DDataEXT :: center dans XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace et XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Utilisation valide (implicite)

Configuration

Si XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT est énuméré dans XrSpatialCapabilityComponentTypesEXT :: componentTypes pour une fonctionnalité, l'application peut l'activer en incluant la valeur d'énumération dans la liste XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Ce composant ne nécessite aucune configuration spéciale pour être inclus dans la prochaine chaîne de XrSpatialCapabilityConfigurationBaseHeaderEXT .

3D limitée

Données des composants

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT utilise XrBoxf pour ses données.

Structure de la liste des composants pour interroger les données

La structure XrSpatialComponentBounded3DListEXT est définie comme suit :

typedef struct XrSpatialComponentBounded3DListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           boundCount;
    XrBoxf*            bounds;
} XrSpatialComponentBounded3DListEXT;

Descriptions des membres

  • 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 l'extension ni dans le cœur d'OpenXR.
  • boundCount est un uint32_t décrivant le nombre d'éléments dans le tableau bounds.
  • bounds est un tableau de XrBoxf .

Le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrQuerySpatialComponentDataEXT si XrSpatialComponentBounded3DListEXT se trouve dans la chaîne suivante de XrSpatialComponentDataQueryResultEXT :: next, mais que XrSpatialComponentDataQueryConditionEXT ::componentTypeCount n'est pas nul et que XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Le runtime doit renvoyer XR_ERROR_SIZE_INSUFFICIENT à partir de xrQuerySpatialComponentDataEXT si boundCount est inférieur à XrSpatialComponentDataQueryResultEXT::entityIdCountOutput .

Si xrQuerySpatialComponentDataEXT :: snapshot a été créé à partir de xrCreateSpatialDiscoverySnapshotCompleteEXT , le runtime doit fournir XrBoxf :: center dans XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace à XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Si xrQuerySpatialComponentDataEXT :: snapshot a été créé à partir de xrCreateSpatialUpdateSnapshotEXT , le runtime doit fournir XrBoxf :: center dans XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace à XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Utilisation valide (implicite)

Configuration

Si XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT est énuméré dans XrSpatialCapabilityComponentTypesEXT :: componentTypes pour une fonctionnalité, l'application peut l'activer en incluant l'énumération dans la liste XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Ce composant ne nécessite aucune configuration spéciale pour être inclus dans la prochaine chaîne de XrSpatialCapabilityConfigurationBaseHeaderEXT .

Parent

Données des composants

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT utilise XrSpatialEntityIdEXT pour ses données.

Structure de la liste des composants pour interroger les données

La structure XrSpatialComponentParentListEXT est définie comme suit :

typedef struct XrSpatialComponentParentListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 parentCount;
    XrSpatialEntityIdEXT*    parents;
} XrSpatialComponentParentListEXT;

Descriptions des membres

  • 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 l'extension ni dans le cœur d'OpenXR.
  • parentCount est un uint32_t décrivant le nombre d'éléments dans le tableau parents.
  • parents est un tableau de XrSpatialEntityIdEXT .

Le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrQuerySpatialComponentDataEXT si XrSpatialComponentParentListEXT se trouve dans la chaîne suivante de XrSpatialComponentDataQueryResultEXT : next, mais XrSpatialComponentDataQueryConditionEXT::componentTypeCount n'est pas nul et XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT::componentTypes .

Le runtime doit renvoyer XR_ERROR_SIZE_INSUFFICIENT à partir de xrQuerySpatialComponentDataEXT si parentCount est inférieur à XrSpatialComponentDataQueryResultEXT::entityIdCountOutput .

Utilisation valide (implicite)

  •  L'extension XR_EXT_spatial_entity doit être activée avant d'utiliser XrSpatialComponentParentListEXT.
  • type doit être XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT.
  • next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.
  • parents must être un pointeur vers un tableau de valeurs parentCount XrSpatialEntityIdEXT
  •  Le paramètre parentCount doit être supérieur à 0
Configuration

Si XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT est énuméré dans XrSpatialCapabilityComponentTypesEXT :: componentTypes pour une fonctionnalité, l'application peut l'activer en incluant l'énumération dans la liste XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Ce composant ne nécessite aucune configuration spéciale pour être inclus dans la prochaine chaîne de XrSpatialCapabilityConfigurationBaseHeaderEXT .

Maillage 3D

Données des composants

La structure XrSpatialMeshDataEXT est définie comme suit :

typedef struct XrSpatialMeshDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
    XrSpatialBufferEXT    indexBuffer;
} XrSpatialMeshDataEXT;

Descriptions des membres

  • origin est une XrPosef qui définit l'origine du maillage. Tous les sommets du maillage doivent être relatifs à cette origine.
  • vertexBuffer est un XrSpatialBufferEXT qui fournit l'ID d'un tampon représentant le tampon de vertex de l'entité sur laquelle se trouve ce composant. La position des sommets doit être relative à origin .
  • indexBuffer est un XrSpatialBufferEXT qui fournit l'ID d'un tampon représentant un tableau d'indices de triangles, spécifiant les indices des sommets du maillage dans vertexBuffer . Les indices de triangle doivent être renvoyés dans le sens inverse des aiguilles d'une montre, et trois indices désignent un triangle.

Le type de composant utilisant XrSpatialMeshDataEXT doit spécifier le XrSpatialBufferTypeEXT de vertexBuffer et indexBuffer .

Utilisation valide (implicite)

Structure de la liste des composants pour interroger les données

La structure XrSpatialComponentMesh3DListEXT est définie comme suit :

typedef struct XrSpatialComponentMesh3DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh3DListEXT;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • meshCount est un uint32_t décrivant le nombre d'éléments dans le tableau meshes.
  • meshes est un tableau de XrSpatialMeshDataEXT .

L'application peut interroger le composant 3D du maillage des entités spatiales dans un XrSpatialSnapshotEXT en ajoutant XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT dans XrSpatialComponentDataQueryConditionEXT::componentTypes et en ajoutant XrSpatialComponentMesh3DListEXT à la chaîne de pointeurs suivante de XrSpatialComponentDataQueryResultEXT .

Le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrQuerySpatialComponentDataEXT si XrSpatialComponentMesh3DListEXT se trouve dans la chaîne suivante de XrSpatialComponentDataQueryResultEXT :: next, mais que XrSpatialComponentDataQueryConditionEXT ::componentTypeCount n'est pas nul et que XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Le runtime doit renvoyer XR_ERROR_SIZE_INSUFFICIENT à partir de xrQuerySpatialComponentDataEXT si meshCount est inférieur à XrSpatialComponentDataQueryResultEXT::entityIdCountOutput .

Pour XrSpatialMeshDataEXT rempli par le runtime dans le tableau meshes, XrSpatialBufferEXT :: bufferType pour XrSpatialMeshDataEXT :: vertexBuffer doit être XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT et XrSpatialBufferEXT :: bufferType pour XrSpatialMeshDataEXT :: indexBuffer doit être XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Utilisation valide (implicite)

Configuration

Si XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT est énuméré dans XrSpatialCapabilityComponentTypesEXT :: componentTypes pour une fonctionnalité, l'application peut l'activer en incluant l'énumération dans la liste XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents de la structure dérivée XrSpatialCapabilityConfigurationBaseHeaderEXT de la fonctionnalité qui prend en charge ce composant.

Ce composant ne nécessite aucune configuration spéciale pour être inclus dans la prochaine chaîne de XrSpatialCapabilityConfigurationBaseHeaderEXT .

Filtres d'état du suivi

La structure XrSpatialFilterTrackingStateEXT est définie comme suit :

typedef struct XrSpatialFilterTrackingStateEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialEntityTrackingStateEXT    trackingState;
} XrSpatialFilterTrackingStateEXT;

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • trackingState correspond à XrSpatialEntityTrackingStateEXT pour lequel l'application souhaite appliquer le filtre.

L'application peut utiliser XrSpatialFilterTrackingStateEXT dans la chaîne suivante de XrSpatialDiscoverySnapshotCreateInfoEXT pour limiter la découverte aux entités dont l'état de suivi est trackingState .

L'application peut utiliser XrSpatialFilterTrackingStateEXT dans la chaîne suivante de XrSpatialComponentDataQueryConditionEXT pour limiter la requête de données de composant à partir d'un instantané uniquement aux entités dont l'état de suivi est trackingState .

Utilisation valide (implicite)

Exemple de code

Utilisation des applications

Les applications utilisent généralement l'extension d'entité spatiale comme suit :

Découvrir les entités spatiales et interroger les données des composants

L'exemple de code suivant montre comment découvrir des entités spatiales pour la requête de capacité "Foo" et interroger ses données de composants.

/****************************/
/* Capability definition    */
/****************************/
// Foo capability has the following components -
// - XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
#define XR_SPATIAL_CAPABILITY_FOO ((XrSpatialCapabilityEXT)1000740000U)

#define XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT ((XrStructureType)1000740000U)
// Derives from XrSpatialCapabilityConfigurationBaseHeaderEXT
typedef struct XrSpatialCapabilityConfigurationFooEXT {
  XrStructureType                     type;
  const void* XR_MAY_ALIAS            next;
  XrSpatialCapabilityEXT              capability;
  uint32_t                            enabledComponentCount;
  const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationFooEXT;

/******************************/
/* End capability definition  */
/******************************/

auto waitUntilReady = [](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  };

  // Configure Foo capability for the spatial context
  XrSpatialCapabilityConfigurationFooEXT fooConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT};
  fooConfig.capability = XR_SPATIAL_CAPABILITY_FOO;
  fooConfig.enabledComponentCount = enabledComponents.size();
  fooConfig.enabledComponents = enabledComponents.data();

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&fooConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components.
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT future = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT;
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = &componentToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    queryResult.entityIdCapacityInput = 0;
    queryResult.entityIds = nullptr;
    queryResult.entityStateCapacityInput = 0;
    queryResult.entityStates = nullptr;
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        // 2D extents for entity entityIds[i] is bounded2d[i].extents.
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Interroger les données du tampon de requête

L'exemple de code suivant montre comment obtenir les données d'un composant qui fournit un XrSpatialBufferEXT .

/****************************/
/* Component definition     */
/****************************/
// Foo component that provides an XrVector3f buffer
#define XR_SPATIAL_COMPONENT_TYPE_FOO_EXT ((XrSpatialComponentTypeEXT)1000740000U)

#define XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT ((XrStructureType)1000740000U)

// XrSpatialComponentFooListEXT extends XrSpatialComponentDataQueryResultEXT
typedef struct XrSpatialComponentFooListEXT {
    XrStructureType                   type;
    void* XR_MAY_ALIAS                next;
    uint32_t                          fooCount;
    XrSpatialBufferEXT*               foo;
} XrSpatialComponentFooListEXT;

/******************************/
/* End Component definition  */
/******************************/

// Query for the foo component data
XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_FOO_EXT;
XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = &componentToQuery;

XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();

std::vector<XrSpatialBufferEXT> fooBuffers(queryResult.entityIdCountOutput);
XrSpatialComponentFooListEXT fooList{XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT};
fooList.fooCount = fooBuffers.size();
fooList.foo = fooBuffers.data();
queryResult.next = &fooList;

CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // foo component data for entity entityIds[i]
  if (fooBuffers[i].bufferType == XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT) {
    XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
    getInfo.bufferId = fooBuffers[i].bufferId;
    uint32_t bufferCountOutput;
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, 0, &bufferCountOutput, nullptr));
    std::vector<XrVector3f> vertexBuffer(bufferCountOutput);
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, bufferCountOutput, &bufferCountOutput, vertexBuffer.data()));

    // XrVertex3f buffer for entity entityIds[i] is now available in vertexBuffer vector.
  }
}

Consignes relatives aux extensions

  • Si une extension définit un nouveau XrSpatialComponentTypeEXT qui fournit des données supplémentaires sur une entité spatiale,

  • Les extensions peuvent définir des structures qui étendent XrSpatialDiscoverySnapshotCreateInfoEXT pour fournir des filtres de découverte supplémentaires. Les filtres permettant de créer l'instantané ne doivent pas affecter la configuration du contexte spatial. Ils doivent plutôt être utilisés pour fournir des indications au runtime sur les entités et les données à inclure dans l'instantané, telles qu'elles sont suivies par la configuration actuelle du contexte spatial (et donc par la configuration actuelle des services sous-jacents).

  • Si une extension définit une nouvelle XrSpatialCapabilityEXT ,

  • Si une extension définit une nouvelle XrSpatialCapabilityFeatureEXT , elle doit également définir une structure de configuration correspondante qui peut être enchaînée au pointeur suivant de XrSpatialCapabilityConfigurationBaseHeaderEXT , que l'application peut utiliser pour activer la fonctionnalité lors de la création d'un XrSpatialContextEXT .

  • Une extension définissant une nouvelle XrSpatialCapabilityEXT doit suivre ce modèle pour la spécification :

    • Présentation
    • Prise en charge des environnements d'exécution
    • Configuration
    • Composants garantis
    • Exemple de code

  • Une extension définissant un nouveau XrSpatialComponentTypeEXT doit suivre ce modèle pour la spécification :

    • Données des composants
    • Structure de la liste des composants pour interroger les données
    • Configuration

  • Lors de l'écriture d'une API qui fournit à l'application un XrSpatialBufferIdEXT , elle doit être accompagnée d'un XrSpatialBufferTypeEXT pour informer l'application du type de données du tampon. L'application peut utiliser une fonction xrGetSpatialBuffer* appropriée pour récupérer le contenu réel du tampon.

Consignes de conception et d'extension des libellés sémantiques

Bien que cette extension ne définisse aucun composant permettant de transmettre les informations sur le libellé sémantique d'une entité, elle établit les règles de conception et les consignes pour toutes les extensions qui définissent un tel composant. Dans le texte suivant, les termes should (devrait) et must (doit) contraignent les auteurs de telles fonctionnalités, plutôt qu'une implémentation d'exécution ou une application utilisant l'API.

  • Si une extension définit des libellés sémantiques pour une XrSpatialCapabilityEXT , elle doit le faire en définissant une nouvelle XrSpatialComponentTypeEXT ainsi qu'une nouvelle énumération avec un ensemble de libellés (un "ensemble de libellés sémantiques") pour être les données de ce composant.
  • Une énumération représentant un ensemble de libellés sémantiques doit avoir une valeur pour indiquer que l'entité n'est classée dans aucun des libellés de cet ensemble. Le nom de cet énumérant doit inclure "UNCATEGORIZED", par exemple XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT. Cette valeur indique aux applications que le runtime reconnaît cette entité, mais qu'il existe d'autres ensembles d'étiquettes sémantiques dans lesquels cette entité est classée.
  • L'énumération de ce XrSpatialComponentTypeEXT nouvellement défini dans xrEnumerateSpatialCapabilityComponentTypesEXT implique que le runtime est compatible avec l'ensemble de libellés sémantiques (et donc avec les libellés définis dans l'ensemble) correspondant à ce type de composant.
  • Les applications expriment leur souhait de découvrir des entités dont les libellés appartiennent à cet ensemble de libellés sémantiques en incluant le XrSpatialComponentTypeEXT correspondant dans le tableau enabledComponents de XrSpatialCapabilityConfigurationBaseHeaderEXT de la structure de configuration pour la fonctionnalité pour laquelle le type de composant est énuméré.
  • Il est possible qu'une même entité spatiale comporte plusieurs composants, chacun lui fournissant un libellé à partir de son propre ensemble de libellés sémantiques. Prenons l'exemple suivant avec des ensembles de libellés sémantiques hypothétiques : XrSpatialObjectSemanticLabel , qui peuvent avoir des valeurs telles que "chaise", "canapé", "table", etc. XrSpatialSofaBrand , qui peut avoir des valeurs telles que IKEA, Wayfair, etc., et XrSpatialIkeaSofa , qui peut avoir des noms de modèles IKEA spécifiques pour les canapés. Dans ce scénario, la même entité de canapé comporte les trois composants (libellés des trois ensembles de libellés sémantiques), chacun fournissant un niveau de précision différent sur l'entité.
  • Si une extension définit un nouveau XrSpatialComponentTypeEXT qui fournit un nouvel ensemble d'étiquettes sémantiques contenant plusieurs étiquettes en plus de l'étiquette UNCATEGORIZED, l'extension doit envisager de définir un XrSpatialCapabilityFeatureEXT qui permet aux applications d'activer uniquement un sous-ensemble des étiquettes définies dans l'ensemble d'étiquettes sémantiques correspondant à ce type de composant. Ce sous-ensemble, fourni dans la chaîne suivante de la configuration des capacités, sert d'indication aux runtimes pour optimiser leurs pipelines de suivi et ne suivre que le sous-ensemble fourni. Vous trouverez un exemple de structure de caractéristiques ci-dessous .
  • Les extensions ne doivent pas ajouter de libellés à l'énumération existante de l'ensemble de libellés sémantiques. Ils doivent plutôt définir une nouvelle énumération contenant des énumérants équivalents avec une sémantique identique et des valeurs égales à celles de l'autre ensemble, en plus des énumérants nouvellement ajoutés. La spécification du nouvel ensemble de libellés sémantiques doit également établir le mappage entre l'ancien et le nouveau. Consultez l'exemple ci-dessous .
Exemple de définition de fonctionnalité spatiale pour un sous-ensemble de libellés sémantiques
// New example semantic label set.
typedef enum XrSpatialExampleSemanticLabelEXT {
  // ... label values
} XrSpatialExampleSemanticLabelEXT;

/*
typedef enum XrSpatialCapabilityFeatureEXT {
  // .. existing values

  // new spatial feature value
  XR_SPATIAL_CAPABILITY_FEATURE_EXAMPLE_SEMANTIC_LABEL_SUBSET_EXT

  // .. existing values
} XrSpatialCapabilityFeatureEXT;
*/

// New spatial feaure configuration structure
typedef struct XrSpatialFeatureExampleSemanticLabelSubsetEXT {
    XrStructureType                             type;
    const void* XR_MAY_ALIAS                    next;
    uint32_t                                    semanticLabelCount;
    const XrSpatialExampleSemanticLabelEXT*     semanticLabels;
} XrSpatialFeatureExampleSemanticLabelSubsetEXT;
Exemple d'extension de libellé sémantique spatial
typedef enum XrSpatialExamplePlaneSemanticLabelExtensionEXT {
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT = 2,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT = 3,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT = 4,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT = 5,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT = 6,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT = 7,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialExamplePlaneSemanticLabelExtensionEXT;

Prenons l'exemple ci-dessus, où une extension définit une énumération XrSpatialExamplePlaneSemanticLabelExtensionEXT afin d'étendre XrSpatialPlaneSemanticLabelEXT avec des valeurs représentant des portes et des fenêtres. La spécification de la nouvelle énumération doit inclure du texte pour le formulaire suivant :

For all non-UNCATEGORIZED label enumerants in elink:XrSpatialPlaneSemanticLabelEXT,
the runtime must: return that enumerant if and only if it returns the corresponding
label enumerant from elink:XrSpatialExamplePlaneSemanticLabelExtensionEXT with the same value
i.e.
the ename:XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT value for that entity must:
correspond with the ename:XR_SPATIAL_COMPONENT_TYPE_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_EXT values
according to the following table -

[width="100%",options="header"]
|====
| XrSpatialExamplePlaneSemanticLabelExtensionEXT                | XrSpatialPlaneSemanticLabelEXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT | XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT  | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
|====

Nouvelles macros

Nouveaux types de bases

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

Nouveaux types d'objets

Nouvelles commandes

Nouvelles structures

Nouveaux enums

Nouvelles constantes d'énumération

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • Extension de XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • Prolonger XrResult :

    • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
    • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT

  • Extension de XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
    • XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
    • XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT

Problèmes

  • Une seule entité dérive-t-elle toujours d'une seule capacité ?

    • Résolu
    • Réponse : Non. C'est entièrement au runtime de décider, en fonction de ses propres capacités de suivi et de la manière dont il souhaite représenter une entité détectée. La spécification ne prescrit aucune représentation particulière d'une entité spatiale, à l'exception des composants garantis d'une capacité donnée pour définir une attente minimale. Un environnement d'exécution peut être en mesure de fusionner des entités détectées par des fonctionnalités distinctes et de les représenter sous la forme d'une seule entité avec les composants garantis de toutes les fonctionnalités qui ont permis de l'identifier. Par exemple, les tables peuvent être détectées à la fois par une fonctionnalité de suivi des plans et une fonctionnalité de suivi des objets. Le suivi des plans fournit le composant XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT sur l'entité, tandis que le suivi des objets fournit XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT. Un certain environnement d'exécution peut fournir le tableau sous la forme de deux entités distinctes, chacune avec son propre ensemble de composants garantis, tandis que certains environnements d'exécution peuvent ne fournir qu'une seule entité pour représenter le tableau, et avoir à la fois XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT et XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT sur la même entité. Il est important de noter qu'une entité spatiale donnée ne peut comporter qu'un seul composant d'un type de composant donné . Par conséquent, si les données de composants produites par les différentes fonctionnalités sont en conflit pour une entité donnée, le runtime doit les représenter sous la forme de deux entités distinctes.

Historique des versions

  • Révision 1, 12/04/2024 (Nihav Jain, Google)

    • Description initiale de l'extension