XR_EXT_spatial_image_tracking

Name String

XR_EXT_spatial_image_tracking

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

783

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

XR_EXT_spatial_entity

Twórcy

Daniel Guttenberg, Qualcomm
Nihav Jain, Google
Jared Finder, Google
Zhipeng Liu, ByteDance

Przegląd

To rozszerzenie zapewnia możliwość śledzenia obrazu w rozszerzeniu XR_EXT_spatial_entity. Umożliwia aplikacjom wykrywanie i śledzenie określonych obrazów płaskich, które są określone przez zestawy wejściowych obrazów referencyjnych.

Śledzony obraz jest reprezentowany jako element przestrzenny z tymi komponentami:

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Aplikacje zwykle używają rozszerzenia do śledzenia obrazu przestrzennego w ten sposób:

  • Aplikacja najpierw tworzy co najmniej 1 uchwyt XrSpatialImageTrackingDatabaseEXT na podstawie zestawów wstępnie załadowanych danych obrazu referencyjnego.
  • Następnie aplikacja tworzy uchwyt XrSpatialContextEXT na podstawie utworzonych wcześniej uchwytów XrSpatialImageTrackingDatabaseEXT.
  • Następnie aplikacja zwalnia dane obrazu referencyjnego, aby zmniejszyć wykorzystanie pamięci.
  • Aplikacja wykrywa obrazy i wysyła zapytania zgodnie ze wzorcami dostępu do elementów przestrzennych.
  • Aplikacja może wczytywać dodatkowe zestawy obrazów referencyjnych i tworzyć na ich podstawie dodatkowe obiekty XrSpatialImageTrackingDatabaseEXT, a następnie XrSpatialContextEXT, aby dynamicznie rozszerzać zestaw obrazów, które można wykrywać i śledzić w czasie działania.
  • Aplikacja może niszczyć uchwyty XrSpatialImageTrackingDatabaseEXT, aby dynamicznie zmniejszać zestaw wykrywalnych i śledzonych obrazów w czasie działania.
  • Aplikacja może niszczyć uchwyty XrSpatialContextEXT, aby dynamicznie zmniejszać zestaw wykrywalnych i śledzonych obrazów w czasie działania.

Obsługa środowiska wykonawczego

Środowisko wykonawcze musi informować o obsłudze funkcji śledzenia obrazu za pomocą xrEnumerateSpatialCapabilitiesEXT, podając tę funkcję:

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Konfiguracja

Aby włączyć wykrywanie i śledzenie obrazów płaskich, aplikacja może przekazywać struktury XrSpatialCapabilityConfigurationImageTrackingEXT w XrSpatialContextCreateInfoEXT :: capabilityConfigs podczas wywoływania funkcji xrCreateSpatialContextAsyncEXT i przekazywać tablice struktur XrSpatialImageTrackingDatabaseEXT w każdej strukturze XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases .

Tworzenie wejściowego zbioru obrazów

Aby określić obrazy referencyjne, które mają być wykrywane i śledzone, aplikacja musi utworzyć co najmniej 1 zestaw wejściowych obrazów referencyjnych. Zestaw wejściowych obrazów referencyjnych jest reprezentowany przez uchwyt XrSpatialImageTrackingDatabaseEXT i zawiera co najmniej 1 obraz.

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

Uchwyt XrSpatialImageTrackingDatabaseEXT reprezentuje zasoby do wykrywania i aktualizowania określonej liczby obrazów przestrzennych w środowisku użytkownika. Aplikacje mogą używać tego uchwytu do wykrywania i aktualizowania obrazów przestrzennych za pomocą innych funkcji tego rozszerzenia.

Tworzenie bazy danych śledzenia obrazów przestrzennych

Funkcja xrCreateSpatialImageTrackingDatabaseAsyncEXT jest zdefiniowana w ten sposób:

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Opisy parametrów

  • session to XrSession, w której będzie aktywna baza danych śledzenia obrazów przestrzennych.
  • createInfo to XrSpatialImageTrackingDatabaseCreateInfoEXT, który służy do określania parametrów bazy danych śledzenia obrazów przestrzennych.
  • future to wskaźnik do XrFutureEXT .

