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. 拥有的商标，已在中国、欧盟、日本和英国注册为商标。