Tiện ích OpenXR XR_ANDROID_trackables

Chuỗi tên

XR_ANDROID_trackables_object

Loại phần mở rộng

Tiện ích thực thể

Số điện thoại mở rộng đã đăng ký

467

Bản sửa đổi

1

Phần mở rộng và phần phụ thuộc phiên bản

XR_ANDROID_trackables

Ngày sửa đổi gần đây nhất

2024-10-03

Trạng thái IP

Không có thông báo xác nhận quyền sở hữu đối với tài sản trí tuệ nào.

Cộng tác viên

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Tổng quan

Tiện ích này cho phép theo dõi đối tượng thực. Ví dụ: bàn phím, chuột và các đối tượng khác trong môi trường.

Theo dõi đối tượng

Tiện ích này thêm XR_TRACKABLE_TYPE_OBJECT_ANDROID vào XrTrackableTypeANDROID.

Ứng dụng có thể tạo một XrTrackableTrackerANDROID bằng cách gọi xrCreateTrackableTrackerANDROID và chỉ định XR_TRACKABLE_TYPE_OBJECT_ANDROID làm loại có thể theo dõi trong XrTrackableTrackerCreateInfoANDROID::trackableType để theo dõi các đối tượng.

Lấy đối tượng có thể theo dõi

Hàm xrGetTrackableObjectANDROID được xác định là:

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

Nội dung mô tả tham số

XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID sẽ được trả về nếu loại có thể theo dõi của XrTrackableANDROID không phải là XR_TRACKABLE_TYPE_OBJECT_ANDROID hoặc nếu loại có thể theo dõi của XrTrackableTrackerANDROID không phải là XR_TRACKABLE_TYPE_OBJECT_ANDROID.

Cách sử dụng hợp lệ (ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
    • XR_SESSION_LOSS_PENDING

Không thành công

  • 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

Cấu trúc XrTrackableObjectANDROID được xác định là: 

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
    • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
    • trackingState là XrTrackingStateANDROID của đối tượng.
    • centerPose là XrPosef của đối tượng nằm trong XrTrackableGetInfoANDROID::baseSpace.
    • extents là phương diện XrExtent3DfEXT của đối tượng.
    • objectLabel là XrObjectLabelANDROID mà thời gian chạy đã xác định cho đối tượng này.
    • lastUpdatedTime là XrTime của lần cập nhật gần đây nhất của đối tượng.

Cách sử dụng hợp lệ (ngầm ẩn)

Enum XrObjectLabelANDROID là nhãn cho đối tượng 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;

Mã ví dụ để lấy các đối tượng có thể theo dõi

Mã ví dụ sau đây minh hoạ cách lấy các đối tượng có thể theo dõi.

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

Hằng số enum mới

Bổ sung enum XrStructureType:

  • XR_TYPE_TRACKABLE_OBJECT_ANDROID
  • XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

Bổ sung enum XrTrackableTypeANDROID:

  • XR_TRACKABLE_TYPE_OBJECT_ANDROID

Enum mới

Cấu trúc mới

Hàm mới

Vấn đề

Nhật ký phiên bản

  • Bản sửa đổi 1, ngày 3 tháng 10 năm 2024 (Kenny Vercaemer)
    • Mô tả ban đầu về tiện ích.