XR_ANDROID_geospatial

Ciąg znaków nazwy

XR_ANDROID_geospatial

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

790

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

XR_EXT_future

Data ostatniej modyfikacji

2025-12-18

Stan adresu IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

John Ullman, Google
Ben King, Google
Nihav Jain, Google
Jared Finder, Google

Omówienie

To rozszerzenie zapewnia śledzenie geoprzestrzenne w interfejsie Geospatial API od Google, który umożliwia precyzyjne określanie lokalizacji geograficznej i orientacji oraz umieszczanie treści w aplikacji w odniesieniu do Ziemi. Wykorzystuje do tego połączenie śledzenia ruchu, GPS-u i innych czujników oraz systemu pozycjonowania wizualnego (VPS) od Google. VPS porównuje obrazy z aparatu urządzenia ze zdjęciami Street View, aby określić dokładną lokalizację i orientację. Interfejs Geospatial API często zapewnia dokładność pozycji poniżej metra (o rzędy wielkości lepszą niż GPS) i dokładność orientacji poniżej stopnia.

Aby móc korzystać z interfejsów API w tym rozszerzeniu (innych niż sprawdzanie obsługi rozszerzenia), aplikacja musi mieć prawidłowo skonfigurowane dane logowania za pomocą jakiegoś mechanizmu, np. XR_ANDROID_google_cloud_auth. Więcej informacji o konfiguracji i wynikach błędów znajdziesz w dokumentacji rozszerzenia uwierzytelniania.

Uprawnienia

Aby korzystać z tego rozszerzenia, aplikacje na Androida muszą mieć w pliku manifestu uprawnienie android.permission.ACCESS_FINE_LOCATION. Uprawnienie android.permission.ACCESS_FINE_LOCATION jest uznawane za niebezpieczne. Aby korzystać z tych funkcji, aplikacja musi prosić o uprawnienia w czasie działania:

(poziom ochrony: niebezpieczny)

Sprawdzanie możliwości systemu

Struktura XrSystemGeospatialPropertiesANDROID jest zdefiniowana w ten sposób:

typedef struct XrSystemGeospatialPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGeospatial;
} XrSystemGeospatialPropertiesANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej specyfikacji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • supportsGeospatial to XrBool32, która wskazuje, czy bieżący system obsługuje funkcje geoprzestrzenne.

Aplikacja może sprawdzić, czy system obsługuje funkcje geoprzestrzenne, łącząc strukturę XrSystemGeospatialPropertiesANDROID ze strukturą XrSystemProperties podczas wywoływania funkcji xrGetSystemProperties .

Jeśli środowisko wykonawcze zwraca XR_FALSE dla supportsGeospatial , system nie obsługuje funkcji geoprzestrzennych, a w związku z tym musi zwracać XR_ERROR_FEATURE_UNSUPPORTED z funkcji xrCreateGeospatialTrackerANDROID . Aplikacja nie powinna używać funkcji geoprzestrzennych, gdy wartość supportsGeospatial to XR_FALSE .

Prawidłowe użycie (domyślne)

Tworzenie uchwytu lokalizatora przestrzennego

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

Funkcja xrCreateGeospatialTrackerANDROID jest zdefiniowana w ten sposób:

XrResult xrCreateGeospatialTrackerANDROID(
    XrSession                                   session,
    const XrGeospatialTrackerCreateInfoANDROID* createInfo,
    XrGeospatialTrackerANDROID*                 geospatialTrackerOutput);

Opisy parametrów

