XR_ANDROID_geospatial

Name String

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 IP

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

Twórcy

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

Przegląd

To rozszerzenie zapewnia śledzenie geoprzestrzenne na potrzeby interfejsu Geospatial API od Google, który zapewnia precyzyjną geolokalizację i orientację oraz umożliwia aplikacji umieszczanie treści względem Ziemi. Wykorzystuje do tego kombinację śledzenia ruchu, GPS-u i innych czujników oraz systemu wizualnego pozycjonowania (VPS) 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ść pozycjonowania 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 (poza sprawdzaniem obsługi rozszerzenia), aplikacja musi mieć skonfigurowane dane uwierzytelniające za pomocą mechanizmu takiego jak XR_ANDROID_google_cloud_auth . Więcej informacji o konfiguracji i błędach 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: niebezpieczne)

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 podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • supportsGeospatial to XrBool32, który wskazuje, czy bieżący system obsługuje funkcje geoprzestrzenne.

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

Jeśli środowisko wykonawcze zwraca XR_FALSE dla supportsGeospatial, system nie obsługuje funkcji geoprzestrzennych i dlatego musi zwracać XR_ERROR_FEATURE_UNSUPPORTED z xrCreateGeospatialTrackerANDROID . Aplikacja powinna unikać korzystania z funkcji geoprzestrzennych, gdy supportsGeospatial ma wartość XR_FALSE .

Prawidłowe użycie (pośrednie)

Tworzenie uchwytu modułu śledzenia geoprzestrzennego

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

Funkcja xrCreateGeospatialTrackerANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

  • session to XrSession, w której aktywny będzie moduł śledzenia geoprzestrzennego.
  • createInfo to wskaźnik do struktury XrGeospatialTrackerCreateInfoANDROID, która określa początkowe parametry modułu śledzenia geoprzestrzennego.
  • geospatialTrackerOutput to wskaźnik do uchwytu, w którym zwracany jest utworzony obiekt XrGeospatialTrackerANDROID.

Aplikacja może utworzyć uchwyt XrGeospatialTrackerANDROID, wywołując xrCreateGeospatialTrackerANDROID . Zwrócony uchwyt XrGeospatialTrackerANDROID można następnie używać w wywołaniach interfejsu API. Jeśli aplikacja nie uzyskała wymaganych uprawnień, środowisko wykonawcze musi zwrócić XR_ERROR_PERMISSION_INSUFFICIENT . W danym momencie dla konkretnej sesji XrSession może istnieć tylko jeden obiekt XrGeospatialTrackerANDROID. Aplikacja musi upewnić się, że wszystkie poprzednie obiekty XrGeospatialTrackerANDROID zostały zniszczone, zanim ponownie wywoła tę funkcję. W przeciwnym razie środowisko wykonawcze musi zwrócić XR_ERROR_LIMIT_REACHED. Jeśli moduł śledzący 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 można użyć modułu śledzącego. Zobacz XrEventDataGeospatialTrackerStateChangedANDROID . Jeśli aplikacja przekazuje XrGeospatialTrackerANDROID, który nie jest w stanie XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, do funkcji, która go wymaga, środowisko wykonawcze musi zwrócić XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

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

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_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 (pośrednie)

Funkcja xrDestroyGeospatialTrackerANDROID jest zdefiniowana w ten sposób:

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

Opisy parametrów

Aplikacja może używać funkcji xrDestroyGeospatialTrackerANDROID, aby zwolnić moduł śledzenia geoprzestrzennego i powiązane z nim zasoby.

Prawidłowe użycie (pośrednie)

Bezpieczeństwo wątków

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

Kody zwrotu

Sukces

  • XR_SUCCESS

Błąd

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Stan modułu śledzenia 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 identyfikuje różne stany trackera geoprzestrzennego.

Elementy wyliczenia mają te wartości:

Opis typu wyliczeniowego

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Geospatial Tracker nie jest uruchomiony.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Moduł śledzenia geoprzestrzennego działa i jest gotowy do użycia.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Nie udało się zainicjować modułu śledzenia geoprzestrzennego i 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 się zmienił.
  • state to nowy 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 modułu śledzenia geoprzestrzennego. Jeśli aplikacja ma prawidłowy element XrGeospatialTrackerANDROID, powinna sprawdzać, czy występuje to zdarzenie. Pierwsze zdarzenie odebrane przez lokalizator będzie miało wartość state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . Po upływie czasu określonego przez środowisko wykonawcze stan musi zmienić się na XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID lub XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID . Przejście zajmie dowolną ilość czasu. Jeśli wartość state zmieni się na XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID, musi to być ostatnie zdarzenie odebrane przez ten tracker, a pole initializationResult będzie zawierać kod błędu. Błąd może pojawić się po kilku sekundach. W takim przypadku aplikacja powinna zniszczyć obiekt śledzący. Jeśli state zmieni się na XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , wszystkie wcześniej utworzone kotwice geoprzestrzenne muszą trwale przestać śledzić i powinny zostać zniszczone przez aplikację. 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 (pośrednie)

Pozycja geoprzestrzenna

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, od –90 do +90.
  • longitude to długość geograficzna w stopniach, 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 (pośrednie)

  • Rozszerzenie XR_ANDROID_geospatial musi być włączone przed użyciem 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 jako:

// 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 pozycji geoprzestrzennych.

Bity flagi mają następujące znaczenie:

Opisy flag

  • XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID – wskazuje, ż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 XrGeospatialPoseFlagBitsANDROID .

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

Konwertowanie XrPosef na pozycję geoprzestrzenną

Funkcja xrLocateGeospatialPoseFromPoseANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

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

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 (pośrednie)

Kody zwrotu

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órej zdefiniowano pose.
  • time to XrTime, dla którego ma zostać obliczona wartość pose .
  • pose to XrPosef w space, który ma zostać przekonwertowany na pozycję geoprzestrzenną.

Prawidłowe użycie (pośrednie)

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 obiekt XrGeospatialPoseANDROID .
  • horizontalAccuracy to szacowana dokładność pozioma pozycji pozy geoprzestrzennej, zdefiniowana jako promień w metrach okręgu o poziomie ufności 68% wokół danej szerokości i długości geograficznej.
  • verticalAccuracy to szacowana dokładność pionowa pozycji geoprzestrzennej, zdefiniowana jako odległość w metrach przy poziomie ufności 68% wokół danej wysokości. Innymi słowy, istnieje 68% prawdopodobieństwa, że rzeczywista wysokość mieści się w zakresie [XrGeospatialPoseANDROID :: altitude – verticalAccuracy, XrGeospatialPoseANDROID :: altitude + verticalAccuracy ].
  • orientationYawAccuracy to szacowana dokładność odchylenia orientacji pozycji geoprzestrzennej, zdefiniowana jako promień w stopniach na poziomie ufności 68% wokół danej orientacji.

Prawidłowe użycie (pośrednie)

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 konwertuje pozycję geoprzestrzenną na XrSpaceLocation . Jeśli XrGeospatialTrackerANDROID nie działa, środowisko wykonawcze musi zwrócić XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Jeśli funkcja zwraca XR_SUCCESS, pole XrSpaceLocation :: locationFlags w location określa, które pola wyjściowe są prawidłowe.

Prawidłowe użycie (pośrednie)

Kody zwrotu

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_POSE_INVALID
  • 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órym będzie reprezentowana wynikowa pozycja.
  • time to XrTime, w którym ma zostać zlokalizowana pozycja.
  • geospatialPose to XrGeospatialPoseANDROID do przekonwertowania.

Prawidłowe użycie (pośrednie)

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.

Elementy wyliczenia mają te wartości:

Opis typu wyliczeniowego

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

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

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

Usługa VPS jest dostępna 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 do XrFutureEXT, który będzie zawierać wynik operacji asynchronicznej.

Dostępność usługi Visual Positioning Service (VPS) wskazuje, czy można jej użyć do poprawy dokładności danych geoprzestrzennych w określonej lokalizacji.

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

Prawidłowe użycie (pośrednie)

  • Rozszerzenie XR_ANDROID_geospatial musi być włączone przed wywołaniem 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 zwrotu

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 (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_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 obiekt 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 (pośrednie)

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 domy

Nowe wartości w polu enum

Nowe maski bitowe

Nowe stałe typu wyliczeniowego

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • Rozszerzanie XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • Rozszerzenie 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 zmian

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

    • Początkowy opis rozszerzenia.