Tiện ích OpenXR XR_ANDROID_trackables_object

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-11-01

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

Diego Tipaldi, Google

David Joseph Tan, Google

Christopher Doer, Google

Spencer Quin, 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.

Thận trọng:

Quyền

Ứng dụng Android phải có quyền android.permission.SCENE_UNDERSTANDING_COARSE được liệt kê trong tệp kê khai vì tiện ích này phụ thuộc vào XR_ANDROID_trackables và hiển thị hình học của môi trường. Quyền android.permission.SCENE_UNDERSTANDING_COARSE được coi là một quyền nguy hiểm.
(cấp độ bảo vệ: nguy hiểm)

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 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.

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

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

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.
• labelCount là số lượng activeLabels.
• activeLabels là con trỏ trỏ đến mảng XRObjectLabelANDROID cho biết các đối tượng đang hoạt động trong quá trình theo dõi.

Ứng dụng có thể thiết lập một cấu hình bổ sung bằng cách thêm XrTrackableObjectConfigurationANDROID vào chuỗi tiếp theo của XrTrackableTrackerCreateInfoANDROID. Kết quả từ xrGetAllTrackablesANDROID sẽ được lọc để khớp với activeLabels.

Nếu ứng dụng không đặt XrTrackableObjectConfigurationANDROID, thì tất cả các đối tượng mà hệ thống đã xác định sẽ được theo dõi.

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

• Bạn phải bật tiện ích XR_ANDROID_trackables_object trước khi sử dụng XrTrackableObjectANDROID
• type phải là XR_TYPE_TRACKABLE_OBJECT_ANDROID
• next phải là NULL hoặc con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• activeLabels phải là con trỏ đến một mảng các giá trị XrObjectLabelANDROID labelCount hợp lệ
• Tham số labelCount phải lớn hơn 0

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;

Nhận đố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ố

• tracker là XrTrackableTrackerANDROID để truy vấn.
• getInfo là XrTrackableGetInfoANDROID có thông tin dùng để lấy đối tượng có thể theo dõi.
• objectOutput là con trỏ đến cấu trúc XrTrackableObjectANDROID trong đó đối tượng có thể theo dõi được trả về.

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)

• Bạn phải bật tiện ích XR_ANDROID_trackables_object trước khi gọi xrGetTrackableObjectANDROID
• tracker phải là tên người dùng XrTrackableTrackerANDROID hợp lệ
• getInfo phải là con trỏ đến một cấu trúc XrTrackableGetInfoANDROID hợp lệ
• objectOutput phải là con trỏ đến cấu trúc XrTrackableObjectANDROID

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

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)

• Bạn phải bật tiện ích XR_ANDROID_trackables_object trước khi sử dụng XrTrackableObjectANDROID
• type phải là XR_TYPE_TRACKABLE_OBJECT_ANDROID
• next phải là NULL hoặc con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• trackingState phải là một giá trị XrTrackingStateANDROID hợp lệ
• objectLabel phải là một giá trị XrObjectLabelANDROID hợp lệ

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

Hằng số enum mới

Bổ sung enum XrStructureType bằng:

• XR_TYPE_TRACKABLE_OBJECT_ANDROID
• XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

Bổ sung enum XrTrackableTypeANDROID bằng:

• XR_TRACKABLE_TYPE_OBJECT_ANDROID

Enum mới

• XrObjectLabelANDROID

Cấu trúc mới

• XrTrackableObjectANDROID
• XrTrackableObjectConfigurationANDROID

Hàm mới

• xrGetTrackableObjectANDROID

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)
  • Nội dung mô tả ban đầu của tiện ích.

---

OpenXR™ và biểu trưng OpenXR là các nhãn hiệu thuộc sở hữu của The Khronos Group Inc. và được đăng ký dưới dạng nhãn hiệu ở Trung Quốc, Liên minh Châu Âu, Nhật Bản và Vương quốc Anh.