XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

Erweiterungstyp

Instanzerweiterung

Registrierte Erweiterungsnummer

709

Revision

1

Ratifizierungsstatus

Nicht ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

XR_ANDROID_trackables

Einstellungsstatus

  • Eingestellt durch die Erweiterung XR_EXT_spatial_marker_tracking

Datum der letzten Änderung

05.02.2025

IP-Status

Keine bekannten IP-Ansprüche.

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 verfolgt und QR-Code-Daten decodiert werden.

Berechtigungen

Android-Anwendungen müssen die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ in ihrem Manifest auflisten, da diese Erweiterung von XR_ANDROID_trackables abhängt und die Geometrie der Umgebung offenlegt. Die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ gilt als gefährliche Berechtigung.

(Schutzstufe: gefährlich)

Systemfunktionen prüfen

Die Struktur „XrSystemQrCodeTrackingPropertiesANDROID“ ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. In OpenXR Core oder dieser Erweiterung sind keine solchen Strukturen definiert.
  • supportsQrCodeTracking ist ein XrBool32, der angibt, ob das aktuelle System die Funktion zum Verfolgen von QR-Codes bietet.
  • supportsQrCodeSizeEstimation ist ein XrBool32, der angibt, ob das aktuelle System die Funktion zum Schätzen der QR-Code-Größe bietet.
  • maxQrCodeCount ist die maximale Anzahl von QR-Codes, die gleichzeitig verfolgt werden können.

Eine Anwendung kann prüfen, ob das System QR-Codes verfolgen kann, indem sie die XrSystemProperties beim Aufrufen von xrGetSystemProperties mit der Struktur „XrSystemQrCodeTrackingPropertiesANDROID“ erweitert . Die Laufzeit muss XR_ERROR_FEATURE_UNSUPPORTED für die Erstellung von QR-Code-Trackern zurückgeben, wenn supportsQrCodeTracking XR_FALSE ist .

Wenn eine Laufzeit das Verfolgen von QR-Codes unterstützt, muss maxQrCodeCount mindestens 1 sein. Wenn eine Laufzeit das Verfolgen von QR-Codes nicht unterstützt, muss maxQrCodeCount 0 sein.

Gültige Verwendung (implizit)

QR-Codes verfolgen

Diese Erweiterung fügt XR_TRACKABLE_TYPE_QR_CODE_ANDROID zu XrTrackableTypeANDROID hinzu .

Die Anwendung kann einen 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 XR_TRACKABLE_TYPE_QR_CODE_ANDROID ist und XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking über xrGetSystemProperties XR_FALSE zurückgibt .

Die Struktur „XrTrackableQrCodeConfigurationANDROID“ ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. In OpenXR Core oder dieser Erweiterung sind keine solchen Strukturen definiert.
  • trackingMode ist ein XrQrCodeTrackingModeANDROID, der den gewünschten Modus für das Tracking angibt.
  • qrCodeEdgeSize gibt die Größe der QR-Code-Kante in Metern an. Wenn der Wert null ist, schätzt die Laufzeit die QR-Code-Größe online.

Die Anwendung muss eine gültige Konfiguration festlegen, indem sie XrTrackableQrCodeConfigurationANDROID zur nächsten Kette von XrTrackableTrackerCreateInfoANDROID 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.0 setzen, um die Verwendung der Schätzung anzugeben.

Wenn die Laufzeit die Schätzung der QR-Code-Größe nicht unterstützt, muss die Anwendung XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize auf einen positiven Wert setzen. Andernfalls muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben.

Die Laufzeit muss die Ausgabe von xrGetAllTrackablesANDROID so filtern, dass sie dem trackingMode entspricht . Wenn XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize nicht auf 0.0 gesetzt ist, muss die Laufzeit nur QR-Codes zurückgeben, die dieser Größe entsprechen. Wenn XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize auf 0.0 gesetzt ist, muss die Laufzeit alle QR-Codes mit geschätzter Größe zurückgeben.

Gültige Verwendung (implizit)

