Android XR for OpenXR | Android Developers

Android XR SDK 已推出開發人員預覽版 3，歡迎提供意見！歡迎試用，如有任何問題，請前往支援頁面與我們聯絡。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

XR_ANDROID_geospatial_anchor

名稱字串

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。

有效用量 (隱含)

使用 XrGeospatialTrackerAnchorTrackingInfoANDROID 前，XR_ANDROID_geospatial_anchor 擴充功能必須啟用
 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。

有效用量 (隱含)

呼叫 xrCreateGeospatialAnchorANDROID 前，XR_ANDROID_geospatial_anchor 擴充功能必須啟用
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_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 must 為有效的 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_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 指定表面的高度，單位為公尺。

有效用量 (隱含)

使用 XrSurfaceAnchorCreateInfoANDROID 前，XR_ANDROID_geospatial_anchor 擴充功能必須啟用。
 type 必須為 XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
next 必須是 NULL，或是指向結構體鏈結中下一個結構體的有效指標
geospatialTracker must 為有效的 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 的指標，可接收結果。

有效用量 (隱含)

呼叫 xrCreateSurfaceAnchorCompleteANDROID 前，XR_ANDROID_geospatial_anchor 擴充功能必須啟用
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 鏈結中的結構可能會提供更多失敗資訊。
是所建立錨點的 XrSpatialEntityIdEXT，如果 futureResult 不是 XR_SUCCESS，則為 XR_NULL_SPATIAL_ENTITY_ID_EXT。anchorEntityId

日後推出的回覆代碼

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)
- 初稿。