Android XR for OpenXR | Android Developers

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

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

XR_ANDROID_spatial_entity_bound_anchor

名称字符串

XR_ANDROID_spatial_entity_bound_anchor

扩展类型

实例扩展程序

已注册的扩展程序编号

791

修订版本

批准状态

未获批准

扩展程序和版本依赖项

XR_EXT_spatial_anchor

上次修改日期

2025-08-18

IP 状态

没有已知的 IP 权利主张。

创作贡献者

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

概览

此扩展程序允许应用创建锚点并将其附加到空间实体，在本扩展程序中，这些锚点称为“实体绑定锚点”。

实体绑定锚点表示为具有 XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT 组件和 XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT 组件的空间实体。XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT 组件存储锚点所附加到的父实体的 XrSpatialEntityIdEXT。

与实体绑定的锚点的姿势始终由其父实体的固定偏移量表示，该父实体被视为锚点的“基准”。例如，假设用户在墙上安装了一个虚拟相框，用户使用实体绑定锚点来表示该虚拟相框，并将其附加到墙壁实体。这样一来，随着实体墙的跟踪估计值不断改进，墙壁与相框之间的相对位置始终保持一致。

运行时支持

运行时必须支持至少一个空间跟踪扩展程序，例如 XR_EXT_spatial_plane_tracking。如果运行时支持空间实体绑定锚点，则必须通过枚举 xrEnumerateSpatialAnchorAttachableComponentsANDROID 函数来提供至少一个可附加的组件。应用可以使用 xrEnumerateSpatialAnchorAttachableComponentsANDROID 来枚举可附加的组件。

xrEnumerateSpatialAnchorAttachableComponentsANDROID 函数的定义如下：

XrResult xrEnumerateSpatialAnchorAttachableComponentsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    attachableComponentCapacityInput,
    uint32_t*                                   attachableComponentCountOutput,
    XrSpatialComponentTypeEXT*                  attachableComponents);

参数说明

instance 是 XrInstance 的句柄。
systemId 是将枚举其空间持久性存储区的 XrSystemId。
attachableComponentCapacityInput 是 attachableComponents 数组的容量，或设为 0 以请求获取所需的容量。
attachableComponentCountOutput 是可附加组件的数量；若 attachableComponentCapacityInput 容量不足，则为所需容量。
attachableComponents 是 XrSpatialComponentTypeEXT 的数组。如果 attachableComponentCapacityInput 为 0，它可以为 NULL。
如需详细了解如何检索所需的 attachableComponents 大小，请参阅缓冲区大小参数一章。

对于给定的 systemId，运行时必须始终从此枚举中返回相同的缓冲区内容，直到实例生命周期结束。

有效使用情况（隐式）

必须先启用 XR_ANDROID_spatial_entity_bound_anchor 扩展程序，然后才能调用 xrEnumerateSpatialAnchorAttachableComponentsANDROID
instance 必须是有效的 XrInstance 句柄
attachableComponentCountOutput 必须是指向 uint32_t 值的指针
如果 attachableComponentCapacityInput 不为 0，则 attachableComponents 必须是指向包含 attachableComponentCapacityInput 个 XrSpatialComponentTypeEXT 值的数组的指针

返回代码

成功

XR_SUCCESS

失败

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SYSTEM_INVALID
XR_ERROR_VALIDATION_FAILURE

创建与空间实体绑定的锚点

应用使用 xrCreateSpatialAnchorEXT 函数来创建锚点。如果应用想要创建附加到空间实体的实体绑定锚点，则在调用 xrCreateSpatialAnchorEXT 函数时，可以将 XrSpatialAnchorParentANDROID 结构链接到 XrSpatialAnchorCreateInfoEXT 结构的下一个指针。

XrSpatialAnchorParentANDROID 结构的定义如下：

typedef struct XrSpatialAnchorParentANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    parentId;
} XrSpatialAnchorParentANDROID;

成员说明

type 是相应结构的 XrStructureType。
next 是 NULL 或指向结构链中下一个结构的指针。
parentId 是锚点将附着于其上的实体的 XrSpatialEntityIdEXT。

运行时必须保证父实体与锚点之间的距离始终一致，其中距离是指锚点到父实体最近表面的姿态（沿表面的法线）。无论父实体有多少个可附加的组件，系统都会根据父实体的位置以及与父实体表面的距离来更新锚点的姿态。

