XR_ANDROID_geospatial_anchor

Name String

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 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 udostępnia kotwice geoprzestrzenne i kotwice powierzchniowe, które bazują na podstawowym rozszerzeniu geoprzestrzennym. Kotwice geoprzestrzenne to kotwice, które są umieszczone w przestrzeni względem Ziemi na określonej szerokości i długości geograficznej oraz wysokości. Kotwice powierzchniowe to kotwice 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 Visual Positioning Service. W miarę jak środowisko wykonawcze będzie coraz dokładniej określać swoją pozycję względem Ziemi, pozycja kotwicy będzie odpowiednio dostosowywana.

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 podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • maxSurfaceAnchorCount to uint32_t wskazujący maksymalną liczbę kotwic powierzchni, które można utworzyć.

Aplikacja może sprawdzać możliwości systemu w zakresie kotwic geoprzestrzennych, łącząc strukturę XrSystemGeospatialAnchorPropertiesANDROID z XrSystemProperties podczas wywoływania xrGetSystemProperties .

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

Jeśli XrSystemGeospatialPropertiesANDROID :: supportsGeospatial nie jest XR_TRUE, maxSurfaceAnchorCount musi wynosić 0.

Prawidłowe użycie (pośrednie)

Śledzenie płaszczyzny na potrzeby 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 wskazujący, czy moduł śledzenia geoprzestrzennego będzie śledzić płaszczyzny, aby poprawić pozycjonowanie kotwic zablokowanych na powierzchni.

Można włączyć śledzenie płaszczyzny, aby poprawić pozycjonowanie kotwic zablokowanych na powierzchni.

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

Prawidłowe użycie (pośrednie)

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ć utworzona kotwica. 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 XrGeospatialAnchorCreateInfoANDROID zawierający parametry tworzenia kotwicy.
  • anchorEntityId to wskaźnik do XrSpatialEntityIdEXT, w którym zwracany jest identyfikator encji kotwicy.

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

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_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • 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

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • geospatialTracker to XrGeospatialTrackerANDROID, który ma zostać użyty do utworzenia kotwicy.
  • geospatialPose to wskaźnik do XrGeospatialPoseANDROID, który określa lokalizację i orientację kotwicy.

Prawidłowe użycie (pośrednie)

Kotwice powierzchniowe

Kotwice powierzchniowe to kotwice umieszczone względem powierzchni, np. terenu lub dachów.

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, do której odnosi się kotwica.

Elementy wyliczenia mają te wartości:

Opis typu wyliczeniowego

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Typ kotwicy umieszczonej względem powierzchni.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Typ kotwicy umieszczonej względem dachu lub gruntu, na którym 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ć utworzona kotwica.
  • createInfo to wskaźnik do XrSurfaceAnchorCreateInfoANDROID zawierającego parametry tworzenia kotwicy.
  • future to wskaźnik do XrFutureEXT, który będzie zawierać 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ż maxSurfaceAnchorCount kotwic powierzchniowych XrSystemGeospatialAnchorPropertiesANDROID jednocześnie. Jeśli 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 asynchronicznym z wynikiem XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID, jeśli dla danej lokalizacji nie ma danych o powierzchni. Środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE, jeśli XR_SPATIAL_CAPABILITY_ANCHOR_EXT nie skonfigurowano dla spatialContext .

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_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • 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 XrSurfaceAnchorTypeANDROID dla kotwicy.
  • eastUpSouthOrientation to orientacja względem układu współrzędnych, w którym +X=wschód, +Y=góra, a +Z=południe.
  • latitude to szerokość geograficzna w stopniach, od –89,9 do +89,9.
  • longitude to długość geograficzna w stopniach, od –180 do +180.
  • altitudeRelativeToSurface to wysokość w metrach względem powierzchni określonej przez surfaceAnchorType .

Prawidłowe użycie (pośrednie)

Funkcja xrCreateSurfaceAnchorCompleteANDROID jest zdefiniowana w ten sposób:

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     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_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 utworzonej kotwicy 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 (pośrednie)

Przykład

Tworzenie kotwicy terenowej

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 domy

Nowe wartości w polu enum

Nowe stałe typu wyliczeniowego

  • XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_geospatial_anchor_SPEC_VERSION

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

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

    • Pierwsza wersja robocza.