XR_EXT_spatial_object_tracking

Name String

XR_EXT_spatial_object_tracking

Type d'extension

Extension d'instance

Numéro d'extension enregistré

745

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

XR_EXT_spatial_entity

État de l'adresse IP

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

Participants

Nihav Jain, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance
Andy Biar, Unity Technologies
Rebecca Nordhauser, Unity Technologies

Présentation

Cette extension s'appuie sur XR_EXT_spatial_entity et définit une fonctionnalité spatiale permettant de suivre un ensemble d'objets prédéfinis sans nécessiter d'ensemble de données d'entrée de l'application.

Compatibilité des environnements d'exécution

Si l'environnement d'exécution est compatible avec le suivi d'objets, il doit l'indiquer en énumérant XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT dans xrEnumerateSpatialCapabilitiesEXT .

Configuration

La structure XrSpatialCapabilityConfigurationObjectTrackingEXT est définie comme suit :

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

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 et doit être XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT .
  • 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 .

Les applications peuvent activer la fonctionnalité spatiale XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT en ajoutant un pointeur vers la structure XrSpatialCapabilityConfigurationObjectTrackingEXT dans XrSpatialContextCreateInfoEXT :: capabilityConfigs .

L'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE si capability n'est pas XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT .

Utilisation valide (implicite)

Composants garantis

Un environnement d'exécution compatible avec XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT doit prendre en charge les composants spatiaux suivants en tant que composants garantis des entités découvertes par cette fonctionnalité et doit les énumérer dans xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT
  • Au moins un type de composant fournissant un ensemble d'étiquettes sémantiques pour les objets suivis. Une fonctionnalité de suivi d'objets n'a de sens que si elle est associée à un composant d'étiquette sémantique. Bien que cette extension définisse XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT et XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT comme des composants d'étiquette sémantique possibles que les environnements d'exécution doivent prendre en charge, d'autres extensions peuvent définir de nouveaux types de composants pour fournir différentes classes d'étiquettes sémantiques décrivant un objet suivi. Pour en savoir plus sur les ensembles d'étiquettes sémantiques et la conception des types de composants, consultez [ext_spatial_semantic_labels_guidelines]. Les environnements d'exécution peuvent ne pas accepter XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT ou XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT pour la fonctionnalité de suivi d'objets, mais doivent accepter au moins un type de composant fournissant un libellé sémantique.

Composant 3D limité

Le composant 3D délimité fournit le centre et l'étendue de l'objet représenté par l'entité sur laquelle il se trouve. Pour en savoir plus, consultez 3D délimitée.

Composants facultatifs

Un environnement d'exécution compatible avec XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT peut prendre en charge des composants spatiaux en plus de ceux listés dans la section Composants garantis. L'application peut utiliser xrEnumerateSpatialCapabilityComponentTypesEXT pour obtenir la liste complète des composants compatibles avec un environnement d'exécution, puis peut configurer ceux qui l'intéressent lors de la création du contexte spatial.

Étiquette sémantique d'objet

Données du composant

