ส่วนขยาย XR_ANDROID_device_anchor_persistence OpenXR

สตริงชื่อ

XR_ANDROID_device_anchor_persistence

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

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

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

458

การแก้ไข

1

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

XR_EXT_uuid และ XR_ANDROID_trackables

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

2024-10-10

สถานะ IP

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

ผู้เขียน

Nihav Jain จาก Google

Levana Chen จาก Google

Spencer Quin จาก Google

Kenny Vercaemer จาก Google

ภาพรวม

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

ตรวจสอบความสามารถของระบบ

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

typedef struct XrSystemDeviceAnchorPersistencePropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAnchorPersistence;
} XrSystemDeviceAnchorPersistencePropertiesANDROID;

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

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

แอปพลิเคชันสามารถตรวจสอบว่าระบบสามารถเก็บข้อมูลอังเกอร์เชิงพื้นที่ได้หรือไม่ (ดู xrCreateAnchorSpaceANDROID) โดยการขยาย XrSystemProperties ด้วยโครงสร้าง XrSystemDeviceAnchorPersistencePropertiesANDROID เมื่อเรียกใช้ xrGetSystemProperties สําหรับหมุดติดตามที่รองรับ แอปพลิเคชันสามารถใช้ xrEnumerateSupportedPersistenceAnchorTypesANDROID เพื่อค้นหาประเภทที่รองรับ

หากระบบแสดงผล XR_FALSE สำหรับ supportsAnchorPersistence ระบบจะแสดงผล XR_ERROR_FEATURE_UNSUPPORTED จากฟังก์ชันการคงอยู่ของหมุดอุปกรณ์ที่ทำงานกับหมุดเชิงพื้นที่

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

ฟังก์ชัน xrEnumerateSupportedPersistenceAnchorTypesANDROID ได้รับการกําหนดดังนี้ 

XrResult xrEnumerateSupportedPersistenceAnchorTypesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    trackableTypeCapacityInput,
    uint32_t*                                   trackableTypeCountOutput,
    XrTrackableTypeANDROID*                     trackableTypes);

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

  • session คือ XrSession ที่สร้าง XrDeviceAnchorPersistenceANDROID
  • trackableTypeCapacityInput คือความจุของ trackableTypes หรือ 0 เพื่อดึงข้อมูลความจุที่จําเป็น
  • trackableTypeCountOutput คือพอยน์เตอร์ไปยังจํานวนอาร์เรย์ หรือพอยน์เตอร์ไปยังความจุที่จําเป็นในกรณีที่trackableTypeCapacityInputไม่เพียงพอ
  • trackableTypes เป็นพอยน์เตอร์ไปยังอาร์เรย์ของ XrTrackableTypeANDROID แต่สามารถเป็น NULL ได้หาก trackableTypeCapacityInput เป็น 0
  • ดูรายละเอียดเกี่ยวกับการดึงข้อมูลtrackableTypesขนาดที่ต้องการได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันสามารถใช้ xrEnumerateSupportedPersistenceAnchorTypesANDROID เพื่อตรวจสอบการรองรับการคงอยู่ของหมุดในองค์ประกอบการติดตาม XrTrackableTypeANDROID อื่นๆ

หากXrTrackableTypeANDROID หนึ่งๆ ไม่แสดงในอาร์เรย์ trackableTypes ระบบจะแสดง XR_ERROR_FEATURE_UNSUPPORTED จากฟังก์ชันการคงที่ของอุปกรณ์แองเคอร์ที่ทำงานกับแองเคอร์ประเภทนั้น

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

  • คุณต้องเปิดใช้ส่วนขยาย XR_ANDROID_device_anchor_persistence ก่อนเรียกใช้ xrEnumerateSupportedPersistenceAnchorTypesANDROID
  • instance ต้องเป็นตัวแฮนเดิล XrInstance ที่ถูกต้อง
  • trackableTypeCountOutput ต้องเป็นพอยน์เตอร์ไปยังค่า uint32_t
  • หาก trackableTypeCapacityInput ไม่ใช่ 0, trackableTypes ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่า trackableTypeCapacityInput XrTrackableTypeANDROID

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

สำเร็จ

  • XR_SUCCESS

ไม่สำเร็จ

  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_FUNCTION_UNSUPPORTED

สร้างตัวแฮนเดิลการคงที่ของอุปกรณ์หลัก

XrDeviceAnchorPersistenceANDROID เป็นแฮนเดิลที่แสดงถึงทรัพยากรที่จําเป็นต่อการคงอยู่และติดตามการยึดเกาะที่คงอยู่ 

XR_DEFINE_HANDLE(XrDeviceAnchorPersistenceANDROID)

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

