ส่วนขยาย XR_ANDROID_trackables OpenXR

สตริงชื่อ

XR_ANDROID_trackables

ประเภทชิ้นงาน

การขยายอินสแตนซ์

หมายเลขต่อที่จดทะเบียน

456

การแก้ไข

1

การพึ่งพาส่วนขยายและเวอร์ชัน

OpenXR 1.0

วันที่แก้ไขล่าสุด

2024-09-30

สถานะ IP

ไม่มีการอ้างสิทธิ์ IP ที่ทราบ

ผู้เขียน

Spencer Quin จาก Google

Nihav Jain จาก Google

John Pursey จาก Google

Jared Finder จาก Google

Levana Chen จาก Google

Kenny Vercaemer จาก Google

ภาพรวม

ส่วนขยายนี้ช่วยให้แอปพลิเคชันเข้าถึงอุปกรณ์ติดตามได้จากสภาพแวดล้อมจริง และสร้างหมุดยึดที่แนบอยู่กับอุปกรณ์ติดตาม

ส่วนขยายนี้จะกำหนดสิ่งที่ติดตามได้ในเครื่องบิน ส่วนขยายอื่นๆ อาจเพิ่มประเภทที่ติดตามได้เพิ่มเติม เช่น XR_ANDROID_trackables_object จะเพิ่มออบเจ็กต์ที่ติดตามได้ และ XR_ANDROID_depth_texture จะเพิ่มบัฟเฟอร์ความลึกที่อนุญาตให้เรย์แคสต์ไปยังจุดใดก็ได้ในสภาพแวดล้อม

รายการที่ติดตามได้คือสิ่งที่ติดตามได้ในสภาพแวดล้อมจริง (ดูXrTrackableTypeANDROID)

• พื้นผิว (เช่น ผนัง พื้น เพดาน โต๊ะ)
• วัตถุ (เช่น แป้นพิมพ์ เมาส์ แล็ปท็อป)

สร้างเครื่องมือติดตามที่ติดตามได้

XrTrackableTrackerANDROID คือแฮนเดิลที่แสดงทรัพยากรที่จําเป็นในการค้นพบและอัปเดตรายการติดตามของ XrTrackableTypeANDROID หนึ่งๆ ในสภาพแวดล้อม

XR_DEFINE_HANDLE(XrTrackableTrackerANDROID)

ฟังก์ชัน xrCreateTrackableTrackerANDROID มีคำจำกัดความดังนี้

XrResult xrCreateTrackableTrackerANDROID(
    XrSession                                   session,
    const XrTrackableTrackerCreateInfoANDROID*  createInfo,
    XrTrackableTrackerANDROID*                  trackableTracker);

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

• session คือ XrSession ที่สร้างอุปกรณ์ติดตาม
• createInfo เป็นพอยน์เตอร์ไปยังโครงสร้าง XrTrackableTrackerCreateInfoANDROID ที่มีพารามิเตอร์ที่จะใช้สร้างเครื่องมือติดตาม
• trackableTracker คือพอยน์เตอร์ไปยังแฮนเดิลที่ระบบจะแสดงXrTrackableTrackerANDROID ที่สร้างขึ้น

แอปพลิเคชันสามารถใช้ฟังก์ชัน xrCreateTrackableTrackerANDROID เพื่อสร้างอุปกรณ์ติดตาม

• ระบบจะแสดงXR_ERROR_FEATURE_UNSUPPORTEDหากไม่รองรับรายการติดตามประเภทที่ระบุ
• ระบบจะแสดง XR_ERROR_PERMISSION_INSUFFICIENT หากแอปที่เรียกใช้ไม่ได้รับสิทธิ์ที่จําเป็น

แอปพลิเคชันสามารถใช้แฮนเดิลเครื่องมือติดตามที่แสดงในการเรียก API ครั้งต่อๆ ไปได้ ต้องยกเลิกการจองตัวแฮนเดิล XrTrackableTrackerANDROID โดยใช้ฟังก์ชัน xrDestroyTrackableTrackerANDROID

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables ก่อนเรียกใช้ xrCreateTrackableTrackerANDROID
• session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
• createInfo ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrTrackableTrackerCreateInfoANDROID ที่ถูกต้อง
• trackableTracker ต้องเป็นพอยน์เตอร์ไปยังตัวแฮนเดิล XrTrackableTrackerANDROID

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

สำเร็จ

• 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_OUT_OF_MEMORY
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_FEATURE_UNSUPPORTED

