Android XR for OpenXR | Android Developers

Android XR SDK 已达到开发者预览版 3，我们希望收到您的反馈！您可以尝试一下，然后访问我们的支持页面与我们联系。

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 状态

没有已知的 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_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_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）
- 初稿。