OpenXR-Erweiterung XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

460

Revision

1

Abhängigkeiten von Erweiterungen und Versionen

XR_ANDROID_trackables

Datum der letzten Änderung

2025-02-05

IP-Status

Es sind keine Ansprüche wegen geistigen Eigentums bekannt.

Mitwirkende

Christopher Doer, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Nihav Jain, Google

Diego Tipaldi, Google

Ken Mackay, Google

Daniel Guttenberg, Qualcomm

Übersicht

Mit dieser Erweiterung können physische QR‑Codes getrackt und QR‑Code-Daten decodiert werden.

Systemfunktionen prüfen

XrSystemQrCodeTrackingPropertiesANDROID

Die XrSystemQrCodeTrackingPropertiesANDROID-Struktur ist so definiert:

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

Mitgliederbeschreibungen

  • type ist die XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • supportsQrCodeTracking ist ein XrBool32, das angibt, ob das aktuelle System QR-Code-Tracking unterstützt.
  • supportsQrCodeSizeEstimation ist ein XrBool32, der angibt, ob das aktuelle System eine Schätzung der QR-Code-Größe bietet.
  • maxQrCodeCount ist die maximale Gesamtzahl der QR‑Codes, die gleichzeitig erfasst werden können.

Eine Anwendung kann prüfen, ob das System QR-Code-Tracking unterstützt, indem sie XrSystemProperties mit der Struktur XrSystemQrCodeTrackingPropertiesANDROID erweitert, wenn xrGetSystemProperties aufgerufen wird. Die Laufzeit muss XR_ERROR_FEATURE_UNSUPPORTED für die Erstellung von QR-Code-Trackern zurückgeben, wenn und nur wenn supportsQrCodeTracking XR_FALSE ist.

Wenn eine Laufzeit QR-Code-Tracking unterstützt, muss sie jederzeit maxQrCodeCount verfolgte QR-Codes unterstützen.

Wenn eine Laufzeit die Schätzung der QR-Code-Größe unterstützt, kann die Anwendung XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 0 festlegen, um die Verwendung der Größenschätzung anzugeben. Andernfalls muss die Anwendung XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize auf einen positiven Wert festlegen. Andernfalls wird XR_ERROR_VALIDATION_FAILURE zurückgegeben.

Gültige Nutzung (implizit)

  • Die Erweiterung XR_ANDROID_trackables_qr_code muss aktiviert sein, bevor Sie XrSystemQrCodeTrackingPropertiesANDROID verwenden können.
  • type muss XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID sein.
  • next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.

QR-Codes erfassen

Diese Erweiterung fügt XR_TRACKABLE_TYPE_QR_CODE_ANDROID zu XrTrackableTypeANDROID hinzu.

Die Anwendung kann ein XrTrackableTrackerANDROID erstellen, indem sie xrCreateTrackableTrackerANDROID aufruft und XR_TRACKABLE_TYPE_QR_CODE_ANDROID als verfolgbaren Typ in XrTrackableTrackerCreateInfoANDROID::trackableType angibt, um QR-Codes zu verfolgen.

Die Laufzeit muss XR_ERROR_FEATURE_UNSUPPORTED zurückgeben, wenn XrTrackableTrackerCreateInfoANDROID::trackableType gleich XR_TRACKABLE_TYPE_QR_CODE_ANDROID ist und XrSystemQrCodeTrackingPropertiesANDROID::supportsQrCodeTracking über xrGetSystemProperties XR_FALSE zurückgibt.

XrTrackableQrCodeConfigurationANDROID

Die XrTrackableQrCodeConfigurationANDROID-Struktur ist so definiert:

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

Mitgliederbeschreibungen

  • type ist die XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • trackingMode ist ein XrQrCodeTrackingModeANDROID, der den gewünschten Modus für das Tracking angibt.
  • qrCodeEdgeSize gibt die Länge der QR‑Code-Kante in Metern an. Wenn der Wert null ist, wird die Größe des QR-Codes online geschätzt.

Die Anwendung muss eine gültige Konfiguration festlegen, indem sie der nächsten Kette von XrTrackableTrackerCreateInfoANDROID ein XrTrackableQrCodeConfigurationANDROID hinzufügt. Andernfalls muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben.

Wenn die Laufzeit die Schätzung der QR-Code-Größe unterstützt, kann die Anwendung XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize auf 0 festlegen, um die Verwendung der Größenschätzung anzugeben. Andernfalls muss die Anwendung XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize auf einen positiven Wert festlegen. Andernfalls wird XR_ERROR_VALIDATION_FAILURE zurückgegeben.

Die Laufzeit muss die Ausgabe von xrGetAllTrackablesANDROID filtern, damit sie mit trackingMode und qrCodeEdgeSize übereinstimmt.

Gültige Nutzung (implizit)

  • Die Erweiterung XR_ANDROID_trackables_qr_code muss aktiviert sein, bevor Sie XrTrackableQrCodeConfigurationANDROID verwenden können.
  • type muss XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID sein.
  • next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
  • trackingMode muss ein gültiger XrQrCodeTrackingModeANDROID-Wert sein