โครงสร้าง XrTrackableTrackerCreateInfoANDROID ได้รับการกําหนดดังนี้

typedef struct XrTrackableTrackerCreateInfoANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackableTypeANDROID    trackableType;
} XrTrackableTrackerCreateInfoANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• trackableType คือ XrTrackableTypeANDROID ที่จะติดตาม

โครงสร้าง XrTrackableTrackerCreateInfoANDROID มีตัวเลือกการสร้างสำหรับ XrTrackableTrackerANDROID เมื่อส่งไปยัง xrCreateTrackableTrackerANDROID

ส่วนขยายอาจกําหนดโครงสร้างที่แนบกับ next ได้เพื่ออนุญาตการกําหนดค่าเพิ่มเติมสําหรับเครื่องมือติดตามที่ติดตามได้

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables ก่อนใช้ XrTrackableTrackerCreateInfoANDROID
• type ต้องเป็น XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง ดูข้อมูลเพิ่มเติมได้ที่ XrTrackableObjectConfigurationANDROID
• trackableType ต้องเป็นค่า XrTrackableTypeANDROID ที่ถูกต้อง

นิพจน์ XrTrackableTypeANDROID มีคำจำกัดความดังนี้

typedef enum XrTrackableTypeANDROID {
    XR_TRACKABLE_TYPE_NOT_VALID_ANDROID = 0,
    XR_TRACKABLE_TYPE_PLANE_ANDROID = 1,
    XR_TRACKABLE_TYPE_DEPTH_ANDROID = 1000463000,
    XR_TRACKABLE_TYPE_OBJECT_ANDROID = 1000466000
} XrTrackableTypeANDROID;

ฟังก์ชัน xrDestroyTrackableTrackerANDROID มีคำจำกัดความดังนี้

XrResult xrDestroyTrackableTrackerANDROID(
    XrTrackableTrackerANDROID                   trackableTracker);

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

• trackableTracker คือแฮนเดิล XrTrackableTrackerANDROID ที่สร้างขึ้นก่อนหน้านี้โดย xrCreateTrackableTrackerANDROID

ฟังก์ชัน xrDestroyTrackableTrackerANDROID จะทำลายอุปกรณ์ติดตามที่ติดตามได้

หากไม่มี XrTrackableTrackerANDROID อื่นที่ถูกต้องซึ่งสร้างขึ้นด้วย XrTrackableTypeANDROID เดียวกัน ระบบอาจปิดใช้บริการติดตามที่จําเป็นสําหรับประเภทที่ติดตามได้นั้นเพื่อประหยัดทรัพยากรของระบบ

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables ก่อนเรียกใช้ xrDestroyTrackableTrackerANDROID
• trackableTracker ต้องเป็นแฮนเดิล XrTrackableTrackerANDROID ที่ถูกต้อง

ความปลอดภัยของชุดข้อความ

• การเข้าถึง trackableTracker และตัวแฮนเดิลย่อยต้องได้รับการซิงค์จากภายนอก

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

สำเร็จ

• XR_SUCCESS

ไม่สำเร็จ

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

รับอุปกรณ์ติดตามทั้งหมด

อะตอม XrTrackableANDROID หมายถึง

XR_DEFINE_ATOM(XrTrackableANDROID)

XrTrackableANDROID ใช้เพื่อแสดงรายการที่ติดตามได้รายการเดียว และใช้ได้เฉพาะในวงจรของ XrTrackableTrackerANDROID ที่เชื่อมโยง

ฟังก์ชัน xrGetAllTrackablesANDROID มีคำจำกัดความดังนี้

XrResult xrGetAllTrackablesANDROID(
    XrTrackableTrackerANDROID                   trackableTracker,
    uint32_t                                    trackableCapacityInput,
    uint32_t*                                   trackableCountOutput,
    XrTrackableANDROID*                         trackables);

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

• trackableTracker คือ XrTrackableTrackerANDROID ที่จะค้นหา

• trackableCapacityInput คือความจุของอาร์เรย์ trackables หรือ 0 เพื่อบ่งบอกคําขอดึงข้อมูลความจุที่จําเป็น

• trackableCountOutput คือพอยน์เตอร์ไปยังจํานวน trackables ที่เขียน หรือพอยน์เตอร์ไปยังความจุที่จําเป็นในกรณีที่ trackables ไม่เพียงพอ

