ส่วนขยาย 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

ภาพรวม

ส่วนขยายนี้เปิดใช้การติดตามวัตถุจริง เช่น แป้นพิมพ์ เมาส์ และวัตถุอื่นๆ ในสภาพแวดล้อม

ติดตามวัตถุ

ส่วนขยายนี้จะเพิ่ม XR_TRACKABLE_TYPE_OBJECT_ANDROID ลงใน XrTrackableTypeANDROID

แอปพลิเคชันอาจสร้าง XrTrackableTrackerANDROID โดยการเรียกใช้ xrCreateTrackableTrackerANDROID และระบุ XR_TRACKABLE_TYPE_OBJECT_ANDROID เป็นประเภทที่ติดตามได้ใน XrTrackableTrackerCreateInfoANDROID::trackableType เพื่อติดตามวัตถุ

โครงสร้าง 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 ระบบจะติดตามวัตถุทั้งหมดที่ระบุ

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables_object ก่อนใช้ XrTrackableObjectANDROID
• type ต้องเป็น XR_TYPE_TRACKABLE_OBJECT_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• activeLabels ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า labelCount ที่ถูกต้อง XrObjectLabelANDROID
• พารามิเตอร์ labelCount ต้องมากกว่า 0

นิพจน์ 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);

คําอธิบายพารามิเตอร์

• tracker คือ XrTrackableTrackerANDROID ที่จะค้นหา
• getInfo คือ XrTrackableGetInfoANDROID ที่มีข้อมูลที่ใช้เพื่อรับออบเจ็กต์ที่ติดตามได้
• objectOutput คือพอยน์เตอร์ไปยังโครงสร้าง XrTrackableObjectANDROID ซึ่งจะแสดงผลออบเจ็กต์ที่ติดตามได้

ระบบจะแสดงผล XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID หากประเภทที่ติดตามได้ของ XrTrackableANDROID ไม่ใช่ XR_TRACKABLE_TYPE_OBJECT_ANDROID หรือหากประเภทที่ติดตามได้ของ XrTrackableTrackerANDROID ไม่ใช่ XR_TRACKABLE_TYPE_OBJECT_ANDROID

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables_object ก่อนโทรหา xrGetTrackableObjectANDROID
• tracker ต้องเป็นแฮนเดิล XrTrackableTrackerANDROID ที่ถูกต้อง
• getInfo ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrTrackableGetInfoANDROID ที่ถูกต้อง
• objectOutput ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrTrackableObjectANDROID

รหัสการคืนสินค้า

สำเร็จ

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

คำอธิบายสมาชิก

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• trackingState คือ XrTrackingStateANDROID ของออบเจ็กต์
• centerPose คือ XrPosef ของออบเจ็กต์ที่อยู่ใน XrTrackableGetInfoANDROID::baseSpace
• extents คือมิติข้อมูล XrExtent3DfEXT ของออบเจ็กต์
• objectLabel คือ XrObjectLabelANDROID ที่รันไทม์กำหนดไว้สำหรับออบเจ็กต์นี้
• lastUpdatedTime คือ XrTime ของการอัปเดตล่าสุดของออบเจ็กต์

การใช้งานที่ถูกต้อง (โดยนัย)

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables_object ก่อนใช้ XrTrackableObjectANDROID
• type ต้องเป็น XR_TYPE_TRACKABLE_OBJECT_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• trackingState ต้องเป็นค่า XrTrackingStateANDROID ที่ถูกต้อง
• objectLabel ต้องเป็นค่า 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;
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);

ค่าคงที่ Enum ใหม่

เพิ่มการแจกแจง XrStructureType ดังนี้

• XR_TYPE_TRACKABLE_OBJECT_ANDROID
• XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

การแจกแจงค่า XrTrackableTypeANDROID ขยายให้มีรายการต่อไปนี้

• XR_TRACKABLE_TYPE_OBJECT_ANDROID

Enum ใหม่

• XrObjectLabelANDROID

โครงสร้างใหม่

• XrTrackableObjectANDROID
• XrTrackableObjectConfigurationANDROID

ฟังก์ชันใหม่

• xrGetTrackableObjectANDROID

ปัญหา

ประวัติเวอร์ชัน

• การแก้ไข 1, 2024-10-03 (Kenny Vercaemer)
  • คำอธิบายส่วนขยายเริ่มต้น

OpenXR™ และโลโก้ OpenXR เป็นเครื่องหมายการค้าของ The Khronos Group Inc. และจดทะเบียนเป็นเครื่องหมายการค้าในจีน สหภาพยุโรป ญี่ปุ่น และสหราชอาณาจักร