typedef enum XrSpatialObjectSemanticLabelEXT {
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT = 2,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_BED_EXT = 3,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CHAIR_EXT = 4,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT = 5,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_LAMP_EXT = 6,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_PLANT_EXT = 7,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT = 8,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT = 9,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CABINET_EXT = 10,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialObjectSemanticLabelEXT;

L'énumération XrSpatialObjectSemanticLabelEXT décrit un ensemble de libellés sémantiques pour les objets.

Pour les entités portant l'étiquette XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT, l'axe +Z du composant Bounded 3D doit correspondre approximativement à la normale de la surface de l'écran.

Pour les entités portant l'étiquette XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT, l'axe +Z du composant Bounded 3D doit correspondre à la normale de la surface du mur sur lequel l'œuvre est découverte.

Pour les entités portant l'étiquette XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT, l'axe +Z du composant Bounded 3D doit correspondre à la normale de la surface de la table.

Pour tous les autres libellés de XrSpatialObjectSemanticLabelEXT , l'application ne doit faire aucune supposition sur la façon dont XrBoxf :: center :: orientation fourni par le composant Bounded 3D sur l'entité s'aligne sur les attributs physiques de cet objet.

Les valeurs d'énumération ont les significations suivantes :

Description de l'enum

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT

L'environnement d'exécution n'a pas pu classer cette entité.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT

L'entité est un canapé.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_BED_EXT

L'entité est un lit.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CHAIR_EXT

L'entité est une chaise.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT

L'entité est une table.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_LAMP_EXT

L'entité est une lampe.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_PLANT_EXT

L'entité est une plante.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT

L'entité est un écran d'affichage, comme un moniteur ou un téléviseur.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT

L'entité est une décoration murale.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CABINET_EXT

L'entité est une armoire.

Structure de liste de composants pour interroger des données

La structure XrSpatialComponentObjectSemanticLabelListEXT est définie comme suit :

typedef struct XrSpatialComponentObjectSemanticLabelListEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            semanticLabelCount;
    XrSpatialObjectSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentObjectSemanticLabelListEXT;

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.
  • semanticLabelCount est un uint32_t décrivant le nombre d'éléments dans le tableau semanticLabels.
  • semanticLabels est un tableau de XrSpatialObjectSemanticLabelEXT .

Pour interroger le composant d'étiquette sémantique d'objet des entités spatiales dans un XrSpatialSnapshotEXT , incluez XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT dans XrSpatialComponentDataQueryConditionEXT :: componentTypes et ajoutez XrSpatialComponentObjectSemanticLabelListEXT à la chaîne XrSpatialComponentDataQueryResultEXT :: next.

L'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrQuerySpatialComponentDataEXT si XrSpatialComponentObjectSemanticLabelListEXT se trouve dans la chaîne XrSpatialComponentDataQueryResultEXT :: next, mais que XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Utilisation valide (implicite)

Configuration

Si XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT est énuméré dans XrSpatialCapabilityComponentTypesEXT :: componentTypes pour une fonctionnalité, une application peut l'activer en incluant l'énumérant 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 XrSpatialCapabilityConfigurationBaseHeaderEXT :: next, mais il propose une configuration facultative que les applications peuvent fournir.

La structure XrSpatialFeatureObjectSemanticLabelSubsetEXT est définie comme suit :

typedef struct XrSpatialFeatureObjectSemanticLabelSubsetEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  semanticLabelCount;
    const XrSpatialObjectSemanticLabelEXT*    semanticLabels;
} XrSpatialFeatureObjectSemanticLabelSubsetEXT;

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.
  • semanticLabelCount est un uint32_t décrivant le nombre d'éléments dans le tableau semanticLabels.
  • semanticLabels est un tableau de XrSpatialObjectSemanticLabelEXT .

Si l'environnement d'exécution énumère XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT à partir de xrEnumerateSpatialCapabilityComponentTypesEXT pour une fonctionnalité donnée, il doit également énumérer XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT à partir de xrEnumerateSpatialCapabilityFeaturesEXT pour la même fonctionnalité. Si une application active XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT lors de la configuration de cette fonctionnalité, elle peut associer XrSpatialFeatureObjectSemanticLabelSubsetEXT à la structure de configuration correspondante de cette fonctionnalité pour fournir à l'environnement d'exécution un sous-ensemble d'étiquettes définies dans XrSpatialObjectSemanticLabelEXT . L'environnement d'exécution peut utiliser ce sous-ensemble d'étiquettes pour optimiser ses pipelines de suivi.

L'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrCreateSpatialContextAsyncEXT si semanticLabels contient un libellé qui n'est pas défini dans XrSpatialObjectSemanticLabelEXT ou si semanticLabels contient XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT .

L'environnement d'exécution doit renvoyer XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT à partir de xrCreateSpatialContextAsyncEXT si l'application fournit une liste valide de libellés dans semanticLabels, mais que XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT n'est pas inclus dans le tableau XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents de la structure de configuration à laquelle XrSpatialFeatureObjectSemanticLabelSubsetEXT est associé.

Si l'application configure une fonctionnalité avec un XrSpatialFeatureObjectSemanticLabelSubsetEXT valide, l'environnement d'exécution ne doit pas inclure d'entités ayant des libellés sémantiques qui ne sont pas listés dans semanticLabels dans un instantané de découverte créé pour le contexte spatial configuré.

Utilisation valide (implicite)

Libellé sémantique du clavier

Données du composant