• trackables เป็นพอยน์เตอร์ไปยังอาร์เรย์ของ XrTrackableANDROID สามารถเป็น NULL ได้หาก trackableCapacityInput เป็น 0

• ดูรายละเอียดเกี่ยวกับการดึงข้อมูลtrackablesขนาดที่ต้องการได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

xrGetAllTrackablesANDROID จะเติมอาร์เรย์ XrTrackableANDROID ที่แสดงถึงรายการติดตามที่พบในสภาพแวดล้อม XrTrackableTypeANDROID ของ trackables ที่แสดงผลต้องตรงกับ XrTrackableTypeANDROID ของ trackableTracker

ดูเครื่องบินที่ติดตามได้

ฟังก์ชัน xrGetTrackablePlaneANDROID มีคำจำกัดความดังนี้

XrResult xrGetTrackablePlaneANDROID(
    XrTrackableTrackerANDROID                   trackableTracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackablePlaneANDROID*                    planeOutput);

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

• trackableTracker คือ XrTrackableTrackerANDROID ที่จะค้นหา

• getInfo คือ XrTrackableGetInfoANDROID ที่มีข้อมูลที่ใช้เพื่อรับเครื่องบินที่ติดตามได้

• planeOutput คือพอยน์เตอร์ไปยังโครงสร้าง XrTrackablePlaneANDROID ที่แสดงผลเครื่องบินที่ติดตามได้

ฟังก์ชัน xrGetTrackablePlaneANDROID จะแสดงรายละเอียดเกี่ยวกับเครื่องบินที่ติดตามได้ เช่น เรขาคณิต การวางแนว และสถานะการติดตาม

ระบบจะแก้ไขข้อมูลระนาบให้สัมพันธ์กับพื้นที่ฐาน ณ เวลาที่มีการเรียกใช้ xrGetTrackablePlaneANDROID โดยใช้ XrTrackableGetInfoANDROID::time, XrTrackableGetInfoANDROID::baseSpace

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables ก่อนเรียกใช้ xrGetTrackablePlaneANDROID
• trackableTracker ต้องเป็นแฮนเดิล XrTrackableTrackerANDROID ที่ถูกต้อง
• getInfo ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrTrackableGetInfoANDROID ที่ถูกต้อง
• planeOutput ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrTrackablePlaneANDROID

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

สำเร็จ

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

โครงสร้าง XrTrackableGetInfoANDROID ได้รับการกําหนดดังนี้

typedef struct XrTrackableGetInfoANDROID {
    XrStructureType       type;
    void*                 next;
    XrTrackableANDROID    trackable;
    XrSpace               baseSpace;
    XrTime                time;
} XrTrackableGetInfoANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• trackable คือเครื่องบิน XrTrackableANDROID ที่จะค้นหา
• baseSpace การวางแนวของเครื่องบินจะสัมพันธ์กับ XrSpace นี้ ที่ time
• time คือ XrTime ที่จะใช้ประเมินพิกัดซึ่งสัมพันธ์กับ baseSpace

โครงสร้าง XrTrackableGetInfoANDROID มีตัวเลือกการค้นหาเมื่อส่งไปยัง xrGetTrackablePlaneANDROID trackable ต้องสอดคล้องกับ trackableTracker ที่ใช้ใน xrGetTrackablePlaneANDROID

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

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables ก่อนใช้ XrTrackableGetInfoANDROID
• type ต้องเป็น XR_TYPE_TRACKABLE_GET_INFO_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• baseSpace ต้องเป็นแฮนเดิล XrSpace ที่ถูกต้อง

โครงสร้าง XrTrackablePlaneANDROID มีคำจำกัดความดังนี้

