XR_ANDROID_spatial_anchor_space

名称字符串

XR_ANDROID_spatial_anchor_space

扩展程序类型

实例扩展程序

已注册的扩展程序编号

796

修订版本

1

批准状态

未批准

扩展程序和版本依赖项

XR_EXT_spatial_anchor

上次修改日期

2025-09-15

IP 状态

没有已知的 IP 权利主张。

创作贡献者

YuSheng Chang，Google
Kyle Chen，Google
Levana Chen，Google
Nihav Jain，Google
Spencer Quin，Google

概览

XR_EXT_spatial_anchor 扩展程序中定义的 xrCreateSpatialAnchorEXT 函数允许应用创建空间锚点，并使用 XrSpatialEntityEXT 句柄来表示该锚点。相比之下，此扩展程序会创建由 XrSpace 句柄表示的空间锚点。这在应用想要执行以下操作时非常有用：

  • 使用 xrLocateSpaces 获取锚点的位置。
  • 定位相对于锚点的其他空间。
  • 使用 XR_ANDROID_anchor_sharing_export 导出锚点。
  • 应用已放置锚点，现在仅关注锚点的位置（用于附加虚拟内容），而不关注通过用于创建锚点的 XrSpatialContextEXT 发现的任何其他实体的任何其他组件，从而允许应用销毁空间上下文。

使用此扩展程序创建的锚点无法使用 XR_ANDROID_device_anchor_persistence 扩展程序进行持久化，应用必须改用 XR_EXT_spatial_persistence_operations。如果 XrPersistedAnchorSpaceInfoANDROID :: anchor 是使用 xrCreateSpatialAnchorSpaceANDROID 或 xrCreateSpatialAnchorSpaceFromIdANDROID 创建的，则运行时必须从 xrPersistAnchorANDROID 返回 XR_ERROR_VALIDATION_FAILURE。

为空间锚点创建 XrSpace

创建空间锚点和空间

xrCreateSpatialAnchorSpaceANDROID 函数的定义如下：

XrResult xrCreateSpatialAnchorSpaceANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpace*                                    anchorSpace);

参数说明

xrCreateSpatialAnchorSpaceANDROID 函数会创建一个锚点，该锚点会输出一个 XrSpatialEntityIdEXT 和一个 XrSpace 句柄。xrCreateSpatialAnchorSpaceANDROID 的验证要求与 xrCreateSpatialAnchorEXT 相同。

如果传递给 xrCreateSpatialAnchorSpaceANDROID 的 XrSpatialContextEXT 未配置 XR_SPATIAL_CAPABILITY_ANCHOR_EXT，则运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

关于 xrCreateSpatialAnchorSpaceANDROID 创建的锚点的可发现性，请参阅 xrCreateSpatialAnchorEXT 规范的最后一段。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • 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_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

基于现有空间锚点创建 XrSpace

xrCreateSpatialAnchorSpaceFromIdANDROID 函数的定义如下：

XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorSpace);

参数说明

在空间锚点实体已存在（例如由于持久性）的情况下，应用可以通过提供这些空间锚点的空间实体 ID，基于这些空间锚点创建 XrSpace。

xrCreateSpatialAnchorSpaceFromIdANDROID 函数通过在 XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId 字段中提供 XrSpatialEntityIdEXT 来创建 XrSpace 句柄。

如果传递给 xrCreateSpatialAnchorSpaceFromIdANDROID 的 XrSpatialContextEXT 未配置 XR_SPATIAL_CAPABILITY_ANCHOR_EXT，则运行时必须返回 XR_ERROR_VALIDATION_FAILURE。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • 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_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialAnchorSpaceFromIdCreateInfoANDROID 结构的定义如下：

typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • anchorEntityId 是现有空间锚点的 XrSpatialEntityIdEXT，用于创建 XrSpace。

如果 XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId 不是 spatialContext 的有效 ID，则运行时必须返回 XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT。

如果 XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId 不是锚点的有效实体 ID，则运行时必须返回 XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID。

有效用法（隐式）

锚点生命周期

XrSpace 句柄的父级是 XrSession。这意味着，即使 xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext 或 xrCreateSpatialAnchorSpaceANDROID :: spatialContext 被销毁，表示锚点的 XrSpace 句柄仍然有效。通过创建 XrSpace 来表示空间实体锚点，应用可以销毁使用 XR_SPATIAL_CAPABILITY_ANCHOR_EXT 配置的 XrSpatialContextEXT，同时仍能继续使用其 XrSpace 通过 xrLocateSpaces 获取锚点的最新姿态，即运行时必须继续跟踪锚点，直到表示该锚点的所有 XrSpace 句柄都已被销毁。

示例代码

将空间锚点创建为 XrSpace

以下示例代码演示了如何创建空间锚点并将其作为 XrSpace 返回。

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpace spatialAnchorSpace {XR_NULL_HANDLE}; // XrSpace handle of anchor

// Spatial anchor create info
XrSpatialAnchorCreateInfoEXT createInfo{
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

// Create spatial anchor using the new API
CHK_XR(xrCreateSpatialAnchorSpaceANDROID(session, spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorSpace));

// ...

根据锚点实体 ID 创建 XrSpace

以下示例代码演示了如何通过预先存在的锚点实体 ID 创建 XrSpace。

XrSpace anchorSpace = XR_NULL_HANDLE;

// Spatial anchor from XrSpace create info
XrSpatialAnchorSpaceFromIdCreateInfoANDROID createInfoFromId{
  .type = XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID,
  .anchorEntityId = spatialAnchorEntityId,
};

// Create XrSpace handle from spatial anchor ID
CHK_XR(xrCreateSpatialAnchorSpaceFromIdANDROID(session, spatialContext, &createInfoFromId, &anchorSpace));

// ...

新增命令

新结构

新枚举常量

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

  • 扩展 XrResult：

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

  • 扩展 XrStructureType：

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

问题

版本历史记录

  • 修订版本 1，2025 年 9 月 15 日（YuSheng Chang、Kyle Chen）

    • 初始扩展程序说明。