typedef enum XrSpatialKeyboardSemanticLabelEXT {
    XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT = 2,
    XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialKeyboardSemanticLabelEXT;

L'énumération XrSpatialKeyboardSemanticLabelEXT décrit un libellé sémantique pour un clavier.

Les étendues et l'orientation de XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT représentées par le composant Bounded 3D sur la même entité sont affichées dans l'image suivante (avec xyz = rgb) provenant du centre de l'objet.

ext spatial object tracking keyboard orientation

Figure 30. Orientation du clavier.

Description de l'enum

XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_UNCATEGORIZED_EXT

L'environnement d'exécution n'a pas pu classer cette entité.

XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT

L'entité est un clavier.

Structure de liste de composants pour interroger des données

La structure XrSpatialComponentKeyboardSemanticLabelListEXT est définie comme suit :

typedef struct XrSpatialComponentKeyboardSemanticLabelListEXT {
    XrStructureType                       type;
    void*                                 next;
    uint32_t                              semanticLabelCount;
    XrSpatialKeyboardSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentKeyboardSemanticLabelListEXT;

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.
  • semanticLabelCount est un uint32_t décrivant le nombre d'éléments dans le tableau semanticLabels.
  • semanticLabels est un tableau de XrSpatialKeyboardSemanticLabelEXT .

Pour interroger le composant d'étiquette sémantique du clavier des entités spatiales dans un XrSpatialSnapshotEXT , incluez XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT dans XrSpatialComponentDataQueryConditionEXT :: componentTypes et ajoutez XrSpatialComponentKeyboardSemanticLabelListEXT à la chaîne XrSpatialComponentDataQueryResultEXT :: next.

L'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrQuerySpatialComponentDataEXT si XrSpatialComponentKeyboardSemanticLabelListEXT se trouve dans la chaîne XrSpatialComponentDataQueryResultEXT :: next, mais que XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Utilisation valide (implicite)

Configuration

Si XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT est énuméré dans XrSpatialCapabilityComponentTypesEXT :: componentTypes pour une fonctionnalité, une application peut l'activer en incluant l'énumérant 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 XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Libellé sémantique de la souris

Données du composant

typedef enum XrSpatialMouseSemanticLabelEXT {
    XR_SPATIAL_MOUSE_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MOUSE_EXT = 2,
    XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialMouseSemanticLabelEXT;

L'énumération XrSpatialMouseSemanticLabelEXT décrit un libellé sémantique pour une souris.

Description de l'enum

XR_SPATIAL_MOUSE_SEMANTIC_LABEL_UNCATEGORIZED_EXT

L'environnement d'exécution n'a pas pu classer cette entité.

XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MOUSE_EXT

L'entité est une souris.

Structure de liste de composants pour interroger des données

La structure XrSpatialComponentMouseSemanticLabelListEXT est définie comme suit :

typedef struct XrSpatialComponentMouseSemanticLabelListEXT {
    XrStructureType                    type;
    void*                              next;
    uint32_t                           semanticLabelCount;
    XrSpatialMouseSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentMouseSemanticLabelListEXT;

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.
  • semanticLabelCount est un uint32_t décrivant le nombre d'éléments dans le tableau semanticLabels.
  • semanticLabels est un tableau de XrSpatialMouseSemanticLabelEXT .

Pour interroger le composant d'étiquette sémantique de la souris des entités spatiales dans un XrSpatialSnapshotEXT , incluez XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT dans XrSpatialComponentDataQueryConditionEXT :: componentTypes et ajoutez XrSpatialComponentMouseSemanticLabelListEXT à la chaîne XrSpatialComponentDataQueryResultEXT :: next.

L'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrQuerySpatialComponentDataEXT si XrSpatialComponentMouseSemanticLabelListEXT se trouve dans la chaîne XrSpatialComponentDataQueryResultEXT :: next, mais que XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Utilisation valide (implicite)

Configuration

Si XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT est énuméré dans XrSpatialCapabilityComponentTypesEXT :: componentTypes pour une fonctionnalité, une application peut l'activer en incluant l'énumérant 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 XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Exemple de code

Configurer la fonctionnalité de suivi des objets

L'exemple de code suivant montre comment configurer la fonctionnalité de suivi d'objets lors de la création d'un contexte spatial.

// Check if object tracking capability is supported
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT) == capabilities.end()) {
  return;
}

// Enumerate supported components for object tracking capability
XrSpatialCapabilityComponentTypesEXT objectComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, &objectComponents));
std::vector<XrSpatialComponentTypeEXT> objectCapabilityComponents(objectComponents.componentTypeCountOutput);
objectComponents.componentTypeCapacityInput = objectCapabilityComponents.size();
objectComponents.componentTypes = objectCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, &objectComponents));

