XR_EXT_spatial_entity

Name String

XR_EXT_spatial_entity

Type d'extension

Extension d'instance

Numéro d'extension enregistré

741

Révision

1

État de la ratification

Ratifié

Dépendances d'extension et de version

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 principes fondamentaux de la compréhension des scènes et du raisonnement spatial dans OpenXR. Cela unifie plusieurs domaines de fonctionnalités liés mais distincts, qui sont énumérés, configurés et interagissent de manière globalement uniforme, comme défini par cette extension. Comme cette extension ne contient pas de définitions concrètes de l'un de ces domaines fonctionnels, le texte de la spécification formelle a tendance à être quelque peu abstrait. Les exemples inclus dans le texte de cette spécification d'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.

Les principaux éléments de cette extension sont les suivants :

  • Entités spatiales : la fonctionnalité est centrée sur les entités , qui fournissent très peu de fonctionnalités par 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 possède au plus un seul composant d'un type de composant donné.
  • Contexte spatial : toutes les interactions avec les entités spatiales se produisent dans un contexte après une phase d'initialisation et de configuration.
  • Fonctionnalités spatiales : la manipulation des entités spatiales est largement assurée par les fonctionnalités . Une capacité est une unité de fonctionnalité, par exemple (sans s'y limiter) des 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 capacité spécifie les types de composants obligatoires pour la capacité ("garantis"), tandis que cette même extension ou d'autres peuvent spécifier des types de composants facultatifs fournis par certaines implémentations potentielles. Un nombre illimité de capacités peut fournir des entités avec des composants d'un type de composant donné, qui sont utilisables de manière uniforme, quelle que soit la capacité qui les a produites.
  • Caractéristiques des fonctionnalités spatiales : certaines fonctionnalités nécessitent une configuration et sont donc paramétrées par des caractéristiques de fonctionnalités .

Cette extension fournit un mécanisme permettant d'énumérer les composants fournis par chaque capacité compatible avec le système actuel, qu'il s'agisse de composants obligatoires ou facultatifs.

Comme certaines implémentations peuvent nécessiter différents degrés de paramétrage 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 sont associées à diverses données organisées en composants. Il peut s'agir de l'un des éléments suivants :

  • Physique (par exemple, surfaces planes comme les murs et les sols, objets comme les chaises et les bibliothèques, etc.)
  • Virtuel (par exemple, contenu placé et partagé par une autre application ou un autre utilisateur)
  • Définis par l'application (par exemple, l'application marque une zone comme "salle de séjour" ou "cuisine", ou marque un point comme l'emplacement où placer le téléviseur, etc.)

Les éléments exposés via le système d'action, tels que les manettes ou le suivi oculaire, 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 d'entités-composants . 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, dont les détails sont fournis dans la section Représentations des 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é. Consultez Composants courants pour découvrir certains composants courants définis par cette extension.

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_GEOMETRY_POINT_ANDROID = 1000803000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1 = 1000808000,
    XR_SPATIAL_COMPONENT_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

L'énumération XrSpatialComponentTypeEXT identifie les différents types de composants que l'environnement 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. 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 l'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 une étiquette 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 d'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 planaire. La structure de liste correspondante est XrSpatialComponentImage2DListEXT. 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 étiquettes sémantiques par sommet 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 à XrSpatialMeshSemanticLabelEXT (ajouté par l'extension XR_EXT_spatial_mesh_tracking).

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

Composant qui fournit les étiquettes sémantiques par face triangulaire 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 à 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 de délimitation. La structure de liste correspondante est XrSpatialComponentMaterialTypeListANDROIDSYS. La structure de données correspondante est XrSpatialMaterialTypeANDROIDSYS (ajouté par l'extension XR_ANDROIDSYS_spatial_room_tracking).

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

Composant qui fournit la confiance d'un élément traçable. 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 fournit l'état de vide d'une pièce. 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 quadrilatère. 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 de paysage urbain. La structure de liste correspondante est XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2. La structure de données correspondante est XrSpatialStreetscapeGeometryMetadataANDROIDX2 (ajouté par l'extension XR_ANDROIDX2_geospatial_streetscape).

XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID

Composant qui identifie une entité en tant que point géométrique. Il n'existe pas de liste ni de structure de données correspondante pour ce type de composant. La présence de ce composant indique simplement qu'une entité peut être associée à une ancre. (Ajouté par l'extension XR_ANDROID_spatial_geometry_point)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1

Composant décrivant le ou les champs d'application de persistance dans lesquels l'entité est conservée. Si l'environnement d'exécution est compatible avec XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT, il doit également être compatible avec ce composant. La structure de données correspondante est XrSpatialBufferEXT . La structure de liste correspondante est XrSpatialComponentPersistenceScopeDataListANDROIDX1 . (Ajouté par l'extension XR_ANDROIDX1_spatial_anchor_cloud_sharing)

Fonctionnalités spatiales et configuration

Les fonctionnalités spatiales définissent les capacités d'un environnement d'exécution à découvrir des entités qui disposent d'un ensemble garanti de composants. Les applications activent les composants d'une fonctionnalité spatiale lors de la création de XrSpatialContextEXT, et l'environnement d'exécution doit à son tour ne fournir que les composants activés sur les entités découvertes. Par exemple, si un environnement d'exécution 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 l'environnement d'exécution doit ne fournir le composant de libellé sémantique que 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 fonctionnalités que l'environnement 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 plans (ajouté par l'extension XR_EXT_spatial_plane_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

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

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

Capacité à détecter et à suivre les codes Micro 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

Capacité à 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

Capacité à 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 sur le tampon de profondeur (ajouté par l'extension XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

Possibilité de suivre un salon (ajoutée par l'extension XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

Capacité à suivre les limites 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 de 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);

Description des paramètres

  • instance est un handle vers un XrInstance .
  • systemId est l'élément XrSystemId dont les capacités spatiales seront énumérées.
  • capabilityCapacityInput est la capacité du tableau capabilities, ou 0 pour indiquer une requête de récupération de la capacité requise.
  • capabilityCountOutput est le nombre de capacités ou la capacité requise si capabilityCapacityInput est insuffisant.
  • capabilities est un tableau de XrSpatialCapabilityEXT . Il peut être NULL si capabilityCapacityInput est égal à 0.
  • Consultez la section Paramètres de taille de la mémoire tampon pour obtenir une description détaillée de la récupération de la taille capabilities requise.

L'application peut énumérer la liste des fonctionnalités spatiales compatibles avec un XrSystemId donné à l'aide de xrEnumerateSpatialCapabilitiesEXT .

L'environnement d'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 doit être un pointeur vers une valeur uint32_t
  • Si capabilityCapacityInput n'est pas 0 , capabilities doit être un pointeur vers un tableau de valeurs capabilityCapacityInput XrSpatialCapabilityEXT

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La fonction xrEnumerateSpatialCapabilityComponentTypesEXT est définie comme suit :

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

Description des paramètres

  • instance est un handle vers un XrInstance .
  • systemId est l'XrSystemId dont les composants de capacité spatiale seront énumérés.
  • capability est le 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é par l'application est renseigné.

Cette fonction énumère les types de composants que la capacité 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 compatibles avec systemId pour capability et peut utiliser cette liste pour déterminer une configuration valide pour capability lors de la création d'un XrSpatialContextEXT pour celui-ci.

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

L'environnement d'exécution ne doit pas énumérer les types de composants spatiaux dont l'extension n'est pas activée pour instance .

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_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 OpenXR de base ou dans cette extension.
  • componentTypeCapacityInput est la capacité du tableau, ou 0 pour indiquer une requête de récupération de la capacité requise.
  • componentTypeCountOutput est le nombre de types de composants ou la capacité requise si componentTypeCapacityInput est insuffisant.
  • componentTypes est un tableau de XrSpatialComponentTypeEXT . Il peut être NULL si componentTypeCapacityInput est égal à 0.
  • Consultez la section Paramètres de taille de la mémoire tampon pour obtenir une description détaillée de la récupération de la taille componentTypes requise.

Utilisation valide (implicite)

Fonctionnalités spatiales

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 du composant sont calculées par l'environnement d'exécution. Ces dimensions de paramétrage/configurabilité sont appelées "fonctionnalités de capacité". Par exemple, pour une fonctionnalité de suivi d'image, un environnement d'exécution peut prendre en charge une fonctionnalité permettant à l'application de spécifier si les images suivies sont fixes ou non.

La transmission de ces informations à l'environnement d'exécution 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, l'environnement d'exécution 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 associé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 de spécifier 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 d'étiquettes de XrSpatialObjectSemanticLabelEXT pour que l'environnement d'exécution 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

L'environnement d'exécution est compatible avec le filtre XrSpatialBoundsSpherefANDROID pour XrSpatialDiscoverySnapshotCreateInfoEXT. Cela ne nécessite pas l'inclusion d'une structure de configuration 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

L'environnement d'exécution est compatible avec le filtre XrSpatialBoundsBoxfANDROID pour XrSpatialDiscoverySnapshotCreateInfoEXT. Cela ne nécessite pas l'inclusion d'une structure de configuration 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

L'environnement d'exécution 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

L'environnement d'exécution 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);

Description des paramètres

  • instance est un handle vers un XrInstance .
  • systemId est l'XrSystemId dont les fonctionnalités spatiales seront énumérées.
  • capability est l'XrSpatialCapabilityEXT pour lequel les fonctionnalités seront énumérées.
  • capabilityFeatureCapacityInput est la capacité du tableau, ou 0 pour indiquer une requête de récupération de la capacité requise.
  • capabilityFeatureCountOutput est le nombre de caractéristiques ou la capacité requise si capabilityFeatureCapacityInput est insuffisant.
  • capabilityFeatures est un tableau de XrSpatialCapabilityFeatureEXT . Il peut être NULL si capabilityFeatureCapacityInput est égal à 0.
  • Consultez la section Paramètres de taille de la mémoire tampon pour obtenir une description détaillée de la récupération de la taille capabilityFeatures requise.

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 de capacité dans XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Si capability n'est pas une fonctionnalité énumérée par xrEnumerateSpatialCapabilitiesEXT , l'environnement d'exécution doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

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

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_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 des 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);

Description 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 de contexte spatial.
  • future est un pointeur vers un XrFutureEXT .

L'application peut créer un handle XrSpatialContextEXT en :

L'environnement d'exécution doit renvoyer XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT si XrSpatialContextCreateInfoEXT ::capabilityConfigCount est égal à 0. Un handle de contexte spatial doit comporter au moins une fonctionnalité.

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

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

L'environnement d'exécution 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 à un XrSpatialCapabilityFeatureEXT qui n'est pas énuméré pour cette fonctionnalité dans xrEnumerateSpatialCapabilityFeaturesEXT , l'environnement d'exécution 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 requêtes spatiales à venir. Par exemple, un environnement d'exécution compatible avec la fonctionnalité de suivi de plan peut ne lancer son pipeline de suivi de plan que si un handle de contexte spatial contenant la fonctionnalité de suivi de plan est créé par l'application. Si les fonctionnalités configurées ont un temps de préchauffage long, 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 ont été initialisés.

Si un environnement d'exécution applique un système d'autorisation pour contrôler l'accès de l'application 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 démarre une opération asynchrone et crée un XrFutureEXT correspondant, utilisable avec xrPollFutureEXT et les fonctions associées. La valeur de retour de cette fonction indique uniquement si les paramètres étaient acceptables pour planifier l'opération asynchrone. La fonction de complétion correspondante est xrCreateSpatialContextCompleteEXT , utilisable lorsqu'un futur de cette fonction est à l'état READY, avec des sorties renseignées par cette fonction dans la structure de complétion XrCreateSpatialContextCompletionEXT .

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_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
  • XR_ERROR_TIME_INVALID (si XR_ANDROID_spatial_annotation_tracking est activé)

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 OpenXR de base ou dans cette extension.
  • 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 fonctionnalité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 un 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'environnement d'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);

Description 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 à l'état prêt. L'environnement d'exécution doit renvoyer XR_ERROR_FUTURE_INVALID_EXT si future a déjà été terminé ou annulé.

Utilisation valide (implicite)

Codes renvoyés

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 est le XrResult de l'opération de création de contexte spatial.
  • spatialContext est un XrSpatialContextEXT créé à l'aide des données et de la configuration dans xrCreateSpatialContextAsyncEXT :: createInfo .

Codes de retour futurs

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

Description 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 aucun autre XrSpatialContextEXT valide créé avec les mêmes fonctionnalités spatiales que spatialContext , cet appel sert de suggestion à l'environnement d'exécution pour désactiver les services de suivi requis pour ces fonctionnalités afin d'économiser les ressources système.

Utilisation valide (implicite)

Thread safety

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

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Représentations d'entités spatiales

ID d'entité spatiale

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT permet de représenter tout type d'entité détecté par l'environnement d'exécution dans l'environnement spatial de l'utilisateur. Un XrSpatialEntityIdEXT est valide pour le XrSpatialContextEXT dans lequel il est découvert, et l'environnement d'exécution ne doit pas réutiliser le même XrSpatialEntityIdEXT pour différentes entités dans le même XrSpatialContextEXT . De plus, l'environnement d'exécution 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 à des fonctions d'API et renvoyé par celles-ci uniquement lorsque cela est spécifiquement autorisé.

Poignée 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 de l'ID

La fonction xrCreateSpatialEntityFromIdEXT est définie comme suit :

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

Description 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'environnement d'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 renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_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 OpenXR de base ou dans cette extension.
  • entityId est l'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);

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

Thread safety

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

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Instantané spatial

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

L'application peut créer des instantanés spatiaux dans le but de découvrir des entités spatiales ou de 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, tel que sélectionné par l'application. L'instantané spatial représente une vue cohérente des entités et des données de leurs composants. Une fois l'instantané créé, ses données doivent rester constantes tant qu'il 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 lorsqu'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);

Description 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 démarre une opération asynchrone et crée un XrFutureEXT correspondant, utilisable avec xrPollFutureEXT et les fonctions associées. La valeur de retour de cette fonction indique uniquement si les paramètres étaient acceptables pour planifier l'opération asynchrone. La fonction de complétion 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 complétion XrCreateSpatialDiscoverySnapshotCompletionEXT .

L'application peut envoyer plusieurs requêtes 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 terminer la création d'instantanés dans n'importe quel ordre. L'environnement d'exécution peut retarder la création de l'instantané de découverte pour limiter l'application s'il doit réduire l'utilisation des ressources système en raison de règles d'alimentation, de 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 l'environnement d'exécution. Si l'application fournit une liste valide de types de composants spatiaux dans XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , l'environnement d'exécution doit inclure uniquement les entités spatiales de l'instantané qui comportent au moins l'un des composants fournis dans XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . De plus, l'environnement d'exécution doit inclure uniquement les données des composants de l'instantané.

L'environnement d'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 fonctionnalité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 , l'environnement d'exécution 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 fonctionnalités configurées pour spatialContext . L'environnement d'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", l'environnement d'exécution peut créer un XrSpatialSnapshotEXT qui ne contient aucune entité 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 . L'environnement d'exécution ne doit pas définir XrCreateSpatialContextCompletionEXT :: futureResult sur un code d'erreur en raison de XrEventDataReferenceSpaceChangePending .

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_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 OpenXR de base ou dans cette extension.
  • 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);

Description des paramètres

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

Utilisation valide (implicite)

Codes renvoyés

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 composant incluses dans l'instantané créé seront représentés dans baseSpace , situé à l'emplacement 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 est le XrResult de l'opération de création d'un instantané de découverte spatiale.
  • snapshot est un XrSpatialSnapshotEXT qui peut être utilisé pour interroger les données de composant des entités spatiales découvertes.

Codes de retour futurs

Valeurs de 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 Discovery

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 le XrSpatialContextEXT pour lequel la découverte est recommandée par l'environnement d'exécution.

L'application peut récupérer cet événement à l'aide de xrPollEvent . L'application peut éviter les appels excessifs à xrCreateSpatialDiscoverySnapshotAsyncEXT pour découvrir des 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 obtenus peuvent contenir les mêmes entités. Par conséquent, la création d'instantanés et les requêtes de données seraient inutiles.

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

L'environnement d'exécution ne doit pas mettre cet événement en file d'attente pour informer l'application des modifications ou des 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 des composants pour les entités spatiales qui l'intéressent.

Un environnement d'exécution 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 mettre en file d'attente 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 indiquer à l'application une cadence de requête de découverte appropriée afin de ne pas surcharger les ressources système. L'environnement d'exécution peut choisir de ne jamais mettre cet événement en file d'attente pour un XrSpatialContextEXT si aucune entité n'est trouvée dans l'environnement de l'utilisateur pendant toute la durée de vie de ce XrSpatialContextEXT .

L'environnement d'exécution ne doit pas mettre cet événement en file d'attente 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 , l'environnement d'exécution ne doit plus mettre en file d'attente d'é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 du composant

La fonction xrQuerySpatialComponentDataEXT est définie comme suit :

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

Description des paramètres

L'application peut utiliser xrQuerySpatialComponentDataEXT pour interroger les données de composant des entités de 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 , l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE .

L'application peut choisir d'associer les structures de liste correspondant à un sous-ensemble de composants listés dans XrSpatialComponentDataQueryConditionEXT :: componentTypes . L'application peut choisir d'omettre complètement les structures de liste si elle souhaite uniquement connaître les ID et l'état de suivi des entités spatiales qui répondent au queryCondition . L'environnement d'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 du composant à partir d'un XrSpatialSnapshotEXT , l'application peut utiliser les données d'événement pour ajuster les poses en conséquence.

L'environnement d'exécution doit renseigner XrSpatialComponentDataQueryResultEXT :: entityIds uniquement avec les entités qui ont tous les composants spécifiés dans XrSpatialComponentDataQueryConditionEXT :: componentTypes . Si XrSpatialComponentDataQueryConditionEXT :: componentTypeCount est égal à 0, l'environnement d'exécution doit renseigner 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, l'environnement d'exécution doit les traiter comme un "ET" avec la disponibilité des types de composants, c'est-à-dire que l'environnement d'exécution doit renseigner XrSpatialComponentDataQueryResultEXT ::entityIds uniquement avec les entités qui remplissent toutes les conditions fournies. L'environnement d'exécution doit renseigner 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 , l'environnement d'exécution ne doit pas modifier les données de l'index correspondant à cette entité dans le tableau contenu dans les structures de liste associées à XrSpatialComponentDataQueryResultEXT .

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_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 contenant cinq entités, où :

  • Les entités 1 et 2 ont les composants XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT et XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
  • Les entités 3 et 4 ont 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

No Text is not SVG - cannot display

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 pourra associer 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 entityId #1

Données pour l'entit...

Données pour entityId 2

Données pour l'entit...

Données pour entityId #5

Données pour l'entit...

entityIds

entityIds

suivant

suivant

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

bounds

bounds

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou... Le texte n'est pas au format SVG. Impossible de l'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 pourra associer des tableaux de XrBoxf et XrSpatialMeshDataEXT dans les structures XrSpatialComponentBounded3DListEXT et XrSpatialComponentMesh3DListEXT respectivement à la chaîne suivante 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 l'entit...

Données pour entityId #4

Données pour l'entit...

Mesh3D

Mesh3D

Données pour l'entityId 3

Données pour l'entit...

Données pour entityId #4

Données pour l'entit...

entityIds

entityIds

suivant

suivant

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

bounds

bounds

suivant

suivant

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

maillages

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 est la capacité du tableau entityIds, ou 0 pour indiquer une requête de récupération de la capacité requise.
  • entityIdCountOutput est le nombre de XrSpatialEntityIdEXT dans entityIds , ou la capacité requise si entityIdCapacityInput est insuffisant.
  • entityIds est un tableau de XrSpatialEntityIdEXT . Il peut être NULL si entityIdCapacityInput est égal à 0.
  • entityStateCapacityInput est la capacité du tableau entityStates, ou 0 pour indiquer une requête de récupération de la capacité requise.
  • entityStateCountOutput est le 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 . Il peut être NULL si entityStateCapacityInput est égal à 0.
  • Consultez la section Paramètres de taille de la mémoire tampon pour obtenir une description détaillée de la récupération de la taille entityIds requise.

Une application peut utiliser l'entityIds avec xrCreateSpatialEntityFromIdEXT pour créer des poignées XrSpatialEntityEXT pour les entités pour lesquelles elle souhaite recevoir des mises à jour régulières. L'application peut ensuite utiliser ces poignées XrSpatialEntityEXT avec xrCreateSpatialUpdateSnapshotEXT pour créer un instantané de mise à jour contenant les dernières données connues de l'environnement d'exécution pour 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;

XrSpatialEntityTrackingStateEXT énumère les états de suivi d'entité spatiale possibles :

Les énumérations ont les significations suivantes :

Description de l'enum

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

L'environnement d'exécution a arrêté de suivre cette entité et ne reprendra jamais son suivi.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

L'environnement d'exécution a suspendu le suivi de cette entité, mais peut le reprendre ultérieurement.

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

L'environnement d'exécution suit actuellement cette entité, et les données de ses composants sont valides.

SUIVI

EN PAUSE

ARRÊTÉ

Figure 23. XrSpatialEntityTrackingStateEXT

  • L'environnement d'exécution peut faire passer 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 est possible de reprendre son suivi à l'avenir. Voici quelques exemples de situations dans lesquelles l'environnement d'exécution peut agir ainsi (liste non exhaustive) : si l'application perd la sélection d'entrée, si l'entité spatiale donnée est trop éloignée de l'utilisateur pour être suivie avec précision, ou si trop d'entités sont suivies et que l'environnement d'exécution souhaite réduire le coût du suivi. XrSpatialEntityTrackingStateEXT aide l'application à s'isoler des différentes règles de suivi de chaque environnement d'exécution.
  • L'environnement d'exécution peut faire passer 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'environnement d'exécution doit faire passer 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 de cette session de suivi comme de nouvelles entités.
  • Une fois que l'état de suivi d'une entité est défini sur XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , l'environnement d'exécution ne doit jamais le modifier.
  • Lors de l'interrogation des données de composant d'une entité spatiale à l'aide de xrQuerySpatialComponentDataEXT , l'environnement d'exécution 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 , l'environnement d'exécution ne doit pas modifier le contenu des tampons.

Idiome à deux appels pour les données de composant

La structure XrSpatialBufferEXT est définie comme suit :

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

Descriptions des membres

  • bufferId l'XrSpatialBufferIdEXT des données du tampon.
  • bufferType est le 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 ont 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 un même bufferId , l'environnement d'exécution 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 composant 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 tout type de données de taille variable pour un composant spatial.

L'environnement d'exécution doit conserver le XrSpatialBufferIdEXT et ses données en mémoire pendant au moins le cycle de vie du XrSpatialSnapshotEXT qui le contient. L'environnement d'exécution peut conserver l'XrSpatialBufferIdEXT et ses données en mémoire plus longtemps que le cycle de vie de l'XrSpatialSnapshotEXT afin de renvoyer le même ID dans les instantanés créés ultérieurement par l'application. Pour un même XrSpatialBufferIdEXT , l'environnement d'exécution 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é XrSpatialBufferIdEXT .

Descriptions des énumérants

La fonction xrGetSpatialBufferStringEXT est définie comme suit :

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

Description des paramètres

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

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

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

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

buffer renseigné par l'environnement d'exécution 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 doit être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput doit être un pointeur vers une valeur uint32_t
  • Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de valeurs de caractères bufferCapacityInput.

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_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);