Aplikacja może utworzyć uchwyt XrSpatialImageTrackingDatabaseEXT za pomocą funkcji xrCreateSpatialImageTrackingDatabaseAsyncEXT i skonfigurować zbiory wejściowych obrazów referencyjnych bazy danych śledzenia obrazów za pomocą createInfo .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT, jeśli XrSpatialReferenceImageEXT :: format dowolnego z wejściowych obrazów referencyjnych nie jest wyliczany przez xrEnumerateSpatialReferenceImageFormatsEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_IMAGE_INVALID_EXT, jeśli nie można ocenić tablicy planes XrSpatialReferenceImageEXT :: żadnego z wejściowych obrazów referencyjnych zgodnie z metadanymi obrazu referencyjnego XrSpatialReferenceImageEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_IMAGE_INVALID_EXT, jeśli tablica planes XrSpatialReferenceImageEXT dowolnego z wejściowych obrazów referencyjnych nie zawiera dokładnie tylu płaszczyzn, ile kanałów kolorów ma format XrSpatialReferenceImageEXT.

Jeśli środowisko wykonawcze wymusza system uprawnień do kontrolowania dostępu aplikacji do funkcji śledzenia obrazu, środowisko wykonawcze musi zwracać wartość XR_ERROR_PERMISSION_INSUFFICIENT, jeśli te uprawnienia nie zostały przyznane tej aplikacji.

Ta funkcja rozpoczyna operację asynchroniczną i tworzy odpowiedni obiekt XrFutureEXT , którego można używać z funkcją xrPollFutureEXT i powiązanymi funkcjami. Wartość zwracana przez tę funkcję wskazuje tylko, czy parametry były akceptowalne do zaplanowania operacji asynchronicznej. Odpowiednia funkcja zakończenia to xrCreateSpatialImageTrackingDatabaseCompleteEXT, której można użyć, gdy przyszłość z tej funkcji jest w stanie READY, a dane wyjściowe są wypełniane przez tę funkcję w strukturze zakończenia XrCreateSpatialImageTrackingDatabaseCompletionEXT .

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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrSpatialImageTrackingDatabaseCreateInfoEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • spatialReferenceImageCount to liczba elementów w tablicy spatialReferenceImages.
  • spatialReferenceImages to tablica obiektów XrSpatialReferenceImageEXT .

Struktura XrSpatialImageTrackingDatabaseCreateInfoEXT opisuje informacje potrzebne do utworzenia uchwytu XrSpatialImageTrackingDatabaseEXT.

Każda baza danych XrSpatialImageTrackingDatabaseEXT musi zostać utworzona z co najmniej 1 obrazem XrSpatialReferenceImageEXT w tablicy XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

Prawidłowe użycie (pośrednie)

Funkcja xrCreateSpatialImageTrackingDatabaseCompleteEXT jest zdefiniowana w ten sposób:

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

Opisy parametrów

Funkcja xrCreateSpatialImageTrackingDatabaseCompleteEXT kończy operację asynchroniczną rozpoczętą przez xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Środowisko wykonawcze nie może mieć dostępu do żadnych wskaźników XrSpatialReferenceImagePlaneEXT :: buffer, które zostały dostarczone przez tablicę wejściową XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages dla tego wywołania xrCreateSpatialImageTrackingDatabaseAsyncEXT po jego zakończeniu. Aplikacja może zwolnić dane XrSpatialReferenceImagePlaneEXT :: buffer po zakończeniu działania xrCreateSpatialImageTrackingDatabaseAsyncEXT, aby zmniejszyć wykorzystanie pamięci.

Środowisko wykonawcze musi zwracać XR_ERROR_FUTURE_PENDING_EXT, jeśli future nie jest w stanie gotowości. Środowisko wykonawcze musi zwrócić XR_ERROR_FUTURE_INVALID_EXT, jeśli future zostało już ukończone lub anulowane.

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

