XR_ANDROID_trackables_object OpenXR 扩展程序

名称字符串

XR_ANDROID_trackables_object

扩展程序类型

实例扩展程序

已注册的扩展程序编号

467

修订版本

1

扩展程序和版本依赖项

XR_ANDROID_trackables

最后修改日期

2024-10-03

IP 状态

无已知 IP 声明。

贡献者

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

概览

此扩展程序支持物理对象追踪。例如，环境中的键盘、鼠标及其他对象。

追踪对象

此扩展程序会将 XR_TRACKABLE_TYPE_OBJECT_ANDROID 添加到 XrTrackableTypeANDROID。

应用可以通过调用 xrCreateTrackableTrackerANDROID 并将 XR_TRACKABLE_TYPE_OBJECT_ANDROID 指定为 XrTrackableTrackerCreateInfoANDROID::trackableType 中的可追踪类型来创建 XrTrackableTrackerANDROID，以追踪对象。

获取可追踪对象

xrGetTrackableObjectANDROID 函数的定义如下：

XrResult xrGetTrackableObjectANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableObjectANDROID*                   objectOutput);

参数说明

如果 XrTrackableANDROID 的可追踪类型不是 XR_TRACKABLE_TYPE_OBJECT_ANDROID，或者 XrTrackableTrackerANDROID 的可追踪类型不是 XR_TRACKABLE_TYPE_OBJECT_ANDROID，则将返回 XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID。

有效用法（隐式）

返回代码

成功

  • 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_SESSION_NOT_RUNNING
  • XR_ERROR_TIME_INVALID

XrTrackableObjectANDROID 结构体的定义如下：

typedef struct XrTrackableObjectANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrPosef                   centerPose;
    XrExtent3DfEXT            extents;
    XrObjectLabelANDROID      objectLabel;
    XrTime                    lastUpdatedTime;
} XrTrackableObjectANDROID;

成员说明

有效用法（隐式）

XrObjectLabelANDROID 枚举是 XrTrackableANDROID 对象的标签。

typedef enum XrObjectLabelANDROID {
    XR_OBJECT_LABEL_UNKNOWN_ANDROID = 0,
    XR_OBJECT_LABEL_KEYBOARD_ANDROID = 1,
    XR_OBJECT_LABEL_MOUSE_ANDROID = 2,
    XR_OBJECT_LABEL_LAPTOP_ANDROID = 3,
    XR_OBJECT_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrObjectLabelANDROID;

获取可追踪对象的示例代码

以下示例代码演示了如何获取可追踪对象。

XrSession session; // previously initialized

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

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.

XrTrackableTrackerCreateInfoANDROID
  createInfo{XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID};
createInfo.trackableType = XR_TRACKABLE_TYPE_OBJECT_ANDROID;
XrTrackableTracker objectTrackableTracker;
XrResult result = xrCreateTrackableTrackerANDROID(
  session,
  &createInfo,
  &objectrackableTracker);
if (result != XR_SUCCESS) { /* Handle failures. */ }

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

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

if (result == XR_SUCCESS) {
  allObjectTrackables.resize(trackableCountOutput, XR_NULL_TRACKABLE_ANDROID);

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

  if (result == XR_SUCCESS) {
    for (XrTrackableANDROID trackable : allObjectTrackables) {

      // Object trackable query information
      XrTrackableGetInfoANDROID objectGetInfo;
      objectGetInfo.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID;
      objectGetInfo.next = nullptr;
      objectGetInfo.trackable = trackable;
      objectGetInfo.space = appSpace;
      objectGetInfo.time = updateTime;

      // Get the object trackable. Note that the tracker only returns object types.
      XrTrackableObjectANDROID object = { XR_TYPE_TRACKABLE_OBJECT_ANDROID };
      result = xrGetTrackableObjectANDROID(
        objectTrackableTracker,
        &objectGetInfo,
        &object
      );

      if (result == XR_SUCCESS) {
        /** Do Stuff with the object */
      }
    }
  }
}

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

新的枚举常量

XrStructureType 枚举已扩展为

  • XR_TYPE_TRACKABLE_OBJECT_ANDROID
  • XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

XrTrackableTypeANDROID 枚举已扩展为

  • XR_TRACKABLE_TYPE_OBJECT_ANDROID

新枚举

新结构体

新函数

问题

版本历史

  • 修订版 1，2024-10-03 (Kenny Vercaemer)
    • 初始扩展程序说明。

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