Aplikacja może utworzyć uchwyt XrGeospatialTrackerANDROID, wywołując funkcję xrCreateGeospatialTrackerANDROID . Zwrócony uchwyt XrGeospatialTrackerANDROID może być później używany w wywołaniach interfejsu API. Jeśli aplikacja nie uzyskała wymaganych uprawnień, środowisko wykonawcze musi zwrócić wartość XR_ERROR_PERMISSION_INSUFFICIENT . W przypadku danej XrSession w danym momencie może istnieć tylko jeden obiekt XrGeospatialTrackerANDROID. Aplikacja musi zadbać o to, aby wszystkie poprzednie obiekty XrGeospatialTrackerANDROID zostały zniszczone przed ponownym wywołaniem tej funkcji. W przeciwnym razie środowisko wykonawcze musi zwrócić wartość XR_ERROR_LIMIT_REACHED. Jeśli tracker zostanie utworzony, początkowo będzie miał stan XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID, a aplikacja musi poczekać, aż stan zmieni się na XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, zanim będzie mogła go użyć. Zobacz XrEventDataGeospatialTrackerStateChangedANDROID . Jeśli aplikacja przekaże do funkcji, która tego wymaga, obiekt XrGeospatialTrackerANDROID, który nie jest w stanie XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, środowisko wykonawcze musi zwrócić wartość XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

Uchwyt XrGeospatialTrackerANDROID musi zostać ostatecznie zwolniony za pomocą funkcji xrDestroyGeospatialTrackerANDROID.

Prawidłowe użycie (domyślne)

Kody zwrotne

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_VALIDATION_FAILURE

Struktura XrGeospatialTrackerCreateInfoANDROID jest zdefiniowana w ten sposób:

typedef struct XrGeospatialTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrGeospatialTrackerCreateInfoANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.

Prawidłowe użycie (domyślne)

Funkcja xrDestroyGeospatialTrackerANDROID jest zdefiniowana w ten sposób:

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

Opisy parametrów

Aplikacja może użyć funkcji xrDestroyGeospatialTrackerANDROID, aby zwolnić tracker geoprzestrzenny i powiązane z nim zasoby.

Prawidłowe użycie (domyślne)

Bezpieczeństwo wątków

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

Kody zwrotne

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Stan trackera geoprzestrzennego

Wyliczenie XrGeospatialTrackerStateANDROID jest zdefiniowane w ten sposób:

typedef enum XrGeospatialTrackerStateANDROID {
    XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID = 0,
    XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID = 1,
    XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID = 2,
    XR_GEOSPATIAL_TRACKER_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGeospatialTrackerStateANDROID;

Wyliczenie XrGeospatialTrackerStateANDROID określa różne stany trackera geoprzestrzennego.

Wartości wyliczeniowe są następujące:

Opis typu wyliczeniowego

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Śledzenie przestrzenne nie działa.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Śledzenie przestrzenne działa i można z niego korzystać.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Nie udało się zainicjować narzędzia Geospatial Tracker, więc nigdy nie będzie można go używać.

Struktura XrEventDataGeospatialTrackerStateChangedANDROID jest zdefiniowana w ten sposób:

typedef struct XrEventDataGeospatialTrackerStateChangedANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrGeospatialTrackerANDROID         geospatialTracker;
    XrGeospatialTrackerStateANDROID    state;
    XrResult                           initializationResult;
    XrTime                             time;
} XrEventDataGeospatialTrackerStateChangedANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • geospatialTracker to XrGeospatialTrackerANDROID, którego stan uległ zmianie.
  • state to nowy stan XrGeospatialTrackerStateANDROID .
  • initializationResult to wynik błędu, jeśli state to XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID, w przeciwnym razie XR_SUCCESS .
  • time to XrTime, w którym nastąpiła zmiana stanu.

Struktura XrEventDataGeospatialTrackerStateChangedANDROID jest wysyłana, gdy zmienia się stan trackera geoprzestrzennego. Jeśli aplikacja ma prawidłowy obiekt XrGeospatialTrackerANDROID, powinna sprawdzać, czy to zdarzenie występuje. Pierwsze zdarzenie otrzymane przez moduł śledzący będzie miało wartość state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . Po określonym czasie stan musi się zmienić na XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID lub XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID . Ta zmiana może potrwać dowolnie długo. Jeśli state zmieni się na XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , musi to być ostatnie zdarzenie otrzymane dla tego trackera, a pole initializationResult będzie zawierać kod błędu. Wystąpienie błędu może zająć kilka sekund. W takim przypadku aplikacja powinna usunąć lokalizator. Jeśli state zmieni się na XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID, wszystkie utworzone wcześniej kotwice geoprzestrzenne muszą trwale przestać śledzić pozycję, a aplikacja powinna je usunąć. Stan może zmieniać się między XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID a XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID dowolną liczbę razy.