Struktura XrCreateSpatialImageTrackingDatabaseCompletionEXT jest zdefiniowana w ten sposób:

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

Opisy członków

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
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

Jeśli futureResult jest kodem sukcesu, database musi być prawidłowym uchwytem. Jeśli database jest prawidłowy, pozostaje taki tylko w cyklu życia xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session lub do momentu, gdy aplikacja zniszczy database za pomocą xrDestroySpatialImageTrackingDatabaseEXT (w zależności od tego, co nastąpi wcześniej).

Prawidłowe użycie (pośrednie)

Zniszczenie bazy danych śledzenia obrazów przestrzennych

Funkcja xrDestroySpatialImageTrackingDatabaseEXT jest zdefiniowana w ten sposób:

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

Opisy parametrów

Aplikacja może wywołać funkcję xrDestroySpatialImageTrackingDatabaseEXT, aby zwolnić uchwyt database i zasoby bazowe po zakończeniu zadań wykrywania i aktualizowania obrazów przestrzennych.

Aplikacja może wywołać funkcję xrDestroySpatialImageTrackingDatabaseEXT przed wywołaniem funkcji xrDestroySpatialContextEXT . Środowisko wykonawcze nie może już zgłaszać obrazów zarządzanych przez zniszczoną bazę danych XrSpatialImageTrackingDatabaseEXT . Środowisko wykonawcze musi nadal zgłaszać obrazy zarządzane przez inne bazy danych.

Środowisko wykonawcze musi zapewnić, że migawki wykrywania zwracane przez xrCreateSpatialDiscoverySnapshotCompleteEXT nie zawierają obrazów związanych ze zniszczonymi lub w inny sposób nieprawidłowymi uchwytami XrSpatialImageTrackingDatabaseEXT, nawet jeśli uchwyt został zniszczony po wywołaniu przez aplikację xrCreateSpatialDiscoverySnapshotAsyncEXT . Ponieważ dane w migawce przestrzennej są niezmienne, aplikacja powinna zniszczyć wszystkie uchwyty XrSpatialSnapshotEXT, które zostały utworzone przed zniszczeniem database. W przeciwnym razie aplikacja może otrzymać nieprawidłowe uchwyty XrSpatialImageTrackingDatabaseEXT podczas korzystania z xrQuerySpatialComponentDataEXT.

Aplikacja może wywołać funkcję xrDestroySpatialContextEXT, aby zwolnić uchwyt XrSpatialContextEXT przed zniszczeniem uchwytów XrSpatialImageTrackingDatabaseEXT, z którymi utworzono XrSpatialContextEXT. Środowisko wykonawcze nie może niejawnie niszczyć tych uchwytów XrSpatialImageTrackingDatabaseEXT, gdy niszczony jest XrSpatialContextEXT.

Niezależne zarządzanie czasem życia obiektów XrSpatialContextEXT i XrSpatialImageTrackingDatabaseEXT umożliwia aplikacjom ponowne używanie wcześniej utworzonych uchwytów XrSpatialImageTrackingDatabaseEXT bez konieczności powtarzania kosztownej procedury tworzenia.

Na przykład zniszczenie XrSpatialContextEXT i późniejsze ponowne utworzenie innego XrSpatialContextEXT z tą samą bazą danych XrSpatialImageTrackingDatabaseEXT umożliwia wstrzymywanie i wznawianie śledzenia obrazu bez konieczności przeprowadzania kolejnej procedury inicjowania.

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

Obsługa formatu pliku graficznego wejściowego

Aplikacje powinny wywoływać funkcję xrEnumerateSpatialReferenceImageFormatsEXT, aby uzyskać listę obsługiwanych formatów plików graficznych obrazów referencyjnych.

Funkcja xrEnumerateSpatialReferenceImageFormatsEXT jest zdefiniowana w ten sposób:

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