如果 XrSpatialAnchorParentANDROID ::parentId 不是 xrCreateSpatialAnchorEXT :: spatialContext 的有效 ID，运行时必须从 xrCreateSpatialAnchorEXT 返回 XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT。

如果 xrEnumerateSpatialAnchorAttachableComponentsANDROID 枚举的任何组件都不在父实体上，运行时必须从 xrCreateSpatialAnchorEXT 返回 XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID。

有效使用情况（隐式）

必须先启用 XR_ANDROID_spatial_entity_bound_anchor 扩展程序，然后才能使用 XrSpatialAnchorParentANDROID
type 必须为 XR_TYPE_SPATIAL_ANCHOR_PARENT_ANDROID
next 必须是 NULL 或指向结构链中下一个结构的有效指针

示例代码

创建与空间实体绑定的锚点

以下示例代码演示了如何创建与实体绑定的锚点并将其附加到空间平面跟踪实体。

XrFutureEXT future {XR_NULL_FUTURE_EXT};

std::vector<XrSpatialEntityEXT> entityBoundAnchorEntities;

// We want to look for entities that have the plane tracking components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{
    .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
    .componentTypeCount = static_cast<uint32_t>(snapshotComponents.size()),
    .componentTypes = snapshotComponents.data(),
  };
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{
    .type = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT,
    .baseSpace = localSpace,
    .time = time,
    .future = future,
  };

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{
    .type = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT,
  };
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    XrSpatialComponentDataQueryConditionEXT queryCond{
      .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
      .componentTypeCount = static_cast<uint32_t>(snapshotComponents.size()),
      .componentTypes = snapshotComponents.data(),
    };

    XrSpatialComponentDataQueryResultEXT queryResult{
      .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
    };
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2D(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT bounded2DList{
      .type = XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT,
      .boundCount = static_cast<uint32_t>(bounded2D.size()),
      .bounds = bounded2D.data(),
    };
    queryResult.next = &bounded2DList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    entityBoundAnchorEntities.reserve(queryResult.entityIdCountOutput);

    // Create anchors attached to the plane entities
    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] != XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        continue;
      }

      // Parent ID info the chained to spatial anchor create info next
      XrSpatialAnchorParentANDROID parentIdCreateInfo{
        .type = XR_TYPE_SPATIAL_ANCHOR_PARENT_ANDROID,
        .parentId = entityIds[i],
      };

      // spatial anchor create info
      XrSpatialAnchorCreateInfoEXT createInfo{
        .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
        // assign Parent ID to anchor create info next, and the pose to the bounded2D center
        .next = &parentIdCreateInfo,
        .baseSpace = localSpace,
        .time = time,
        .pose = bounded2D[i].center,
      };

      XrSpatialEntityIdEXT entityBoundAnchorEntityId {XR_NULL_SPATIAL_ENTITY_ID_EXT};
      XrSpatialEntityEXT entityBoundAnchorEntity {XR_NULL_HANDLE};
      CHK_XR(xrCreateSpatialAnchorEXT(spatialContext, &createInfo, &entityBoundAnchorEntityId, &entityBoundAnchorEntity));

      entityBoundAnchorEntities.push_back(entityBoundAnchorEntity);
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {
    .type = XR_TYPE_EVENT_DATA_BUFFER,
  };
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      if (event.type == XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT) {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
      }
  }

  // ...
  // Finish frame loop
  // ...
}

获取与实体绑定的锚姿势和父实体 ID

以下示例代码演示了如何获取实体绑定锚点的姿势及其父实体的 ID。

std::vector<XrSpatialEntityEXT> entities;

