XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

Type d'extension

Extension d'instance

Numéro d'extension enregistré

708

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

XR_ANDROID_trackables

État d'abandon

  • Obsolète par l'extension XR_EXT_spatial_marker_tracking

Date de dernière modification

03/07/2025

État de l'adresse IP

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

Participants

Christopher Doer, Google
Diego Tipaldi, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Ken Mackay, Google
Daniel Guttenberg, Qualcomm

Présentation

Cette extension permet de suivre les marqueurs physiques et permet aux applications d'associer du contenu XR à des marqueurs physiques de manière efficace.

L'extension est compatible avec les types de repères bien connus, en particulier les tags ArUco et April. Il permet aux environnements d'exécution de prendre en charge l'estimation de la taille des repères.

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 une autorisation dangereuse, ce qui signifie que les applications doivent la demander explicitement.

(niveau de protection : dangereux)

Inspecter les capacités du système

La structure XrSystemMarkerTrackingPropertiesANDROID est définie comme suit :

typedef struct XrSystemMarkerTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsMarkerTracking;
    XrBool32           supportsMarkerSizeEstimation;
    uint16_t           maxMarkerCount;
} XrSystemMarkerTrackingPropertiesANDROID;

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. Pour en savoir plus sur la chaîne de structure, consultez la structure étendue ( XrSystemProperties).
  • supportsMarkerTracking est un XrBool32 indiquant si le système actuel fournit une fonctionnalité de suivi des marqueurs.
  • supportsMarkerSizeEstimation est un XrBool32 indiquant si le système actuel fournit une estimation de la taille du repère.
  • maxMarkerCount est le nombre maximal de repères que l'environnement d'exécution peut suivre en même temps.

Une application peut vérifier si le système est capable de suivre les repères en étendant XrSystemProperties avec la structure XrSystemMarkerTrackingPropertiesANDROID lors de l'appel de xrGetSystemProperties . L'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED pour la création du tracker de repères si et seulement si supportsMarkerTracking est XR_FALSE .

Si un environnement d'exécution accepte le suivi des repères, maxMarkerCount doit être supérieur ou égal à 1.

Utilisation valide (implicite)

Marqueurs de suivi

Cette extension ajoute XR_TRACKABLE_TYPE_MARKER_ANDROID à XrTrackableTypeANDROID .

L'application crée un XrTrackableTrackerANDROID en appelant xrCreateTrackableTrackerANDROID et en spécifiant XR_TRACKABLE_TYPE_MARKER_ANDROID comme type d'élément traçable dans XrTrackableTrackerCreateInfoANDROID :: trackableType, et en définissant une configuration valide en ajoutant un XrTrackableMarkerConfigurationANDROID à la chaîne suivante de XrTrackableTrackerCreateInfoANDROID .

L'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED si XrTrackableTrackerCreateInfoANDROID :: trackableType est XR_TRACKABLE_TYPE_MARKER_ANDROID et que XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking renvoie XR_FALSE via xrGetSystemProperties .

La structure XrTrackableMarkerConfigurationANDROID est définie comme suit :

typedef struct XrTrackableMarkerConfigurationANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrTrackableMarkerTrackingModeANDROID       trackingMode;
    uint32_t                                   databaseCount;
    const XrTrackableMarkerDatabaseANDROID*    databases;
} XrTrackableMarkerConfigurationANDROID;

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.
  • trackingMode est un XrTrackableMarkerTrackingModeANDROID indiquant le mode de suivi souhaité.
  • databaseCount est un uint32_t décrivant le nombre d'éléments dans le tableau databases.
  • databases est un pointeur vers un tableau de XrTrackableMarkerDatabaseANDROID , chacun contenant les repères souhaités d'un dictionnaire donné à suivre.

L'application doit définir une configuration valide en ajoutant un XrTrackableMarkerConfigurationANDROID à la chaîne XrTrackableTrackerCreateInfoANDROID :: next lors de l'appel de xrCreateTrackableTrackerANDROID avec XrTrackableTrackerCreateInfoANDROID :: trackableType défini sur XR_TRACKABLE_TYPE_MARKER_ANDROID . Sinon, si le type de traceur est défini comme ci-dessus, mais que la structure de configuration n'est pas présente ou n'est pas valide, l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE .

Si un environnement d'exécution est compatible avec l'estimation de la taille des repères, l'application peut définir XrTrackableMarkerDatabaseEntryANDROID :: edgeSize sur 0 dans XrTrackableMarkerDatabaseANDROID :: entries pour indiquer l'utilisation de l'estimation de la taille. Sinon, l'application doit définir XrTrackableMarkerDatabaseEntryANDROID :: edgeSize sur une valeur positive, ou l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE .

L'environnement d'exécution doit filtrer la sortie de xrGetAllTrackablesANDROID pour qu'elle corresponde à trackingMode et XrTrackableMarkerDatabaseEntryANDROID :: edgeSize .

Utilisation valide (implicite)

L'énumération XrTrackableMarkerTrackingModeANDROID décrit les modes de suivi compatibles des repères.

typedef enum XrTrackableMarkerTrackingModeANDROID {
    XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_TRACKABLE_MARKER_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerTrackingModeANDROID;

Descriptions des énumérants

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID : suivi des repères dynamiques. Ce mode offre la plus grande précision et fonctionne sur les repères mobiles et statiques, mais il consomme également le plus d'énergie.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID : suivi des repères statiques. Ce mode est principalement utile pour les repères connus comme étant statiques, ce qui permet de réduire la consommation d'énergie par rapport au mode dynamique.

La structure XrTrackableMarkerDatabaseANDROID définit un dictionnaire et les ID de repères correspondants à suivre.

typedef struct XrTrackableMarkerDatabaseANDROID {
    XrTrackableMarkerDictionaryANDROID              dictionary;
    uint32_t                                        entryCount;
    const XrTrackableMarkerDatabaseEntryANDROID*    entries;
} XrTrackableMarkerDatabaseANDROID;

Descriptions des membres

  • dictionary est le XrTrackableMarkerDictionaryANDROID auquel appartiennent tous les entries.
  • entryCount est un uint32_t décrivant le nombre d'éléments dans le tableau entries. L'application peut définir entryCount 0 pour suivre tous les repères dans dictionary .
  • entries est un pointeur vers un tableau de XrTrackableMarkerDatabaseEntryANDROID , chacun contenant la configuration d'un repère à suivre.

Utilisation valide (implicite)

L'énumération XrTrackableMarkerDictionaryANDROID décrit les dictionnaires de repères compatibles.

typedef enum XrTrackableMarkerDictionaryANDROID {
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID = 0,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_100_ANDROID = 1,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_250_ANDROID = 2,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_1000_ANDROID = 3,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_50_ANDROID = 4,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_100_ANDROID = 5,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_250_ANDROID = 6,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_1000_ANDROID = 7,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_50_ANDROID = 8,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_100_ANDROID = 9,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_250_ANDROID = 10,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_1000_ANDROID = 11,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_50_ANDROID = 12,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_100_ANDROID = 13,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_250_ANDROID = 14,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_1000_ANDROID = 15,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_16H5_ANDROID = 16,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_25H9_ANDROID = 17,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H10_ANDROID = 18,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H11_ANDROID = 19,
    XR_TRACKABLE_MARKER_DICTIONARY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerDictionaryANDROID;

La structure XrTrackableMarkerDatabaseEntryANDROID configure un seul ID de repère d'un dictionnaire.

typedef struct XrTrackableMarkerDatabaseEntryANDROID {
    int32_t    id;
    float      edgeSize;
} XrTrackableMarkerDatabaseEntryANDROID;

Descriptions des membres

  • id est l'ID du repère, tel qu'il est indiqué dans le dictionnaire.
  • edgeSize représente la taille du bord du repère en mètres. Si l'environnement d'exécution est compatible avec l'estimation de la taille des repères, l'application peut définir cette valeur sur zéro, et la taille des repères sera estimée en ligne. Si cette valeur est définie sur zéro, mais que l'environnement d'exécution n'est pas compatible avec l'estimation de la taille des repères, l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE .

Utilisation valide (implicite)

Obtenir des repères

La fonction xrGetTrackableMarkerANDROID est définie comme suit :

XrResult xrGetTrackableMarkerANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableMarkerANDROID*                   markerOutput);

Description des paramètres

L'environnement d'exécution doit renvoyer XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID si le type d'élément traçable de XrTrackableANDROID n'est pas XR_TRACKABLE_TYPE_MARKER_ANDROID ou si le type d'élément traçable de XrTrackableTrackerANDROID n'est pas XR_TRACKABLE_TYPE_MARKER_ANDROID .

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_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La structure XrTrackableMarkerANDROID est définie comme suit :

typedef struct XrTrackableMarkerANDROID {
    XrStructureType                       type;
    void*                                 next;
    XrTrackingStateANDROID                trackingState;
    XrTime                                lastUpdatedTime;
    XrTrackableMarkerDictionaryANDROID    dictionary;
    int32_t                               markerId;
    XrPosef                               centerPose;
    XrExtent2Df                           extents;
} XrTrackableMarkerANDROID;

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.
  • trackingState est l'état XrTrackingStateANDROID du repère.
  • lastUpdatedTime est l'XrTime de la dernière mise à jour du repère.
  • dictionary est le XrTrackableMarkerDictionaryANDROID du repère.
  • markerId est l'ID du repère, tel qu'il est indiqué dans le dictionnaire.
  • centerPose est le XrPosef du repère situé dans XrTrackableGetInfoANDROID :: baseSpace . Le repère se trouve dans le plan XZ, avec X pointant vers la droite du repère, Z pointant vers le bas et Y sortant du repère comme la normale.
  • extents correspond aux dimensions XrExtent2Df du repère. La limite du cadre de délimitation se trouve aux points : centerPose +/- ( extents / 2).

Utilisation valide (implicite)

Exemple de code pour obtenir des repères traçables

L'exemple de code suivant montre comment obtenir des repères traçables.

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

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // previously initialized
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // previously initialized
PFN_xrGetTrackableMarkerANDROID xrGetTrackableMarkerANDROID;           // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // 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
XrSystemMarkerTrackingPropertiesANDROID markerProperty {
  .type = XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &markerProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!markerProperty.supportsMarkerTracking) {
    // Marker tracking is not supported.
    return;
}

// Create a trackable tracker for marker tracking.
// If the runtime does not support size estimation, configures marker edge size of 0.1m.
XrTrackableMarkerDatabaseEntryANDROID markerEntries {
  .id = 0,
  .edgeSize = markerProperty.supportsMarkerSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableMarkerDatabaseANDROID markerDatabases {
  .dictionary = XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID,
  .entryCount = 1,
  .entries = &markerEntries,
};
XrTrackableMarkerConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID,
  .databaseCount = 1,
  .databases = &markerDatabases,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_MARKER_ANDROID,
};
XrTrackableTrackerANDROID markerTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &markerTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get markers.
std::vector<XrTrackableANDROID> trackables(markerProperty.maxMarkerCount);
std::vector<XrTrackableMarkerANDROID> markers(markerProperty.maxMarkerCount, {
  .type = XR_TYPE_TRACKABLE_MARKER_ANDROID,
  .next = nullptr,
});
uint32_t markerSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(markerTracker, markerProperty.maxMarkerCount, &markerSize,
                                 trackables.data()));
for (int i = 0; i < markerSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables[i],
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableMarkerANDROID(markerTracker, &getInfo, &markers[i]));
    // Handle markers.
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(markerTracker));

Nouvelles commandes

Nouvelles structures

Nouvelles énumérations

Nouvelles constantes d'énumération

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • Extension de XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • Extension de XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Problèmes

Historique des versions

  • Révision 1, 23/07/2025 (Levana Chen)

    • Description initiale de l'extension.