XR_ANDROID_trackables_qr_code

Chaîne de nom

XR_ANDROID_trackables_qr_code

Type d'extension

Extension d'instance

Numéro d'extension enregistré

709

Révision

1

État de ratification

Non ratifié

Dépendances d'extension et de version

XR_ANDROID_trackables

État d'obsolescence

  • Obsolète en raison de l'extension XR_EXT_spatial_marker_tracking

Date de dernière modification

2025-02-05

État de la propriété intellectuelle

Aucune réclamation connue concernant la propriété intellectuelle.

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 le suivi physique des codes QR et le décodage des données des codes QR.

Autorisations

Les applications Android doivent disposer de 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 la capacité 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;

Description des membres

  • type correspond au 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 le noyau OpenXR ni dans cette extension.
  • supportsQrCodeTracking est un XrBool32 indiquant si le système actuel fournit une fonctionnalité de suivi des codes QR.
  • supportsQrCodeSizeEstimation est un XrBool32 indiquant si le système actuel fournit une estimation de la taille des codes QR.
  • maxQrCodeCount correspond au nombre maximal total de codes QR qui peuvent être suivis simultanément.

Une application peut vérifier si le système est capable de suivre les codes QR 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 des codes QR si et seulement si supportsQrCodeTracking est XR_FALSE .

Si un environnement d'exécution est compatible avec le suivi des codes QR, maxQrCodeCount doit être au moins égal à 1. Si un environnement d'exécution n'est pas compatible avec le suivi des codes QR, maxQrCodeCount doit être égal à 0.

Utilisation valide (implicite)

Suivre les codes QR

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 de suivi dans XrTrackableTrackerCreateInfoANDROID :: trackableType pour suivre les codes QR.

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;

Description des membres

  • type correspond au 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 le noyau OpenXR ni dans cette extension.
  • trackingMode est un XrQrCodeTrackingModeANDROID indiquant le mode de suivi souhaité.
  • qrCodeEdgeSize indique la taille du bord du code QR en mètres. Si la valeur est zéro, l'environnement d'exécution estime la taille du code QR 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 codes QR, 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 codes QR, 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 uniquement renvoyer les codes QR qui correspondent à cette taille. Si XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize est défini sur 0.0, l'environnement d'exécution doit renvoyer tous les codes QR dont la taille est estimée.

Utilisation valide (implicite)

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

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;

Description 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 codes QR statiques et en mouvement, mais il consomme également le plus d'énergie.
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID : suivi des codes QR statiques. Ce mode est principalement utile pour les codes QR connus pour être statiques, ce qui entraîne une consommation d'énergie inférieure à celle du mode dynamique.
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM : ce mode doit être utilisé pour les codes QR statiques. Contrairement au mode statique, ce mode ne suit le code QR 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 continue même si le code QR sort du champ de vision du cadre de référence. Cela entraîne une consommation d'énergie minimale une fois le code QR suivi. (Ajouté par l'extension XR_QCOM_trackables_qr_code_operations)

Obtenir des codes QR

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 de suivi du XrTrackableANDROID n'est pas XR_TRACKABLE_TYPE_QR_CODE_ANDROID ou si le type de suivi du 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;

Description des membres

  • type correspond au 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 le noyau OpenXR ni dans cette extension.
  • trackingState correspond au XrTrackingStateANDROID du code QR.
  • lastUpdatedTime correspond au XrTime de la dernière mise à jour du code QR. Si lastUpdatedTime est modifié par rapport au dernier appel, tous les autres champs peuvent avoir été modifiés.
  • centerPose correspond au XrPosef du code QR situé dans XrTrackableGetInfoANDROID :: baseSpace . Le code QR se trouve dans le plan XZ, X pointant vers la droite du code QR, Z pointant vers le bas et Y sortant du code QR comme normale.
  • extents correspond aux dimensions XrExtent2Df du code QR. La limite du cadre de délimitation se trouve aux points suivants : centerPose +/- ( extents / 2).
  • bufferCapacityInput correspond à la capacité du 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 code QR 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 décodées du code QR. Si l'application ne se soucie pas des données décodées du code QR, elle peut transmettre nullptr et omettre le deuxième appel à deux appels. Les données du code QR sont renvoyées sous forme de chaîne UTF-8 terminée par une valeur nulle.
  • 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 codes QR pouvant être suivis

L'exemple de code suivant montre comment obtenir des codes QR pouvant être suivis.

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

Nouveaux enums

Nouvelles constantes enum

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