XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

Type d'extension

Extension d'instance

Numéro d'extension enregistré

709

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

2025-02-05

État de l'adresse IP

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

Participants

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

Présentation

Cette extension permet de suivre les QR codes physiques et de décoder les données des QR codes.

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

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint16_t           maxQrCodeCount;
} XrSystemQrCodeTrackingPropertiesANDROID;

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.
  • supportsQrCodeTracking est un XrBool32 indiquant si le système actuel fournit une fonctionnalité de suivi par QR code.
  • supportsQrCodeSizeEstimation est un XrBool32 indiquant si le système actuel fournit une estimation de la taille du QR code.
  • maxQrCodeCount est le nombre maximal de codes QR qui peuvent être suivis en même temps.

Une application peut vérifier si le système est capable de suivre les QR codes en étendant XrSystemProperties avec la structure XrSystemQrCodeTrackingPropertiesANDROID lors de l'appel de xrGetSystemProperties . L'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED pour la création d'un outil de suivi par QR code si et seulement si supportsQrCodeTracking est XR_FALSE .

Si un environnement d'exécution accepte le suivi par QR code, maxQrCodeCount doit être supérieur ou égal à 1. Si un environnement d'exécution n'est pas compatible avec le suivi par QR code, maxQrCodeCount doit être défini sur 0.

Utilisation valide (implicite)

Suivi des QR codes

Cette extension ajoute XR_TRACKABLE_TYPE_QR_CODE_ANDROID à XrTrackableTypeANDROID .

L'application peut créer un XrTrackableTrackerANDROID en appelant xrCreateTrackableTrackerANDROID et en spécifiant XR_TRACKABLE_TYPE_QR_CODE_ANDROID comme type d'élément traçable dans XrTrackableTrackerCreateInfoANDROID :: trackableType pour suivre les QR codes.

L'environnement d'exécution doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED si XrTrackableTrackerCreateInfoANDROID :: trackableType est XR_TRACKABLE_TYPE_QR_CODE_ANDROID et que XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking renvoie XR_FALSE via xrGetSystemProperties .

La structure XrTrackableQrCodeConfigurationANDROID est définie comme suit :

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType                type;
    void*                          next;
    XrQrCodeTrackingModeANDROID    trackingMode;
    float                          qrCodeEdgeSize;
} XrTrackableQrCodeConfigurationANDROID;

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.
  • trackingMode est un XrQrCodeTrackingModeANDROID indiquant le mode de suivi souhaité.
  • qrCodeEdgeSize indique la taille du bord du QR code en mètres. Si la valeur est zéro, l'environnement d'exécution estime la taille du QR code en ligne.

L'application doit définir une configuration valide en ajoutant un XrTrackableQrCodeConfigurationANDROID à la chaîne suivante de XrTrackableTrackerCreateInfoANDROID . Sinon, l'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE .

Si l'environnement d'exécution est compatible avec l'estimation de la taille des QR codes, l'application peut définir XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize sur 0.0 pour indiquer l'utilisation de l'estimation de la taille.

Si l'environnement d'exécution n'est pas compatible avec l'estimation de la taille des QR codes, l'application doit définir XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize sur une valeur positive. Sinon, 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 . Si XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize n'est pas défini sur 0.0, l'environnement d'exécution doit renvoyer uniquement les QR codes correspondant à cette taille. Si XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize est défini sur 0.0, l'environnement d'exécution doit renvoyer tous les QR codes avec une taille estimée.

Utilisation valide (implicite)

L'énumération XrQrCodeTrackingModeANDROID décrit les modes de suivi des QR codes compatibles.

typedef enum XrQrCodeTrackingModeANDROID {
    XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM = 1000314000,
    XR_QR_CODE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrQrCodeTrackingModeANDROID;

Descriptions des énumérants

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID : suivi des codes QR dynamiques. Ce mode offre la plus grande précision et fonctionne sur les QR codes mobiles et statiques, mais il consomme également le plus d'énergie.
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID : suivi des QR codes statiques. Ce mode est principalement utile pour les QR codes connus pour être statiques, ce qui réduit la consommation d'énergie par rapport au mode dynamique.
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM : ce mode doit être utilisé pour les QR codes statiques. Contrairement au mode statique, ce mode ne suit le QR code qu'une seule fois, puis met à jour les positions des instances suivies uniquement en fonction de la position de l'appareil. Par conséquent, le suivi se poursuit même si le QR code sort du champ de vision du cadre de référence. Cela permet de réduire la consommation d'énergie une fois que le QR code a été suivi. (Ajouté par l'extension XR_QCOM_trackables_qr_code_operations)