Prawidłowe użycie (domyślne)

Geospatial Pose

Struktura XrGeospatialPoseANDROID jest zdefiniowana w ten sposób:

typedef struct XrGeospatialPoseANDROID {
    XrQuaternionf    eastUpSouthOrientation;
    double           latitude;
    double           longitude;
    double           altitude;
} XrGeospatialPoseANDROID;

Opisy członków

  • eastUpSouthOrientation to XrQuaternionf określający orientację względem układu współrzędnych, w którym +X=wschód, +Y=góra i +Z=południe.
  • latitude to szerokość geograficzna w stopniach z zakresu od -90 do +90.
  • longitude to długość geograficzna w stopniach z zakresu od –180 do +180.
  • altitude to wysokość w metrach nad elipsoidą WGS84.

Struktura XrGeospatialPoseANDROID reprezentuje pozycję i orientację względem Ziemi przy użyciu elipsoidy WGS84.

Prawidłowe użycie (domyślne)

  •  Rozszerzenie XR_ANDROID_geospatial musi być włączone przed użyciem funkcji XrGeospatialPoseANDROID.
  • latitude musi być prawidłową wartością double
  • longitude musi być prawidłową wartością double
  • altitude musi być prawidłową wartością double

Wyliczenie XrGeospatialPoseFlagBitsANDROID jest zdefiniowane w ten sposób:

// Flag bits for XrGeospatialPoseFlagsANDROID
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID = 0x00000001;
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID = 0x00000002;

Wyliczenie XrGeospatialPoseFlagBitsANDROID określa flagi dla pozycji geoprzestrzennych.

Bity flagi mają następujące znaczenia:

Opisy flag

  • XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID – oznacza, że element orientacji zawiera prawidłowe dane.
  • XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID – wskazuje, że element pozycji zawiera prawidłowe dane.

Typ XrGeospatialPoseFlagsANDROID to maska bitowa typu XrGeospatialPoseFlagBitsANDROID .

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

Konwertowanie XrPosef na Geospatial Pose

Funkcja xrLocateGeospatialPoseFromPoseANDROID jest zdefiniowana w ten sposób:

XrResult xrLocateGeospatialPoseFromPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseFromPoseLocateInfoANDROID* locateInfo,
    XrGeospatialPoseResultANDROID*              geospatialPoseResult);

Opisy parametrów

Funkcja xrLocateGeospatialPoseFromPoseANDROID przekształca pozę w XrGeospatialPoseFromPoseLocateInfoANDROID :: space w pozę geoprzestrzenną. Jeśli stan geospatialTracker nie jest równy XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , środowisko wykonawcze musi zwrócić wartość XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Jeśli funkcja zwraca XR_SUCCESS, pole XrGeospatialPoseResultANDROID :: poseFlags w geospatialPoseResult określa, które pola wyjściowe są prawidłowe. Jeśli w XrGeospatialPoseResultANDROID :: poseFlags nie ustawiono wartości XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID , aplikacja nie może odczytywać pól XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy ani XrGeospatialPoseResultANDROID :: verticalAccuracy w XrGeospatialPoseResultANDROID . Jeśli w XrGeospatialPoseResultANDROID :: poseFlags nie ustawiono wartości XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID , aplikacja nie może odczytywać wartości XrGeospatialPoseANDROID :: eastUpSouthOrientation ani XrGeospatialPoseResultANDROID :: orientationYawAccuracy . Jeśli pole XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID nie jest ustawione, pole XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID nie może być ustawione.

Jeśli dokładność jest niższa niż oczekiwana, może to oznaczać, że urządzenie nie korzysta z lokalizacji VPS. Aplikacja może poprosić użytkownika o skierowanie urządzenia na znaki i budynki, aby poprawić lokalizację.

