Extension OpenXR 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é

460

Révision

1

Dépendances des extensions et des versions

XR_ANDROID_trackables

Date de dernière modification

2025-02-05

État de l'adresse IP

Aucune réclamation connue pour atteinte à la propriété intellectuelle.

Contributeurs

Christopher Doer, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Nihav Jain, Google

Diego Tipaldi, Google

Ken Mackay, Google

Daniel Gutenberg, Qualcomm

Présentation

Cette extension permet le suivi des codes QR physiques et le décodage des données des codes QR.

Autorisations

Les applications Android doivent avoir l'autorisation `android.permission.SCENE_UNDERSTANDING` listée 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" est considérée comme dangereuse.
(niveau de protection : dangereux)

Inspecter les capacités du système

XrSystemQrCodeTrackingPropertiesANDROID

La structure XrSystemQrCodeTrackingPropertiesANDROID est définie comme suit :

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint32_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 l'extension ni dans le cœur d'OpenXR.
• supportsQrCodeTracking est un XrBool32 indiquant si le système actuel permet le suivi par code QR.
• supportsQrCodeSizeEstimation est un XrBool32 indiquant si le système actuel fournit une estimation de la taille du code QR.
• maxQrCodeCount correspond au nombre total maximal de codes QR pouvant être suivis en même temps.

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. Le runtime doit renvoyer XR_ERROR_FEATURE_UNSUPPORTED pour la création d'un tracker de code QR si et seulement si supportsQrCodeTracking est XR_FALSE.

Si un environnement d'exécution est compatible avec le suivi des codes QR, il doit être compatible avec le suivi de maxQrCodeCount codes QR à tout moment.

Si un environnement d'exécution est compatible avec l'estimation de la taille du code QR, l'application peut définir XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 0 pour indiquer l'utilisation de l'estimation de la taille. Sinon, l'application doit définir XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize sur une valeur positive. Dans le cas contraire, XR_ERROR_VALIDATION_FAILURE sera renvoyé.

Utilisation valide (implicite)

• L'extension XR_ANDROID_trackables_qr_code doit être activée avant d'utiliser XrSystemQrCodeTrackingPropertiesANDROID.
• type doit être XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.

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

XrTrackableQrCodeConfigurationANDROID

La structure XrTrackableQrCodeConfigurationANDROID est définie comme suit :

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType               type;
    const 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 l'extension ni dans le cœur d'OpenXR.
• trackingMode est un XrQrCodeTrackingModeANDROID qui indique le mode de suivi souhaité.
• qrCodeEdgeSize indique la taille du bord du code QR en mètres. Si la valeur est zéro, la taille du code QR sera estimée en ligne.

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

Si l'environnement d'exécution est compatible avec l'estimation de la taille du code QR, l'application peut définir XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize sur 0 pour indiquer l'utilisation de l'estimation de la taille. Sinon, l'application doit définir XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize sur une valeur positive. Dans le cas contraire, XR_ERROR_VALIDATION_FAILURE sera renvoyé.

L'exécution doit filtrer la sortie de xrGetAllTrackablesANDROID pour qu'elle corresponde à trackingMode et qrCodeEdgeSize.

Utilisation valide (implicite)

• L'extension XR_ANDROID_trackables_qr_code doit être activée avant d'utiliser XrTrackableQrCodeConfigurationANDROID.
• type doit être XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.
• trackingMode doit être une valeur XrQrCodeTrackingModeANDROID valide

XrQrCodeTrackingModeANDROID

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

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

| Enum | Description , and unlock your rideXR_QR_CODE_TRACKING_MODE_STATIC_ANDROID ' | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | Le code QR est dynamique et peut se déplacer. |

Obtenir des codes QR

xrGetTrackableQrCodeANDROID

La fonction xrGetTrackableQrCodeANDROID est définie comme suit :

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

Descriptions des paramètres