// Check if the object & keyboard semantic labels component is supported
const auto supportsComponent = [&objectCapabilityComponents](XrSpatialComponentTypeEXT component) {
  return std::find(objectCapabilityComponents.begin(), objectCapabilityComponents.end(), component) != objectCapabilityComponents.end();
};

const bool supportsObjectSemanticLabel = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT);
const bool supportsKeyboardSemanticLabel = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT);

// Enumerate supported features for object tracking capability
uint32_t featureCount;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, 0, &featureCount, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> features(featureCount);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, featureCount, &featureCount, features.data()));

const bool supportsObjectSemanticLabelSubsetFeature = std::find(features.begin(), features.end(), XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT) != features.end();

// Create a spatial context
XrSpatialContextEXT spatialContext{};

// Enable the guaranteed components of the object tracking capability
std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT,
};
// Optionally enable the supported semantic labels
if (supportsObjectSemanticLabel) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT);
}
if (supportsKeyboardSemanticLabel) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT);
}

// We only want to track sofa and table.
std::vector<XrSpatialObjectSemanticLabelEXT> objectSemanticLabelSubset = {
  XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT,
  XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT
};
XrSpatialFeatureObjectSemanticLabelSubsetEXT subsetFeature{XR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT};
subsetFeature.semanticLabelCount = objectSemanticLabelSubset.size();
subsetFeature.semanticLabels = objectSemanticLabelSubset.data();

XrSpatialCapabilityConfigurationObjectTrackingEXT objectTrackingConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXT};
objectTrackingConfig.capability = XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT;
objectTrackingConfig.enabledComponentCount = enabledComponents.size();
objectTrackingConfig.enabledComponents = enabledComponents.data();
if (supportsObjectSemanticLabelSubsetFeature) {
  objectTrackingConfig.next = &subsetFeature;
}

std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
  reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&objectTrackingConfig),
};

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;

// ...
// Discovery entities with the spatial context
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

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 un contexte configuré avec XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT et interroger ses données de composant.

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT,
};
if (supportsKeyboardSemanticLabel) {
  snapshotComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT);
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  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 semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

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

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

    std::vector<XrBoxf> bounded3D(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded3DListEXT bounded3DList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT};
    bounded3DList.boundCount = bounded3D.size();
    bounded3DList.bounds = bounded3D.data();
    queryResult.next = &bounded3DList;

    std::vector<XrSpatialKeyboardSemanticLabelEXT> semanticLabels;
    XrSpatialComponentKeyboardSemanticLabelListEXT semanticLabelsList{XR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXT};
    if (supportsKeyboardSemanticLabel) {
      semanticLabels.resize(queryResult.entityIdCountOutput);
      semanticLabelsList.semanticLabelCount = semanticLabels.size();
      semanticLabelsList.semanticLabels = semanticLabels.data();
      semanticLabelsList.next = queryResult.next;
      queryResult.next = &semanticLabelsList;
    }

    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) {
        continue;
      }

      // 3D bounds for entity entityIds[i] is bounded3D[i].extents centered on bounded3D[i].center.

      if (supportsKeyboardSemanticLabel) {
        // semantic label for entity entityIds[i] is semanticLabels[i].
      }
    }

    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
  // ...
}

Nouvelles structures

Nouvelles énumérations

Nouvelles constantes d'énumération

  • XR_EXT_SPATIAL_OBJECT_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_object_tracking_SPEC_VERSION

  • Extension de XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

  • Extension de XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

  • Extension de XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT
    • XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT
    • XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

  • Extension de XrStructureType :

    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MOUSE_SEMANTIC_LABEL_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_EXT
    • XR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

Problèmes

Historique des versions

  • Révision 1, 03/06/2025 (Nihav Jain, Google)

    • Description initiale de l'extension