typedef struct XrTrackablePlaneANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrPosef                   centerPose;
    XrExtent2Df               extents;
    XrPlaneTypeANDROID        planeType;
    XrPlaneLabelANDROID       planeLabel;
    XrTrackableANDROID        subsumedByPlane;
    XrTime                    lastUpdatedTime;
    uint32_t                  vertexCapacityInput;
    uint32_t*                 vertexCountOutput;
    XrVector2f*               vertices;
} XrTrackablePlaneANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• trackingState คือ XrTrackingStateANDROID ของเครื่องบิน
• centerPose คือ XrPosef ที่กําหนดตําแหน่งและการวางแนวของระนาบภายในเฟรมอ้างอิงของ XrTrackableGetInfoANDROID::baseSpace ที่เกี่ยวข้อง การวางแนวแบบไม่ระบุค่านี้แสดงแกนพิกัดที่มี +Y ขนานกับเส้นตั้งฉากของระนาบ
• extents คือมิติข้อมูล XrExtent2Df ของเครื่องบิน
• planeType คือ XrPlaneTypeANDROID ที่รันไทม์กำหนดไว้สำหรับเครื่องบินนี้
• planeLabel คือ XrPlaneLabelANDROID ที่รันไทม์กำหนดไว้สำหรับเครื่องบินนี้
• subsumedByPlane คือ XrTrackableANDROID ของระนาบที่รวมระนาบนี้ไว้ (XR_NULL_TRACKABLE_ANDROID หากไม่มี)
• lastUpdatedTime คือ XrTime ของการอัปเดตครั้งล่าสุดของแพลตฟอร์ม
• vertexCapacityInput คือความจุของอาร์เรย์ vertices หรือ 0 เพื่อบ่งบอกคําขอดึงข้อมูลความจุที่จําเป็น
• vertexCountOutput คือพอยน์เตอร์ไปยังจํานวน vertices ที่เขียน หรือพอยน์เตอร์ไปยังความจุที่จําเป็นในกรณีที่ vertices ไม่เพียงพอ
• vertices คือพอยน์เตอร์ไปยังอาร์เรย์ XrVector2f NULLได้หาก vertexCapacityInput เป็น 0 เวิร์กเทอร์ซิสจะเรียงตามลำดับทวนเข็มนาฬิกา รูปหลายเหลี่ยมอาจเว้าและต้องไม่ตัดกันเอง
• ดูรายละเอียดเกี่ยวกับการดึงข้อมูลverticesขนาดที่ต้องการได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables ก่อนใช้ XrTrackablePlaneANDROID
• type ต้องเป็น XR_TYPE_TRACKABLE_PLANE_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• trackingState ต้องเป็นค่า XrTrackingStateANDROID ที่ถูกต้อง
• planeType ต้องเป็นค่า XrPlaneTypeANDROID ที่ถูกต้อง
• planeLabel ต้องเป็นค่า XrPlaneLabelANDROID ที่ถูกต้อง
• vertexCountOutput ต้องเป็นพอยน์เตอร์ไปยังค่า uint32_t
• vertices ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของโครงสร้าง vertexCapacityInput XrVector2f
• พารามิเตอร์ vertexCapacityInput ต้องมากกว่า 0

อาร์เรย์ XrTrackingStateANDROID อธิบายสถานะการติดตามของ XrTrackableANDROID

typedef enum XrTrackingStateANDROID {
    XR_TRACKING_STATE_PAUSED_ANDROID = 0,
    XR_TRACKING_STATE_STOPPED_ANDROID = 1,
    XR_TRACKING_STATE_TRACKING_ANDROID = 2
} XrTrackingStateANDROID;

อาร์เรย์ XrPlaneTypeANDROID คือประเภทของเครื่องบิน XrTrackableANDROID

typedef enum XrPlaneTypeANDROID {
    XR_PLANE_TYPE_HORIZONTAL_DOWNWARD_FACING_ANDROID = 0,
    XR_PLANE_TYPE_HORIZONTAL_UPWARD_FACING_ANDROID = 1,
    XR_PLANE_TYPE_VERTICAL_ANDROID = 2,
    XR_PLANE_TYPE_ARBITRARY_ANDROID = 3
} XrPlaneTypeANDROID;

อาร์ติแฟกต์ XrPlaneLabelANDROID คือป้ายกำกับสำหรับเครื่องบิน XrTrackableANDROID

typedef enum XrPlaneLabelANDROID {
    XR_PLANE_LABEL_UNKNOWN_ANDROID = 0,
    XR_PLANE_LABEL_WALL_ANDROID = 1,
    XR_PLANE_LABEL_FLOOR_ANDROID = 2,
    XR_PLANE_LABEL_CEILING_ANDROID = 3,
    XR_PLANE_LABEL_TABLE_ANDROID = 4
} XrPlaneLabelANDROID;

สร้างพื้นที่ยึด

XrResult xrCreateAnchorSpaceANDROID(
    XrSession                                   session,
    const XrAnchorSpaceCreateInfoANDROID*       createInfo,
    XrSpace*                                    anchorOutput);

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