Prawidłowe użycie (domyślne)

Kody zwrotne

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrGeospatialPoseFromPoseLocateInfoANDROID jest zdefiniowana w ten sposób:

typedef struct XrGeospatialPoseFromPoseLocateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrPosef            pose;
} XrGeospatialPoseFromPoseLocateInfoANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • space to XrSpace, w którym zdefiniowano pose.
  • time to XrTime, w którym obliczana jest wartość funkcji pose .
  • pose to XrPosef w space, które należy przekształcić w pozycję geoprzestrzenną.

Prawidłowe użycie (domyślne)

Struktura XrGeospatialPoseResultANDROID jest zdefiniowana w ten sposób:

typedef struct XrGeospatialPoseResultANDROID {
    XrStructureType                 type;
    void*                           next;
    XrGeospatialPoseFlagsANDROID    poseFlags;
    XrGeospatialPoseANDROID         geospatialPose;
    double                          horizontalAccuracy;
    double                          verticalAccuracy;
    double                          orientationYawAccuracy;
} XrGeospatialPoseResultANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • poseFlags to maska bitowa XrGeospatialPoseFlagsANDROID wskazująca prawidłowość komponentów pozycji.
  • geospatialPose to wynikowy element XrGeospatialPoseANDROID .
  • horizontalAccuracy to szacowana dokładność pozioma pozycji Geospatial pose, zdefiniowana jako promień w metrach okręgu o poziomie ufności 68% wokół podanej szerokości i długości geograficznej.
  • verticalAccuracy to szacowana dokładność pionowa pozycji Geospatial pose, zdefiniowana jako odległość w metrach na poziomie ufności 68% wokół podanej wysokości. Innymi słowy, istnieje 68% szans, że rzeczywista wysokość znajduje się w zakresie [ XrGeospatialPoseANDROID :: altitude – verticalAccuracy, XrGeospatialPoseANDROID :: altitude + verticalAccuracy ].
  • orientationYawAccuracy to szacowana dokładność odchylenia orientacji pozycji przestrzennej, zdefiniowana jako promień w stopniach na poziomie ufności 68% wokół danej orientacji.

Prawidłowe użycie (domyślne)

Konwertowanie pozycji geoprzestrzennej na XrPosef

Funkcja xrLocateGeospatialPoseANDROID jest zdefiniowana w ten sposób:

XrResult xrLocateGeospatialPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseLocateInfoANDROID*    locateInfo,
    XrSpaceLocation*                            location);

Opisy parametrów

Funkcja xrLocateGeospatialPoseANDROID przekształca pozę geoprzestrzenną w XrSpaceLocation . Jeśli XrGeospatialTrackerANDROID nie działa, środowisko wykonawcze musi zwrócić XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Jeśli funkcja zwraca wartość XR_SUCCESS, pole XrSpaceLocation :: locationFlags w location określa, które pola wyjściowe są prawidłowe.

Prawidłowe użycie (domyślne)

Kody zwrotne

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrGeospatialPoseLocateInfoANDROID jest zdefiniowana w ten sposób:

typedef struct XrGeospatialPoseLocateInfoANDROID {
    XrStructureType            type;
    const void*                next;
    XrSpace                    space;
    XrTime                     time;
    XrGeospatialPoseANDROID    geospatialPose;
} XrGeospatialPoseLocateInfoANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • space to XrSpace, w której będzie reprezentowana wynikowa pozycja.
  • time to XrTime, w którym należy zlokalizować pozę.
  • geospatialPose to XrGeospatialPoseANDROID do przekonwertowania.

Prawidłowe użycie (domyślne)

Dostępność VPS

Wyliczenie XrVPSAvailabilityANDROID jest zdefiniowane w ten sposób:

