XR_ANDROID_trackables OpenXR 扩展

名称字符串

XR_ANDROID_trackables

扩展程序类型

实例扩展程序

已注册的扩展程序编号

456

修订版本

1

扩展程序和版本依赖项

OpenXR 1.0

上次修改日期

2024-09-30

IP 状态

没有已知的 IP 权利主张。

贡献者

Spencer Quin，Google

Nihav Jain，Google

John Pursey，Google

Jared Finder，Google

Levana Chen，Google

Kenny Vercaemer，Google

概览

此扩展程序能让你的应用访问物理环境中的可跟踪对象，并创建附着其上的锚点。

此扩展程序定义了平面可跟踪对象。其他扩展程序可能会添加其他可跟踪对象类型。例如，XR_ANDROID_trackables_object 添加了物体可跟踪对象，而 XR_ANDROID_depth_texture 则添加了深度缓冲区，支持向环境中的任意点进行光线投射。

可跟踪对象是指在物理环境中被跟踪的物体（参见 XrTrackableTypeANDROID）：

  • 平面（例如墙壁、地板、天花板、桌子）
  • 物品（例如键盘、鼠标、笔记本电脑）

创建可跟踪对象跟踪器

XrTrackableTrackerANDROID 是一个句柄，表示在环境中发现和更新给定 XrTrackableTypeANDROID 类型的可跟踪对象时所需的资源。

XR_DEFINE_HANDLE(XrTrackableTrackerANDROID)

xrCreateTrackableTrackerANDROID 函数的定义如下： 

XrResult xrCreateTrackableTrackerANDROID(
    XrSession                                   session,
    const XrTrackableTrackerCreateInfoANDROID*  createInfo,
    XrTrackableTrackerANDROID*                  trackableTracker);

参数说明

应用可以使用 xrCreateTrackableTrackerANDROID 函数来创建一个可跟踪对象跟踪器。

  • 如果系统不支持指定类型的可跟踪对象，函数将返回 XR_ERROR_FEATURE_UNSUPPORTED。
  • 如果发出调用的应用未被授予所需权限，函数将返回 XR_ERROR_PERMISSION_INSUFFICIENT。

应用可以在后续 API 调用中使用返回的跟踪器句柄。 XrTrackableTrackerANDROID 句柄最终必须通过 xrDestroyTrackableTrackerANDROID 函数释放。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_FEATURE_UNSUPPORTED

XrTrackableTrackerCreateInfoANDROID 结构的定义如下：

typedef struct XrTrackableTrackerCreateInfoANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackableTypeANDROID    trackableType;
} XrTrackableTrackerCreateInfoANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • trackableType 是跟踪器将要跟踪的 XrTrackableTypeANDROID。

XrTrackableTrackerCreateInfoANDROID 结构在传递给 xrCreateTrackableTrackerANDROID 时，会为 XrTrackableTrackerANDROID 提供创建选项。

扩展程序可以定义能够附加到 next 上的结构，以允许对可跟踪对象跟踪器进行额外配置。

有效用法（隐式）

XrTrackableTypeANDROID 枚举的定义如下：

typedef enum XrTrackableTypeANDROID {
    XR_TRACKABLE_TYPE_NOT_VALID_ANDROID = 0,
    XR_TRACKABLE_TYPE_PLANE_ANDROID = 1,
    XR_TRACKABLE_TYPE_DEPTH_ANDROID = 1000463000,
    XR_TRACKABLE_TYPE_OBJECT_ANDROID = 1000466000
} XrTrackableTypeANDROID;

xrDestroyTrackableTrackerANDROID 函数的定义如下： 

XrResult xrDestroyTrackableTrackerANDROID(
    XrTrackableTrackerANDROID                   trackableTracker);

参数说明

xrDestroyTrackableTrackerANDROID 函数用于销毁可跟踪对象跟踪器。

如果不存在其他使用相同 XrTrackableTypeANDROID 创建的有效 XrTrackableTrackerANDROID，系统可能会停用该可跟踪对象类型所需的跟踪服务，以节省系统资源。

有效用法（隐式）

线程安全

  • 对 trackableTracker 及其任何子句柄的访问都必须在外部进行同步

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

获取所有可跟踪对象

XrTrackableANDROID 原子的定义如下：

XR_DEFINE_ATOM(XrTrackableANDROID)

XrTrackableANDROID 用于表示单个可跟踪对象，并且仅在其关联的 XrTrackableTrackerANDROID 的生命周期内有效。

xrGetAllTrackablesANDROID 函数的定义如下： 

XrResult xrGetAllTrackablesANDROID(
    XrTrackableTrackerANDROID                   trackableTracker,
    uint32_t                                    trackableCapacityInput,
    uint32_t*                                   trackableCountOutput,
    XrTrackableANDROID*                         trackables);