• session คือ XrSession ที่สร้างพื้นที่ยึด
• createInfo เป็นพอยน์เตอร์ไปยังโครงสร้าง XrAnchorSpaceCreateInfoANDROID ที่มีพารามิเตอร์ที่จะใช้สร้างพื้นที่ยึด
• anchorOutput คือพอยน์เตอร์ไปยังแฮนเดิลที่แสดงXrSpace ที่สร้างขึ้น

ไม่ว่าเวลาใดก็ตาม ระบบจะติดตามหรือยกเลิกการติดตามทั้งตำแหน่งและทิศทางของจุดยึด ซึ่งหมายความว่าต้องตั้งค่าทั้ง XR_SPACE_LOCATION_POSITION_TRACKED_BIT และ XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT หรือต้องล้างค่าทั้ง 2 รายการเมื่อแอปพลิเคชันเรียกใช้ xrLocateSpace หรือ xrLocateSpaces สำหรับ anchorOutput

แอปพลิเคชันต้องทำให้ XrSpace ที่แสดงผลว่างเปล่าในท้ายที่สุดโดยใช้ xrDestroySpace

• ต้องแสดงผล XR_ERROR_FEATURE_UNSUPPORTED หากระบบไม่รองรับหมุด
• XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID ต้องแสดงขึ้นหากระบบไม่รองรับไฟล์แนบของหมุด

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables ก่อนเรียกใช้ xrCreateAnchorSpaceANDROID
• session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
• createInfo ต้องเป็นพอยน์เตอร์ไปยังโครงสร้าง XrAnchorSpaceCreateInfoANDROID ที่ถูกต้อง
• anchorOutput ต้องเป็นพอยน์เตอร์ไปยังแฮนเดิล XrSpace

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

สำเร็จ

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ไม่สำเร็จ

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_POSE_INVALID
• XR_ERROR_TIME_INVALID
• XR_ERROR_OUT_OF_MEMORY

โครงสร้าง XrAnchorSpaceCreateInfoANDROID มีคำจำกัดความดังนี้

typedef struct XrAnchorSpaceCreateInfoANDROID {
    XrStructureType       type;
    void*                 next;
    XrSpace               space;
    XrTime                time;
    XrPosef               pose;
    XrTrackableANDROID    trackable;
} XrAnchorSpaceCreateInfoANDROID;

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

• type คือ XrStructureType ของโครงสร้างนี้
• next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• space คือ XrSpace ที่จะสร้างหมุดยึด
• time คือ XrTime ของการสร้างหมุด
• pose คือ XrPosef ของโฆษณา Anchor
• trackable คือ XrTrackableANDROID ที่จะใช้ยึดหมุด อาจต้องใช้เวลา XR_NULL_TRACKABLE_ANDROID ในการสร้างหมุดยึดเชิงพื้นที่

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables ก่อนใช้ XrAnchorSpaceCreateInfoANDROID
• type ต้องเป็น XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง
• space ต้องเป็นแฮนเดิล XrSpace ที่ถูกต้อง

ตัวอย่างโค้ดสําหรับรับรายการติดตามทั้งหมด

โค้ดตัวอย่างต่อไปนี้แสดงวิธีรับรายการติดตามทั้งหมดของประเภทหนึ่งๆ

XrSession session; // previously initialized

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

XrTrackableTrackerCreateInfoANDROID createInfo{XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID};
createInfo.trackableType = XR_TRACKABLE_TYPE_PLANE_ANDROID;
XrTrackableTrackerANDROID planeTrackableTracker;
XrResult result = xrCreateTrackableTrackerANDROID(
  session,
  &createInfo,
  &planeTrackableTracker);
if (result != XR_SUCCESS) { /* Handle failures. */ }

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

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

if (result == XR_SUCCESS) {
  allPlaneTrackables.resize(trackableCountOutput, XR_NULL_HANDLE);

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

  if (result == XR_SUCCESS) {
    for (XrTrackableANDROID trackable : allPlaneTrackables) {
      // You now have all trackables of the specified type.
    }
  }
}

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

ตัวอย่างโค้ดสําหรับรับเครื่องบินที่ติดตามได้

โค้ดตัวอย่างต่อไปนี้แสดงวิธีรับเครื่องบินที่ติดตามได้จาก XrTrackableANDROID ที่มีอยู่ ซึ่งได้จากผลการค้นหา XR_ANDROID_raycast หรือ xrGetTrackablesANDROID

XrTrackableTrackerANDROID planeTracker; // previously created

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetTrackablePlaneANDROID xrGetTrackablePlaneANDROID; // previously initialized

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrTrackableANDROID planeTrackable; // Acquired from a hit result or getTrackables().