• tracker est le XrTrackableTrackerANDROID à interroger.
• getInfo est le XrTrackableGetInfoANDROID avec les informations utilisées pour obtenir le code QR traçable.
• qrCodeOutput est un pointeur vers la structure XrTrackableQrCodeANDROID dans laquelle le code QR suivi est renvoyé.

Le runtime doit renvoyer XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID si le type de suivi de XrTrackableANDROID n'est pas XR_TRACKABLE_TYPE_QR_CODE_ANDROID ou si le type de suivi de XrTrackableTrackerANDROID n'est pas XR_TRACKABLE_TYPE_QR_CODE_ANDROID.

Utilisation valide (implicite)

• L'extension XR_ANDROID_trackables_qr_code doit être activée avant l'appel de xrGetTrackableQrCodeANDROID.
• tracker doit être un identifiant XrTrackableTrackerANDROID valide
• getInfo doit être un pointeur vers une structure XrTrackableGetInfoANDROID valide.
• qrCodeOutput doit être un pointeur vers une structure XrTrackableQrCodeANDROID.

XrTrackableQrCodeANDROID

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 l'extension ni dans le cœur d'OpenXR.
• trackingState correspond au XrTrackingStateANDROID du code QR.
• lastUpdatedTime correspond à XrTime de la dernière mise à jour du code QR.
• centerPose correspond à XrPosef du code QR situé dans XrTrackableGetInfoANDROID::baseSpace. Le code QR se trouve dans le plan XZ, avec l'axe X pointant vers la droite du code QR et l'axe Z pointant vers le bas.
• extents correspond aux dimensions XrExtent2Df du code QR. La limite du cadre de sélection se trouve aux points suivants : centerPose +/- (extents / 2).
• bufferCapacityInput correspond à la capacité de buffer ou 0 à récupérer la capacité requise.
• bufferCountOutput Si bufferCapacityInput est défini sur 0, le runtime écrit la taille de mémoire tampon requise dans bufferCountOutput. Sinon, il contient le nombre total d'éléments écrits dans buffer.
• buffer est un pointeur vers un tableau de char pour écrire les données du code QR décodé. L'application peut transmettre un nullptr pour déterminer la taille de mémoire tampon requise ou si elle ne demande pas les données du code QR à décoder. Les données du code QR sont renvoyées sous forme de chaîne UTF-8 terminée par un caractère nul.
• Pour obtenir une description détaillée de la récupération de la taille buffer requise, consultez la section Paramètres de taille du tampon.

Utilisation valide (implicite)

• L'extension XR_ANDROID_trackables_qr_code doit être activée avant d'utiliser XrTrackableQrCodeANDROID.
• type doit être XR_TYPE_TRACKABLE_QR_CODE_ANDROID
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures.
• trackingState doit être une valeur XrTrackingStateANDROID valide
• Si bufferCapacityInput n'est pas 0, buffer doit être un pointeur vers un tableau de valeurs char bufferCapacityInput.

Exemple de code pour obtenir des codes QR traçables

L'exemple de code suivant montre comment obtenir des codes QR 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);
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    qrCodes[i].type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID;
    qrCodes[i].next = nullptr;
    qrCodes[i].bufferCountOutput = 0;
    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 constantes d'énumération

L'énumération XrStructureType est étendue avec les éléments suivants :

• XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
• XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
• XR_TYPE_TRACKABLE_QR_CODE_ANDROID

L'énumération XrTrackableTypeANDROID est étendue avec les éléments suivants :

• XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Nouvelles énumérations

• XrQrCodeTrackingModeANDROID

Nouvelles structures

• XrSystemQrCodeTrackingPropertiesANDROID
• XrTrackableQrCodeConfigurationANDROID
• XrTrackableQrCodeANDROID

Nouvelles fonctions

• xrGetTrackableQrCodeANDROID

Problèmes

Historique des versions

• Révision 1, 2025-02-05 (Levana Chen)
  • Description initiale de l'extension.

---

OpenXR™ et le logo OpenXR sont des marques déposées appartenant à The Khronos Group Inc. et sont enregistrées en Chine, dans l'Union européenne, au Japon et au Royaume-Uni.