Rozszerzenie OpenXR XR_ANDROID_trackables_qr_code

Ciąg znaków nazwy

XR_ANDROID_trackables_qr_code

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

460

Wersja

1

Zależności rozszerzeń i wersji

XR_ANDROID_trackables

Data ostatniej modyfikacji

2025-02-05

Stan adresu IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

Christopher Doer, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Nihav Jain, Google

Diego Tipaldi, Google

Ken Mackay, Google

Daniel Guttenberg, Qualcomm

Omówienie

To rozszerzenie umożliwia śledzenie fizycznych kodów QR i dekodowanie danych z kodów QR.

Sprawdzanie możliwości systemu

XrSystemQrCodeTrackingPropertiesANDROID

Struktura XrSystemQrCodeTrackingPropertiesANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type jest XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • supportsQrCodeTracking to XrBool32 wskazujący, czy bieżący system obsługuje śledzenie za pomocą kodu QR.
  • supportsQrCodeSizeEstimation to XrBool32 wskazujący, czy bieżący system umożliwia oszacowanie rozmiaru kodu QR.
  • maxQrCodeCount to łączna maksymalna liczba kodów QR, które można śledzić jednocześnie.

Aplikacja może sprawdzić, czy system obsługuje śledzenie kodu QR, rozszerzając XrSystemProperties o strukturę XrSystemQrCodeTrackingPropertiesANDROID podczas wywoływania xrGetSystemProperties. Środowisko wykonawcze musi zwracać XR_ERROR_FEATURE_UNSUPPORTED w przypadku tworzenia narzędzia do śledzenia za pomocą kodu QR, jeśli i tylko jeśli supportsQrCodeTracking jest równe XR_FALSE.

Jeśli środowisko wykonawcze obsługuje śledzenie kodów QR, musi obsługiwać maxQrCodeCount śledzone kody QR w dowolnym momencie.

Jeśli środowisko wykonawcze obsługuje szacowanie rozmiaru kodu QR, aplikacja może ustawić wartość XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 0, aby wskazać użycie szacowania rozmiaru. W przeciwnym razie aplikacja musi ustawić wartość XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize na wartość dodatnią lub zostanie zwrócona wartość XR_ERROR_VALIDATION_FAILURE.

Prawidłowe użycie (domyślne)

  • Rozszerzenie XR_ANDROID_trackables_qr_code musi być włączone przed użyciem XrSystemQrCodeTrackingPropertiesANDROID.
  • type musi mieć wartość XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • next musi być wartością NULL lub prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur.

Śledzenie kodów QR

To rozszerzenie dodaje XR_TRACKABLE_TYPE_QR_CODE_ANDROID do XrTrackableTypeANDROID.

Aplikacja może utworzyć XrTrackableTrackerANDROID, wywołując xrCreateTrackableTrackerANDROID i określając XR_TRACKABLE_TYPE_QR_CODE_ANDROID jako typ śledzenia w XrTrackableTrackerCreateInfoANDROID::trackableType, aby śledzić kody QR.

Środowisko wykonawcze musi zwrócić wartość XR_ERROR_FEATURE_UNSUPPORTED, jeśli XrTrackableTrackerCreateInfoANDROID::trackableType ma wartość XR_TRACKABLE_TYPE_QR_CODE_ANDROID, a XrSystemQrCodeTrackingPropertiesANDROID::supportsQrCodeTracking zwraca wartość XR_FALSE za pomocą xrGetSystemProperties.

XrTrackableQrCodeConfigurationANDROID

Struktura XrTrackableQrCodeConfigurationANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type jest XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • trackingMode to XrQrCodeTrackingModeANDROID wskazujący odpowiedni tryb śledzenia.
  • qrCodeEdgeSize oznacza rozmiar krawędzi kodu QR w metrach. Jeśli wartość wynosi zero, rozmiar kodu QR zostanie oszacowany online.

Aplikacja musi ustawić prawidłową konfigurację, dodając XrTrackableQrCodeConfigurationANDROID do następnego łańcucha XrTrackableTrackerCreateInfoANDROID. W przeciwnym razie środowisko wykonawcze musi zwrócić wartość XR_ERROR_VALIDATION_FAILURE.

Jeśli środowisko wykonawcze obsługuje szacowanie rozmiaru kodu QR, aplikacja może ustawić wartość XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize na 0, aby wskazać użycie szacowania rozmiaru. W przeciwnym razie aplikacja musi ustawić wartość XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize na wartość dodatnią lub zostanie zwrócona wartość XR_ERROR_VALIDATION_FAILURE.

Filtr czasu działania musi filtrować dane wyjściowe z xrGetAllTrackablesANDROID, aby pasowały do trackingMode i qrCodeEdgeSize.

Prawidłowe użycie (domyślne)

  • Rozszerzenie XR_ANDROID_trackables_qr_code musi być włączone przed użyciem XrTrackableQrCodeConfigurationANDROID.
  • type musi mieć wartość XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • next musi być wartością NULL lub prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur.
  • trackingMode musi być prawidłową wartością XrQrCodeTrackingModeANDROID.

