XR_EXT_spatial_image_tracking

Name String

XR_EXT_spatial_image_tracking

Type d'extension

Extension d'instance

Numéro d'extension enregistré

783

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

XR_EXT_spatial_entity

Participants

Daniel Guttenberg, Qualcomm
Nihav Jain, Google
Jared Finder, Google
Zhipeng Liu, ByteDance

Présentation

Cette extension fournit la fonctionnalité de suivi d'image pour l'extension XR_EXT_spatial_entity. Elle permet aux applications de détecter et de suivre des images planes spécifiques, telles que spécifiées par des ensembles d'images de référence d'entrée.

Une image suivie est représentée sous la forme d'une entité spatiale avec (ou "qui possède") les composants suivants :

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Les applications utilisent généralement l'extension de suivi d'image spatiale selon le schéma suivant :

  • Une application crée d'abord un ou plusieurs handles XrSpatialImageTrackingDatabaseEXT en fonction d'ensembles de données d'images de référence préchargées.
  • L'application crée ensuite un handle XrSpatialContextEXT basé sur les handles XrSpatialImageTrackingDatabaseEXT créés précédemment.
  • L'application libère ensuite les données de l'image de référence pour réduire sa consommation de mémoire.
  • L'application découvre et interroge les images en fonction des modèles d'accès aux entités spatiales.
  • L'application peut charger des ensembles supplémentaires d'images de référence et créer des XrSpatialImageTrackingDatabaseEXT supplémentaires, puis des XrSpatialContextEXT à partir de ceux-ci pour étendre l'ensemble d'images détectables et traçables de manière dynamique au moment de l'exécution.
  • L'application peut détruire les poignées XrSpatialImageTrackingDatabaseEXT pour réduire l'ensemble d'images détectables et traçables de manière dynamique au moment de l'exécution.
  • L'application peut détruire les poignées XrSpatialContextEXT pour réduire l'ensemble d'images détectables et traçables de manière dynamique au moment de l'exécution.

Compatibilité des environnements d'exécution

Un environnement d'exécution doit annoncer sa compatibilité avec la fonctionnalité de suivi d'images à l'aide de xrEnumerateSpatialCapabilitiesEXT en listant la fonctionnalité suivante :

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Configuration

Pour activer la détection et le suivi des images planes, l'application peut transmettre des structures XrSpatialCapabilityConfigurationImageTrackingEXT dans XrSpatialContextCreateInfoEXT :: capabilityConfigs lors de l'appel de la fonction xrCreateSpatialContextAsyncEXT, et transmettre des tableaux de structures XrSpatialImageTrackingDatabaseEXT dans chaque XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases .

Création d'un ensemble d'images d'entrée

Pour spécifier les images de référence à détecter et à suivre, l'application doit créer au moins un ensemble d'images de référence d'entrée. Un ensemble d'images de référence d'entrée est représenté par un handle XrSpatialImageTrackingDatabaseEXT et contient au moins une image.

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

Le handle XrSpatialImageTrackingDatabaseEXT représente les ressources permettant de découvrir et de mettre à jour un certain nombre d'images spatiales dans l'environnement de l'utilisateur. Les applications peuvent utiliser ce handle pour découvrir et mettre à jour des images spatiales à l'aide d'autres fonctions de cette extension.

Créer la base de données de suivi d'images spatiales

La fonction xrCreateSpatialImageTrackingDatabaseAsyncEXT est définie comme suit :

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Description des paramètres

  • session est une XrSession dans laquelle la base de données de suivi des images spatiales sera active.
  • createInfo est l'élément XrSpatialImageTrackingDatabaseCreateInfoEXT utilisé pour spécifier les paramètres de la base de données de suivi d'images spatiales.
  • future est un pointeur vers un XrFutureEXT .

Une application peut créer un handle XrSpatialImageTrackingDatabaseEXT à l'aide de la fonction xrCreateSpatialImageTrackingDatabaseAsyncEXT et configurer les ensembles d'images de référence d'entrée de la base de données de suivi d'images avec createInfo .

L'environnement d'exécution doit renvoyer XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT si l'XrSpatialReferenceImageEXT :: format de l'une des images de référence d'entrée n'est pas énuméré par xrEnumerateSpatialReferenceImageFormatsEXT .

L'environnement d'exécution doit renvoyer XR_ERROR_SPATIAL_IMAGE_INVALID_EXT si le tableau planes de XrSpatialReferenceImageEXT de l'une des images de référence d'entrée ne peut pas être évalué en fonction des métadonnées de l'image de référence de XrSpatialReferenceImageEXT .