XrTrackableGetInfoANDROID planeGetInfo;
planeGetInfo.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID;
planeGetInfo.next = nullptr;
planeGetInfo.trackable = planeTrackable;
planeGetInfo.space = appSpace;
planeGetInfo.time = updateTime;

XrTrackablePlaneANDROID plane = { XR_TYPE_TRACKABLE_PLANE_ANDROID };
result = xrGetTrackablePlaneANDROID(
  planeTracker,
  &planeGetInfo,
  &plane
);

if (result == XR_SUCCESS) {
  // Plane tracking state, center pose, extents, type now available in plane.
}

ตัวอย่างโค้ดสําหรับการสร้างพื้นที่โฆษณา

โค้ดตัวอย่างต่อไปนี้แสดงวิธีสร้างพื้นที่ยึดที่แนบมากับรายการติดตาม

XrSession session; // Created at app startup.
XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrTrackableANDROID planeTrackable; // Acquired from a hit result or getTrackables().

// Create an anchor at (2, 2, 2) world-coordinates.
XrAnchorSpaceCreateInfoANDROID spatialAnchorCreateInfo;
spatialAnchorCreateInfo.type = XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID;
spatialAnchorCreateInfo.next = nullptr;
spatialAnchorCreateInfo.space = appSpace;
spatialAnchorCreateInfo.time = updateTime;
spatialAnchorCreateInfo.pose = { { 0, 0, 0, 1 }, { 2, 2, 2 } };

XrSpace spatialAnchor = XR_NULL_HANDLE;
XrResult result = xrCreateAnchorSpaceANDROID(
  session,
  &spatialAnchorCreateInfo,
  &spatialAnchor
);

// Create an anchor attached to a trackable.
XrTrackablePlane plane = ...;
XrAnchorSpaceCreateInfoANDROID trackableAnchorCreateInfo;
trackableAnchorCreateInfo.type = XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID;
trackableAnchorCreateInfo.next = nullptr;
trackableAnchorCreateInfo.space = appState;
trackableAnchorCreateInfo.pose = plane.centerPose;
trackableAnchorCreateInfo.trackable = planeTrackable;

XrSpace trackableAnchor = XR_NULL_HANDLE;
XrResult result = xrCreateAnchorSpaceANDROID(
  session,
  &trackableAnchorCreateInfo,
  &trackableAnchor
);
while (true) {
  // app update loop
  // ...

  // Get the current location of the anchor's space w.r.t the world.
  XrSpaceLocation anchorLocation = { XR_TYPE_SPACE_LOCATION };
  result = xrLocateSpace(trackableAnchor, appSpace, updateTime, &anchorLocation);

  if (anchor.trackingState == XR_TRACKING_STATE_TRACKING_ANDROID) {
    // Update anchor pose.
    doDrawingForAnchor(anchorLocation.pose);
  } else {
    // ...
  }
}

// Cleanup - destroy the space, detatch the anchor so its no longer tracked by the
// runtime and then release all resources held by it.
xrDestroySpace(spatialAnchor);
xrDestroySpace(trackableAnchor);

ประเภทฐานใหม่

• XrTrackableANDROID

ประเภทออบเจ็กต์ใหม่

• XrTrackableTrackerANDROID

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

เพิ่มรายการต่อไปนี้ในอนุกรม XrStructureType

• XR_TYPE_TRACKABLE_GET_INFO_ANDROID
• XR_TYPE_ANCHOR_SPACE_CREATE_INFO_ANDROID
• XR_TYPE_TRACKABLE_PLANE_ANDROID
• XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID

เพิ่มรายการต่อไปนี้ในคําจํากัดความของ XrObjectType

• XR_OBJECT_TYPE_TRACKABLE_TRACKER_ANDROID

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

• XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
• XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID

Enum ใหม่

• XrTrackingStateANDROID
• XrTrackableTypeANDROID
• XrPlaneTypeANDROID
• XrPlaneLabelANDROID

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

• XrTrackableTrackerCreateInfoANDROID
• XrTrackableGetInfoANDROID
• XrTrackablePlaneANDROID
• XrAnchorSpaceCreateInfoANDROID

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

• xrCreateTrackableTrackerANDROID
• xrDestroyTrackableTrackerANDROID
• xrGetAllTrackablesANDROID
• xrGetTrackablePlaneANDROID
• xrCreateAnchorSpaceANDROID

ปัญหา

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

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

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