Opisy parametrów

  • instance to uchwyt do XrInstance .
  • systemId to XrSystemId, którego formaty wejściowych obrazów referencyjnych zostaną wymienione.
  • capability to XrSpatialCapabilityEXT, dla którego zostaną wyliczone formaty wejściowych obrazów referencyjnych.
  • formatCapacityInput to pojemność tablicy formats lub 0, co oznacza prośbę o pobranie wymaganej pojemności.
  • formatCountOutput to liczba formatów lub wymagana pojemność, jeśli formatCapacityInput jest niewystarczająca.
  • formats to tablica XrSpatialReferenceImageFormatEXT . Może mieć wartość NULL, jeśli formatCapacityInput wynosi 0.
  • Szczegółowy opis pobierania wymaganego rozmiaru formats znajdziesz w sekcji Parametry rozmiaru bufora.

Aplikacja może wyświetlić listę formatów pliku graficznego obrazów referencyjnych obsługiwanych przez dany element XrSystemId dla danego elementu XrSpatialCapabilityEXT za pomocą funkcji xrEnumerateSpatialReferenceImageFormatsEXT .

Środowisko wykonawcze nie może wyliczać formatów rozszerzeń, które nie są włączone w przypadku instance .

Prawidłowe użycie (pośrednie)

Kody zwrotu

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Pełną listę wszystkich formatów obrazów referencyjnych obsługiwanych przez dowolne rozszerzenie znajdziesz w sekcji XrSpatialReferenceImageFormatEXT.

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

Wyliczenie XrSpatialReferenceImageFormatEXT identyfikuje formaty plików graficznych wejściowych obrazów referencyjnych, które mogą być obsługiwane przez środowisko wykonawcze.

Muszą być obsługiwane co najmniej wartości XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT i XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT.

Elementy wyliczenia mają następujące znaczenie:

Opisy elementów wyliczenia

  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT – bufor RGBA. Format nie gwarantuje układu danych pikseli w pamięci. Dostęp do pikseli musi być uzyskiwany za pomocą metadanych dostarczanych przez odpowiednie struktury XrSpatialReferenceImagePlaneEXT. Każdy kanał koloru piksela ma rozmiar 8 bitów, co oznacza, że każdy piksel ma rozmiar 32 bitów.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT – bufor RGB. Format nie gwarantuje układu danych pikseli w pamięci. Dostęp do pikseli musi być uzyskiwany za pomocą metadanych dostarczanych przez odpowiednie struktury XrSpatialReferenceImagePlaneEXT. Każdy kanał koloru piksela ma rozmiar 8 bitów, co daje 24 bity na piksel.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT – bufor YUV z podpróbkowaniem chrominancji we wzorcu 4:2:0. Format nie gwarantuje układu danych pikseli w pamięci. Dostęp do pikseli musi być uzyskiwany za pomocą metadanych dostarczanych przez odpowiednie struktury XrSpatialReferenceImagePlaneEXT. Każdy zdekodowany kanał koloru piksela RGB ma rozmiar 8 bitów, co oznacza, że każdy piksel ma rozmiar 24 bitów.

Ustawienia śledzenia obrazu przestrzennego

To rozszerzenie udostępnia opcjonalne struktury, których aplikacja może używać do konfigurowania funkcji śledzenia obrazu.

Optymalizacja obrazu statycznego

Struktura XrSpatialImageStaticOptimizationEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • optimizeForStaticImage to XrBool32, który wskazuje, czy obrazy się poruszają. Wartość XR_TRUE oznacza, że obrazy się nie poruszają.

Jeśli XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT jest wyliczany przez xrEnumerateSpatialCapabilityFeaturesEXT dla funkcji XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, aplikacja może połączyć XrSpatialImageStaticOptimizationEXT z łańcuchem XrSpatialImageTrackingDatabaseCreateInfoEXT :: next lub XrSpatialReferenceImageEXT :: next .