Die Enumeration „XrQrCodeTrackingModeANDROID“ beschreibt die unterstützten Tracking-Modi von QR-Codes.

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;

Beschreibungen der Enumerationswerte

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID: Dynamische QR-Codes verfolgen. Dieser Modus bietet die höchste Genauigkeit und funktioniert mit beweglichen und statischen QR-Codes, hat aber auch den höchsten Stromverbrauch.
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID: Statische QR-Codes verfolgen. Dieser Modus ist hauptsächlich für QR-Codes nützlich, die bekanntermaßen statisch sind. Dadurch wird im Vergleich zum dynamischen Modus weniger Strom verbraucht.
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM: Dieser Modus sollte für statische QR-Codes verwendet werden. Im Gegensatz zum statischen Modus wird der QR-Code nur einmal verfolgt. Die Positionen der verfolgten Instanzen werden dann ausschließlich anhand der Geräteposition aktualisiert. Dadurch wird das Tracking auch dann fortgesetzt, wenn der QR-Code aus dem Blickfeld des Referenzrahmens gerät. Sobald der QR-Code verfolgt wurde, ist der Stromverbrauch minimal. (Hinzugefügt durch die Erweiterung XR_QCOM_trackables_qr_code_operations)

QR-Codes abrufen

Die Funktion „xrGetTrackableQrCodeANDROID“ ist so definiert:

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

Parameterbeschreibungen

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

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Struktur „XrTrackableQrCodeANDROID“ 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 der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. In OpenXR Core oder dieser Erweiterung sind keine solchen Strukturen definiert.
  • trackingState ist der XrTrackingStateANDROID des QR-Codes.
  • lastUpdatedTime ist die XrTime der letzten Aktualisierung des QR-Codes. Wenn sich lastUpdatedTime seit dem letzten Aufruf geändert hat, können sich auch alle anderen Felder geändert haben.
  • centerPose ist die XrPosef des QR-Codes in XrTrackableGetInfoANDROID :: baseSpace . Der QR-Code liegt in der XZ-Ebene, wobei X nach rechts vom QR-Code zeigt, Z nach unten und Y als Normale aus dem QR-Code herauskommt.
  • extents sind die XrExtent2Df-Dimensionen des QR-Codes. Die Grenze des Begrenzungsrahmens liegt an den Punkten: centerPose +/- ( extents / 2).
  • bufferCapacityInput ist die Kapazität des buffer oder 0 , um die erforderliche Kapazität abzurufen.
  • bufferCountOutput: Wenn bufferCapacityInput 0 ist , schreibt die Laufzeit die erforderliche Puffergröße in bufferCountOutput . Andernfalls enthält sie die Gesamtzahl der in buffer geschriebenen Elemente . Wenn die QR-Code-Daten noch nicht decodiert wurden, muss die Laufzeit „bufferCountOutput“ auf 0 setzen.
  • buffer ist ein Zeiger auf ein Array von char, in das die decodierten QR-Code-Daten geschrieben werden. Wenn die Anwendung die decodierten QR-Code-Daten nicht benötigt, kann sie nullptr übergeben und den zweiten Aufruf mit zwei Aufrufen weglassen. Die QR-Code-Daten werden als nullterminierter UTF-8-String zurückgegeben.
  • Eine detaillierte Beschreibung des Abrufens der erforderlichen buffer Größe finden Sie im Abschnitt Parameter für die Puffergröße.

Gültige Verwendung (implizit)

Beispielcode zum Abrufen verfolgbarer QR-Codes

Der folgende Beispielcode zeigt, wie verfolgbare QR-Codes abgerufen werden.

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

Neue Befehle

Neue Strukturen

Neue Enumerationen

Neue Enumerationskonstanten

  • XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
  • XR_ANDROID_trackables_qr_code_SPEC_VERSION

  • XrStructureType erweitern :

    • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID

  • XrTrackableTypeANDROID erweitern :

    • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Probleme

Versionsverlauf

  • Revision 1, 05.02.2025 (Levana Chen)

    • Erste Beschreibung der Erweiterung.