XrQrCodeTrackingModeANDROID

Wyliczenie XrQrCodeTrackingModeANDROID opisuje obsługiwane tryby śledzenia kodów QR.

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 -0x0A>| XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID | The QR Code is static and does not move. ' | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | Kod QR jest dynamiczny i może się przesuwać. |

Uzyskiwanie kodów QR

xrGetTrackableQrCodeANDROID

Funkcja xrGetTrackableQrCodeANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

  • tracker to XrTrackableTrackerANDROID, o który chcesz zapytać.
  • getInfo to XrTrackableGetInfoANDROID z informacjami używanymi do uzyskania kodu QR z możliwością śledzenia.
  • qrCodeOutput to wskaźnik struktury XrTrackableQrCodeANDROID, w której zwracany jest śledzony kod QR.

Środowisko wykonawcze musi zwracać XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID, jeśli typ śledzenia elementu XrTrackableANDROID nie jest równy XR_TRACKABLE_TYPE_QR_CODE_ANDROID lub jeśli typ śledzenia elementu XrTrackableTrackerANDROID nie jest równy XR_TRACKABLE_TYPE_QR_CODE_ANDROID.

Prawidłowe użycie (domyślne)

  • Przed wywołaniem xrGetTrackableQrCodeANDROID musisz włączyć XR_ANDROID_trackables_qr_code rozszerzenie.
  • tracker musi być prawidłowym identyfikatorem XrTrackableTrackerANDROID
  • getInfo musi być wskaźnikiem do prawidłowej struktury XrTrackableGetInfoANDROID
  • qrCodeOutput musi być wskaźnikiem do struktury XrTrackableQrCodeANDROID.

XrTrackableQrCodeANDROID

Struktura XrTrackableQrCodeANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type jest XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • trackingState to XrTrackingStateANDROID kodu QR.
  • lastUpdatedTime to XrTime ostatniej aktualizacji kodu QR.
  • centerPose to XrPosef kodu QR znajdującego się w XrTrackableGetInfoANDROID::baseSpace. Kod QR znajduje się w płaszczyźnie XZ, przy czym oś X jest skierowana na prawo od kodu QR, a oś Z – w dół.
  • extents to XrExtent2Df wymiary kodu QR. Granica ramki ograniczającej znajduje się w punktach: centerPose +/- (extents / 2).
  • bufferCapacityInput to możliwość buffer lub 0 pobrania wymaganej funkcji.
  • bufferCountOutput Jeśli wartość bufferCapacityInput to 0, środowisko wykonawcze zapisze wymagany rozmiar bufora w bufferCountOutput. W przeciwnym razie zawiera łączną liczbę elementów zapisanych w buffer.
  • buffer to wskaźnik do tablicy char, do której zapisywane są zdekodowane dane kodu QR. Aplikacja może przekazać wartość nullptr, aby określić wymagany rozmiar bufora lub jeśli nie żąda danych z dekodowania kodu QR. Dane kodu QR są zwracane jako ciąg znaków UTF-8 zakończony znakiem null.
  • Szczegółowy opis pobierania wymaganego rozmiaru buffer znajdziesz w sekcji Parametry rozmiaru bufora.

Prawidłowe użycie (domyślne)

  • Rozszerzenie XR_ANDROID_trackables_qr_code musi być włączone przed użyciem XrTrackableQrCodeANDROID.
  • type musi mieć wartość XR_TYPE_TRACKABLE_QR_CODE_ANDROID
  • next musi być wartością NULL lub prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur.
  • trackingState musi być prawidłową wartością XrTrackingStateANDROID.
  • Jeśli bufferCapacityInput nie jest równe 0, buffer musi być wskaźnikiem do tablicy wartości bufferCapacityInput typu char.

Przykładowy kod do uzyskiwania kodów QR z możliwością śledzenia

Poniższy przykładowy kod pokazuje, jak uzyskać kody QR z możliwością śledzenia.

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

Nowe stałe wyliczeniowe

Wyliczenie XrStructureType zostało rozszerzone o:

  • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_ANDROID

Wyliczenie XrTrackableTypeANDROID zostało rozszerzone o:

  • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Nowe wartości w polu enum

  • XrQrCodeTrackingModeANDROID

Nowe struktury

  • XrSystemQrCodeTrackingPropertiesANDROID
  • XrTrackableQrCodeConfigurationANDROID
  • XrTrackableQrCodeANDROID

Nowe funkcje

  • xrGetTrackableQrCodeANDROID

Problemy

Historia wersji

  • Wersja 1, 5 lutego 2025 r. (Levana Chen)
    • Początkowy opis rozszerzenia.

OpenXR™ i logo OpenXR są znakami towarowymi należącymi do The Khronos Group Inc. i są zarejestrowane jako znaki towarowe w Chinach, Unii Europejskiej, Japonii i Wielkiej Brytanii.