XR_ANDROID_geospatial_anchor

Ciąg znaków nazwy

XR_ANDROID_geospatial_anchor

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

798

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

XR_ANDROID_geospatial
oraz
XR_EXT_future
oraz
XR_EXT_spatial_entity
oraz
XR_EXT_spatial_anchor

Data ostatniej modyfikacji

2025-10-30

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 udostępnia kotwice geoprzestrzenne i kotwice powierzchniowe, które bazują na podstawowym rozszerzeniu geoprzestrzennym. Kotwice geoprzestrzenne to kotwice, które są umieszczane w przestrzeni względem Ziemi na danej szerokości i długości geograficznej oraz wysokości nad poziomem morza. Kotwice powierzchniowe to kotwice względne względem Ziemi, które są umieszczane na danej szerokości i długości geograficznej oraz wysokości względem powierzchni znanej usłudze pozycjonowania wizualnego. W miarę jak dokładność określania pozycji środowiska wykonawczego względem Ziemi będzie się zwiększać, pozycja kotwicy będzie się odpowiednio dostosowywać.

Możliwości systemu w zakresie kotwic geoprzestrzennych

Struktura XrSystemGeospatialAnchorPropertiesANDROID jest zdefiniowana w ten sposób:

typedef struct XrSystemGeospatialAnchorPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSurfaceAnchorCount;
} XrSystemGeospatialAnchorPropertiesANDROID;

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.
  • maxSurfaceAnchorCount to uint32_t, co oznacza maksymalną liczbę kotwic powierzchni, które można utworzyć.

Aplikacja może sprawdzić możliwości systemu w zakresie przestrzennych punktów zakotwiczenia, łącząc strukturę XrSystemGeospatialAnchorPropertiesANDROID ze strukturą XrSystemProperties podczas wywoływania funkcji xrGetSystemProperties .

Jeśli XrSystemGeospatialPropertiesANDROID :: supportsGeospatial ma wartość XR_TRUE , to maxSurfaceAnchorCount wskazuje maksymalną liczbę kotwic powierzchniowych obsługiwanych przez środowisko wykonawcze. W tym przypadku limit musi być większy od 0.

Jeśli XrSystemGeospatialPropertiesANDROID :: supportsGeospatial nie jest równe XR_TRUE , to maxSurfaceAnchorCount musi mieć wartość 0.

Prawidłowe użycie (domyślne)

Śledzenie płaszczyzny dla kotwic

Struktura XrGeospatialTrackerAnchorTrackingInfoANDROID jest zdefiniowana w ten sposób:

typedef struct XrGeospatialTrackerAnchorTrackingInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrBool32           shouldTrackPlanes;
} XrGeospatialTrackerAnchorTrackingInfoANDROID;

Opisy członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • shouldTrackPlanes to XrBool32, które wskazuje, czy śledzenie geoprzestrzenne będzie śledzić samoloty w celu poprawy pozycjonowania zakotwiczeń na powierzchni.

Śledzenie płaszczyzny można włączyć, aby poprawić pozycjonowanie kotwic przytwierdzonych do powierzchni.

Jeśli aplikacja chce włączyć śledzenie płaszczyzn, aby poprawić pozycje kotwic powierzchniowych, może połączyć strukturę XrGeospatialTrackerAnchorTrackingInfoANDROID ze strukturą XrGeospatialTrackerCreateInfoANDROID podczas wywoływania funkcji xrCreateGeospatialTrackerANDROID .

Prawidłowe użycie (domyślne)

Kotwice geoprzestrzenne

Funkcja xrCreateGeospatialAnchorANDROID jest zdefiniowana w ten sposób:

XrResult xrCreateGeospatialAnchorANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrGeospatialAnchorCreateInfoANDROID*  createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId);

Opisy parametrów

  • spatialContext to XrSpatialContextEXT, w którym ma zostać utworzony punkt kotwiczący. Kontekst musi być skonfigurowany dla XR_SPATIAL_CAPABILITY_ANCHOR_EXT, w przeciwnym razie środowisko wykonawcze musi zwrócić XR_ERROR_VALIDATION_FAILURE .
  • createInfo to wskaźnik do struktury XrGeospatialAnchorCreateInfoANDROID zawierającej parametry tworzenia kotwicy.
  • anchorEntityId to wskaźnik do XrSpatialEntityIdEXT, w którym zwracany jest identyfikator jednostki kotwiczącej.

Jeśli element XrGeospatialTrackerANDROID określony w XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker nie jest w stanie XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, środowisko wykonawcze musi zwrócić wartość XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

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

Struktura XrGeospatialAnchorCreateInfoANDROID jest zdefiniowana w ten sposób:

typedef struct XrGeospatialAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrGeospatialPoseANDROID       geospatialPose;
} XrGeospatialAnchorCreateInfoANDROID;

Opisy członków

Prawidłowe użycie (domyślne)

Kotwy powierzchniowe

Kotwice powierzchniowe to kotwice umieszczane względem powierzchni, np. terenu lub dachu.

Wyliczenie XrSurfaceAnchorTypeANDROID jest zdefiniowane w ten sposób:

typedef enum XrSurfaceAnchorTypeANDROID {
    XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID = 1,
    XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID = 2,
    XR_SURFACE_ANCHOR_TYPE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSurfaceAnchorTypeANDROID;

Wyliczenie XrSurfaceAnchorTypeANDROID określa typ powierzchni, względem której jest umieszczony punkt zakotwiczenia.

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

Opis typu wyliczeniowego

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Typ kotwicy umieszczonej względem powierzchni.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Rodzaj punktu zakotwiczenia umieszczonego względem dachu lub gruntu, jeśli nie ma budynku.

Funkcja xrCreateSurfaceAnchorAsyncANDROID jest zdefiniowana w ten sposób:

XrResult xrCreateSurfaceAnchorAsyncANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSurfaceAnchorCreateInfoANDROID*     createInfo,
    XrFutureEXT*                                future);