XrResult xrCreateDeviceAnchorPersistenceANDROID(
    XrSession                                   session,
    const XrDeviceAnchorPersistenceCreateInfoANDROID* createInfo,
    XrDeviceAnchorPersistenceANDROID*           outHandle);

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

แอปพลิเคชันสามารถสร้างตัวแฮนเดิล XrDeviceAnchorPersistenceANDROID ได้โดยเรียกใช้ xrCreateDeviceAnchorPersistenceANDROID XrDeviceAnchorPersistenceANDROID สามารถใช้ในคำเรียก API ถัดไปเพื่อเก็บหรือยกเลิกการเก็บรักษาหมุด ต้องยกเลิกการจองหน่วยความจำของตัวแฮนเดิล XrDeviceAnchorPersistenceANDROID โดยใช้ฟังก์ชัน xrDestroyDeviceAnchorPersistenceANDROID ในที่สุด

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

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

สำเร็จ

  • 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

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

typedef struct XrDeviceAnchorPersistenceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrDeviceAnchorPersistenceCreateInfoANDROID;

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

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

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

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

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

XrResult xrDestroyDeviceAnchorPersistenceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle);

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

  • handle เป็นตัวแฮนเดิล XrDeviceAnchorPersistenceANDROID ที่ xrCreateDeviceAnchorPersistenceANDROID สร้างขึ้นก่อนหน้านี้

ฟังก์ชัน xrDestroyDeviceAnchorPersistenceANDROID จะทำลายตัวแฮนเดิลการคงอยู่ของอุปกรณ์หลัก

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

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

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

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

สำเร็จ

  • XR_SUCCESS

ไม่สำเร็จ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

เก็บ Anchor

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

XrResult xrPersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceInfoANDROID*    persistedInfo,
    XrUuidEXT*                                  anchorIdOutput);

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

  • handle คือ XrDeviceAnchorPersistenceANDROID
  • persistedInfo คือ XrPersistedAnchorSpaceInfoANDROID ที่มีพารามิเตอร์สำหรับการจัดเก็บข้อมูลหมุด
  • anchorIdOutput คือพอยน์เตอร์ไปยัง XrUuidEXT ซึ่งจะแสดง UUID ของแฮนเดิลที่เก็บไว้

แอปพลิเคชันสามารถขอให้ระบบเก็บข้อมูลหมุดโดยเรียกใช้ xrPersistAnchorANDROID แอปพลิเคชันต้องไม่ถือว่าค่าที่แสดงผลเป็น "สำเร็จ" หมายความว่าระบบจัดเก็บข้อมูล Anchor ไว้ทันที แอปพลิเคชันควรใช้ xrGetAnchorPersistStateANDROID เพื่อตรวจสอบสถานะการคงอยู่ของแอนคอร์โดยใช้แอนคอร์ที่แสดงผล XrUuidEXT แอปพลิเคชันสามารถใช้ xrUnpersistAnchorANDROID เพื่อยกเลิกการเก็บรักษา Anchor

  • ระบบจะแสดงผล XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID หากไม่มีการติดตามหมุด ณ เวลาที่มีการเรียกใช้
  • ระบบจะแสดง XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID หากข้อมูลถาวรไม่พร้อม
  • ระบบจะแสดง XR_SUCCESS เมื่อระบบจัดคิวหมุดเพื่อเก็บรักษาแล้ว

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

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ไม่สำเร็จ

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

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

typedef struct XrPersistedAnchorSpaceInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            anchor;
} XrPersistedAnchorSpaceInfoANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • anchor คือ XrSpace หลักที่สร้างขึ้นก่อนหน้านี้โดย xrCreateAnchorSpaceANDROID เพื่อเก็บไว้

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

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

XrResult xrGetAnchorPersistStateANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId,
    XrAnchorPersistStateANDROID*                persistState);

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

  • handle คือ XrDeviceAnchorPersistenceANDROID
  • anchorId คือ XrUuidEXT ของหมุด
  • persistState คือพอยน์เตอร์ไปยัง XrAnchorPersistStateANDROID ซึ่งจะแสดงสถานะของหมุด
  • ระบบจะแสดงผล XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID หากไม่พบXrUuidEXT
  • ระบบจะแสดง XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID หากข้อมูล anchorId ที่เก็บถาวรยังไม่พร้อม

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

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

สำเร็จ

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

รายการ XrAnchorPersistStateANDROID มีคำจำกัดความดังนี้ 

typedef enum XrAnchorPersistStateANDROID {
    XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID = 0,
    XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID = 1,
    XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID = 2
} XrAnchorPersistStateANDROID;

Enum

คำอธิบาย

XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID

แอปไม่ได้ขอให้เก็บหมุดไว้

XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID

มีคำขอเก็บรักษาหมุด แต่ยังไม่ได้เก็บรักษา

XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID

รันไทม์เก็บข้อมูลหมุดเรียบร้อยแล้ว

สร้างหมุดจากข้อมูลที่เก็บไว้

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

XrResult xrCreatePersistedAnchorSpaceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorOutput);

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

แอปพลิเคชันสามารถสร้างหมุด XrSpace จากหมุดที่เก็บถาวรไว้ก่อนหน้านี้โดยเรียกใช้ xrCreatePersistedAnchorSpaceANDROID ที่มี XrUuidEXT เดียวกัน วิธีนี้เป็นวิธีสร้างจุดยึดอีกวิธีหนึ่งตามที่ระบุไว้ใน XR_ANDROID_trackables

  • ระบบจะแสดงผล XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID หากไม่พบXrUuidEXT

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

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

สำเร็จ

  • 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_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

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

typedef struct XrPersistedAnchorSpaceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrUuidEXT          anchorId;
} XrPersistedAnchorSpaceCreateInfoANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือพอยน์เตอร์ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • anchorId คือ XrUuidEXT ของหมุดที่เก็บไว้เพื่อสร้างXrSpace ของหมุด

โครงสร้าง XrPersistedAnchorSpaceCreateInfoANDROID มีตัวเลือกการสร้างสำหรับหมุดเมื่อส่งไปยัง xrCreateDeviceAnchorPersistenceANDROID

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

แสดงรายการ Anchor ถาวร

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

XrResult xrEnumeratePersistedAnchorsANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    uint32_t                                    anchorIdsCapacityInput,
    uint32_t*                                   anchorIdsCountOutput,
    XrUuidEXT*                                  anchorIds);

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

  • handle คือ XrDeviceAnchorPersistenceANDROID
  • anchorIdsCapacityInput คือความจุของอาร์เรย์ anchorIds หรือ 0 เพื่อบ่งบอกคําขอดึงข้อมูลความจุที่จําเป็น
  • anchorIdsCountOutput คือพอยน์เตอร์ไปยังจํานวน anchorIds ที่เขียน หรือพอยน์เตอร์ไปยังความจุที่จําเป็นในกรณีที่ anchorIdsCapacityInput ไม่เพียงพอ
  • anchorIds คือตัวชี้ไปยังอาร์เรย์ของโครงสร้าง XrUuidEXT สามารถเป็น NULL ได้หาก anchorIdsCapacityInput เป็น 0
  • ดูรายละเอียดเกี่ยวกับการดึงข้อมูลanchorIdsขนาดที่ต้องการได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

แอปพลิเคชันอาจแสดงรายการหมุดคงที่ปัจจุบันทั้งหมดโดยเรียกใช้ xrEnumeratePersistedAnchorsANDROID anchorIds จะเก็บ UUID ของแอนคอร์ที่เก็บไว้ตามความจุของอาร์เรย์ หากมีจำนวนไม่เพียงพอ แอปพลิเคชันจะไม่มีการรับประกันว่าระบบจะแสดงหมุดใด

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

  • คุณต้องเปิดใช้ส่วนขยาย XR_ANDROID_device_anchor_persistence ก่อนเรียกใช้ xrEnumeratePersistedAnchorsANDROID
  • handle ต้องเป็นตัวแฮนเดิล XrDeviceAnchorPersistenceANDROID ที่ถูกต้อง
  • anchorIdsCountOutput ต้องเป็นพอยน์เตอร์ไปยังค่า uint32_t
  • หาก anchorIdsCapacityInput ไม่ใช่ 0, anchorIds ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของโครงสร้าง anchorIdsCapacityInput XrUuidEXT

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ไม่สำเร็จ

  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID
  • 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_SIZE_INSUFFICIENT

ยกเลิกการคงที่ของหมุดถาวร

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

XrResult xrUnpersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId);

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

แอปพลิเคชันอาจทำให้หมุดที่เก็บถาวรอยู่คงอยู่ต่อไปไม่ได้โดยเรียกใช้ xrUnpersistAnchorANDROID และส่งหมุด XrUuidEXT ของหมุดที่จะคงอยู่ต่อไปไม่ได้

  • ระบบจะแสดงผลลัพธ์เป็น XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID หากข้อมูลถาวรยังไม่พร้อม
  • ระบบจะแสดงผล XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID หากไม่พบXrUuidEXT

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

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

สำเร็จ

  • 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_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

ตัวอย่างโค้ดสำหรับการจัดเก็บข้อมูล Anchor

โค้ดตัวอย่างต่อไปนี้แสดงวิธีตรวจสอบความสามารถของระบบ เก็บ แสดงรายการ และยกเลิกการเก็บรักษาหมุด รวมถึงสร้างหมุดจากหมุดที่เก็บไว้ XrUuidEXT