Description des paramètres

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

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

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

L'environnement d'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 doit être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput doit être un pointeur vers une valeur uint32_t
  • Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de valeurs bufferCapacityInput uint8_t.

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_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);

Description des paramètres

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

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

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

L'environnement d'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 doit être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput doit être un pointeur vers une valeur uint32_t
  • Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de valeurs bufferCapacityInput uint16_t.

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_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);

Description des paramètres

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

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

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

L'environnement d'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 doit être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput doit être un pointeur vers une valeur uint32_t
  • Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de valeurs bufferCapacityInput uint32_t.

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_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);

Description des paramètres

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

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

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

L'environnement d'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 doit être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput doit être un pointeur vers une valeur uint32_t
  • Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de valeurs bufferCapacityInput float.

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_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);

Description des paramètres

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

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

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

L'environnement d'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 doit être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput doit être un pointeur vers une valeur uint32_t
  • Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de structures bufferCapacityInput XrVector2f.

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_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);

Description des paramètres

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

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

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

L'environnement d'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 doit être un pointeur vers une structure XrSpatialBufferGetInfoEXT valide
  • bufferCountOutput doit être un pointeur vers une valeur uint32_t
  •  Si bufferCapacityInput n'est pas 0 , buffer doit être un pointeur vers un tableau de structures bufferCapacityInput XrVector3f.

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_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 un XrSpatialBufferIdEXT pour le tampon dont vous souhaitez récupérer les donné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 à des 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);