参数说明

  • trackableTracker 是要查询的 XrTrackableTrackerANDROID。

  • trackableCapacityInput 是 trackables 数组的容量，或设为 0 以请求获取所需的容量。

  • trackableCountOutput 是一个指针，指向写入的 trackables 数量；若 trackables 容量不足，则指向所需的容量。

  • trackables 是一个指向 XrTrackableANDROID 数组的指针。如果 trackableCapacityInput 为 0，它可以为 NULL。

  • 如需详细了解如何检索所需的 trackables 大小，请参阅缓冲区大小参数部分。

xrGetAllTrackablesANDROID 会填充一个 XrTrackableANDROID 数组，用以表示在环境中找到的可跟踪对象。返回的 trackables 的 XrTrackableTypeANDROID 必须与 trackableTracker 的 XrTrackableTypeANDROID 匹配。

获取可跟踪平面

xrGetTrackablePlaneANDROID 函数的定义如下：

XrResult xrGetTrackablePlaneANDROID(
    XrTrackableTrackerANDROID                   trackableTracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackablePlaneANDROID*                    planeOutput);

参数说明

xrGetTrackablePlaneANDROID 函数会返回有关可跟踪平面的详细信息，例如其几何形状、朝向和跟踪状态。

平面信息会在调用 xrGetTrackablePlaneANDROID 时，使用 XrTrackableGetInfoANDROID::time、XrTrackableGetInfoANDROID::baseSpace 进行解析，并且是相对于基准空间的。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_TIME_INVALID

XrTrackableGetInfoANDROID 结构的定义如下： 

typedef struct XrTrackableGetInfoANDROID {
    XrStructureType       type;
    void*                 next;
    XrTrackableANDROID    trackable;
    XrSpace               baseSpace;
    XrTime                time;
} XrTrackableGetInfoANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • trackable 是要查询的 XrTrackableANDROID 平面。
  • baseSpace 平面姿态相对于 time 时刻的此 XrSpace。
  • time 是用于评估相对于 baseSpace 的坐标的 XrTime。

当传递给 xrGetTrackablePlaneANDROID 时，XrTrackableGetInfoANDROID 结构提供了查询选项。trackable 必须与 xrGetTrackablePlaneANDROID 中使用的 trackableTracker 相对应。

如果 trackable 的可跟踪对象类型不是 XR_TRACKABLE_TYPE_PLANE_ANDROID，函数将返回 XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID。

有效用法（隐式）

XrTrackablePlaneANDROID 结构的定义如下： 

typedef struct XrTrackablePlaneANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrPosef                   centerPose;
    XrExtent2Df               extents;
    XrPlaneTypeANDROID        planeType;
    XrPlaneLabelANDROID       planeLabel;
    XrTrackableANDROID        subsumedByPlane;
    XrTime                    lastUpdatedTime;
    uint32_t                  vertexCapacityInput;
    uint32_t*                 vertexCountOutput;
    XrVector2f*               vertices;
} XrTrackablePlaneANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • trackingState 是平面的 XrTrackingStateANDROID。
  • centerPose 是一个 XrPosef，定义了在相应的 XrTrackableGetInfoANDROID::baseSpace 参考系内平面的位置和朝向。这里的单位方向表示 +Y 轴平行于平面法线。
  • extents 是平面的 XrExtent2Df 尺寸。
  • planeType 是运行时为此平面确定的 XrPlaneTypeANDROID。
  • planeLabel 是运行时为此平面确定的 XrPlaneLabelANDROID。
  • subsumedByPlane 是包含此平面的那个平面的 XrTrackableANDROID（如果不存在，则为 XR_NULL_TRACKABLE_ANDROID）。
  • lastUpdatedTime 是平面最后一次更新的 XrTime。
  • vertexCapacityInput 是 vertices 数组的容量，或设为 0 以请求获取所需的容量。
  • vertexCountOutput 是一个指针，指向写入的 vertices 数量；若 vertices 容量不足，则指向所需的容量。
  • vertices 是指向 XrVector2f 数组的指针。如果 vertexCapacityInput 为 0，它可以为 NULL。顶点按逆时针顺序排列。多边形可以是凹形的，但不能自相交。
  • 如需详细了解如何检索所需的 vertices 大小，请参阅缓冲区大小参数部分。

有效用法（隐式）

XrTrackingStateANDROID 枚举描述了 XrTrackableANDROID 的跟踪状态。

