XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

709

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

XR_ANDROID_trackables

Stan wycofania

  • 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 XR_ANDROID_trackables i ujawnia geometrię środowiska. Uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE jest uznawane za niebezpieczne.

(poziom ochrony: niebezpieczne)

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 członków

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

Aplikacja może sprawdzić, czy system jest w stanie śledzić kody QR, rozszerzając XrSystemProperties o strukturę XrSystemQrCodeTrackingPropertiesANDROID podczas wywoływania xrGetSystemProperties . Środowisko wykonawcze musi zwracać XR_ERROR_FEATURE_UNSUPPORTED w przypadku tworzenia modułu śledzenia za pomocą kodu QR tylko wtedy, gdy supportsQrCodeTracking to XR_FALSE .

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

Prawidłowe użycie (pośrednie)

Śledzenie za pomocą 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 obiektu śledzonego w XrTrackableTrackerCreateInfoANDROID :: trackableType, aby śledzić kody QR.

Środowisko wykonawcze musi zwracać XR_ERROR_FEATURE_UNSUPPORTED, jeśli XrTrackableTrackerCreateInfoANDROID :: trackableType to XR_TRACKABLE_TYPE_QR_CODE_ANDROID, a XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking zwraca XR_FALSE przez xrGetSystemProperties .

Struktura XrTrackableQrCodeConfigurationANDROID jest zdefiniowana w ten sposób:

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

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie 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 wynosi 0, ś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 funkcji xrGetAllTrackablesANDROID, aby pasowały do trackingMode . Jeśli właściwość XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize nie jest ustawiona na 0.0, środowisko wykonawcze musi zwracać tylko kody QR, które pasują do tego rozmiaru. Jeśli parametr XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize jest ustawiony na 0.0, środowisko wykonawcze musi zwracać wszystkie kody QR z szacowanym rozmiarem.

Prawidłowe użycie (pośrednie)

Typ wyliczeniowy 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 elementów wyliczenia

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID – śledzenie dynamicznych kodów QR. Ten tryb zapewnia 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 stałych 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 powinien być używany 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 jeśli kod QR zniknie z pola widzenia ramki odniesienia. Dzięki temu po śledzeniu kodu QR zużycie energii jest minimalne. (dodane przez rozszerzenie XR_QCOM_trackables_qr_code_operations)

Uzyskiwanie 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 zwracać 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 zwrotu

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 członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • trackingState to XrTrackingStateANDROID kodu QR.
  • lastUpdatedTime to XrTime ostatniej aktualizacji kodu QR. Jeśli wartość lastUpdatedTime zmieniła się od ostatniego wywołania, wszystkie inne pola mogły ulec zmianie.
  • centerPose to XrPosef kodu QR znajdującego się w XrTrackableGetInfoANDROID :: baseSpace . Kod QR znajduje się na płaszczyźnie XZ, gdzie oś X wskazuje prawą stronę kodu QR, oś Z – jego dół, a oś Y – prostopadłą do kodu QR.
  • extents to wymiary XrExtent2Df kodu QR. Granica ramki ograniczającej znajduje się w punktach: centerPose +/- ( extents / 2).
  • bufferCapacityInput to funkcja buffer lub 0, która umożliwia pobranie wymaganej funkcji.
  • bufferCountOutput Jeśli bufferCapacityInput to 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ć wartość bufferCountOutput na 0.
  • buffer to wskaźnik do tablicy char, w której mają zostać zapisane zdekodowane dane kodu QR. Jeśli aplikacja nie potrzebuje zdekodowanych danych z 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 uzyskiwania kodów QR możliwych do śledzenia

Poniższy przykładowy kod pokazuje, jak uzyskać kody QR możliwe do ś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, {
  .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 domy

Nowe wartości w polu enum

Nowe stałe typu wyliczeniowego

  • 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 lutego 2025 r. (Levana Chen)

    • Początkowy opis rozszerzenia.