auto updateEntityBoundAnchorInfo = [&](XrSpatialContextEXT spatialContext, XrTime time) {
    // We want to get updated data for all components of the entities, so skip specifying componentTypes.
    XrSpatialUpdateSnapshotCreateInfoEXT snapshotCreateInfo{
      .type = XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT,
      .entityCount = static_cast<uint32_t>(entities.size()),
      .entities = entities.data(),
      .baseSpace = localSpace,
      .time = time,
    };

    XrSpatialSnapshotEXT snapshot {XR_NULL_HANDLE};
    CHK_XR(xrCreateSpatialUpdateSnapshotEXT(spatialContext, &snapshotCreateInfo, &snapshot));

    // Query for the entities that have the anchor component and parent component on them.
    std::array<XrSpatialComponentTypeEXT, 2> componentsToQuery {XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT, XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{
      .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
      .componentTypeCount = componentsToQuery.size(),
      .componentTypes = componentsToQuery.data(),
    };

    XrSpatialComponentDataQueryResultEXT queryResult{
      .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
    };
    CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    // query for the pose data
    std::vector<XrPosef> locations(queryResult.entityIdCountOutput);
    XrSpatialComponentAnchorListEXT locationList{
      .type = XR_TYPE_SPATIAL_COMPONENT_ANCHOR_LIST_EXT,
      .locationCount = static_cast<uint32_t>(locations.size()),
      .locations = locations.data(),
    };
    queryResult.next = &locationList;

    // query for the parent entity ID data
    std::vector<XrSpatialEntityIdEXT> parentIds(queryResult.entityIdCountOutput);
    XrSpatialComponentParentListEXT parentList{
      .type = XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT,
      .parentCount = static_cast<uint32_t>(parentIds.size()),
      .parents = parentIds.data(),
    };
    queryResult.next = &parentList;

    CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        // Pose for entity entityIds[i] is locations[i].
        // Parent entity ID for entity entityIds[i] is parentIds[i].
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(snapshot));
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  updateEntityBoundAnchorInfo(spatialContext, time);

  // ...
  // Finish frame loop
  // ...
}

枚举可附加的组件并检查实体绑定的锚点功能

以下示例代码演示了如何枚举可附加的组件，以及如何检查运行时是否支持实体绑定锚点功能。

// Check spatial capability
uint32_t capabilityCount = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

// Check if anchor capability is supported
if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_ANCHOR_EXT) == capabilities.end()) {
  return;
}

// Check if plane tracking capability is supported
if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT) == capabilities.end()) {
  return;
}

// The supported spatial tracking components
std::vector<XrSpatialComponentTypeEXT> spatialTrackingCapabilityComponents;

// Enumerate supported components for plane tracking capability
XrSpatialCapabilityComponentTypesEXT planeComponents{
  .type = XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT,
};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &planeComponents));
std::vector<XrSpatialComponentTypeEXT> planeCapabilityComponents(planeComponents.componentTypeCountOutput);
planeComponents.componentTypes = planeCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &planeComponents));

// Add plane supported components to spatial tracking supported components
spatialTrackingCapabilityComponents.insert(spatialTrackingCapabilityComponents.end(), planeCapabilityComponents.begin(), planeCapabilityComponents.end());

// Enumerate supported attachable components for anchor
uint32_t attachableComponentCount = 0;
CHK_XR(xrEnumerateSpatialAnchorAttachableComponentsANDROID(instance, systemId, 0, &attachableComponentCount, nullptr));
std::vector<XrSpatialComponentTypeEXT> attachableComponents(attachableComponentCount);
CHK_XR(xrEnumerateSpatialAnchorAttachableComponentsANDROID(instance, systemId, attachableComponentCount, &attachableComponentCount, attachableComponents.data()));

// Check if at least one spatial tracking component is supported
const auto supportsComponent = [&spatialTrackingCapabilityComponents](XrSpatialComponentTypeEXT component) {
  return std::find(spatialTrackingCapabilityComponents.begin(), spatialTrackingCapabilityComponents.end(), component) != spatialTrackingCapabilityComponents.end();
};

bool atLeastOneComponentSupported = false;
for (int32_t i = 0; i < attachableComponentCount; ++i) {
  if(supportsComponent(attachableComponents[i])) {
    atLeastOneComponentSupported = true;
    break;
  }
}

// No spatial tracking component supported for anchor attachment
if(!atLeastOneComponentSupported) return;

// ...
// Create spatial entity anchors and get their latest pose in the frame loop.
// ...

新增命令

xrEnumerateSpatialAnchorAttachableComponentsANDROID

新结构

扩展 XrSpatialAnchorCreateInfoEXT：
- XrSpatialAnchorParentANDROID

新的枚举常量

XR_ANDROID_SPATIAL_ENTITY_BOUND_ANCHOR_EXTENSION_NAME
XR_ANDROID_spatial_entity_bound_anchor_SPEC_VERSION
扩展 XrResult：
- XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID
扩展 XrStructureType：
- XR_TYPE_SPATIAL_ANCHOR_PARENT_ANDROID

问题

版本历史记录

修订版 1，2025-08-18（张育升）
- 初始扩展程序说明。
修订版 2，2025-12-16（Kyle Chen）
- 为 API 的某些行为添加了更具规范性的语言。
- 添加了 xrEnumerateSpatialAnchorAttachableComponentsANDROID 的示例代码。