XR_ANDROID_trackables_image

Name String

XR_ANDROID_trackables_image

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

710

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

XR_EXT_future
oraz
XR_ANDROID_trackables

Data ostatniej modyfikacji

2025-04-08

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
Daniel Guttenberg, Qualcomm
Mark Vadasi, Qualcomm
Markus Birkner, Qualcomm
Maximilian Mayer, Qualcomm

Przegląd

To rozszerzenie umożliwia śledzenie obrazów planarnych określonych przez zestawy wejściowych obrazów referencyjnych.

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 XrSystemImageTrackingPropertiesANDROID jest zdefiniowana w ten sposób:

typedef struct XrSystemImageTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsImageTracking;
    XrBool32           supportsPhysicalSizeEstimation;
    uint32_t           maxTrackedImageCount;
    uint32_t           maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;

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. Więcej informacji o łańcuchu struktur znajdziesz w rozszerzanej strukturze ( XrSystemProperties).
  • supportsImageTracking to XrBool32, który wskazuje, czy bieżący system zapewnia możliwość śledzenia obrazu.
  • supportsPhysicalSizeEstimation to XrBool32 wskazujący, czy bieżący system udostępnia szacowany rozmiar obrazu.
  • maxTrackedImageCount to maksymalna liczba obrazów, które mogą być śledzone jednocześnie.
  • maxLoadedImageCount to maksymalna łączna liczba obrazów referencyjnych, które można wczytać we wszystkich bazach danych.

Aplikacja może sprawdzić, czy system jest w stanie śledzić obrazy, rozszerzając XrSystemProperties o strukturę XrSystemImageTrackingPropertiesANDROID podczas wywoływania xrGetSystemProperties . Środowisko wykonawcze musi zwracać XR_ERROR_FEATURE_UNSUPPORTED w przypadku tworzenia modułu śledzenia obrazu tylko wtedy, gdy supportsImageTracking to XR_FALSE .

Jeśli środowisko wykonawcze obsługuje śledzenie obrazów, musi obsługiwać maxTrackedImageCount śledzonych obrazów w dowolnym momencie.

Jeśli środowisko wykonawcze obsługuje śledzenie obrazów, musi obsługiwać maxLoadedImageCount załadowanych obrazów w dowolnym momencie.

Jeśli środowisko wykonawcze obsługuje szacowanie rozmiaru obrazu, aplikacja może ustawić XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0, aby wskazać użycie szacowania rozmiaru. W przeciwnym razie aplikacja musi ustawić XrTrackableImageDatabaseEntryANDROID :: physicalWidth na wartość dodatnią, bo inaczej zostanie zwrócony błąd XR_ERROR_VALIDATION_FAILURE.

Prawidłowe użycie (pośrednie)

Tworzenie baz danych

Aplikacja może utworzyć uchwyt XrTrackableImageDatabaseANDROID, tworząc co najmniej 1 strukturę XrTrackableImageDatabaseEntryANDROID i przekazując ją do funkcji xrCreateTrackableImageDatabaseAsyncANDROID za pomocą struktury XrTrackableImageDatabaseCreateInfoANDROID.

Podczas tworzenia uchwytu XrTrackableImageDatabaseANDROID aplikacja musi podać co najmniej 1 wpis XrTrackableImageDatabaseEntryANDROID.

XrTrackableImageDatabaseANDROID to uchwyt reprezentujący zbiór przetworzonych obrazów referencyjnych, które mogą być wykrywane i śledzone w środowisku.

XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)

Struktura XrTrackableImageDatabaseEntryANDROID jest zdefiniowana w ten sposób:

typedef struct XrTrackableImageDatabaseEntryANDROID {
    XrStructureType                        type;
    const void*                            next;
    XrTrackableImageTrackingModeANDROID    trackingMode;
    float                                  physicalWidth;
    uint32_t                               imageWidth;
    uint32_t                               imageHeight;
    XrTrackableImageFormatANDROID          format;
    uint32_t                               bufferSize;
    const uint8_t*                         buffer;
} XrTrackableImageDatabaseEntryANDROID;

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 XrTrackableImageTrackingModeANDROID wskazujący żądany tryb śledzenia.
  • physicalWidth – szerokość obrazu w metrach. Jeśli wartość wynosi 0, rozmiar obrazu zostanie oszacowany online.
  • imageWidth wskazuje szerokość obrazu w pikselach.
  • imageHeight wskazuje wysokość obrazu w pikselach.
  • format to XrTrackableImageFormatANDROID wskazujący format danych obrazu w buffer .
  • bufferSize wskazuje długość buffer w bajtach.
  • buffer to bufor uint8_t zawierający dane pikseli obrazu referencyjnego. Zawartość buffer musi być prawidłowa przez cały czas trwania asynchronicznej operacji tworzenia bazy danych, która jest uruchamiana przez xrCreateTrackableImageDatabaseAsyncANDROID i kończona przez xrCreateTrackableImageDatabaseCompleteANDROID .