Jeśli aplikacja łączy XrSpatialImageStaticOptimizationEXT ze strukturą XrSpatialImageTrackingDatabaseCreateInfoEXT, środowisko wykonawcze musi założyć, że wszystkie obrazy w tej strukturze XrSpatialImageTrackingDatabaseEXT są statyczne, jeśli optimizeForStaticImage jest ustawione na XR_TRUE . W związku z tym środowisko wykonawcze musi zakładać, że wszystkie obrazy w bazie danych XrSpatialImageTrackingDatabaseEXT nie są statyczne, jeśli parametr optimizeForStaticImage jest ustawiony na XR_FALSE .

Jeśli aplikacja łączy XrSpatialImageStaticOptimizationEXT ze strukturą XrSpatialReferenceImageEXT, środowisko wykonawcze musi założyć, że ten obraz referencyjny jest statyczny, jeśli optimizeForStaticImage jest ustawione na XR_TRUE . W związku z tym środowisko wykonawcze musi założyć, że ten obraz referencyjny nie jest statyczny, jeśli właściwość optimizeForStaticImage jest ustawiona na XR_FALSE . Łączenie struktury XrSpatialImageStaticOptimizationEXT ze strukturą XrSpatialReferenceImageEXT ma pierwszeństwo przed łączeniem jej ze strukturą XrSpatialImageTrackingDatabaseCreateInfoEXT.

Jeśli XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT nie jest wyliczany przez xrEnumerateSpatialCapabilityFeaturesEXT dla funkcji XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, a aplikacja łączy strukturę XrSpatialImageStaticOptimizationEXT z dowolnym z odpowiednich kolejnych łańcuchów, środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE z xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Może to pozwolić środowisku wykonawczemu na wygenerowanie dokładniejszej pozycji i rozmiaru.

Może to pozwolić środowisku wykonawczemu na zmniejszenie zużycia energii.

Prawidłowe użycie (pośrednie)

Szerokość obrazu referencyjnego

Struktura XrSpatialImageSizeEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • physicalWidth to wartość typu float reprezentująca fizyczną szerokość w metrach, którą chcesz ustawić.

Jeśli XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT jest wyliczany przez xrEnumerateSpatialCapabilityFeaturesEXT dla funkcji XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, aplikacja może połączyć XrSpatialImageSizeEXT z XrSpatialImageTrackingDatabaseCreateInfoEXT :: next lub XrSpatialReferenceImageEXT :: next .

Jeśli aplikacja łączy XrSpatialImageSizeEXT ze strukturą XrSpatialImageTrackingDatabaseCreateInfoEXT, środowisko wykonawcze musi założyć, że wszystkie obrazy w tej bazie danych XrSpatialImageTrackingDatabaseEXT mają szerokość physicalWidth m i wysokość zgodną z formatem obrazu podanym pośrednio przez XrSpatialReferenceImageEXT :: width i XrSpatialReferenceImageEXT :: height .

Jeśli aplikacja łączy XrSpatialImageSizeEXT ze strukturą XrSpatialReferenceImageEXT, środowisko wykonawcze musi założyć, że ten obraz referencyjny ma szerokość physicalWidth m i wysokość zgodną z formatem obrazu podanym pośrednio przez XrSpatialReferenceImageEXT :: width i XrSpatialReferenceImageEXT :: height . Łączenie struktury XrSpatialImageSizeEXT ze strukturą XrSpatialReferenceImageEXT ma pierwszeństwo przed łączeniem jej ze strukturą XrSpatialImageTrackingDatabaseCreateInfoEXT.

Może to pozwolić środowisku wykonawczemu na zwrócenie dokładniejszej pozycji i rozmiaru.

Środowisko wykonawcze musi wyliczać XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT lub XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT albo obie te wartości.

Jeśli funkcja XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT jest wyliczana przez xrEnumerateSpatialCapabilityFeaturesEXT, środowisko wykonawcze musi automatycznie podawać rozmiary obrazów, dla których aplikacja nie dostarczyła żadnych struktur XrSpatialImageSizeEXT w ramach odpowiednich łańcuchów Next.

Aby środowisko wykonawcze mogło automatycznie i dokładnie generować rozmiary obrazów, mogą być wymagane pewne funkcje urządzenia i warunki wstępne, np. kamery stereo, dokładnie skalibrowane parametry zewnętrzne i wewnętrzne kamery.