typedef enum XrVPSAvailabilityANDROID {
    XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID = 1,
    XR_VPS_AVAILABILITY_AVAILABLE_ANDROID = 2,
    XR_VPSAVAILABILITY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrVPSAvailabilityANDROID;

Wyliczenie XrVPSAvailabilityANDROID wskazuje dostępność VPS.

Wartości wyliczeniowe są następujące:

Opis typu wyliczeniowego

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

VPS nie jest dostępna w pobliżu podanej lokalizacji.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

VPS jest dostępny w pobliżu podanej lokalizacji.

Funkcja xrCheckVpsAvailabilityAsyncANDROID jest zdefiniowana w ten sposób:

XrResult xrCheckVpsAvailabilityAsyncANDROID(
    XrSession                                   session,
    double                                      latitude,
    double                                      longitude,
    XrFutureEXT*                                future);

Opisy parametrów

  • session to XrSession, którego należy użyć do sprawdzenia.
  • latitude to szerokość geograficzna w stopniach.
  • longitude to długość geograficzna w stopniach.
  • future to wskaźnik XrFutureEXT, który będzie przechowywać wynik operacji asynchronicznej.

Dostępność usługi Visual Positioning Service (VPS) wskazuje, czy można używać VPS do zwiększania dokładności geoprzestrzennej w danej lokalizacji.

Funkcja xrCheckVpsAvailabilityAsyncANDROID rozpoczyna asynchroniczne sprawdzanie dostępności VPS w danej lokalizacji. Aplikacja nie potrzebuje obiektu XrGeospatialTrackerANDROID, aby wywołać tę funkcję, i może użyć wyniku tej operacji, aby zdecydować, czy utworzyć taki obiekt. Jeśli aplikacja nie uzyskała wymaganych uprawnień, środowisko wykonawcze musi zwrócić wartość XR_ERROR_PERMISSION_INSUFFICIENT .

Prawidłowe użycie (domyślne)

  •  Rozszerzenie XR_ANDROID_geospatial musi być włączone przed wywołaniem funkcji xrCheckVpsAvailabilityAsyncANDROID.
  • session musi być prawidłowym uchwytem XrSession
  • latitude musi być prawidłową wartością double
  • longitude musi być prawidłową wartością double
  • future musi być wskaźnikiem do wartości XrFutureEXT

Kody zwrotne

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Funkcja xrCheckVpsAvailabilityCompleteANDROID jest zdefiniowana w ten sposób:

XrResult xrCheckVpsAvailabilityCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrVPSAvailabilityCheckCompletionANDROID*    completion);

Opisy parametrów

Prawidłowe użycie (domyślne)

Kody zwrotne

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

Struktura XrVPSAvailabilityCheckCompletionANDROID jest zdefiniowana w ten sposób:

typedef struct XrVPSAvailabilityCheckCompletionANDROID {
    XrStructureType             type;
    void*                       next;
    XrResult                    futureResult;
    XrVPSAvailabilityANDROID    availability;
} XrVPSAvailabilityCheckCompletionANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • futureResult to XrResult operacji sprawdzania. Jeśli futureResult to XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , struktura w łańcuchu next może zawierać więcej informacji o błędzie.
  • availability to wynikowy element XrVPSAvailabilityANDROID . Aplikacja nie może odczytywać tego pola, chyba że futureResult ma wartość XR_SUCCESS .

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_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Prawidłowe użycie (domyślne)

Przykład

Konfigurowanie trackera geoprzestrzennego

PFN_xrCheckVpsAvailabilityAsyncANDROID xrCheckVpsAvailabilityAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCheckVpsAvailabilityCompleteANDROID xrCheckVpsAvailabilityCompleteANDROID;
PFN_xrCreateGeospatialTrackerANDROID xrCreateGeospatialTrackerANDROID;
XrInstance instance = XR_NULL_HANDLE;
XrSystemId systemId = XR_NULL_SYSTEM_ID;
XrSession session = XR_NULL_HANDLE;
double lat = 37.422, lng = -122.084;

