XR_ANDROID_trackables_image
Ciąg znaków nazwy
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
i
XR_ANDROID_trackables
Data ostatniej modyfikacji
2025-04-08
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
Daniel Guttenberg, Qualcomm
Mark Vadasi, Qualcomm
Markus Birkner, Qualcomm
Maximilian Mayer, Qualcomm
Przegląd
To rozszerzenie umożliwia śledzenie obrazów płaskich 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 udostępnia geometrię otoczenia. Uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE jest uznawane za niebezpieczne.
(poziom ochrony: niebezpieczny)
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
typeto XrStructureType tej struktury.nexttoNULLlub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur. Więcej informacji o łańcuchu struktur znajdziesz w sekcji dotyczącej rozszerzanej struktury ( XrSystemProperties ).supportsImageTrackingtoXrBool32, które wskazuje, czy bieżący system obsługuje śledzenie obrazów.supportsPhysicalSizeEstimationtoXrBool32wskazujący, czy bieżący system zapewnia szacowanie rozmiaru obrazu.maxTrackedImageCountto łączna maksymalna liczba obrazów, które można śledzić w tym samym czasie.maxLoadedImageCountto łączna maksymalna liczba obrazów referencyjnych, które można wczytać we wszystkich bazach danych.
Aplikacja może sprawdzić, czy system obsługuje śledzenie obrazu, rozszerzając strukturę XrSystemProperties o strukturę XrSystemImageTrackingPropertiesANDROID podczas wywoływania funkcji xrGetSystemProperties . Środowisko wykonawcze musi zwracać wartość XR_ERROR_FEATURE_UNSUPPORTED w przypadku tworzenia narzędzia do śledzenia obrazów, jeśli i tylko wtedy, gdy wartość 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ą. W przeciwnym razie zostanie zwrócona wartość XR_ERROR_VALIDATION_FAILURE.
Prawidłowe użycie (domyślne)
- Rozszerzenie
XR_ANDROID_trackables_imagemusi być włączone przed użyciem XrSystemImageTrackingPropertiesANDROID. -
typemusi mieć wartośćXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID -
nextmusi mieć wartośćNULLlub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur.
Tworzenie baz danych
Aplikacja może utworzyć uchwyt XrTrackableImageDatabaseANDROID, tworząc co najmniej jedną strukturę XrTrackableImageDatabaseEntryANDROID i przekazując ją do funkcji xrCreateTrackableImageDatabaseAsyncANDROID za pomocą struktury XrTrackableImageDatabaseCreateInfoANDROID.
Podczas tworzenia uchwytu XrTrackableImageDatabaseANDROID aplikacja musi udostępnić co najmniej 1 element XrTrackableImageDatabaseEntryANDROID.
XrTrackableImageDatabaseANDROID to uchwyt reprezentujący zestaw przetworzonych obrazów referencyjnych, które można wykrywać i śledzić 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
typeto XrStructureType tej struktury.nexttoNULLlub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.trackingModeto XrTrackableImageTrackingModeANDROID wskazujący żądany tryb śledzenia.physicalWidthoznacza szerokość obrazu w metrach. Jeśli wartość wynosi zero, rozmiar obrazu zostanie oszacowany online.imageWidthoznacza szerokość obrazu w pikselach.imageHeightoznacza wysokość obrazu w pikselach.formatto XrTrackableImageFormatANDROID wskazujący format danych obrazu wbuffer.bufferSizeoznacza długość w bajtach elementubuffer.buffertouint8_tbufor zawierający dane pikseli obrazu referencyjnego. Zawartośćbuffermusi być prawidłowa przez cały czas trwania asynchronicznej operacji tworzenia bazy danych, która jest rozpoczynana przez xrCreateTrackableImageDatabaseAsyncANDROID i kończona przez xrCreateTrackableImageDatabaseCompleteANDROID .
Aplikacja może ustawić wartość physicalWidth na 0, aby poprosić o oszacowanie rozmiaru online, jeśli XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation ma wartość XR_TRUE .
Środowisko wykonawcze może zwrócić wartość XR_ERROR_VALIDATION_FAILURE z funkcji xrCreateTrackableImageDatabaseAsyncANDROID, jeśli wartość bufferSize nie pasuje do oczekiwanego rozmiaru na podstawie wartości imageWidth, imageHeight i format w pozycji .
Prawidłowe użycie (domyślne)
- Rozszerzenie
XR_ANDROID_trackables_imagemusi być włączone przed użyciem XrTrackableImageDatabaseEntryANDROID. -
typemusi mieć wartośćXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID -
nextmusi mieć wartośćNULLlub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur. -
trackingModemusi być prawidłową wartością XrTrackableImageTrackingModeANDROID. -
formatmusi być prawidłową wartością XrTrackableImageFormatANDROID -
buffermusi być wskaźnikiem tablicy wartościbufferSizeuint8_t. - Parametr
bufferSizemusi być większy niż0.
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
typeto XrStructureType tej struktury.nexttoNULLlub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.entryCounttouint32_tokreślająca liczbę elementów w tablicyentries.entriesto tablica struktur XrTrackableImageDatabaseEntryANDROID.
Prawidłowe użycie (domyślne)
- Przed użyciem XrTrackableImageDatabaseCreateInfoANDROID należy włączyć rozszerzenie
XR_ANDROID_trackables_image. -
typemusi mieć wartośćXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID -
nextmusi mieć wartośćNULLlub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur. -
entriesmusi być wskaźnikiem do tablicyentryCountprawidłowych struktur XrTrackableImageDatabaseEntryANDROID - Parametr
entryCountmusi być większy niż0.
Struktura XrCreateTrackableImageDatabaseCompletionANDROID jest zdefiniowana w ten sposób:
typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrTrackableImageDatabaseANDROID database;
} XrCreateTrackableImageDatabaseCompletionANDROID;
Opisy członków
typeto XrStructureType tej struktury.nexttoNULLlub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.futureResultto XrResult operacji asynchronicznej.databaseto utworzony uchwyt XrTrackableImageDatabaseANDROID.
Kody zwrotu w przyszłości
Wartości pola futureResult:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
Prawidłowe użycie (domyślne)
- Rozszerzenie
XR_ANDROID_trackables_imagemusi być włączone przed użyciem funkcji XrCreateTrackableImageDatabaseCompletionANDROID. -
typemusi mieć wartośćXR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID -
nextmusi mieć wartośćNULLlub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur. -
futureResultmusi być prawidłową wartością XrResult -
databasemusi być prawidłowym uchwytem XrTrackableImageDatabaseANDROID
Funkcja xrCreateTrackableImageDatabaseAsyncANDROID jest zdefiniowana w ten sposób:
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
Opisy parametrów
sessionto uchwyt do XrSession utworzonego wcześniej za pomocą funkcji xrCreateSession .createInfoto wskaźnik struktury XrTrackableImageDatabaseCreateInfoANDROID.futureto wskaźnik do utworzonego obiektuXrFutureEXT.
Prawidłowe użycie (domyślne)
- Rozszerzenie
XR_ANDROID_trackables_imagemusi być włączone przed wywołaniem funkcji xrCreateTrackableImageDatabaseAsyncANDROID. -
sessionmusi być prawidłowym uchwytem XrSession -
createInfomusi być wskaźnikiem do prawidłowej struktury XrTrackableImageDatabaseCreateInfoANDROID -
futuremusi być wskaźnikiem do wartościXrFutureEXT
Kody zwrotne
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Funkcja xrCreateTrackableImageDatabaseCompleteANDROID jest zdefiniowana w ten sposób:
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
Opisy parametrów
sessionto uchwyt do XrSession utworzonego wcześniej za pomocą funkcji xrCreateSession .futuretoXrFutureEXTprzyszłości.completionto wskaźnik struktury XrCreateTrackableImageDatabaseCompletionANDROID zawierającej wynik operacji.
Prawidłowe użycie (domyślne)
- Rozszerzenie
XR_ANDROID_trackables_imagemusi być włączone przed wywołaniem funkcji xrCreateTrackableImageDatabaseCompleteANDROID. -
sessionmusi być prawidłowym uchwytem XrSession -
completionmusi być wskaźnikiem struktury XrCreateTrackableImageDatabaseCompletionANDROID.
Kody zwrotne
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Funkcja xrDestroyTrackableImageDatabaseANDROID jest zdefiniowana w ten sposób:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
Opisy parametrów
databaseto uchwyt XrTrackableImageDatabaseANDROID do zniszczenia.
Prawidłowe użycie (domyślne)
- Rozszerzenie
XR_ANDROID_trackables_imagemusi być włączone przed wywołaniem funkcji xrDestroyTrackableImageDatabaseANDROID. -
databasemusi być prawidłowym uchwytem XrTrackableImageDatabaseANDROID
Bezpieczeństwo wątków
- Dostęp do
databasei wszystkich uchwytów podrzędnych musi być synchronizowany zewnętrznie.
Kody zwrotne
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
Obrazy śledzące
To rozszerzenie dodaje XR_TRACKABLE_TYPE_IMAGE_ANDROID do XrTrackableTypeANDROID .
Aplikacja może utworzyć obiekt XrTrackableTrackerANDROID, wywołując funkcję xrCreateTrackableTrackerANDROID i określając XR_TRACKABLE_TYPE_IMAGE_ANDROID jako typ śledzenia w strukturze XrTrackableTrackerCreateInfoANDROID :: trackableType, aby śledzić obrazy.
Środowisko wykonawcze musi zwracać XR_ERROR_FEATURE_UNSUPPORTED, jeśli XrTrackableTrackerCreateInfoANDROID :: trackableType ma wartość XR_TRACKABLE_TYPE_IMAGE_ANDROID, a XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking zwraca XR_FALSE za pomocą funkcji 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
typeto XrStructureType tej struktury.nexttoNULLlub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.databaseCounttouint32_t, który określa liczbę elementów wdatabases.databasesto tablica XrTrackableImageDatabaseANDROID, która określa bazy danych, na podstawie których ma zostać utworzony tracker.
Aplikacja musi ustawić prawidłową konfigurację, dodając element XrTrackableImageConfigurationANDROID do łańcucha next elementu XrTrackableTrackerCreateInfoANDROID . W przeciwnym razie środowisko wykonawcze musi zwrócić wartość XR_ERROR_VALIDATION_FAILURE .
Aplikacja musi udostępniać co najmniej 1 strukturę XrTrackableImageDatabaseANDROID, aby można było utworzyć tracker.
Prawidłowe użycie (domyślne)
- Rozszerzenie
XR_ANDROID_trackables_imagemusi być włączone przed użyciem XrTrackableImageConfigurationANDROID. -
typemusi mieć wartośćXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID -
nextmusi mieć wartośćNULLlub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur. -
databasesmusi być wskaźnikiem do tablicydatabaseCountprawidłowych uchwytów XrTrackableImageDatabaseANDROID - Parametr
databaseCountmusi być większy niż0.
Wyliczenie 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 opóźnieniem. Ma też najwyższe zużycie energii.XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID– ten tryb należy stosować w przypadku obrazów, które są statyczne lub półstatyczne. W porównaniu z trybem dynamicznym ten tryb zużywa mniej energii. Jeśli obraz statyczny jest przenoszony, będzie aktualizowany z dużo większym opóźnieniem niż w trybie dynamicznym.
Wyliczenie 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 obrazu RGBA z 8 bitami na kanał koloru i danymi o przezroczystości.
Funkcja xrAddTrackableImageDatabaseANDROID jest zdefiniowana w ten sposób:
XrResult xrAddTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Opisy parametrów
trackerto uchwyt XrTrackableTrackerANDROID, do którego chcesz dodać elementdatabase.databaseto uchwyt XrTrackableImageDatabaseANDROID, który należy dodać dotracker.
Gdy do trackera zostanie dodana baza danych XrTrackableImageDatabaseANDROID, obrazy referencyjne z tej bazy danych muszą być brane pod uwagę 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 (domyślne)
- Rozszerzenie
XR_ANDROID_trackables_imagemusi być włączone przed wywołaniem funkcji xrAddTrackableImageDatabaseANDROID. -
trackermusi być prawidłowym uchwytem XrTrackableTrackerANDROID -
databasemusi być prawidłowym uchwytem XrTrackableImageDatabaseANDROID - Zarówno
database, jak itrackermuszą zostać utworzone, przydzielone lub pobrane z tej samej XrSession.
Kody zwrotne
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Funkcja xrRemoveTrackableImageDatabaseANDROID jest zdefiniowana w ten sposób:
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Opisy parametrów
trackerto uchwyt XrTrackableTrackerANDROID, z którego należy usunąć elementdatabase.databaseto uchwyt XrTrackableImageDatabaseANDROID, który ma zostać usunięty ztracker.
Gdy XrTrackableImageDatabaseANDROID zostanie usunięta z XrTrackableTrackerANDROID , struktury XrTrackableImageDatabaseEntryANDROID tej bazy danych nie mogą być już brane pod uwagę podczas wykrywania i śledzenia. Wszelkie aktywnie śledzone wpisy w tej bazie danych nie mogą być już raportowane. Usunięty uchwyt XrTrackableImageDatabaseANDROID nie może zostać niejawnie zniszczony w ramach tej operacji.
Prawidłowe użycie (domyślne)
- Rozszerzenie
XR_ANDROID_trackables_imagemusi być włączone przed wywołaniem funkcji xrRemoveTrackableImageDatabaseANDROID. -
trackermusi być prawidłowym uchwytem XrTrackableTrackerANDROID -
databasemusi być prawidłowym uchwytem XrTrackableImageDatabaseANDROID - Zarówno
database, jak itrackermuszą zostać utworzone, przydzielone lub pobrane z tej samej XrSession.
Kody zwrotne
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Pobieranie obrazów
Funkcja xrGetTrackableImageANDROID jest zdefiniowana w ten sposób:
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
Opisy parametrów
trackerto obiekt XrTrackableTrackerANDROID, o który chcesz wysłać zapytanie.getInfoto XrTrackableGetInfoANDROID z informacjami używanymi do uzyskania kodu QR śledzenia.trackableto wskaźnik struktury XrTrackableImageANDROID, w której zwracany jest śledzony obraz.
Środowisko wykonawcze musi zwracać wartość XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID , jeśli typ śledzenia elementu XrTrackableANDROID nie jest równy XR_TRACKABLE_TYPE_IMAGE_ANDROID lub jeśli typ śledzenia elementu XrTrackableTrackerANDROID nie jest równy XR_TRACKABLE_TYPE_IMAGE_ANDROID .
Prawidłowe użycie (domyślne)
- Rozszerzenie
XR_ANDROID_trackables_imagemusi być włączone przed wywołaniem funkcji xrGetTrackableImageANDROID. -
trackermusi być prawidłowym uchwytem XrTrackableTrackerANDROID -
getInfomusi być wskaźnikiem do prawidłowej struktury XrTrackableGetInfoANDROID -
trackablemusi być wskaźnikiem struktury XrTrackableImageANDROID.
Kody zwrotne
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_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
typeto XrStructureType tej struktury.nexttoNULLlub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.trackingStateto XrTrackingStateANDROID obrazu.lastUpdatedTimetoXrTimeostatniej aktualizacji obrazu.databaseto uchwyt XrTrackableImageDatabaseANDROID, z którego śledzono ten obraz.databaseEntryIndexto indeks, który jest mapowany na tablicę XrTrackableImageDatabaseCreateInfoANDROID ::entriestypudatabase.centerPoseto XrPosef obrazu znajdującego się w XrTrackableGetInfoANDROID ::baseSpace. Obraz leży w płaszczyźnie XZ, przy czym oś X jest skierowana w prawo, a oś Z – w dół.extentsto wymiary XrExtent2Df obrazu. Granica ramki ograniczającej znajduje się w punktach:centerPose+/- (extents/ 2).
Prawidłowe użycie (domyślne)
- Rozszerzenie
XR_ANDROID_trackables_imagemusi być włączone przed użyciem funkcji XrTrackableImageANDROID. -
typemusi mieć wartośćXR_TYPE_TRACKABLE_IMAGE_ANDROID -
nextmusi mieć wartośćNULLlub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur. -
trackingStatemusi być prawidłową wartością XrTrackingStateANDROID. -
databasemusi być prawidłowym uchwytem XrTrackableImageDatabaseANDROID
Obsługa błędów
Aplikacja musi odpytywać o zdarzenie XrEventDataImageTrackingLostANDROID za pomocą funkcji 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
typeto XrStructureType tej struktury.nexttoNULLlub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.timeXrTime
Otrzymanie zdarzenia XrEventDataImageTrackingLostANDROID oznacza, że śledzenie obrazu zostało przerwane i wystąpił błąd wewnętrzny, który spowodował unieważnienie istniejących zasobów. Aplikacja musi zniszczyć wszystkie uchwyty XrTrackableImageDatabaseANDROID i utworzyć je ponownie, jeśli chce kontynuować śledzenie obrazów. 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 (domyślne)
- Rozszerzenie
XR_ANDROID_trackables_imagemusi być włączone przed użyciem funkcji XrEventDataImageTrackingLostANDROID. -
typemusi mieć wartośćXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID -
nextmusi mieć wartośćNULLlub być prawidłowym wskaźnikiem do następnej struktury w łańcuchu struktur.
Przykładowy kod do pobierania obrazów z możliwością śledzenia
Poniższy przykładowy kod pokazuje, jak uzyskać obrazy, które można śledzić.
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 reagowania na błędy śledzenia obrazu
Poniższy przykładowy kod pokazuje, jak obsługiwać błędy przez sondowanie zdarzenia 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
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
Nowe struktury
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
Rozszerzanie XrSystemProperties :
Nowe wartości w polu enum
Nowe stałe wyliczeniowe
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_ANDROID_trackables_image_SPEC_VERSIONRozszerzanie XrObjectType :
XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
Rozszerzanie XrResult :
XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
Rozszerzanie XrStructureType :
XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
Rozszerzanie XrTrackableTypeANDROID :
XR_TRACKABLE_TYPE_IMAGE_ANDROID
Problemy
Historia zmian
Wersja 1, 8.04.2025 r. (Daniel Guttenberg)
- Początkowy opis rozszerzenia.