Description des paramètres

L'application peut utiliser xrCreateSpatialUpdateSnapshotEXT pour créer un instantané et obtenir les dernières données de composant pour des entités spécifiques, telles qu'elles sont connues par l'environnement d'exécution. Les applications peuvent fournir les poignées 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 , l'environnement d'exécution doit inclure uniquement les entités spatiales de l'instantané qui comportent au moins l'un des composants fournis dans XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . De plus, l'environnement d'exécution doit inclure uniquement les données de ces composants dans l'instantané.

L'environnement d'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 fonctionnalité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 , l'environnement d'exécution doit inclure toutes les entités spatiales listées dans XrSpatialUpdateSnapshotCreateInfoEXT :: entities dans l'instantané et il doit inclure les données de tous les composants activés des fonctionnalités configurées pour spatialContext .

L'environnement d'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 lorsqu'elle n'en a plus besoin.

Utilisation valide (implicite)

Codes renvoyés

Opération réussie

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_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 OpenXR de base ou dans cette extension.
  • entityCount est un uint32_t décrivant le nombre d'éléments dans le tableau entities.
  • entities est un tableau de XrSpatialEntityEXT pour lequel l'environnement d'exécution 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 l'environnement d'exécution doit inclure les données dans l'instantané.
  • baseSpace est l'XrSpace par rapport auquel tous les emplacements de la mise à jour XrSpatialSnapshotEXT seront situés.
  • time est l'XrTime où se trouvent 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 poignées XrSpatialEntityEXT valides
  • Si componentTypeCount n'est pas 0 , componentTypes doit être un pointeur vers un tableau de valeurs XrSpatialComponentTypeEXT valides componentTypeCount
  • 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 l'instantané