Aplikacja może ustawić physicalWidth na 0, aby poprosić o oszacowanie rozmiaru online, jeśli XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation to XR_TRUE .

Środowisko wykonawcze może zwrócić XR_ERROR_VALIDATION_FAILURE z xrCreateTrackableImageDatabaseAsyncANDROID, jeśli bufferSize nie pasuje do oczekiwanego rozmiaru na podstawie imageWidth, imageHeight i format wpisu.

Prawidłowe użycie (pośrednie)

Struktura XrTrackableImageDatabaseCreateInfoANDROID jest zdefiniowana w ten sposób:

typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
    XrStructureType                                type;
    const void*                                    next;
    uint32_t                                       entryCount;
    const XrTrackableImageDatabaseEntryANDROID*    entries;
} XrTrackableImageDatabaseCreateInfoANDROID;

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.
  • entryCount to uint32_t określający liczbę elementów w tablicy entries.
  • entries to tablica struktur XrTrackableImageDatabaseEntryANDROID.

Prawidłowe użycie (pośrednie)

Struktura XrCreateTrackableImageDatabaseCompletionANDROID jest zdefiniowana w ten sposób:

typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
    XrStructureType                    type;
    void*                              next;
    XrResult                           futureResult;
    XrTrackableImageDatabaseANDROID    database;
} XrCreateTrackableImageDatabaseCompletionANDROID;

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.
  • futureResult to XrResult operacji asynchronicznej.
  • database to utworzony uchwyt XrTrackableImageDatabaseANDROID.

Kody zwrotu w przyszłości

Wartości futureResult:

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Prawidłowe użycie (pośrednie)

Funkcja xrCreateTrackableImageDatabaseAsyncANDROID jest zdefiniowana w ten sposób:

XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
    XrSession                                   session,
    const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

Opisy parametrów

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Funkcja xrCreateTrackableImageDatabaseCompleteANDROID jest zdefiniowana w ten sposób:

XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateTrackableImageDatabaseCompletionANDROID* completion);

Opisy parametrów

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Funkcja xrDestroyTrackableImageDatabaseANDROID jest zdefiniowana w ten sposób:

XrResult xrDestroyTrackableImageDatabaseANDROID(
    XrTrackableImageDatabaseANDROID             database);

Opisy parametrów

Prawidłowe użycie (pośrednie)

Bezpieczeństwo wątków

  • Dostęp do database i wszystkich uchwytów podrzędnych musi być synchronizowany zewnętrznie.

Kody zwrotu

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Obrazy śledzące

To rozszerzenie dodaje XR_TRACKABLE_TYPE_IMAGE_ANDROID do XrTrackableTypeANDROID .

Aplikacja może utworzyć XrTrackableTrackerANDROID, wywołując xrCreateTrackableTrackerANDROID i określając XR_TRACKABLE_TYPE_IMAGE_ANDROID jako typ obiektu możliwego do śledzenia w XrTrackableTrackerCreateInfoANDROID :: trackableType, aby śledzić obrazy.

Środowisko wykonawcze musi zwracać XR_ERROR_FEATURE_UNSUPPORTED, jeśli XrTrackableTrackerCreateInfoANDROID :: trackableType to XR_TRACKABLE_TYPE_IMAGE_ANDROID, a XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking zwraca XR_FALSE przez xrGetSystemProperties .

Struktura XrTrackableImageConfigurationANDROID jest zdefiniowana w ten sposób:

typedef struct XrTrackableImageConfigurationANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  databaseCount;
    const XrTrackableImageDatabaseANDROID*    databases;
} XrTrackableImageConfigurationANDROID;

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.
  • databaseCount to uint32_t, który określa liczbę elementów w databases
  • databases to tablica XrTrackableImageDatabaseANDROID, która określa bazy danych, za pomocą których ma zostać utworzony tracker.

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

Aplikacja musi udostępniać co najmniej 1 strukturę XrTrackableImageDatabaseANDROID, aby utworzyć tracker.

Prawidłowe użycie (pośrednie)

Typ wyliczeniowy XrTrackableImageTrackingModeANDROID opisuje obsługiwane tryby śledzenia obrazów.