L'environnement d'exécution doit renvoyer XR_ERROR_SPATIAL_IMAGE_INVALID_EXT si le tableau planes de XrSpatialReferenceImageEXT de l'une des images de référence d'entrée ne fournit pas exactement autant de plans que format de XrSpatialReferenceImageEXT a de canaux de couleur.

Si un environnement d'exécution applique un système d'autorisation pour contrôler l'accès de l'application à la fonctionnalité de suivi d'image, 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 xrCreateSpatialImageTrackingDatabaseCompleteEXT , 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 XrCreateSpatialImageTrackingDatabaseCompletionEXT .

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_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

La structure XrSpatialImageTrackingDatabaseCreateInfoEXT est définie comme suit :

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

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.
  • spatialReferenceImageCount est le nombre d'éléments du tableau spatialReferenceImages.
  • spatialReferenceImages est un tableau de XrSpatialReferenceImageEXT .

La structure XrSpatialImageTrackingDatabaseCreateInfoEXT décrit les informations permettant de créer un handle XrSpatialImageTrackingDatabaseEXT.

Chaque XrSpatialImageTrackingDatabaseEXT doit être créé avec au moins un XrSpatialReferenceImageEXT dans le tableau XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

Utilisation valide (implicite)

La fonction xrCreateSpatialImageTrackingDatabaseCompleteEXT est définie comme suit :

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

Description des paramètres

xrCreateSpatialImageTrackingDatabaseCompleteEXT termine l'opération asynchrone lancée par xrCreateSpatialImageTrackingDatabaseAsyncEXT .

L'environnement d'exécution ne doit pas accéder aux pointeurs XrSpatialReferenceImagePlaneEXT :: buffer fournis par le tableau d'entrée XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages pour cet appel xrCreateSpatialImageTrackingDatabaseAsyncEXT une fois qu'il est terminé. L'application peut libérer toutes les données XrSpatialReferenceImagePlaneEXT :: buffer une fois que xrCreateSpatialImageTrackingDatabaseAsyncEXT a été exécuté pour réduire son empreinte mémoire.

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 XrCreateSpatialImageTrackingDatabaseCompletionEXT est définie comme suit :

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

Descriptions des membres

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_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

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

Utilisation valide (implicite)

Détruire la base de données de suivi des images spatiales

La fonction xrDestroySpatialImageTrackingDatabaseEXT est définie comme suit :

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

Description des paramètres

L'application peut appeler la fonction xrDestroySpatialImageTrackingDatabaseEXT pour libérer le handle database et les ressources sous-jacentes une fois les tâches de découverte et de mise à jour des images spatiales terminées.

L'application peut appeler la fonction xrDestroySpatialImageTrackingDatabaseEXT avant d'appeler xrDestroySpatialContextEXT . L'environnement d'exécution ne doit plus signaler les images gérées par cette XrSpatialImageTrackingDatabaseEXT détruite. L'environnement d'exécution doit continuer à signaler les images gérées par d'autres bases de données.

L'environnement d'exécution doit s'assurer que les instantanés de découverte renvoyés par xrCreateSpatialDiscoverySnapshotCompleteEXT ne contiennent pas d'images appartenant à des handles XrSpatialImageTrackingDatabaseEXT détruits ou non valides, même si le handle a été détruit après l'appel de xrCreateSpatialDiscoverySnapshotAsyncEXT par l'application. Étant donné que les données d'un instantané spatial sont immuables, l'application doit détruire tous les handles XrSpatialSnapshotEXT créés avant de détruire database . Sinon, l'application peut recevoir des handles XrSpatialImageTrackingDatabaseEXT non valides lors de l'utilisation de xrQuerySpatialComponentDataEXT .

L'application peut appeler la fonction xrDestroySpatialContextEXT pour libérer le handle XrSpatialContextEXT avant de détruire l'un des handles XrSpatialImageTrackingDatabaseEXT avec lesquels XrSpatialContextEXT a été créé. L'environnement d'exécution ne doit pas détruire implicitement ces poignées XrSpatialImageTrackingDatabaseEXT lorsque XrSpatialContextEXT est détruit.

La gestion indépendante de la durée de vie de XrSpatialContextEXT et de XrSpatialImageTrackingDatabaseEXT permet aux applications de réutiliser les handles XrSpatialImageTrackingDatabaseEXT précédemment créés sans avoir à répéter la procédure de création coûteuse.

Par exemple, détruire un XrSpatialContextEXT, puis recréer un autre XrSpatialContextEXT avec le même XrSpatialImageTrackingDatabaseEXT permet de suspendre et de reprendre le suivi d'images sans avoir à effectuer une autre procédure d'initialisation.

Utilisation valide (implicite)