La fonction xrDestroySpatialSnapshotEXT est définie comme suit :

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

Description des paramètres

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

Utilisation valide (implicite)

Thread safety

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

Codes renvoyés

Opération réussie

  • XR_SUCCESS

Échec

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Composants courants

2D limité

Données du composant

La structure XrSpatialBounded2DDataEXT est définie comme suit :

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

Descriptions des membres

  • center est un XrPosef définissant le centre géométrique du composant 2D délimité.
  • extents correspond aux étendues du composant 2D délimité le long de l'axe X (extents.width) et de l'axe Y (extents.height), centrées 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.

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

L'environnement d'exécution 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 égal à zéro et que XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .

L'environnement d'exécution 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 , l'environnement d'exécution doit fournir XrSpatialBounded2DDataEXT :: center dans XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace et XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Si xrQuerySpatialComponentDataEXT :: snapshot a été créé à partir de xrCreateSpatialUpdateSnapshotEXT , l'environnement d'exécution 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 chaîne suivante de XrSpatialCapabilityConfigurationBaseHeaderEXT .

3D limitée

Données du composant

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

L'environnement d'exécution 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 égal à zéro et que XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .

L'environnement d'exécution 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 , l'environnement d'exécution doit fournir XrBoxf :: center dans XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace à XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Si xrQuerySpatialComponentDataEXT :: snapshot a été créé à partir de xrCreateSpatialUpdateSnapshotEXT , l'environnement d'exécution 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 chaîne suivante de XrSpatialCapabilityConfigurationBaseHeaderEXT .