Obtenir des QR codes

La fonction xrGetTrackableQrCodeANDROID est définie comme suit :

XrResult xrGetTrackableQrCodeANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableQrCodeANDROID*                   qrCodeOutput);

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_QR_CODE_ANDROID ou si le type d'élément traçable de XrTrackableTrackerANDROID n'est pas XR_TRACKABLE_TYPE_QR_CODE_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_SIZE_INSUFFICIENT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La structure XrTrackableQrCodeANDROID est définie comme suit :

typedef struct XrTrackableQrCodeANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrTime                    lastUpdatedTime;
    XrPosef                   centerPose;
    XrExtent2Df               extents;
    uint32_t                  bufferCapacityInput;
    uint32_t                  bufferCountOutput;
    char*                     buffer;
} XrTrackableQrCodeANDROID;

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'élément XrTrackingStateANDROID du code QR.
  • lastUpdatedTime est la date et l'heure (XrTime) de la dernière mise à jour du QR code. Si lastUpdatedTime est modifié depuis le dernier appel, tous les autres champs peuvent avoir changé.
  • centerPose est le XrPosef du QR code situé dans XrTrackableGetInfoANDROID :: baseSpace . Le QR code se trouve dans le plan XZ, avec X pointant vers la droite du QR code, Z pointant vers le bas et Y sortant du QR code comme la normale.
  • extents correspond aux dimensions XrExtent2Df du QR code. La limite du cadre de délimitation se trouve aux points : centerPose +/- ( extents / 2).
  • bufferCapacityInput est la capacité de buffer ou 0 pour récupérer la capacité requise.
  • bufferCountOutput Si bufferCapacityInput est 0 , l'environnement d'exécution écrit la taille de la mémoire tampon requise dans bufferCountOutput . Sinon, il contient le nombre total d'éléments écrits dans buffer . Si les données du QR code n'ont pas encore été décodées, l'environnement d'exécution doit définir bufferCountOutput sur 0.
  • buffer est un pointeur vers un tableau de char pour écrire les données du QR code décodé. Si l'application ne se soucie pas des données du QR code décodé, elle peut transmettre nullptr et omettre le deuxième appel. Les données du QR code sont renvoyées sous forme de chaîne UTF-8 terminée par un caractère nul.
  • Consultez la section Paramètres de taille de la mémoire tampon pour obtenir une description détaillée de la récupération de la taille buffer requise.

Utilisation valide (implicite)

Exemple de code pour obtenir des QR codes traçables

L'exemple de code suivant montre comment obtenir des QR codes 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_xrGetTrackableQrCodeANDROID xrGetTrackableQrCodeANDROID;           // 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
XrSystemQrCodeTrackingPropertiesANDROID qrCodeProperty {
  .type = XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &qrCodeProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!qrCodeProperty.supportsQrCodeTracking) {
    // QR code tracking is not supported.
    return;
}

// Create a trackable tracker for QR code tracking.
// If the runtime does not support size estimation, configures QR code edge size of 0.1m.
XrTrackableQrCodeConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID,
  .qrCodeEdgeSize = qrCodeProperty.supportsQrCodeSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_QR_CODE_ANDROID
};
XrTrackableTrackerANDROID qrCodeTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &qrCodeTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get QR codes.
std::vector<XrTrackableANDROID> trackables(qrCodeProperty.maxQrCodeCount);
std::vector<XrTrackableQrCodeANDROID> qrCodes(qrCodeProperty.maxQrCodeCount, {
  .type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID,
  .next = nullptr,
  .bufferCountOutput = 0,
});
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables.at(i),
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
    if (qrCodes[i].bufferCountOutput > 0) {
        // Allocate the buffer if it is not already allocated.
        if (qrCodes[i].bufferCapacityInput == 0) {
            qrCodes[i].buffer = new char[qrCodes[i].bufferCountOutput];
            qrCodes[i].bufferCapacityInput = qrCodes[i].bufferCountOutput;
            CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
        }
    }
}

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

Nouvelles commandes

Nouvelles structures

Nouvelles énumérations

Nouvelles constantes d'énumération

  • XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
  • XR_ANDROID_trackables_qr_code_SPEC_VERSION

  • Extension de XrStructureType :

    • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID

  • Extension de XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Problèmes

Historique des versions

  • Révision 1, 05/02/2025 (Levana Chen)

    • Description initiale de l'extension.