Thread safety

  • L'accès à database 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

Formats d'image d'entrée acceptés

Les applications doivent appeler xrEnumerateSpatialReferenceImageFormatsEXT pour obtenir la liste des formats d'image de référence d'entrée compatibles.

La fonction xrEnumerateSpatialReferenceImageFormatsEXT est définie comme suit :

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

Description des paramètres

  • instance est un handle vers un XrInstance .
  • systemId est l'élément XrSystemId dont les formats d'image de référence d'entrée seront énumérés.
  • capability est l'XrSpatialCapabilityEXT pour lequel les formats d'image de référence d'entrée seront énumérés.
  • formatCapacityInput est la capacité du tableau formats, ou 0 pour indiquer une requête de récupération de la capacité requise.
  • formatCountOutput est le nombre de formats ou la capacité requise si formatCapacityInput est insuffisant.
  • formats est un tableau de XrSpatialReferenceImageFormatEXT . Il peut être NULL si formatCapacityInput 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 formats requise.

L'application peut énumérer la liste des formats d'image de référence d'entrée compatibles avec un XrSystemId donné pour un XrSpatialCapabilityEXT donné à l'aide de xrEnumerateSpatialReferenceImageFormatsEXT .

L'environnement d'exécution ne doit pas énumérer les formats des extensions qui ne sont pas activées 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

Consultez XrSpatialReferenceImageFormatEXT pour obtenir la liste complète de tous les formats d'image de référence compatibles avec une extension.

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

L'énumération XrSpatialReferenceImageFormatEXT identifie les formats d'image de référence d'entrée que l'environnement d'exécution peut accepter.

Au moins la valeur XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT et la valeur XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT doivent être acceptées.

Les énumérants ont la signification suivante :

Descriptions des énumérants

  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT : tampon RVBA. Le format ne garantit pas la disposition des données de pixels en mémoire. Les pixels doivent être accessibles à l'aide des métadonnées fournies par les structures XrSpatialReferenceImagePlaneEXT correspondantes. Chaque canal de couleur de pixel a une taille de 8 bits, ce qui donne à chaque pixel une taille de 32 bits.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT : un tampon RVB. Le format ne garantit pas la disposition des données de pixels en mémoire. Les pixels doivent être accessibles à l'aide des métadonnées fournies par les structures XrSpatialReferenceImagePlaneEXT correspondantes. Chaque canal de couleur de pixel a une taille de 8 bits, ce qui donne à chaque pixel une taille de 24 bits.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT : tampon YUV sous-échantillonné selon un schéma de chrominance 4:2:0. Le format ne garantit pas la disposition des données de pixels en mémoire. Les pixels doivent être accessibles à l'aide des métadonnées fournies par les structures XrSpatialReferenceImagePlaneEXT correspondantes. Chaque canal de couleur de pixel RVB décodé a une taille de 8 bits, ce qui donne une taille de 24 bits par pixel.

Paramètres de suivi des images spatiales

Cette extension fournit des structures facultatives que l'application peut utiliser pour configurer la fonctionnalité de suivi d'images.

Optimisation des images statiques

La structure XrSpatialImageStaticOptimizationEXT est définie comme suit :

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

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.
  • optimizeForStaticImage est un XrBool32 qui indique si les images bougent ou non. La valeur XR_TRUE indique que les images ne bougent pas.

Si XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT est énuméré par xrEnumerateSpatialCapabilityFeaturesEXT pour la fonctionnalité XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, l'application peut associer XrSpatialImageStaticOptimizationEXT à la chaîne XrSpatialImageTrackingDatabaseCreateInfoEXT :: next ou XrSpatialReferenceImageEXT :: next .

Si l'application associe XrSpatialImageStaticOptimizationEXT à la structure XrSpatialImageTrackingDatabaseCreateInfoEXT, l'environnement d'exécution doit supposer que toutes les images de cet XrSpatialImageTrackingDatabaseEXT sont statiques si optimizeForStaticImage est défini sur XR_TRUE . De même, l'environnement d'exécution doit supposer que toutes les images de cet XrSpatialImageTrackingDatabaseEXT ne sont pas statiques si optimizeForStaticImage est défini sur XR_FALSE .

Si l'application associe XrSpatialImageStaticOptimizationEXT à la structure XrSpatialReferenceImageEXT, l'environnement d'exécution doit supposer que cette image de référence est statique si optimizeForStaticImage est défini sur XR_TRUE . De même, l'environnement d'exécution doit supposer que cette image de référence n'est pas statique si optimizeForStaticImage est défini sur XR_FALSE . Le chaînage de la structure XrSpatialImageStaticOptimizationEXT à la structure XrSpatialReferenceImageEXT est prioritaire sur le chaînage à la structure XrSpatialImageTrackingDatabaseCreateInfoEXT.

