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 函数会返回与可跟踪平面相关的详细信息，例如其几何图形、方向和跟踪状态。

使用 XrTrackableGetInfoANDROID::time、XrTrackableGetInfoANDROID::baseSpace 解析平面信息，并将其相对于调用 xrGetTrackablePlaneANDROID 时的基准空间。

有效用法（隐式）

返回代码

成功

  • 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);

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

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

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)
    • 初始扩展程序说明。