typedef enum XrTrackingStateANDROID {
    XR_TRACKING_STATE_PAUSED_ANDROID = 0,
    XR_TRACKING_STATE_STOPPED_ANDROID = 1,
    XR_TRACKING_STATE_TRACKING_ANDROID = 2
} XrTrackingStateANDROID;

XrTrackingStateANDROID

说明

XR_TRACKING_STATE_PAUSED_ANDROID

表示对此可跟踪对象或锚点的跟踪已暂停，但未来可能会恢复。

XR_TRACKING_STATE_STOPPED_ANDROID

对此可跟踪对象的跟踪已停止，且绝不会恢复。

XR_TRACKING_STATE_TRACKING_ANDROID

系统正在跟踪此对象，并分析其当前姿态。

XrPlaneTypeANDROID 枚举是 XrTrackableANDROID 平面的类型。

typedef enum XrPlaneTypeANDROID {
    XR_PLANE_TYPE_HORIZONTAL_DOWNWARD_FACING_ANDROID = 0,
    XR_PLANE_TYPE_HORIZONTAL_UPWARD_FACING_ANDROID = 1,
    XR_PLANE_TYPE_VERTICAL_ANDROID = 2,
    XR_PLANE_TYPE_ARBITRARY_ANDROID = 3
} XrPlaneTypeANDROID;

XrPlaneLabelANDROID 枚举是 XrTrackableANDROID 平面的标签。

typedef enum XrPlaneLabelANDROID {
    XR_PLANE_LABEL_UNKNOWN_ANDROID = 0,
    XR_PLANE_LABEL_WALL_ANDROID = 1,
    XR_PLANE_LABEL_FLOOR_ANDROID = 2,
    XR_PLANE_LABEL_CEILING_ANDROID = 3,
    XR_PLANE_LABEL_TABLE_ANDROID = 4
} XrPlaneLabelANDROID;

创建锚点空间

XrResult xrCreateAnchorSpaceANDROID(
    XrSession                                   session,
    const XrAnchorSpaceCreateInfoANDROID*       createInfo,
    XrSpace*                                    anchorOutput);

参数说明

  • session 是创建该锚点空间的 XrSession。
  • createInfo 是一个指向 XrAnchorSpaceCreateInfoANDROID 结构的指针，其中包含用于创建锚点空间的参数。
  • anchorOutput 是一个指向句柄的指针，创建的 XrSpace 将通过该句柄返回。

在任何时间点，锚点的位置和方向要么同时处于被跟踪状态，要么同时处于未被跟踪状态。这意味着，当应用为 anchorOutput 调用 xrLocateSpace 或 xrLocateSpaces 时，XR_SPACE_LOCATION_POSITION_TRACKED_BIT 和 XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT 必须同时被设置或同时被清除。

应用最终必须使用 xrDestroySpace 来释放返回的 XrSpace。

  • 如果系统不支持锚点，则必须返回 XR_ERROR_FEATURE_UNSUPPORTED。
  • 如果不支持特定的锚点附着方式，则必须返回 XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_OUT_OF_MEMORY

XrAnchorSpaceCreateInfoANDROID 结构的定义如下： 

typedef struct XrAnchorSpaceCreateInfoANDROID {
    XrStructureType       type;
    void*                 next;
    XrSpace               space;
    XrTime                time;
    XrPosef               pose;
    XrTrackableANDROID    trackable;
} XrAnchorSpaceCreateInfoANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • space 是将在其上创建锚点的 XrSpace。
  • time 是锚点创建时的 XrTime。
  • pose 是锚点的 XrPosef。
  • trackable 是锚点将附着于其上的 XrTrackableANDROID。它可以是 XR_NULL_TRACKABLE_ANDROID，用以创建一个空间锚点。

有效用法（隐式）

获取所有可跟踪对象的示例代码

以下示例代码演示了如何获取给定类型的所有可跟踪对象。 

XrSession session; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized

XrTrackableTrackerCreateInfoANDROID createInfo{XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID};
createInfo.trackableType = XR_TRACKABLE_TYPE_PLANE_ANDROID;
XrTrackableTrackerANDROID planeTrackableTracker;
XrResult result = xrCreateTrackableTrackerANDROID(
  session,
  &createInfo,
  &planeTrackableTracker);
if (result != XR_SUCCESS) { /* Handle failures. */ }

uint32_t trackableCountOutput = 0;
std::vector<XrTrackableANDROID> allPlaneTrackables;

// Query the number of trackables available.
result = xrGetAllTrackablesANDROID(
  planeTrackableTracker,
  0,
  &trackableCountOutput,
  nullptr
);