// Check for support.
XrSystemGeospatialPropertiesANDROID geospatialSystemProperties{
    XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{XR_TYPE_SYSTEM_PROPERTIES,
                                    &geospatialSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!geospatialSystemProperties.supportsGeospatial) {
  return;
}

// Check VPS Availability.
XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCheckVpsAvailabilityAsyncANDROID(session, lat, lng, &future));

XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
pollInfo.future = future;
pollResult.state = XR_FUTURE_STATE_PENDING_EXT;
while (pollResult.state == XR_FUTURE_STATE_PENDING_EXT) {
  // Do in render loop/state loop.
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
}

XrVPSAvailabilityCheckCompletionANDROID vpsCompletion{
    XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID};
CHK_XR(xrCheckVpsAvailabilityCompleteANDROID(session, future, &vpsCompletion));
if (vpsCompletion.futureResult == XR_SUCCESS) {
  if (vpsCompletion.availability == XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID) {
    // Visual Positioning Service is not available. Accuracy of positions and
    // orientations from Geospatial APIs are expected to be lower at this location.
  } else {
    // Visual Positioning Service is available. Higher accuracy of position and
    // orientation is achievable at this location.
  }
}

// Create Geospatial Tracker.
XrGeospatialTrackerCreateInfoANDROID createInfo{
    XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID};
XrGeospatialTrackerANDROID geospatialTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateGeospatialTrackerANDROID(session, &createInfo, &geospatialTracker));

// In application main event loop:
while (true) {
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  if (xrPollEvent(instance, &event) != XR_SUCCESS) {
    continue;
  }
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID:
      const XrEventDataGeospatialTrackerStateChangedANDROID& eventData =
          *reinterpret_cast<XrEventDataGeospatialTrackerStateChangedANDROID*>(&event);
      switch (eventData.state) {
        case XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID:
          // Destroy existing anchors, if any.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID:
          // Start adding content.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID:
          // Handle eventData.initializationResult error result.
          break;
      }
  }
}

Wywoływanie interfejsów Geospatial Pose API

PFN_xrLocateGeospatialPoseFromPoseANDROID xrLocateGeospatialPoseFromPoseANDROID;
PFN_xrLocateGeospatialPoseANDROID xrLocateGeospatialPoseANDROID;

XrGeospatialTrackerANDROID geospatialTracker;

// Get pose from view space.
XrSpace viewSpace;
XrPosef identityPose = {{0,0,0,1},{0,0,0}};
XrGeospatialPoseFromPoseLocateInfoANDROID poseGetInfo{
    XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID};
XrGeospatialPoseResultANDROID poseResult{
    XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID};
poseGetInfo.space = viewSpace;
poseGetInfo.pose = identityPose;
poseGetInfo.time = 0;  // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseFromPoseANDROID(geospatialTracker, &poseGetInfo, &poseResult));
if ((poseResult.poseFlags & XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID) &&
    (poseResult.poseFlags & XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID)) {
  // poseResult.geospatialPose is valid.
}

// Convert Geospatial pose to an XrSpaceLocation.
XrGeospatialPoseLocateInfoANDROID poseLocateInfo{
    XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID};
XrSpaceLocation location{XR_TYPE_SPACE_LOCATION};
poseLocateInfo.space = viewSpace;
poseLocateInfo.geospatialPose = poseResult.geospatialPose;
poseLocateInfo.time = 0; // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseANDROID(geospatialTracker, &poseLocateInfo, &location));
if ((location.locationFlags & XR_SPACE_LOCATION_ORIENTATION_VALID_BIT) &&
    (location.locationFlags & XR_SPACE_LOCATION_POSITION_VALID_BIT)) {
  // location.pose is valid.
}

Nowe typy obiektów

Nowe polecenia

Nowe struktury

Nowe wartości w polu enum

Nowe maski bitowe

Nowe stałe wyliczeniowe

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • Rozszerzanie XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • Rozszerzanie XrResult :

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • Rozszerzanie XrStructureType :

    • XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID
    • XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID

Problemy

Historia wersji

  • Wersja 1, 18 grudnia 2025 r. (Ben King)

    • Początkowy opis rozszerzenia.