XrQrCodeTrackingModeANDROID

Das Enum XrQrCodeTrackingModeANDROID beschreibt die unterstützten Tracking-Modi von QR-Codes.

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 | Beschreibung chaft.XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID ' | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | Der QR-Code ist dynamisch und kann sich bewegen. |

QR-Codes abrufen

xrGetTrackableQrCodeANDROID

Die Funktion xrGetTrackableQrCodeANDROID ist so definiert:

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

Parameterbeschreibungen

  • tracker ist die XrTrackableTrackerANDROID, die abgefragt werden soll.
  • getInfo ist die XrTrackableGetInfoANDROID mit den Informationen, die zum Abrufen des trackbaren QR‑Codes verwendet werden.
  • qrCodeOutput ist ein Zeiger auf die XrTrackableQrCodeANDROID-Struktur, in der der verfolgbare QR-Code zurückgegeben wird.

Die Laufzeit muss XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID zurückgeben, wenn der verfolgbare Typ von XrTrackableANDROID nicht XR_TRACKABLE_TYPE_QR_CODE_ANDROID ist oder wenn der verfolgbare Typ von XrTrackableTrackerANDROID nicht XR_TRACKABLE_TYPE_QR_CODE_ANDROID ist.

Gültige Nutzung (implizit)

  • Die XR_ANDROID_trackables_qr_code-Erweiterung muss aktiviert sein, bevor xrGetTrackableQrCodeANDROID aufgerufen wird.
  • tracker muss ein gültiger XrTrackableTrackerANDROID-Alias sein.
  • getInfo muss ein Zeiger auf eine gültige XrTrackableGetInfoANDROID-Struktur sein.
  • qrCodeOutput muss ein Zeiger auf eine XrTrackableQrCodeANDROID-Struktur sein.

XrTrackableQrCodeANDROID

Die XrTrackableQrCodeANDROID-Struktur ist so definiert:

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

Mitgliederbeschreibungen

  • type ist die XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.
  • trackingState ist die XrTrackingStateANDROID des QR‑Codes.
  • lastUpdatedTime ist die XrTime der letzten Aktualisierung des QR‑Codes.
  • centerPose ist die XrPosef des QR‑Codes in XrTrackableGetInfoANDROID::baseSpace. Der QR‑Code liegt in der XZ‑Ebene, wobei X nach rechts und Z nach unten zeigt.
  • extents sind die XrExtent2Df-Abmessungen des QR-Codes. Die Grenze des Begrenzungsrahmens liegt bei den Punkten: centerPose +/- (extents / 2).
  • bufferCapacityInput ist die Funktion des buffer oder 0, um die erforderliche Funktion abzurufen.
  • bufferCountOutput: Wenn bufferCapacityInput gleich 0 ist, schreibt die Laufzeit die erforderliche Puffergröße in bufferCountOutput. Andernfalls enthält sie die Gesamtzahl der in buffer geschriebenen Elemente.
  • buffer ist ein Zeiger auf ein Array von char, in das die decodierten QR‑Code-Daten geschrieben werden. Die Anwendung kann ein nullptr übergeben, um die erforderliche Puffergröße zu ermitteln oder um anzugeben, dass die Daten des decodierten QR‑Codes nicht angefordert werden. Die QR-Code-Daten werden als nullterminierter UTF-8-String zurückgegeben.
  • Eine detaillierte Beschreibung zum Abrufen der erforderlichen buffer-Größe finden Sie im Abschnitt Puffergrößenparameter.

Gültige Nutzung (implizit)

  • Die Erweiterung XR_ANDROID_trackables_qr_code muss aktiviert sein, bevor Sie XrTrackableQrCodeANDROID verwenden können.
  • type muss XR_TYPE_TRACKABLE_QR_CODE_ANDROID sein.
  • next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
  • trackingState muss ein gültiger XrTrackingStateANDROID-Wert sein
  • Wenn bufferCapacityInput nicht 0 ist, muss buffer ein Zeiger auf ein Array von bufferCapacityInput-Zeichenwerten sein.

Beispielcode zum Abrufen von QR-Codes mit Tracking

Der folgende Beispielcode zeigt, wie Sie nachverfolgbare QR‑Codes abrufen.

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));

Neue Enum-Konstanten

Die Aufzählung XrStructureType wird um Folgendes erweitert:

  • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_ANDROID

Die Aufzählung XrTrackableTypeANDROID wird um Folgendes erweitert:

  • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Neue Enums

  • XrQrCodeTrackingModeANDROID

Neue Strukturen

  • XrSystemQrCodeTrackingPropertiesANDROID
  • XrTrackableQrCodeConfigurationANDROID
  • XrTrackableQrCodeANDROID

Neue Funktionen

  • xrGetTrackableQrCodeANDROID

Probleme

Versionsverlauf

  • Revision 1, 05.02.2025 (Levana Chen)
    • Erste Beschreibung der Erweiterung.

OpenXR™ und das OpenXR-Logo sind Marken von The Khronos Group Inc. und sind in China, der Europäischen Union, Japan und dem Vereinigten Königreich als Marke eingetragen.