Jeśli XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT nie jest wyliczany przez xrEnumerateSpatialCapabilityFeaturesEXT, aplikacja musi połączyć struktury XrSpatialImageSizeEXT z odpowiednimi kolejnymi łańcuchami, tak aby wszystkie obrazy miały podany wyraźny rozmiar. W przeciwnym razie środowisko wykonawcze musi zwrócić XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT z xrCreateSpatialImageTrackingDatabaseAsyncEXT.

Prawidłowe użycie (pośrednie)

Struktura XrSpatialCapabilityConfigurationImageTrackingEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • capability to XrSpatialCapabilityEXT i musi mieć wartość XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT .
  • enabledComponentCount to uint32_t, który określa liczbę elementów w enabledComponents .
  • enabledComponents to tablica XrSpatialComponentTypeEXT, która określa komponenty, które mają być włączone dla tej funkcji.
  • imageTrackingDatabaseCount to unint32_t, który określa liczbę elementów w imageTrackingDatabases .
  • imageTrackingDatabases to tablica uchwytów XrSpatialImageTrackingDatabaseEXT, która określa bazy danych śledzenia obrazów, które mają być włączone w kontekście przestrzennym.

Jeśli śledzenie obrazu jest obsługiwane, środowisko wykonawcze musi je włączyć, gdy struktura XrSpatialCapabilityConfigurationImageTrackingEXT jest przekazywana w XrSpatialContextCreateInfoEXT :: capabilityConfigs podczas wywoływania xrCreateSpatialContextAsyncEXT .

Struktura XrSpatialCapabilityConfigurationImageTrackingEXT umożliwia aplikacji wykrywanie obrazów referencyjnych reprezentowanych przez uchwyty XrSpatialImageTrackingDatabaseEXT w imageTrackingDatabases .

Środowisko wykonawcze musi zwracać XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT, jeśli XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT nie jest wyliczany przez xrEnumerateSpatialCapabilitiesEXT .

Prawidłowe użycie (pośrednie)

Obraz referencyjny przestrzenny

Struktura XrSpatialReferenceImagePlaneEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

Opisy parametrów

  • bufferSize to rozmiar tablicy buffer.
  • buffer to tablica danych uint8_t reprezentujących dane płaszczyzny.
  • rowStride to odległość w bajtach między 2 pozycjami początkowymi kolejnych wierszy danych pikseli.
  • pixelStride to odległość w bajtach między 2 kolejnymi pikselami.

Środowisko wykonawcze musi uzyskiwać dostęp do buffer zgodnie ze wzorcami podanymi w parametrach rowStride i pixelStride.

Aplikacja musi ustawić parametry rowStride i pixelStride w taki sposób, aby środowisko wykonawcze wyodrębniało tylko istotne piksele tego elementu XrSpatialReferenceImagePlaneEXT.

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_EXT_spatial_image_tracking musi być włączone przed użyciem XrSpatialReferenceImagePlaneEXT.
  • buffer musi być wskaźnikiem do tablicy wartości bufferSize uint8_t
  • Parametr bufferSize musi być większy niż 0

Struktura XrSpatialReferenceImageEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

Opisy parametrów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • width to szerokość obrazu referencyjnego w pikselach.
  • height to wysokość obrazu referencyjnego w pikselach.
  • format to XrSpatialReferenceImageFormatEXT reprezentujący format obrazu.
  • planeCount to liczba elementów w tablicy planes.
  • planes to tablica struktur XrSpatialReferenceImagePlaneEXT reprezentujących płaszczyzny danych obrazu.

Aplikacja może utworzyć co najmniej 1 strukturę XrSpatialReferenceImageEXT, z których każda reprezentuje pojedynczy wejściowy obraz referencyjny, który ma zostać przekazany do funkcji xrCreateSpatialImageTrackingDatabaseAsyncEXT za pomocą XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages podczas tworzenia uchwytu XrSpatialImageTrackingDatabaseEXT.