XrSession session; // previously initialized
XrSpace anchor; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedPersistenceAnchorTypesANDROID xrEnumerateSupportedPersistenceAnchorTypesANDROID; // previously initialized
PFN_xrCreateDeviceAnchorPersistenceANDROID xrCreateDeviceAnchorPersistenceANDROID; // previously initialized
PFN_xrDestroyDeviceAnchorPersistenceANDROID xrDestroyDeviceAnchorPersistenceANDROID; // previously initialized
PFN_xrPersistAnchorANDROID xrPersistAnchorANDROID; // previously initialized
PFN_xrGetAnchorPersistStateANDROID xrGetAnchorPersistStateANDROID; // previously initialized
PFN_xrCreatePersistedAnchorSpaceANDROID xrCreatePersistedAnchorSpaceANDROID; // previously initialized
PFN_xrEnumeratePersistedAnchorsANDROID xrEnumeratePersistedAnchorsANDROID; // previously initialized
PFN_xrUnpersistAnchorANDROID xrUnpersistAnchorANDROID; // previously initialized

// Create a device anchor persistence handle
XrDeviceAnchorPersistenceCreateInfoANDROID persistenceHandleCreateInfo;
persistenceHandleCreateInfo.type = XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID;
persistenceHandleCreateInfo.next = nullptr;

XrDeviceAnchorPersistenceANDROID persistenceHandle;
CHK_XR(xrCreateDeviceAnchorPersistenceANDROID(session, &persistenceHandleCreateInfo, &persistenceHandle));

/// Persist an anchor
XrPersistedAnchorSpaceInfo anchorSpaceInfo;
anchorSpaceInfo.type = XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID;
anchorSpaceInfo.next = nullptr;
anchorSpaceInfo.anchor = anchor;

XrUuidEXT anchorId;
do {
  XrResult result = xrPersistAnchorANDROID(
    persistenceHandle, &anchorSpaceInfo, &anchorId);
} while (result == XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID ||
         result == XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID);
if (result != XR_SUCCESS) {
  // Handle errors
}


// ... Update loop ...
// Poll for anchor persist state to confirm if it was successfully persisted
XrAnchorPersistStateANDROID persistState;
CHK_XR(xrGetAnchorPersistStateANDROID(persistenceHandle, &anchorId, &persistState));
if (persistState == XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID)  {
  // The anchor was persisted successfully
}

// Enumerate all persisted anchors
uint32_t anchorCountOutput = 0;
std::vector<XrUuidEXT> allAnchors;

CHK_XR(xrEnumeratePersistedAnchorsANDROID(
  persistenceHandle,
  anchorCountOutput,
  &anchorCountOutput,
  nullptr
));
allAnchors.resize(anchorCountOutput, XR_NULL_HANDLE);

// Fetch the actual anchors in an appropriately resized array.
CHK_XR(xrEnumeratePersistedAnchorsANDROID(
  persistenceHandle,
  anchorCountOutput,
  &anchorCountOutput,
  allAnchors.data()
));

// Creating an anchor from a previously persisted anchor using its UUID
XrTime updateTime; // Time used for the current frame's simulation update.
XrUuidEXT anchorId = allAnchors[0];

XrPersistedAnchorSpaceCreateInfo createInfo;
createInfo.type = XR_TYPE_PERSISTED_ANCHOR_CREATE_INFO_ANDROID;
createInfo.next = nullptr;
createInfo.anchorId = anchorId;

XrSpace anchorSpace = XR_NULL_HANDLE;
CHK_XR(xrCreatePersistedAnchorSpaceANDROID(
  persistenceHandle,
  &createInfo,
  &anchorSpace
));

// The anchor was found and retrieved from the local device successfully.
XrSpaceLocation anchorLocation = { XR_TYPE_SPACE_LOCATION };
CHK_XR(xrLocateSpace(anchorSpace, appSpace, updateTime, &anchorLocation));
XrPosef pose = anchorLocation.pose;

// Unpersist the anchor
do {
  XrResult result = xrUnpersistAnchorANDROID(persistenceHandle, &anchorId);
} while (result == XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID);
if (result != XR_SUCCESS) {
  // Handle errors
}

// Once app is done with all persistence related tasks
CHK_XR(xrDestroySpace(anchorSpace));
CHK_XR(xrDestroyDeviceAnchorPersistenceANDROID(persistenceHandle));

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

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

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

  • XR_OBJECT_TYPE_DEVICE_ANCHOR_PERSISTENCE_ANDROID

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

  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_ANCHOR_ALREADY_PERSISTED_ANDROID
  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

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

  • XR_TYPE_PERSISTED_ANCHOR_ANDROID
  • XR_TYPE_PERSISTED_ANCHOR_SPACE_CREATE_INFO_ANDROID
  • XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID
  • XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID

Enum ใหม่

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

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

ปัญหา

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

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

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