Parent

Données du composant

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

L'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrQuerySpatialComponentDataEXT si XrSpatialComponentParentListEXT se trouve dans la chaîne suivante de XrSpatialComponentDataQueryResultEXT :: next, mais que XrSpatialComponentDataQueryConditionEXT ::componentTypeCount n'est pas égal à zéro et que XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .

L'environnement d'exécution 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 doit ê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 chaîne suivante de XrSpatialCapabilityConfigurationBaseHeaderEXT .

Maillage 3D

Données du composant

La structure XrSpatialMeshDataEXT est définie comme suit :

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

Descriptions des membres

  • origin est un XrPosef définissant 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 sommet 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 de maillage 3D 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 .

L'environnement d'exécution 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 égal à zéro et que XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .

L'environnement d'exécution doit renvoyer XR_ERROR_SIZE_INSUFFICIENT à partir de xrQuerySpatialComponentDataEXT si meshCount est inférieur à XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Pour l'XrSpatialMeshDataEXT renseigné par l'environnement d'exécution dans le tableau meshes, l'XrSpatialBufferEXT :: bufferType pour XrSpatialMeshDataEXT :: vertexBuffer doit être XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT et l'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 chaîne suivante de XrSpatialCapabilityConfigurationBaseHeaderEXT .

Filtres d'état de 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 est l'XrSpatialEntityTrackingStateEXT auquel 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 d'un instantané aux entités dont l'état de suivi est trackingState .