Si XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT n'est pas énuméré par xrEnumerateSpatialCapabilityFeaturesEXT pour la fonctionnalité XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT et que l'application associe une structure XrSpatialImageStaticOptimizationEXT à l'une des chaînes suivantes applicables, l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Cela peut permettre à l'environnement d'exécution de générer une pose et une taille plus précises.

Cela peut permettre à l'environnement d'exécution de réduire la consommation d'énergie.

Utilisation valide (implicite)

Largeur de l'image de référence

La structure XrSpatialImageSizeEXT est définie comme suit :

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

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.
  • physicalWidth est une valeur float représentant la largeur physique à définir, en mètres.

Si XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT est énuméré par xrEnumerateSpatialCapabilityFeaturesEXT pour la fonctionnalité XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, l'application peut associer XrSpatialImageSizeEXT à XrSpatialImageTrackingDatabaseCreateInfoEXT :: next ou XrSpatialReferenceImageEXT :: next .

Si l'application associe XrSpatialImageSizeEXT à la structure XrSpatialImageTrackingDatabaseCreateInfoEXT, l'environnement d'exécution doit supposer que toutes les images de cet XrSpatialImageTrackingDatabaseEXT ont une largeur de physicalWidth mètres et une hauteur correspondant au format fourni implicitement par XrSpatialReferenceImageEXT :: width et XrSpatialReferenceImageEXT :: height .

Si l'application associe XrSpatialImageSizeEXT à la structure XrSpatialReferenceImageEXT, l'environnement d'exécution doit supposer que cette image de référence a une largeur de physicalWidth mètres et une hauteur correspondant au format fourni implicitement par XrSpatialReferenceImageEXT :: width et XrSpatialReferenceImageEXT :: height . Le chaînage de la structure XrSpatialImageSizeEXT à la structure XrSpatialReferenceImageEXT est prioritaire sur le chaînage à la structure XrSpatialImageTrackingDatabaseCreateInfoEXT.

Cela peut permettre à l'environnement d'exécution de renvoyer une pose et une taille plus précises.

L'environnement d'exécution doit énumérer XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT ou XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT, ou les deux.

Si XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT est énuméré par xrEnumerateSpatialCapabilityFeaturesEXT, l'environnement d'exécution doit fournir automatiquement des tailles d'image pour les images pour lesquelles l'application n'a fourni aucune structure XrSpatialImageSizeEXT dans l'une des chaînes suivantes applicables.

Pour que l'environnement d'exécution puisse générer automatiquement et précisément des tailles d'image, certaines fonctionnalités de l'appareil et conditions préalables peuvent être requises, par exemple des caméras stéréo, des paramètres extrinsèques et intrinsèques de la caméra calibrés avec précision.

Si XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT n'est pas énuméré par xrEnumerateSpatialCapabilityFeaturesEXT, l'application doit lier les structures XrSpatialImageSizeEXT aux chaînes suivantes applicables afin que toutes les images aient une taille explicite. Sinon, l'environnement d'exécution doit renvoyer XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT à partir de xrCreateSpatialImageTrackingDatabaseAsyncEXT.

Utilisation valide (implicite)

La structure XrSpatialCapabilityConfigurationImageTrackingEXT est définie comme suit :

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

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_IMAGE_TRACKING_EXT .
  • enabledComponentCount est un uint32_t qui spécifie le nombre d'éléments dans enabledComponents .
  • enabledComponents est un tableau de XrSpatialComponentTypeEXT qui spécifie les composants à activer pour cette fonctionnalité.
  • imageTrackingDatabaseCount est un unint32_t qui spécifie le nombre d'éléments dans imageTrackingDatabases .
  • imageTrackingDatabases est un tableau de poignées XrSpatialImageTrackingDatabaseEXT qui spécifie les bases de données de suivi d'images à activer pour le contexte spatial.

Si le suivi d'image est compatible, l'environnement d'exécution doit l'activer si une structure XrSpatialCapabilityConfigurationImageTrackingEXT est transmise dans XrSpatialContextCreateInfoEXT :: capabilityConfigs lors de l'appel de xrCreateSpatialContextAsyncEXT .

La structure XrSpatialCapabilityConfigurationImageTrackingEXT permet à l'application de découvrir les images de référence représentées par les poignées XrSpatialImageTrackingDatabaseEXT dans imageTrackingDatabases .

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

Utilisation valide (implicite)

Image de référence spatiale

La structure XrSpatialReferenceImagePlaneEXT est définie comme suit :

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

