XR_ANDROID_trackables_qr_code

Nazwa ciągu znaków

XR_ANDROID_trackables_qr_code

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer rozszerzenia

709

Wersja

1

Stan ratyfikacji

Niezatwierdzone

Zależności rozszerzenia i wersji

XR_ANDROID_trackables

Stan wycofywania

  • Wycofane przez rozszerzenie XR_EXT_spatial_marker_tracking

Data ostatniej modyfikacji

5.02.2025 r.

Stan 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

Przegląd

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

Uprawnienia

Aplikacje na Androida muszą mieć w pliku manifestu uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE, ponieważ to rozszerzenie zależy od rozszerzenia XR_ANDROID_trackables i udostępnia geometrię otoczenia. Uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE jest uważane za niebezpieczne.

(poziom ochrony: niebezpieczny)

Sprawdzanie możliwości systemu

Struktura XrSystemQrCodeTrackingPropertiesANDROID jest zdefiniowana w ten sposób:

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

Opisy elementów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym 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 obsługuje szacowanie 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 za pomocą kodu QR, rozszerzając XrSystemProperties o strukturę XrSystemQrCodeTrackingPropertiesANDROID podczas wywoływania xrGetSystemProperties . Środowisko wykonawcze musi zwrócić XR_ERROR_FEATURE_UNSUPPORTED w przypadku tworzenia trackera kodu QR tylko wtedy, gdy supportsQrCodeTracking ma wartość XR_FALSE .

Jeśli środowisko wykonawcze obsługuje śledzenie za pomocą kodu QR, maxQrCodeCount musi mieć wartość co najmniej 1. Jeśli środowisko wykonawcze nie obsługuje śledzenia za pomocą kodu QR, maxQrCodeCount musi mieć wartość 0.

Prawidłowe użycie (pośrednie)

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

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

Struktura XrTrackableQrCodeConfigurationANDROID jest zdefiniowana w ten sposób:

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

Opisy elementów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • trackingMode to XrQrCodeTrackingModeANDROID wskazujący żądany tryb śledzenia.
  • qrCodeEdgeSize wskazuje rozmiar krawędzi kodu QR w metrach. Jeśli wartość wynosi zero, środowisko wykonawcze szacuje rozmiar kodu QR online.

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

Jeśli środowisko wykonawcze obsługuje szacowanie rozmiaru kodu QR, aplikacja może ustawić XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize na 0.0, aby wskazać użycie szacowania rozmiaru.

Jeśli środowisko wykonawcze nie obsługuje szacowania rozmiaru kodu QR, aplikacja musi ustawić XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize na wartość dodatnią. W przeciwnym razie środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE.

Środowisko wykonawcze musi filtrować dane wyjściowe z xrGetAllTrackablesANDROID, aby pasowały do trackingMode . Jeśli XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize nie jest ustawione na 0.0, środowisko wykonawcze musi zwracać tylko kody QR pasujące do tego rozmiaru. Jeśli XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize jest ustawione na 0.0, środowisko wykonawcze musi zwracać wszystkie kody QR o szacowanym rozmiarze.

Prawidłowe użycie (pośrednie)

Wyliczenie XrQrCodeTrackingModeANDROID opisuje obsługiwane tryby śledzenia kodów 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;

Opisy wyliczeń

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID – śledzenie dynamicznych kodów QR. Ten tryb ma najwyższą dokładność i działa w przypadku ruchomych i statycznych kodów QR, ale też zużywa najwięcej energii.
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID – śledzenie statycznych kodów QR. Ten tryb jest przydatny głównie w przypadku kodów QR, które są statyczne, co prowadzi do mniejszego zużycia energii w porównaniu z trybem dynamicznym.
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM – ten tryb należy stosować w przypadku statycznych kodów QR. W przeciwieństwie do trybu statycznego ten tryb śledzi kod QR tylko raz, a następnie aktualizuje pozycje śledzonych instancji wyłącznie na podstawie pozycji urządzenia. Dzięki temu śledzenie jest kontynuowane nawet wtedy, gdy kod QR wyjdzie poza pole widzenia ramki odniesienia. Po śledzeniu kodu QR zużycie energii jest minimalne. (Dodane przez rozszerzenie XR_QCOM_trackables_qr_code_operations)

Pobieranie kodów QR

Funkcja xrGetTrackableQrCodeANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

Środowisko wykonawcze musi zwrócić XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID , jeśli typ śledzenia XrTrackableANDROID nie jest XR_TRACKABLE_TYPE_QR_CODE_ANDROID lub jeśli typ śledzenia XrTrackableTrackerANDROID nie jest XR_TRACKABLE_TYPE_QR_CODE_ANDROID .

Prawidłowe użycie (pośrednie)

Kody powrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

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 elementów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • trackingState to XrTrackingStateANDROID kodu QR.
  • lastUpdatedTime to XrTime ostatniej aktualizacji kodu QR. Jeśli lastUpdatedTime zmieni się od ostatniego wywołania, wszystkie inne pola mogą się zmienić.
  • centerPose to XrPosef kodu QR znajdującego się w XrTrackableGetInfoANDROID :: baseSpace . Kod QR znajduje się w płaszczyźnie XZ, przy czym X wskazuje na prawą stronę kodu QR, Z na jego dół, a Y wychodzi z kodu QR jako normalna.
  • extents to wymiary XrExtent2Df kodu QR. Granica ramki ograniczającej znajduje się w punktach: centerPose +/- ( extents / 2).
  • bufferCapacityInput to pojemność buffer lub 0 , aby pobrać wymaganą pojemność.
  • bufferCountOutput Jeśli bufferCapacityInput ma wartość 0 , środowisko wykonawcze zapisze wymagany rozmiar bufora w bufferCountOutput . W przeciwnym razie zawiera łączną liczbę elementów zapisanych w buffer . Jeśli dane kodu QR nie zostały jeszcze zdekodowane, środowisko wykonawcze musi ustawić bufferCountOutput na 0.
  • buffer to wskaźnik do tablicy char, w której zapisywane są zdekodowane dane kodu QR. Jeśli aplikacja nie potrzebuje zdekodowanych danych kodu QR, może przekazać nullptr i pominąć drugie wywołanie. 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 (pośrednie)

Przykładowy kod do pobierania śledzonych kodów QR

Poniższy przykładowy kod pokazuje, jak pobierać śledzone kody QR.

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

Nowe polecenia

Nowe struktury

Nowe wyliczenia

Nowe stałe wyliczenia

  • XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
  • XR_ANDROID_trackables_qr_code_SPEC_VERSION

  • Rozszerzanie XrStructureType :

    • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID

  • Rozszerzanie XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Problemy

Historia zmian

  • Wersja 1, 5.02.2025 r. (Levana Chen)

    • Wstępny opis rozszerzenia.