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。

当传递给 xrCreateTrackableTrackerANDROID 时，XrTrackableTrackerCreateInfoANDROID 结构提供了 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。

XrTrackableGetInfoANDROID 结构在传递给 xrGetTrackablePlaneANDROID 时提供了查询选项。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-09-27 (Kenny Vercaemer)
    • 初始扩展描述。

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