Description des paramètres

  • bufferSize est la taille du tableau buffer.
  • buffer est un tableau de données uint8_t représentant les données du plan.
  • rowStride est la distance en octets entre deux positions de départ de lignes de données de pixels consécutives.
  • pixelStride est la distance en octets entre deux pixels consécutifs.

L'environnement d'exécution doit accéder à buffer selon les modèles fournis par les paramètres rowStride et pixelStride.

L'application doit définir rowStride et pixelStride de sorte que seuls les pixels significatifs de ce XrSpatialReferenceImagePlaneEXT soient extraits par l'environnement d'exécution.

Utilisation valide (implicite)

  • L'extension XR_EXT_spatial_image_tracking doit être activée avant d'utiliser XrSpatialReferenceImagePlaneEXT.
  • buffer doit être un pointeur vers un tableau de valeurs bufferSize uint8_t
  • Le paramètre bufferSize doit être supérieur à 0.

La structure XrSpatialReferenceImageEXT est définie comme suit :

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

Description des paramètres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • width est la largeur en pixels de l'image de référence.
  • height est la hauteur en pixels de l'image de référence.
  • format est un XrSpatialReferenceImageFormatEXT représentant le format de l'image.
  • planeCount est le nombre d'éléments du tableau planes.
  • planes est un tableau de structures XrSpatialReferenceImagePlaneEXT représentant les plans des données d'image.

L'application peut créer une ou plusieurs structures XrSpatialReferenceImageEXT, chacune représentant une seule image de référence d'entrée à transmettre à la fonction xrCreateSpatialImageTrackingDatabaseAsyncEXT via XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages lors de la création d'un handle XrSpatialImageTrackingDatabaseEXT.

Les données XrSpatialReferenceImagePlaneEXT :: buffer doivent être fournies par l'application dans un ordre de pixels de gauche à droite et de haut en bas.

L'application doit fournir une structure XrSpatialReferenceImagePlaneEXT dans le tableau XrSpatialReferenceImageEXT :: planes pour chaque canal de couleur de XrSpatialReferenceImageEXT :: format .

Utilisation valide (implicite)

Composants garantis

Un environnement d'exécution compatible avec XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT doit fournir les composants spatiaux suivants en tant que composants garantis de toutes les entités découvertes par ces fonctionnalités, et doit les énumérer dans xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Composant Image 2D

Structure de liste de composants pour interroger des données

La structure XrSpatialComponentImage2DListEXT est définie comme suit :

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

Description des paramètres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • imageCount est le nombre d'éléments du tableau images.
  • images est un tableau de XrSpatialImage2DDataEXT .

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

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

Utilisation valide (implicite)

Données du composant

La structure XrSpatialImage2DDataEXT est définie comme suit :

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

Description des paramètres

L'application peut utiliser imageTrackingDatabase pour identifier l'XrSpatialImageTrackingDatabaseEXT précédemment créé qui contient l'image de référence de cette structure XrSpatialImage2DDataEXT. Pour ce XrSpatialImageTrackingDatabaseEXT , l'application peut utiliser referenceImageIndex pour identifier le XrSpatialReferenceImageEXT de cette structure XrSpatialImage2DDataEXT en le faisant correspondre à l'ordre d'entrée du tableau XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

L'ensemble d'images de référence défini par l'ensemble de toutes les bases de données actives ne doit pas inclure d'images en double. L'inclusion d'images en double peut entraîner des comportements de découverte ou de suivi indésirables, par exemple l'affichage d'index incohérents ou multiples.

Utilisation valide (implicite)

Configuration

Si XR_SPATIAL_COMPONENT_TYPE_IMAGE_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 .

Composant 2D limité

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

Exemple de code

Découvrir les images spatiales et interroger les données des composants

L'exemple de code suivant montre comment découvrir des entités spatiales pour la fonctionnalité de suivi d'image et interroger les données de ses composants.

XrInstance instance; // Previously initialized
XrSystemId systemId; // Previously initialized
XrSession session; // Previously initialized

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
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);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

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

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  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) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

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

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

  waitUntilReady(discoveryFuture);

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

  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 componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

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

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

    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) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

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

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

Nouveaux types d'objets

Nouvelles commandes

Nouvelles structures

Nouvelles énumérations

Nouvelles constantes d'énumération

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • Extension de XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • Extension de XrResult :

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • Extension de XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

  • Extension de XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

  • Extension de XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

  • Extension de XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
    • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
    • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
    • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

Problèmes

Historique des versions

  • Révision 1, 22/04/2025 (Daniel Guttenberg, Qualcomm)

    • Description initiale de l'extension