typedef enum XrTrackableImageTrackingModeANDROID {
    XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;

Opisy elementów wyliczenia

  • XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID – ten tryb zapewnia najwyższą dokładność i umożliwia śledzenie ruchomych obrazów z niskim czasem oczekiwania. Ma też największe zużycie energii.
  • XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID – tego trybu należy używać w przypadku obrazów, które są statyczne lub półstatyczne. Ten tryb zużywa mniej energii niż tryb dynamiczny. Jeśli obraz statyczny zostanie przeniesiony, zostanie zaktualizowany ze znacznie większym opóźnieniem niż w trybie dynamicznym.

Typ wyliczeniowy XrTrackableImageFormatANDROID opisuje obsługiwane formaty obrazów.

typedef enum XrTrackableImageFormatANDROID {
    XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
    XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;

Opisy elementów wyliczenia

  • XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID – format pliku graficznego RGBA z 8-bitowym kolorem na kanał i danymi o przezroczystości.

Funkcja xrAddTrackableImageDatabaseANDROID jest zdefiniowana w ten sposób:

XrResult xrAddTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

Opisy parametrów

Gdy do trackera zostanie dodana baza danych XrTrackableImageDatabaseANDROID, obrazy referencyjne z tej bazy danych muszą być uwzględniane podczas wykrywania i śledzenia, oprócz innych baz danych dodanych wcześniej za pomocą funkcji xrAddTrackableImageDatabaseANDROID lub struktury XrTrackableImageConfigurationANDROID podczas początkowego tworzenia trackera.

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Funkcja xrRemoveTrackableImageDatabaseANDROID jest zdefiniowana w ten sposób:

XrResult xrRemoveTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

Opisy parametrów

Gdy baza danych XrTrackableImageDatabaseANDROID zostanie usunięta z XrTrackableTrackerANDROID , struktury XrTrackableImageDatabaseEntryANDROID tej bazy danych nie mogą być już uwzględniane podczas wykrywania i śledzenia. Wszystkie aktywnie śledzone wpisy w tej bazie danych nie mogą być już zgłaszane. Usunięty uchwyt XrTrackableImageDatabaseANDROID nie może zostać niejawnie zniszczony w ramach tej operacji.

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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Pobieram obrazy

Funkcja xrGetTrackableImageANDROID jest zdefiniowana w ten sposób:

XrResult xrGetTrackableImageANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableImageANDROID*                    trackable);

Opisy parametrów

Środowisko wykonawcze musi zwracać XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID, jeśli typ śledzenia XrTrackableANDROID nie jest XR_TRACKABLE_TYPE_IMAGE_ANDROID lub jeśli typ śledzenia XrTrackableTrackerANDROID nie jest XR_TRACKABLE_TYPE_IMAGE_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_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrTrackableImageANDROID jest zdefiniowana w ten sposób:

typedef struct XrTrackableImageANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrTrackingStateANDROID             trackingState;
    XrTime                             lastUpdatedTime;
    XrTrackableImageDatabaseANDROID    database;
    uint32_t                           databaseEntryIndex;
    XrPosef                            centerPose;
    XrExtent2Df                        extents;
} XrTrackableImageANDROID;

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 obrazu.
  • lastUpdatedTime to XrTime ostatniej aktualizacji obrazu.
  • database to uchwyt XrTrackableImageDatabaseANDROID, z którego śledzony był ten obraz.
  • databaseEntryIndex to indeks, który mapuje do tablicy entries database w XrTrackableImageDatabaseCreateInfoANDROID.
  • centerPose to XrPosef obrazu znajdującego się w XrTrackableGetInfoANDROID :: baseSpace . Obraz znajduje się na płaszczyźnie XZ, przy czym oś X wskazuje prawą stronę obrazu, a oś Z – jego dół.
  • extents to wymiary obrazu XrExtent2Df. Granica ramki ograniczającej znajduje się w punktach: centerPose +/- ( extents / 2).

Prawidłowe użycie (pośrednie)

Obsługa błędów

Aplikacja musi sprawdzać zdarzenie XrEventDataImageTrackingLostANDROID za pomocą xrPollEvent i nie może go ignorować.

Struktura XrEventDataImageTrackingLostANDROID jest zdefiniowana w ten sposób:

typedef struct XrEventDataImageTrackingLostANDROID {
    XrStructureType    type;
    const void*        next;
    XrTime             time;
} XrEventDataImageTrackingLostANDROID;

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.
  • time XrTime

Zdarzenie XrEventDataImageTrackingLostANDROID oznacza, że wystąpił błąd wewnętrzny śledzenia obrazu, który spowodował unieważnienie istniejących zasobów. Aplikacja musi zniszczyć wszystkie uchwyty XrTrackableImageDatabaseANDROID i utworzyć je ponownie, jeśli chce kontynuować śledzenie obrazu. Aplikacja musi też zniszczyć wszystkie uchwyty XrTrackableTrackerANDROID związane ze śledzeniem obrazu i utworzyć je ponownie, jeśli chce kontynuować śledzenie obrazu.

Prawidłowe użycie (pośrednie)

Przykładowy kod do pobierania obrazów możliwych do śledzenia

Poniższy przykładowy kod pokazuje, jak uzyskać obrazy możliwe do śledzenia.