Aplikacja musi dostarczać dane XrSpatialReferenceImagePlaneEXT :: buffer w kolejności pikseli od lewej do prawej i od góry do dołu.

Aplikacja musi udostępniać strukturę XrSpatialReferenceImagePlaneEXT w tablicy XrSpatialReferenceImageEXT :: planes dla każdego kanału kolorów XrSpatialReferenceImageEXT :: format .

Prawidłowe użycie (pośrednie)

Komponenty gwarantowane

Środowisko wykonawcze obsługujące XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT musi udostępniać te komponenty przestrzenne jako gwarantowane komponenty wszystkich elementów wykrywanych przez te funkcje i musi je wyliczać w xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Komponent obrazu 2D

Struktura listy komponentów do danych zapytania

Struktura XrSpatialComponentImage2DListEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

Opisy parametrów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • imageCount to liczba elementów w tablicy images.
  • images to tablica obiektów XrSpatialImage2DDataEXT .

Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE z xrQuerySpatialComponentDataEXT, jeśli XrSpatialComponentImage2DListEXT znajduje się w łańcuchu XrSpatialComponentDataQueryResultEXT :: next, ale XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT nie jest uwzględniony w XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Środowisko wykonawcze musi zwracać XR_ERROR_SIZE_INSUFFICIENT z xrQuerySpatialComponentDataEXT, jeśli imageCount jest mniejsze niż XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Prawidłowe użycie (pośrednie)

Dane komponentu

Struktura XrSpatialImage2DDataEXT jest zdefiniowana w ten sposób:

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

Opisy parametrów

Aplikacja może używać imageTrackingDatabase, aby określić, która wcześniej utworzona baza danych XrSpatialImageTrackingDatabaseEXT zawiera obraz referencyjny tej struktury XrSpatialImage2DDataEXT. W przypadku tego elementu XrSpatialImageTrackingDatabaseEXT aplikacja może użyć referenceImageIndex, aby zidentyfikować element XrSpatialReferenceImageEXT tej struktury XrSpatialImage2DDataEXT, dopasowując go do kolejności wejściowej tablicy XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

Zbiór obrazów referencyjnych zdefiniowany przez zbiór wszystkich aktywnych baz danych nie powinien zawierać zduplikowanych obrazów. Dołączenie zduplikowanych obrazów może spowodować nieprawidłowe działanie funkcji wykrywania lub śledzenia, np. zwracanie niespójnych lub wielokrotnych indeksów.

Prawidłowe użycie (pośrednie)

Konfiguracja

Jeśli XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT jest wymieniony w XrSpatialCapabilityComponentTypesEXT :: componentTypes dla danej funkcji, aplikacja może ją włączyć, dodając wartość wyliczeniową do listy XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Ten komponent nie wymaga żadnej specjalnej konfiguracji, aby można go było uwzględnić w następnym łańcuchu XrSpatialCapabilityConfigurationBaseHeaderEXT .

Ograniczony komponent 2D

Komponent ograniczony 2D określa środek i zakres obrazu przestrzennego reprezentowanego przez element, na którym się znajduje. Więcej informacji o komponencie ograniczonym 2D znajdziesz w sekcji Ograniczony 2D.

Przykładowy kod

Odkrywanie obrazów przestrzennych i wysyłanie zapytań o dane komponentów

Poniższy przykładowy kod pokazuje, jak wykrywać elementy przestrzenne na potrzeby funkcji śledzenia obrazu i wysyłać zapytania o dane komponentu.

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

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components
  std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = discoveryFuture;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // For every frame in frame loop

  XrFrameState frameState;  // Previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata = *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

Nowe typy obiektów

Nowe polecenia

Nowe domy

Nowe wartości w polu enum

Nowe stałe typu wyliczeniowego

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • Rozszerzanie XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • Rozszerzenie XrResult :

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • Rozszerzenie XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

  • Rozszerzenie XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

  • Rozszerzenie XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

  • Rozszerzanie XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
    • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
    • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
    • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

Problemy

Historia zmian

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

    • Początkowy opis rozszerzenia