Opisy parametrów

  • spatialContext to XrSpatialContextEXT, w którym ma zostać utworzony punkt kotwiczący.
  • createInfo to wskaźnik do struktury XrSurfaceAnchorCreateInfoANDROID zawierającej parametry tworzenia kotwicy.
  • future to wskaźnik XrFutureEXT, który będzie przechowywać wynik operacji asynchronicznej.

Funkcja xrCreateSurfaceAnchorAsyncANDROID rozpoczyna asynchroniczną operację tworzenia kotwicy powierzchni. W przeciwieństwie do standardowych kotwic geoprzestrzennych środowisko wykonawcze może pobierać dane o terenie, aby określić prawidłową wysokość. Środowisko wykonawcze musi zwracać XR_ERROR_LIMIT_REACHED, jeśli aplikacja próbuje utworzyć więcej niż XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount kotwic powierzchniowych naraz. Jeśli element XrGeospatialTrackerANDROID określony w XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker nie jest w stanie XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, środowisko wykonawcze musi zwrócić XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Operacja może zakończyć się niepowodzeniem asynchronicznie z wynikiem XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID, jeśli dla danej lokalizacji nie ma danych o powierzchni. Środowisko wykonawcze musi zwrócić wartość XR_ERROR_VALIDATION_FAILURE, jeśli dla spatialContext nie skonfigurowano wartości XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

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

Struktura XrSurfaceAnchorCreateInfoANDROID jest zdefiniowana w ten sposób:

typedef struct XrSurfaceAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrSurfaceAnchorTypeANDROID    surfaceAnchorType;
    XrQuaternionf                 eastUpSouthOrientation;
    double                        latitude;
    double                        longitude;
    double                        altitudeRelativeToSurface;
} XrSurfaceAnchorCreateInfoANDROID;

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 należy użyć.
  • surfaceAnchorType to wartość XrSurfaceAnchorTypeANDROID dla kotwicy.
  • eastUpSouthOrientation to orientacja 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 -89,9 do +89,9.
  • longitude to długość geograficzna w stopniach z zakresu od –180 do +180.
  • altitudeRelativeToSurface to wysokość w metrach względem powierzchni określonej przez surfaceAnchorType .

Prawidłowe użycie (domyślne)

Funkcja xrCreateSurfaceAnchorCompleteANDROID jest zdefiniowana w ten sposób:

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     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_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Struktura XrSurfaceAnchorCreateCompletionANDROID zawiera wynik asynchronicznego tworzenia kotwicy powierzchni.

typedef struct XrSurfaceAnchorCreateCompletionANDROID {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSurfaceAnchorCreateCompletionANDROID;

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 tworzenia. 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.
  • anchorEntityId to XrSpatialEntityIdEXT utworzonego punktu kotwiczenia lub XR_NULL_SPATIAL_ENTITY_ID_EXT, jeśli futureResult nie jest 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_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Prawidłowe użycie (domyślne)

Przykład

Tworzenie kotwicy terenu

PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
PFN_xrCreateSurfaceAnchorAsyncANDROID xrCreateSurfaceAnchorAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCreateSurfaceAnchorCompleteANDROID xrCreateSurfaceAnchorCompleteANDROID;
XrInstance instance;
XrSession session;
XrGeospatialTrackerANDROID geospatialTracker;

// Create a spatial context
XrSpatialContextEXT spatialContext{};
{
  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  XrSpatialCapabilityConfigurationAnchorEXT
       anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  // ... wait until future is ready ...

  XrCreateSpatialContextCompletionEXT contextCompletion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &contextCompletion));
  if (contextCompletion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = contextCompletion.spatialContext;
}

XrSurfaceAnchorCreateInfoANDROID anchorCreateInfo{
    XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID};
anchorCreateInfo.surfaceAnchorType = XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID;
anchorCreateInfo.eastUpSouthOrientation = {0, 0, 0, 1};
anchorCreateInfo.latitude = 37.7749;
anchorCreateInfo.longitude = -122.4194;
anchorCreateInfo.altitudeRelativeToSurface = 0;
anchorCreateInfo.geospatialTracker = geospatialTracker;
XrFutureEXT anchorFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSurfaceAnchorAsyncANDROID(spatialContext, &anchorCreateInfo, &anchorFuture));

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

XrSurfaceAnchorCreateCompletionANDROID anchorCompletion{
    XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID};
CHK_XR(xrCreateSurfaceAnchorCompleteANDROID(spatialContext, anchorFuture, &anchorCompletion));
if (anchorCompletion.futureResult == XR_SUCCESS) {
  // Use completion.anchorEntityId.
  XrSpatialEntityIdEXT anchorId = anchorCompletion.anchorEntityId;

  // Query in UpdateSnapshot.
}

Nowe polecenia

Nowe struktury

Nowe wartości w polu enum

Nowe stałe wyliczeniowe

  • XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_geospatial_anchor_SPEC_VERSION

  • Rozszerzanie XrResult :

    • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID

  • Rozszerzanie XrStructureType :

    • XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID

Problemy

Historia wersji

  • Wersja 1, 30 października 2025 r. (Ben King)

    • Pierwsza wersja robocza.