Android XR for OpenXR | Android Developers

Android 開發人員高峰會再度登場，並專為 Android XR 規劃一系列議程。歡迎試用，並提供意見！

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

798

修訂版本

批准狀態

未批准

擴充功能和版本依附元件

XR_ANDROID_geospatial
和
XR_EXT_future
和
XR_EXT_spatial_entity
和
XR_EXT_spatial_anchor

上次修改日期

2025-10-30

IP 狀態

沒有已知的智慧財產權聲明。

著作人

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

總覽

這項擴充功能提供地理空間錨點和表面錨點，以基礎地理空間擴充功能為建構基礎。地理空間錨點是相對於地球，位於特定經緯度和高度的錨點。表面錨點是與地球相關的錨點，會放置在相對於表面的指定經緯度和高度，由視覺定位服務辨識。隨著執行階段相對於地球的位置準確度提高，錨點的姿勢也會隨之調整。

地理空間錨點的系統功能

XrSystemGeospatialAnchorPropertiesANDROID 結構定義如下：

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

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
maxSurfaceAnchorCount 是 uint32_t，表示可建立的表面錨點數量上限。

應用程式可以檢查系統的地理空間錨點功能，方法是在呼叫 xrGetSystemProperties 時，將 XrSystemGeospatialAnchorPropertiesANDROID 結構鏈結至 XrSystemProperties。

如果 XrSystemGeospatialPropertiesANDROID :: supportsGeospatial 為 XR_TRUE，則 maxSurfaceAnchorCount 表示執行階段支援的表面錨點數量上限。在這種情況下，限制必須大於 0。

如果 XrSystemGeospatialPropertiesANDROID :: supportsGeospatial 不是 XR_TRUE，則 maxSurfaceAnchorCount「必須」為 0。

有效用途 (隱含)

必須先啟用 XR_ANDROID_geospatial_anchor 擴充功能，才能使用 XrSystemGeospatialAnchorPropertiesANDROID
type「必須」為 XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID
next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標

錨點平面追蹤

XrGeospatialTrackerAnchorTrackingInfoANDROID 結構定義如下：

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

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或指向結構鏈中下一個結構的指標。
shouldTrackPlanes 是 XrBool32，指出地理空間追蹤器是否會追蹤平面，以改善表面鎖定錨點的位置。

可以啟用平面追蹤功能，改善表面鎖定錨點的定位。

如果應用程式想啟用平面追蹤功能，改善表面錨點姿勢，可以在呼叫 xrCreateGeospatialTrackerANDROID 時，將 XrGeospatialTrackerAnchorTrackingInfoANDROID 結構鏈結至 XrGeospatialTrackerCreateInfoANDROID。

有效用途 (隱含)

必須先啟用 XR_ANDROID_geospatial_anchor 擴充功能，才能使用 XrGeospatialTrackerAnchorTrackingInfoANDROID
type「必須」為 XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標

地理空間錨點

xrCreateGeospatialAnchorANDROID 函式的定義如下：

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

參數說明

spatialContext 是要在其中建立錨點的 XrSpatialContextEXT。必須為 XR_SPATIAL_CAPABILITY_ANCHOR_EXT 設定情境，否則執行階段必須傳回 XR_ERROR_VALIDATION_FAILURE。
createInfo 是指向 XrGeospatialAnchorCreateInfoANDROID 的指標，其中包含錨點建立參數。
anchorEntityId 是 XrSpatialEntityIdEXT 的指標，錨點實體 ID 會傳回至該指標。

如果 XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker 中指定的 XrGeospatialTrackerANDROID 未處於 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 狀態，執行階段必須傳回 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID。

有效用途 (隱含)

必須先啟用 XR_ANDROID_geospatial_anchor 擴充功能，才能呼叫 xrCreateGeospatialAnchorANDROID
spatialContext「必須」是有效的 XrSpatialContextEXT 控制代碼
createInfo「必須」是指向有效 XrGeospatialAnchorCreateInfoANDROID 結構的指標
anchorEntityId「必須」是指向 XrSpatialEntityIdEXT 值的指標

傳回代碼

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

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

XrGeospatialAnchorCreateInfoANDROID 結構定義如下：

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

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或指向結構鏈中下一個結構的指標。
geospatialTracker 是用於建立錨點的 XrGeospatialTrackerANDROID。
geospatialPose 是指向 XrGeospatialPoseANDROID 的指標，用於定義錨點的位置和方向。

有效用途 (隱含)

您必須先啟用 XR_ANDROID_geospatial_anchor 擴充功能，才能使用 XrGeospatialAnchorCreateInfoANDROID
type「必須」為 XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標
geospatialTracker「必須」是有效的 XrGeospatialTrackerANDROID 控制代碼
geospatialPose「必須」是有效的 XrGeospatialPoseANDROID 結構

表面錨點

表面錨點是相對於表面 (例如地形或屋頂) 放置的錨點。

XrSurfaceAnchorTypeANDROID 列舉的定義如下：

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;

XrSurfaceAnchorTypeANDROID 列舉會指定錨點相對於哪種表面。

列舉值如下：

列舉說明

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

相對於地面放置的錨點類型。

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

相對於屋頂或地面 (無建築物) 放置的錨點類型。

xrCreateSurfaceAnchorAsyncANDROID 函式的定義如下：

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

