XR_ANDROID_geospatial_anchor
名称字符串
XR_ANDROID_geospatial_anchor
扩展程序类型
实例扩展程序
已注册的扩展程序编号
798
修订版本
1
批准状态
未批准
扩展程序和版本依赖项
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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROIDXR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROIDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_POSE_INVALIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_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 函数会启动异步操作来创建 Surface 锚点。与标准地理空间锚点不同，运行时可能会提取地形数据来确定正确的高度。如果应用尝试一次创建超过 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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROIDXR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROIDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_POSE_INVALIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_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_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHEDXR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROIDXR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROIDXR_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.
}
新增命令
- xrCreateGeospatialAnchorANDROID
- xrCreateSurfaceAnchorAsyncANDROID
- xrCreateSurfaceAnchorCompleteANDROID
新结构
- XrGeospatialAnchorCreateInfoANDROID
- XrSurfaceAnchorCreateCompletionANDROID
- XrSurfaceAnchorCreateInfoANDROID
新枚举
新枚举常量
XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAMEXR_ANDROID_geospatial_anchor_SPEC_VERSION扩展 XrResult：
XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
扩展 XrStructureType：
XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROIDXR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROIDXR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROIDXR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROIDXR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID
问题
版本记录
修订版 1，2025 年 10 月 30 日（Ben King）
- 初始草稿。