XR_ANDROID_trackables_object OpenXR 扩展

名称字符串

XR_ANDROID_trackables_object

扩展程序类型

实例扩展

已注册的扩展号码

467

修订版本

1

扩展程序和版本依赖项

XR_ANDROID_trackables

上次修改日期

2024-11-01

IP 状态

没有已知的 IP 版权主张。

创作贡献者

Diego Tipaldi，Google

David Joseph Tan，Google

Christopher Doer，Google

Spencer Quin，Google

Jared Finder，Google

Levana Chen，Google

Kenny Vercaemer，Google

概览

此扩展程序支持实体对象跟踪。例如，键盘、鼠标和环境中的其他物品。

跟踪对象

此扩展程序会向 XrTrackableTypeANDROID 添加 XR_TRACKABLE_TYPE_OBJECT_ANDROID。

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

XrTrackableObjectConfigurationANDROID 结构的定义如下： 

typedef struct XrTrackableObjectConfigurationANDROID {  XrStructureType type;  void* next;  uint32_t labelCount;  const XrObjectLabelANDROID* activeLabels; } XrTrackableObjectConfigurationANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展中未定义任何此类结构。
  • labelCount 是 activeLabels 的计数。
  • activeLabels 是指向 XRObjectLabelANDROID 数组的指针，用于指示跟踪中的有效对象。

应用可以通过将 XrTrackableObjectConfigurationANDROID 添加到 XrTrackableTrackerCreateInfoANDROID 的下一个链中来设置其他配置。xrGetAllTrackablesANDROID 的输出将被过滤以匹配 activeLabels。

如果应用未设置 XrTrackableObjectConfigurationANDROID，则系统会跟踪其识别到的所有对象。

有效使用（隐式）

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;

获取可跟踪对象

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
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID

XrTrackableObjectANDROID 结构的定义如下： 

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

成员说明

有效使用（隐式）

用于获取可跟踪对象的示例代码

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

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; XrTrackableTrackerANDROID objectTrackableTracker; XrResult result = xrCreateTrackableTrackerANDROID(  session,  &createInfo,  &objectTrackableTracker); 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.baseSpace = 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 月 3 日 (Kenny Vercaemer)
    • 初始扩展程序说明。

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