參數說明

spatialContext 是要在其中建立錨點的 XrSpatialContextEXT。
createInfo 是指向 XrSurfaceAnchorCreateInfoANDROID 的指標，其中包含錨點建立參數。
future 是指向 XrFutureEXT 的指標，會保留非同步作業的結果。

xrCreateSurfaceAnchorAsyncANDROID 函式會啟動非同步作業，建立表面錨點。與標準地理空間錨點不同，執行階段可能會擷取地形資料，判斷正確的高度。如果應用程式嘗試一次建立超過 XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount 個表面錨點，執行階段必須傳回 XR_ERROR_LIMIT_REACHED。如果 XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker 中指定的 XrGeospatialTrackerANDROID 不在 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 狀態，執行階段必須傳回 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID。如果指定位置沒有表面資料，作業可能會以非同步方式失敗，並傳回 XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID 結果。如果未為 spatialContext 設定 XR_SPATIAL_CAPABILITY_ANCHOR_EXT，執行階段「必須」傳回 XR_ERROR_VALIDATION_FAILURE。

有效用途 (隱含)

必須先啟用 XR_ANDROID_geospatial_anchor 擴充功能，才能呼叫 xrCreateSurfaceAnchorAsyncANDROID
spatialContext「必須」是有效的 XrSpatialContextEXT 控制代碼
createInfo「必須」是指向有效 XrSurfaceAnchorCreateInfoANDROID 結構的指標
future「必須」是指向 XrFutureEXT 值的指標

傳回代碼

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

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

XrSurfaceAnchorCreateInfoANDROID 結構定義如下：

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

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或指向結構鏈中下一個結構的指標。
geospatialTracker 是要使用的 XrGeospatialTrackerANDROID。
surfaceAnchorType 是錨點的 XrSurfaceAnchorTypeANDROID。
eastUpSouthOrientation 是相對於座標系統的方向，其中 +X=東、+Y=上、+Z=南。
latitude 是緯度 (以度為單位)，介於 -89.9 和 +89.9 之間。
longitude 是經度 (以度為單位)，介於 -180 到 +180 之間。
altitudeRelativeToSurface 是相對於 surfaceAnchorType 指定表面的高度 (以公尺為單位)。

有效用途 (隱含)

必須先啟用 XR_ANDROID_geospatial_anchor 擴充功能，才能使用 XrSurfaceAnchorCreateInfoANDROID
type「必須」為 XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標
geospatialTracker「必須」是有效的 XrGeospatialTrackerANDROID 控制代碼
surfaceAnchorType「必須」是有效的 XrSurfaceAnchorTypeANDROID 值
latitude「必須」是有效的 double 值
longitude「必須」是有效的 double 值
altitudeRelativeToSurface「必須」是有效的 double 值

xrCreateSurfaceAnchorCompleteANDROID 函式的定義如下：

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     completion);

參數說明

spatialContext 是用於建立的 XrSpatialContextEXT。
future 是 xrCreateSurfaceAnchorAsyncANDROID 傳回的 XrFutureEXT。
completion 是指向 XrSurfaceAnchorCreateCompletionANDROID 的指標，用於接收結果。

有效用途 (隱含)

必須先啟用 XR_ANDROID_geospatial_anchor 擴充功能，才能呼叫 xrCreateSurfaceAnchorCompleteANDROID
spatialContext「必須」是有效的 XrSpatialContextEXT 控制代碼
completion「必須」是指向 XrSurfaceAnchorCreateCompletionANDROID 結構的指標

傳回代碼

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

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

XrSurfaceAnchorCreateCompletionANDROID 結構會保留非同步建立表面錨點的結果。

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

成員說明

type 是這個結構的 XrStructureType。
next 是 NULL，或指向結構鏈中下一個結構的指標。
futureResult 是建立作業的 XrResult。如果 futureResult 為 XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID，next 鏈結中的結構可能會提供更多失敗相關資訊。
anchorEntityId 是所建立錨點的 XrSpatialEntityIdEXT，如果 futureResult 不是 XR_SUCCESS，則為 XR_NULL_SPATIAL_ENTITY_ID_EXT。

未來退貨代碼

futureResult 值：

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

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

有效用途 (隱含)

必須先啟用 XR_ANDROID_geospatial_anchor 擴充功能，才能使用 XrSurfaceAnchorCreateCompletionANDROID
type「必須」為 XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
next「必須」為 NULL，或指向結構鏈中下一個結構的有效指標
futureResult「必須」是有效的 XrResult 值

範例

建立地形錨點

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.
}

新結構

XrGeospatialAnchorCreateInfoANDROID
XrSurfaceAnchorCreateCompletionANDROID
XrSurfaceAnchorCreateInfoANDROID
擴充 XrGeospatialTrackerCreateInfoANDROID：
- XrGeospatialTrackerAnchorTrackingInfoANDROID
擴充 XrSystemProperties：
- XrSystemGeospatialAnchorPropertiesANDROID

新列舉

XrSurfaceAnchorTypeANDROID

新列舉常數

XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
XR_ANDROID_geospatial_anchor_SPEC_VERSION
擴充 XrResult：
- XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
擴充 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

問題

版本記錄

修訂版本 1，2025 年 10 月 30 日 (Ben King)
- 初始草稿。