XR_ANDROID_trackables_image
Chaîne de nom
XR_ANDROID_trackables_image
Type d'extension
Extension d'instance
Numéro d'extension enregistré
710
Révision
1
État de ratification
Non ratifié
Dépendances des extensions et des versions
XR_EXT_future
et
XR_ANDROID_trackables
Date de dernière modification
2025-04-08
État de l'adresse IP
Aucune réclamation connue pour atteinte à la propriété intellectuelle.
Participants
Christopher Doer, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Diego Tipaldi, Google
Daniel Guttenberg, Qualcomm
Mark Vadasi, Qualcomm
Markus Birkner, Qualcomm
Maximilian Mayer, Qualcomm
Présentation
Cette extension permet de suivre des images planes spécifiées par des ensembles d'images de référence d'entrée.
Autorisations
Les applications Android doivent inclure l'autorisation android.permission.SCENE_UNDERSTANDING_COARSE dans leur fichier manifeste, car cette extension dépend de XR_ANDROID_trackables et expose la géométrie de l'environnement. L'autorisation android.permission.SCENE_UNDERSTANDING_COARSE est considérée comme dangereuse.
(niveau de protection : dangereux)
Inspecter les capacités du système
La structure XrSystemImageTrackingPropertiesANDROID est définie comme suit :
typedef struct XrSystemImageTrackingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsImageTracking;
XrBool32 supportsPhysicalSizeEstimation;
uint32_t maxTrackedImageCount;
uint32_t maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans l'extension ni dans le cœur d'OpenXR. Pour en savoir plus sur la chaîne de structure, consultez la structure en cours d'extension ( XrSystemProperties ).supportsImageTrackingest unXrBool32indiquant si le système actuel offre une fonctionnalité de suivi d'image.supportsPhysicalSizeEstimationest unXrBool32indiquant si le système actuel fournit une estimation de la taille d'image.maxTrackedImageCountcorrespond au nombre maximal total d'images pouvant être suivies en même temps.maxLoadedImageCountcorrespond au nombre maximal total d'images de référence pouvant être chargées dans toutes les bases de données.
Une application peut inspecter si le système est capable de suivre les images en étendant XrSystemProperties avec la structure XrSystemImageTrackingPropertiesANDROID lors de l'appel de xrGetSystemProperties . Le runtime doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED pour la création de trackers d'images si et seulement si supportsImageTracking est XR_FALSE .
Si un environnement d'exécution est compatible avec le suivi d'images, il doit prendre en charge maxTrackedImageCount images suivies à tout moment.
Si un environnement d'exécution est compatible avec le suivi d'images, il doit prendre en charge les images maxLoadedImageCount chargées à tout moment.
Si un environnement d'exécution prend en charge l'estimation de la taille des images, l'application peut définir XrTrackableImageDatabaseEntryANDROID::physicalWidth 0 pour indiquer l'utilisation de l'estimation de la taille. Sinon, l'application doit définir XrTrackableImageDatabaseEntryANDROID::physicalWidth sur une valeur positive, sinon XR_ERROR_VALIDATION_FAILURE sera renvoyé.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant d'utiliser XrSystemImageTrackingPropertiesANDROID. -
typedoit êtreXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures.
Créer des bases de données
L'application peut créer un handle XrTrackableImageDatabaseANDROID en créant une ou plusieurs structures XrTrackableImageDatabaseEntryANDROID et en les transmettant à la fonction xrCreateTrackableImageDatabaseAsyncANDROID via une structure XrTrackableImageDatabaseCreateInfoANDROID.
L'application doit fournir au moins une XrTrackableImageDatabaseEntryANDROID lors de la création d'un handle XrTrackableImageDatabaseANDROID.
XrTrackableImageDatabaseANDROID est un handle qui représente un ensemble d'images de référence traitées qui peuvent être découvertes et suivies dans l'environnement.
XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)
La structure XrTrackableImageDatabaseEntryANDROID est définie comme suit :
typedef struct XrTrackableImageDatabaseEntryANDROID {
XrStructureType type;
const void* next;
XrTrackableImageTrackingModeANDROID trackingMode;
float physicalWidth;
uint32_t imageWidth;
uint32_t imageHeight;
XrTrackableImageFormatANDROID format;
uint32_t bufferSize;
const uint8_t* buffer;
} XrTrackableImageDatabaseEntryANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans l'extension ni dans le cœur d'OpenXR.trackingModeest un XrTrackableImageTrackingModeANDROID qui indique le mode de suivi souhaité.physicalWidthindique la largeur de l'image en mètres. Si la valeur est zéro, la taille d'image sera estimée en ligne.imageWidthindique la largeur de l'image en pixels.imageHeightindique la hauteur de l'image en pixels.formatest un XrTrackableImageFormatANDROID qui indique le format des données d'image dansbuffer.bufferSizeindique la longueur en octets debuffer.bufferest le tamponuint8_tcontenant les données de pixels de l'image de référence. Le contenu debufferdoit être valide pendant toute la durée de l'opération asynchrone de création de la base de données, qui est lancée par xrCreateTrackableImageDatabaseAsyncANDROID et terminée par xrCreateTrackableImageDatabaseCompleteANDROID .
L'application peut définir physicalWidth sur 0 pour demander une estimation de la taille en ligne si XrSystemImageTrackingPropertiesANDROID::supportsPhysicalSizeEstimation est XR_TRUE .
Le runtime peut renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrCreateTrackableImageDatabaseAsyncANDROID si bufferSize ne correspond pas à la taille attendue en fonction des imageWidth , imageHeight et format de l'entrée .
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant d'utiliser XrTrackableImageDatabaseEntryANDROID. -
typedoit êtreXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures. -
trackingModemust être une valeur XrTrackableImageTrackingModeANDROID valide -
formatmust être une valeur XrTrackableImageFormatANDROID valide -
buffermust être un pointeur vers un tableau de valeursbufferSizeuint8_t - Le paramètre
bufferSizedoit être supérieur à0
La structure XrTrackableImageDatabaseCreateInfoANDROID est définie comme suit :
typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
XrStructureType type;
const void* next;
uint32_t entryCount;
const XrTrackableImageDatabaseEntryANDROID* entries;
} XrTrackableImageDatabaseCreateInfoANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans l'extension ni dans le cœur d'OpenXR.entryCountest unuint32_tqui spécifie le nombre d'éléments dans le tableauentries.entriesest un tableau de structures XrTrackableImageDatabaseEntryANDROID.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant d'utiliser XrTrackableImageDatabaseCreateInfoANDROID. -
typedoit êtreXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures. -
entriesmust être un pointeur vers un tableau de structures XrTrackableImageDatabaseEntryANDROID validesentryCount. - Le paramètre
entryCountdoit être supérieur à0
La structure XrCreateTrackableImageDatabaseCompletionANDROID est définie comme suit :
typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrTrackableImageDatabaseANDROID database;
} XrCreateTrackableImageDatabaseCompletionANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans l'extension ni dans le cœur d'OpenXR.futureResultest le XrResult de l'opération asynchrone.databaseest le handle XrTrackableImageDatabaseANDROID créé.
Codes de retour futurs
Valeurs futureResult :
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant d'utiliser XrCreateTrackableImageDatabaseCompletionANDROID. -
typedoit êtreXR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures. -
futureResultmust être une valeur XrResult valide -
databasemust être un handle XrTrackableImageDatabaseANDROID valide
La fonction xrCreateTrackableImageDatabaseAsyncANDROID est définie comme suit :
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
Descriptions des paramètres
sessionest un handle vers une XrSession précédemment créée avec xrCreateSession .createInfoest un pointeur vers une structure XrTrackableImageDatabaseCreateInfoANDROID.futureest un pointeur vers leXrFutureEXTcréé .
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant d'appeler xrCreateTrackableImageDatabaseAsyncANDROID. -
sessionmust être un handle XrSession valide -
createInfodoit être un pointeur vers une structure XrTrackableImageDatabaseCreateInfoANDROID valide -
futuremust être un pointeur vers une valeurXrFutureEXT
Codes de retour
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
La fonction xrCreateTrackableImageDatabaseCompleteANDROID est définie comme suit :
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
Descriptions des paramètres
sessionest un handle vers une XrSession précédemment créée avec xrCreateSession .futureest leXrFutureEXTà compléter.completionest un pointeur vers une structure XrCreateTrackableImageDatabaseCompletionANDROID contenant le résultat de l'opération.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant l'appel de xrCreateTrackableImageDatabaseCompleteANDROID. -
sessionmust être un handle XrSession valide -
completionmust be a pointer to an XrCreateTrackableImageDatabaseCompletionANDROID structure
Codes de retour
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
La fonction xrDestroyTrackableImageDatabaseANDROID est définie comme suit :
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
Descriptions des paramètres
databaseest le handle XrTrackableImageDatabaseANDROID à détruire.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant d'appeler xrDestroyTrackableImageDatabaseANDROID. -
databasemust être un handle XrTrackableImageDatabaseANDROID valide
Sécurité des threads
- L'accès à
databaseet à tous les identifiants enfants doit être synchronisé en externe.
Codes de retour
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
Images de suivi
Cette extension ajoute XR_TRACKABLE_TYPE_IMAGE_ANDROID à XrTrackableTypeANDROID .
L'application peut créer un XrTrackableTrackerANDROID en appelant xrCreateTrackableTrackerANDROID et en spécifiant XR_TRACKABLE_TYPE_IMAGE_ANDROID comme type de suivi dans XrTrackableTrackerCreateInfoANDROID :: trackableType pour suivre les images.
L'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED si XrTrackableTrackerCreateInfoANDROID :: trackableType est XR_TRACKABLE_TYPE_IMAGE_ANDROID et XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking renvoie XR_FALSE via xrGetSystemProperties .
La structure XrTrackableImageConfigurationANDROID est définie comme suit :
typedef struct XrTrackableImageConfigurationANDROID {
XrStructureType type;
const void* next;
uint32_t databaseCount;
const XrTrackableImageDatabaseANDROID* databases;
} XrTrackableImageConfigurationANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans l'extension ni dans le cœur d'OpenXR.databaseCountest unuint32_tqui spécifie le nombre d'éléments dansdatabases.databasesest un tableau XrTrackableImageDatabaseANDROID qui spécifie les bases de données avec lesquelles créer le tracker.
L'application doit définir une configuration valide en ajoutant un XrTrackableImageConfigurationANDROID à la chaîne next de XrTrackableTrackerCreateInfoANDROID . Sinon, le runtime doit renvoyer XR_ERROR_VALIDATION_FAILURE .
L'application doit fournir au moins une structure XrTrackableImageDatabaseANDROID pour créer le suivi.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant d'utiliser XrTrackableImageConfigurationANDROID. -
typedoit êtreXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures. -
databasesmust être un pointeur vers un tableau dedatabaseCounthandles XrTrackableImageDatabaseANDROID valides - Le paramètre
databaseCountdoit être supérieur à0
L'énumération XrTrackableImageTrackingModeANDROID décrit les modes de suivi d'images compatibles.
typedef enum XrTrackableImageTrackingModeANDROID {
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;
Descriptions des énumérants
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID: ce mode offre la plus grande précision et permet de suivre les images en mouvement avec une faible latence. Elle présente également la consommation d'énergie la plus élevée.XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID: ce mode doit être utilisé pour les images connues pour être statiques ou semi-statiques. Ce mode entraîne une consommation d'énergie inférieure à celle du mode dynamique. Si une image statique est déplacée, elle sera mise à jour avec une latence beaucoup plus élevée qu'en mode dynamique.
L'énumération XrTrackableImageFormatANDROID décrit les formats d'image compatibles.
typedef enum XrTrackableImageFormatANDROID {
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;
Descriptions des énumérants
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID: format d'image RGBA avec des données de couleur et de transparence de 8 bits par canal.
La fonction xrAddTrackableImageDatabaseANDROID est définie comme suit :
XrResult xrAddTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Descriptions des paramètres
trackerest le handle XrTrackableTrackerANDROID auquel ajouterdatabase.databaseest le handle XrTrackableImageDatabaseANDROID à ajouter àtracker.
Lorsqu'une XrTrackableImageDatabaseANDROID est ajoutée à un tracker, les images de référence de cette base de données doivent être prises en compte pour la détection et le suivi, en plus de toutes les autres bases de données qui ont été ajoutées précédemment avec xrAddTrackableImageDatabaseANDROID ou via la structure XrTrackableImageConfigurationANDROID lors de la création initiale du tracker.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant d'appeler xrAddTrackableImageDatabaseANDROID. -
trackermust be a valid XrTrackableTrackerANDROID handle -
databasemust être un handle XrTrackableImageDatabaseANDROID valide -
databaseettrackerdoivent avoir été créés, alloués ou récupérés à partir de la même XrSession.
Codes de retour
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
La fonction xrRemoveTrackableImageDatabaseANDROID est définie comme suit :
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Descriptions des paramètres
trackerest le handle XrTrackableTrackerANDROID à partir duquel supprimerdatabase.databaseest le handle XrTrackableImageDatabaseANDROID à supprimer detracker.
Lorsqu'une XrTrackableImageDatabaseANDROID est supprimée d'un XrTrackableTrackerANDROID , les structures XrTrackableImageDatabaseEntryANDROID de cette base de données ne doivent plus être prises en compte pour la détection et le suivi. Toutes les entrées suivies activement dans cette base de données ne doivent plus être signalées. Le handle XrTrackableImageDatabaseANDROID supprimé ne doit pas être détruit de manière implicite dans le cadre de cette opération.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant d'appeler xrRemoveTrackableImageDatabaseANDROID. -
trackermust be a valid XrTrackableTrackerANDROID handle -
databasemust être un handle XrTrackableImageDatabaseANDROID valide -
databaseettrackerdoivent avoir été créés, alloués ou récupérés à partir de la même XrSession.
Codes de retour
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Obtenir des images
La fonction xrGetTrackableImageANDROID est définie comme suit :
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
Descriptions des paramètres
trackerest l'XrTrackableTrackerANDROID à interroger.getInfoest XrTrackableGetInfoANDROID avec les informations utilisées pour obtenir le code QR pouvant être suivi.trackableest un pointeur vers la structure XrTrackableImageANDROID dans laquelle l'image détectable est renvoyée.
Le runtime doit renvoyer XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID si le type de suivi de XrTrackableANDROID n'est pas XR_TRACKABLE_TYPE_IMAGE_ANDROID ou si le type de suivi de XrTrackableTrackerANDROID n'est pas XR_TRACKABLE_TYPE_IMAGE_ANDROID .
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant d'appeler xrGetTrackableImageANDROID. -
trackermust be a valid XrTrackableTrackerANDROID handle -
getInfodoit être un pointeur vers une structure XrTrackableGetInfoANDROID valide -
trackabledoit être un pointeur vers une structure XrTrackableImageANDROID.
Codes de retour
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_ERROR_VALIDATION_FAILURE
La structure XrTrackableImageANDROID est définie comme suit :
typedef struct XrTrackableImageANDROID {
XrStructureType type;
const void* next;
XrTrackingStateANDROID trackingState;
XrTime lastUpdatedTime;
XrTrackableImageDatabaseANDROID database;
uint32_t databaseEntryIndex;
XrPosef centerPose;
XrExtent2Df extents;
} XrTrackableImageANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans l'extension ni dans le cœur d'OpenXR.trackingStatecorrespond à XrTrackingStateANDROID de l'image.lastUpdatedTimecorrespond àXrTimede la dernière mise à jour de l'image.databaseest le handle XrTrackableImageDatabaseANDROID à partir duquel cette image a été suivie.databaseEntryIndexest l'index qui correspond au tableauentriesdedatabasedans XrTrackableImageDatabaseCreateInfoANDROID .centerPosecorrespond à XrPosef de l'image située dans XrTrackableGetInfoANDROID ::baseSpace. L'image se trouve dans le plan XZ, avec l'axe X pointant vers la droite de l'image et l'axe Z pointant vers le bas.extentscorrespond aux dimensions XrExtent2Df de l'image. La limite du cadre de délimitation se trouve aux points suivants :centerPose+/- (extents/ 2).
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant d'utiliser XrTrackableImageANDROID. -
typedoit êtreXR_TYPE_TRACKABLE_IMAGE_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures. -
trackingStatedoit être une valeur XrTrackingStateANDROID valide -
databasemust être un handle XrTrackableImageDatabaseANDROID valide
Gestion des pannes
L'application doit interroger l'événement XrEventDataImageTrackingLostANDROID à l'aide de xrPollEvent et ne doit pas l'ignorer.
La structure XrEventDataImageTrackingLostANDROID est définie comme suit :
typedef struct XrEventDataImageTrackingLostANDROID {
XrStructureType type;
const void* next;
XrTime time;
} XrEventDataImageTrackingLostANDROID;
Descriptions des membres
typeest le XrStructureType de cette structure.nextestNULLou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans l'extension ni dans le cœur d'OpenXR.timeXrTime
La réception de l'événement XrEventDataImageTrackingLostANDROID indique que le suivi d'image a subi un échec interne qui a invalidé les ressources existantes. L'application doit détruire tous les handles XrTrackableImageDatabaseANDROID et les recréer si elle souhaite continuer à suivre les images. L'application doit également détruire tous les handles XrTrackableTrackerANDROID liés au suivi d'image et les recréer si elle souhaite continuer à suivre les images.
Utilisation valide (implicite)
- L'extension
XR_ANDROID_trackables_imagedoit être activée avant d'utiliser XrEventDataImageTrackingLostANDROID. -
typedoit êtreXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID. -
nextdoit êtreNULLou un pointeur valide vers la structure suivante dans une chaîne de structures.
Exemple de code pour obtenir des images à suivre
L'exemple de code suivant montre comment obtenir des images traçables.
XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.
XrSystemId systemId; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties; // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT; // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID; // Previously initialized.
XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
// Inspect system capability
XrSystemImageTrackingPropertiesANDROID imageProperty {
.type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
.next = nullptr,
};
XrSystemProperties systemProperties {
.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
// image tracking is not supported.
return;
}
uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.
XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
{
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
.next = nullptr,
.trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
.physicalWidth = 0.1f, // The width of the image in meters.
.imageWidth = 640,
.imageHeight = 480,
.format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
.bufferSize = imageBufferSize, // RGBA buffer size in bytes.
.buffer = imageBuffer, // RGBA data.
}
};
XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
.next = nullptr,
.entryCount = 1,
.entries = imageDatabaseEntries
};
XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));
bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = imageDatabaseFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
futureReady = true;
keepLooping = false;
} else {
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
}
XrTrackableImageDatabaseANDROID imageDatabase;
if (futureReady) {
XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
.type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
.next = nullptr,
};
CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
CHK_XR(imageDatabaseCompletion.futureResult);
imageDatabase = imageDatabaseCompletion.database;
}
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &imageDatabase
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.
// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
while (1) {
uint32_t trackableCountOutput = 0;
CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));
std::vector<XrTrackableANDROID> allImageTrackables;
allImageTrackables.resize(trackableCountOutput);
CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));
for (XrTrackableANDROID trackable : allImageTrackables) {
XrTrackableGetInfoANDROID imageGetInfo {
.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
.next = nullptr,
.trackable = trackable,
.baseSpace = appSpace,
.time = updateTime
};
XrTrackableImageANDROID trackableImage{
.type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
};
CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));
// Use XrTrackableImageANDROID data.
(void)trackableImage.trackingState;
(void)trackableImage.lastUpdatedTime;
(void)trackableImage.centerPose;
(void)trackableImage.extents;
if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
// Knowing which image the index of 0 maps to, use the specific image database
// entry (e.g. rendering A for image A).
}
// indices 1+N comparisons for another specific image database entry.
}
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));
Exemple de code pour gérer les bases de données d'images au moment de l'exécution
L'exemple de code suivant montre comment modifier l'ensemble des images suivies.
XrSession session; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID; // Previously initialized.
// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.
// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 2,
.databases = imageDatabases
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.
// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &anotherImageDatabase
};
XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &anotherImageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));
// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.
Exemple de code pour réagir aux échecs de suivi d'image
L'exemple de code suivant montre comment gérer l'échec en interrogeant l'événement XrEventDataImageTrackingLostANDROID.
XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT; // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.
// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
.type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
switch (event.type) {
case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
const XrEventDataImageTrackingLostANDROID& eventdata =
*reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);
// All existing databases and trackers need to be destroyed.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));
// To resume image tracking, the database(s) and the tracker need to be re-created.
XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
.next = nullptr,
.entryCount = 1,
.entries = imageDatabaseEntries
};
XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));
while (true) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = imageDatabaseFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
break;
} else {
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
}
XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
.type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
.next = nullptr,
};
CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
CHK_XR(imageDatabaseCompletion.futureResult);
imageDatabase = imageDatabaseCompletion.database;
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &imageDatabase
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
break;
}
}
}
Nouveaux types d'objets
Nouvelles commandes
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
Nouvelles structures
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
Extension de XrSystemProperties :
Nouveaux enums
Nouvelles constantes d'énumération
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_ANDROID_trackables_image_SPEC_VERSIONExtension de XrObjectType :
XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
Prolonger XrResult :
XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
Extension de XrStructureType :
XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
Prolonger XrTrackableTypeANDROID :
XR_TRACKABLE_TYPE_IMAGE_ANDROID
Problèmes
Historique des versions
Révision 1, 2025-04-08 (Daniel Guttenberg)
- Description initiale de l'extension.