if (result == XR_SUCCESS) {
  allPlaneTrackables.resize(trackableCountOutput, XR_NULL_HANDLE);

  // Fetch the actual trackable handles in the appropriately resized array.
  result = xrGetAllTrackablesANDROID(
    planeTrackableTracker,
    trackableCountOutput,
    &trackableCountOutput,
    allPlaneTrackables.data());

  if (result == XR_SUCCESS) {
    for (XrTrackableANDROID trackable : allPlaneTrackables) {
      // You now have all trackables of the specified type.
    }
  }
}

// Release trackable tracker.
result = xrDestroyTrackableTrackerANDROID(planeTrackableTracker);

获取可跟踪平面的示例代码

以下示例代码演示了如何从一个现有的 XrTrackableANDROID（通过 XR_ANDROID_raycast 的命中结果或 xrGetTrackablesANDROID 获得）来获取一个可跟踪平面。

XrTrackableTrackerANDROID planeTracker; // previously created

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetTrackablePlaneANDROID xrGetTrackablePlaneANDROID; // previously initialized

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrTrackableANDROID planeTrackable; // Acquired from a hit result or getTrackables().

XrTrackableGetInfoANDROID planeGetInfo;
planeGetInfo.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID;
planeGetInfo.next = nullptr;
planeGetInfo.trackable = planeTrackable;
planeGetInfo.space = appSpace;
planeGetInfo.time = updateTime;

XrTrackablePlaneANDROID plane = { XR_TYPE_TRACKABLE_PLANE_ANDROID };
result = xrGetTrackablePlaneANDROID(
  planeTracker,
  &planeGetInfo,
  &plane
);

if (result == XR_SUCCESS) {
  // Plane tracking state, center pose, extents, type now available in plane.
}

创建锚点空间的示例代码

以下示例代码演示了如何创建一个附着于可跟踪对象的锚点空间。

XrSession session; // Created at app startup.
XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrTrackableANDROID planeTrackable; // Acquired from a hit result or getTrackables().

// Create an anchor at (2, 2, 2) world-coordinates.
XrAnchorSpaceCreateInfoANDROID spatialAnchorCreateInfo;
spatialAnchorCreateInfo.type = XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID;
spatialAnchorCreateInfo.next = nullptr;
spatialAnchorCreateInfo.space = appSpace;
spatialAnchorCreateInfo.time = updateTime;
spatialAnchorCreateInfo.pose = { { 0, 0, 0, 1 }, { 2, 2, 2 } };

XrSpace spatialAnchor = XR_NULL_HANDLE;
XrResult result = xrCreateAnchorSpaceANDROID(
  session,
  &spatialAnchorCreateInfo,
  &spatialAnchor
);

// Create an anchor attached to a trackable.
XrTrackablePlane plane = ...;
XrAnchorSpaceCreateInfoANDROID trackableAnchorCreateInfo;
trackableAnchorCreateInfo.type = XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID;
trackableAnchorCreateInfo.next = nullptr;
trackableAnchorCreateInfo.space = appState;
trackableAnchorCreateInfo.pose = plane.centerPose;
trackableAnchorCreateInfo.trackable = planeTrackable;

XrSpace trackableAnchor = XR_NULL_HANDLE;
XrResult result = xrCreateAnchorSpaceANDROID(
  session,
  &trackableAnchorCreateInfo,
  &trackableAnchor
);
while (true) {
  // app update loop
  // ...

  // Get the current location of the anchor's space w.r.t the world.
  XrSpaceLocation anchorLocation = { XR_TYPE_SPACE_LOCATION };
  result = xrLocateSpace(trackableAnchor, appSpace, updateTime, &anchorLocation);

  if (anchor.trackingState == XR_TRACKING_STATE_TRACKING_ANDROID) {
    // Update anchor pose.
    doDrawingForAnchor(anchorLocation.pose);
  } else {
    // ...
  }
}

// Cleanup - destroy the space, detatch the anchor so its no longer tracked by the
// runtime and then release all resources held by it.
xrDestroySpace(spatialAnchor);
xrDestroySpace(trackableAnchor);

新的基础类型

新的对象类型

新的枚举常量

XrStructureType 枚举新增了：

  • XR_TYPE_TRACKABLE_GET_INFO_ANDROID
  • XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID
  • XR_TYPE_TRACKABLE_PLANE_ANDROID
  • XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID

XrObjectType 枚举新增了：

  • XR_OBJECT_TYPE_TRACKABLE_TRACKER_ANDROID

XrResult 枚举新增了：

  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID

新枚举

新结构

新函数

问题

版本历史记录

  • 修订版本 1，2024 年 9 月 27 日 (Kenny Vercaemer)
    • 初始扩展程序说明。

OpenXR™ 和 OpenXR 徽标是 Khronos Group Inc. 拥有的商标，已在中国、欧盟、日本和英国注册为商标。