XrInstance instance;  // Previously initialized.
XrSession session;    // Previously initialized.
XrSystemId systemId;  // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID;                                        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // 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
XrSystemImageTrackingPropertiesANDROID imageProperty {
  .type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
    // image tracking is not supported.
    return;
}

uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
  {
    .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
    .next = nullptr,
    .trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
    .physicalWidth = 0.1f, // The width of the image in meters.
    .imageWidth = 640,
    .imageHeight = 480,
    .format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
    .bufferSize = imageBufferSize, // RGBA buffer size in bytes.
    .buffer = imageBuffer, // RGBA data.
  }
};

XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
  .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .entryCount = 1,
  .entries = imageDatabaseEntries
};

XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
  XrFuturePollInfoEXT pollInfo{
    .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
    .future = imageDatabaseFuture,
  };
  XrFuturePollResultEXT pollResult{
    .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
  };
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

  if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
    futureReady = true;
    keepLooping = false;
  } else {
    // Throttle the loop to not fully expend this CPU core.
    std::this_thread::yield();
  }
}

XrTrackableImageDatabaseANDROID imageDatabase;

if (futureReady) {
  XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
    .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
    .next = nullptr,
  };

  CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
  CHK_XR(imageDatabaseCompletion.futureResult);
  imageDatabase = imageDatabaseCompletion.database;
}

XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &imageDatabase
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.

// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

while (1) {
  uint32_t trackableCountOutput = 0;

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));

  std::vector<XrTrackableANDROID> allImageTrackables;
  allImageTrackables.resize(trackableCountOutput);

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));

  for (XrTrackableANDROID trackable : allImageTrackables) {
    XrTrackableGetInfoANDROID imageGetInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackable,
      .baseSpace = appSpace,
      .time = updateTime
    };

    XrTrackableImageANDROID trackableImage{
      .type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
    };
    CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));

    // Use XrTrackableImageANDROID data.
    (void)trackableImage.trackingState;
    (void)trackableImage.lastUpdatedTime;
    (void)trackableImage.centerPose;
    (void)trackableImage.extents;

    if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
      // Knowing which image the index of 0 maps to, use the specific image database
      // entry (e.g. rendering A for image A).
    }
    // indices 1+N comparisons for another specific image database entry.
  }

  // Throttle the loop to not fully expend this CPU core.
  std::this_thread::yield();
}

// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

Przykładowy kod do zarządzania bazami danych obrazów w czasie działania

Poniższy przykładowy kod pokazuje, jak zmodyfikować zestaw śledzonych obrazów.

XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.

// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 2,
  .databases = imageDatabases
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.

CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.

CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.

CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.

// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &anotherImageDatabase
};

XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &anotherImageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));

// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.

Przykładowy kod do reagowania na błędy śledzenia obrazu

Poniższy przykładowy kod pokazuje, jak obsłużyć błąd przez odpytywanie o zdarzenie XrEventDataImageTrackingLostANDROID.

XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.

// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
  .type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
      const XrEventDataImageTrackingLostANDROID& eventdata =
        *reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);

      // All existing databases and trackers need to be destroyed.
      CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
      CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

      // To resume image tracking, the database(s) and the tracker need to be re-created.

      XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
        .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
        .next = nullptr,
        .entryCount = 1,
        .entries = imageDatabaseEntries
      };

      XrFutureEXT imageDatabaseFuture;
      CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

      while (true) {
        XrFuturePollInfoEXT pollInfo{
          .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
          .future = imageDatabaseFuture,
        };
        XrFuturePollResultEXT pollResult{
          .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
        };
        CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

        if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
          break;
        } else {
          // Throttle the loop to not fully expend this CPU core.
          std::this_thread::yield();
        }
      }

      XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
        .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
        .next = nullptr,
      };

      CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
      CHK_XR(imageDatabaseCompletion.futureResult);
      imageDatabase = imageDatabaseCompletion.database;

      XrTrackableImageConfigurationANDROID imageConfig {
       .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
       .next = nullptr,
       .databaseCount = 1,
       .databases = &imageDatabase
      };

      XrTrackableTrackerCreateInfoANDROID createInfo {
        .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
        .next = &imageConfig,
        .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
      };

      XrTrackableTrackerANDROID imageTrackableTracker;
      CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

      break;
    }
  }
}

Nowe typy obiektów

Nowe polecenia

Nowe domy

Nowe wartości w polu enum

Nowe stałe typu wyliczeniowego

  • XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAME
  • XR_ANDROID_trackables_image_SPEC_VERSION
  • Rozszerzanie XrObjectType :

    • XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
  • Rozszerzenie XrResult :

    • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • Rozszerzanie XrStructureType :

    • XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID
    • XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
  • Rozszerzanie XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_IMAGE_ANDROID

Problemy

Historia zmian

  • Wersja 1, 8 kwietnia 2025 r. (Daniel Guttenberg)

    • Początkowy opis rozszerzenia.