Utilisation valide (implicite)

Exemple de code

Utilisation de l'application

Les applications utilisent généralement l'extension d'entité spatiale selon le modèle suivant :

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 fonctionnalité "Foo" et interroger ses données de composant.

/****************************/
/* 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

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 concernant les 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 supplémentaires pour la découverte. Les filtres de création de l'instantané ne doivent pas affecter la configuration du contexte spatial. Ils doivent plutôt être utilisés pour fournir des indications à l'environnement d'exécution 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 la configuration actuelle des services sous-jacents).

  • Si une extension définit un nouveau XrSpatialCapabilityEXT ,

  • Si une extension définit un nouveau XrSpatialCapabilityFeatureEXT , elle doit également définir une structure de configuration correspondante qui peut être associé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 un nouveau 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 du composant
    • Structure de la liste des composants pour interroger les données
    • Configuration

  • Lorsque vous écrivez une API qui fournit un XrSpatialBufferIdEXT à l'application, 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 pour transmettre les informations d'étiquette 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 "devrait" et "doit" s'appliquent aux auteurs de ces fonctionnalités, et non à une implémentation d'exécution ou à une application utilisant l'API.

  • Si une extension définit des étiquettes sémantiques pour un XrSpatialCapabilityEXT , elle doit le faire en définissant un nouveau XrSpatialComponentTypeEXT ainsi qu'une nouvelle énumération avec un ensemble d'étiquettes (un "ensemble d'étiquettes sémantiques") qui serviront de données pour ce composant.
  • Une énumération représentant un ensemble d'étiquettes sémantiques doit avoir une valeur pour indiquer que l'entité n'est classée dans aucune des étiquettes 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 l'environnement d'exécution 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 nouveau XrSpatialComponentTypeEXT dans xrEnumerateSpatialCapabilityComponentTypesEXT implique que l'environnement d'exécution est compatible avec l'ensemble d'étiquettes sémantiques (et donc avec les étiquettes définies dans l'ensemble) correspondant à ce type de composant.
  • Les applications expriment leur souhait de découvrir des entités dont les étiquettes appartiennent à cet ensemble d'étiquettes sémantiques en incluant le XrSpatialComponentTypeEXT correspondant dans le tableau XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents de la structure de configuration de 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 une étiquette issue de son propre ensemble d'étiquettes sémantiques. Prenons l'exemple suivant avec des ensembles d'étiquettes sémantiques hypothétiques : XrSpatialObjectSemanticLabel , qui peut 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 de canapés IKEA spécifiques. Dans ce scénario, la même entité "canapé" comporte les trois composants (étiquettes des trois ensembles d'étiquettes 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 de la fonctionnalité, sert d'indication aux environnements d'exécution 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 d'étiquettes à l'énumération d'un ensemble d'étiquettes sémantiques existant. 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 groupe de libellés sémantiques nouvellement défini doit également établir le mappage entre l'ancien groupe de libellés et le nouveau. Consultez l'exemple ci-dessous .
Exemple de définition de caractéristique 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 d'étiquette sémantique spatiale
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 l'XrSpatialPlaneSemanticLabelEXT existant avec des valeurs représentant les portes et les fenêtres. La spécification de la nouvelle énumération doit inclure le texte du 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 base

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

Nouveaux types d'objets

Nouvelles commandes

Nouvelles structures

Nouvelles énumérations

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

  • Extension de 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. Cela dépend entièrement de l'environnement d'exécution, 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 de l'entité spatiale, à l'exception des composants garantis d'une capacité donnée pour définir une attente minimale. Un environnement d'exécution peut fusionner les entités détectées par des fonctionnalités distinctes et 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 de plan et une fonctionnalité de suivi d'objet. Le suivi de plan fournit le composant XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT sur l'entité, et le suivi d'objet fournit XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT. Un certain environnement d'exécution peut fournir la table 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 la table, 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 peut avoir au maximum un seul composant d'un type de composant donné. Par conséquent, si les données de composant produites par les différentes fonctionnalités sont en conflit pour une certaine entité, l'environnement d'exécution 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