XR_ANDROID_trackables_image

Name String

XR_ANDROID_trackables_image

ประเภทส่วนขยาย

ส่วนขยายอินสแตนซ์

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

710

การแก้ไข

1

สถานะการให้สัตยาบัน

ยังไม่ได้รับการรับรอง

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

XR_EXT_future
และ
XR_ANDROID_trackables

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

2025-04-08

สถานะ IP

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

ผู้เขียน

Christopher Doer, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Diego Tipaldi, Google
Daniel Guttenberg, Qualcomm
Mark Vadasi, Qualcomm
Markus Birkner, Qualcomm
Maximilian Mayer, Qualcomm

ภาพรวม

ส่วนขยายนี้ช่วยให้ติดตามรูปภาพระนาบได้ตามที่ระบุโดยชุดรูปภาพอ้างอิงอินพุต

สิทธิ์

แอปพลิเคชัน Android ต้องมีสิทธิ์ android.permission.SCENE_UNDERSTANDING_COARSE แสดงอยู่ในไฟล์ Manifest เนื่องจากส่วนขยายนี้ขึ้นอยู่กับ XR_ANDROID_trackables และแสดงเรขาคณิตของสภาพแวดล้อม สิทธิ์ android.permission.SCENE_UNDERSTANDING_COARSE ถือเป็นสิทธิ์ที่เป็นอันตราย

(ระดับการป้องกัน: อันตราย)

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

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

typedef struct XrSystemImageTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsImageTracking;
    XrBool32           supportsPhysicalSizeEstimation;
    uint32_t           maxTrackedImageCount;
    uint32_t           maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้ ดูรายละเอียดเพิ่มเติมเกี่ยวกับเชนโครงสร้างได้ที่โครงสร้างที่กำลังขยาย ( XrSystemProperties )
  • supportsImageTracking คือ XrBool32 ที่ระบุว่าระบบปัจจุบันมีความสามารถในการติดตามรูปภาพหรือไม่
  • supportsPhysicalSizeEstimation คือ XrBool32 ที่ระบุว่าระบบปัจจุบันมีการประมาณขนาดรูปภาพหรือไม่
  • maxTrackedImageCount คือจำนวนรูปภาพสูงสุดทั้งหมดที่ติดตามได้พร้อมกัน
  • maxLoadedImageCount คือจำนวนสูงสุดทั้งหมดของรูปภาพอ้างอิงที่โหลดได้ในฐานข้อมูลทั้งหมด

แอปพลิเคชันสามารถตรวจสอบว่าระบบรองรับการติดตามรูปภาพหรือไม่โดยขยาย XrSystemProperties ด้วยโครงสร้าง XrSystemImageTrackingPropertiesANDROID เมื่อเรียกใช้ xrGetSystemProperties รันไทม์ต้องแสดงผล XR_ERROR_FEATURE_UNSUPPORTED สำหรับการสร้างเครื่องมือติดตามรูปภาพก็ต่อเมื่อ supportsImageTracking เป็น XR_FALSE เท่านั้น

หากรันไทม์รองรับการติดตามรูปภาพ รันไทม์ต้องรองรับmaxTrackedImageCountรูปภาพที่ติดตาม ณ เวลาใดก็ตาม

หากรันไทม์รองรับการติดตามรูปภาพ ต้องรองรับmaxLoadedImageCountรูปภาพที่โหลดแล้วในเวลาใดก็ตาม

หากรันไทม์รองรับการประมาณขนาดรูปภาพ แอปพลิเคชันสามารถตั้งค่า XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0 เพื่อระบุการใช้การประมาณขนาดได้ ไม่เช่นนั้น แอปพลิเคชันต้องตั้งค่า XrTrackableImageDatabaseEntryANDROID :: physicalWidth เป็นค่าบวก หรือระบบจะแสดงผล XR_ERROR_VALIDATION_FAILURE

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

การสร้างฐานข้อมูล

แอปพลิเคชันสามารถสร้างแฮนเดิล XrTrackableImageDatabaseANDROID ได้โดยการสร้างโครงสร้าง XrTrackableImageDatabaseEntryANDROID อย่างน้อย 1 รายการ แล้วส่งไปยังฟังก์ชัน xrCreateTrackableImageDatabaseAsyncANDROID ผ่านโครงสร้าง XrTrackableImageDatabaseCreateInfoANDROID

แอปพลิเคชันต้องระบุ XrTrackableImageDatabaseEntryANDROID อย่างน้อย 1 รายการเมื่อสร้างแฮนเดิล XrTrackableImageDatabaseANDROID

XrTrackableImageDatabaseANDROID คือแฮนเดิลที่แสดงชุดรูปภาพอ้างอิงที่ประมวลผลแล้วซึ่งค้นพบและติดตามในสภาพแวดล้อมได้

XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)

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

typedef struct XrTrackableImageDatabaseEntryANDROID {
    XrStructureType                        type;
    const void*                            next;
    XrTrackableImageTrackingModeANDROID    trackingMode;
    float                                  physicalWidth;
    uint32_t                               imageWidth;
    uint32_t                               imageHeight;
    XrTrackableImageFormatANDROID          format;
    uint32_t                               bufferSize;
    const uint8_t*                         buffer;
} XrTrackableImageDatabaseEntryANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
  • trackingMode คือ XrTrackableImageTrackingModeANDROID ที่ระบุโหมดที่ต้องการสำหรับการติดตาม
  • physicalWidth ระบุความกว้างของรูปภาพเป็นเมตร หากเป็น 0 ระบบจะประมาณขนาดรูปภาพทางออนไลน์
  • imageWidth ระบุความกว้างของรูปภาพเป็นพิกเซล
  • imageHeight ระบุความสูงของรูปภาพเป็นพิกเซล
  • format คือ XrTrackableImageFormatANDROID ที่ระบุรูปแบบของข้อมูลรูปภาพใน buffer
  • bufferSize ระบุความยาวของไบต์ของ buffer
  • buffer คือบัฟเฟอร์ uint8_t ที่มีข้อมูลพิกเซลภาพของรูปภาพอ้างอิง เนื้อหาของ buffer ต้องถูกต้องตลอดระยะเวลาของการดำเนินการแบบไม่พร้อมกันในการสร้างฐานข้อมูล ซึ่งเริ่มต้นโดย xrCreateTrackableImageDatabaseAsyncANDROID และสิ้นสุดโดย xrCreateTrackableImageDatabaseCompleteANDROID

แอปพลิเคชันอาจตั้งค่า physicalWidth เป็น 0 เพื่อขอการประมาณขนาดออนไลน์ หาก XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation เป็น XR_TRUE

รันไทม์อาจแสดงผล XR_ERROR_VALIDATION_FAILURE จาก xrCreateTrackableImageDatabaseAsyncANDROID หาก bufferSize ไม่ตรงกับขนาดที่คาดไว้ตาม imageWidth , imageHeight และ format ของรายการ

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

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

typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
    XrStructureType                                type;
    const void*                                    next;
    uint32_t                                       entryCount;
    const XrTrackableImageDatabaseEntryANDROID*    entries;
} XrTrackableImageDatabaseCreateInfoANDROID;

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

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

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

โครงสร้าง XrCreateTrackableImageDatabaseCompletionANDROID มีการกำหนดไว้ดังนี้

typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
    XrStructureType                    type;
    void*                              next;
    XrResult                           futureResult;
    XrTrackableImageDatabaseANDROID    database;
} XrCreateTrackableImageDatabaseCompletionANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
  • futureResult คือ XrResult ของการดำเนินการแบบอะซิงโครนัส
  • database คือแฮนเดิล XrTrackableImageDatabaseANDROID ที่สร้างขึ้น

รหัสการคืนสินค้าในอนาคต

ค่า futureResult

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

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

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

XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
    XrSession                                   session,
    const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

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

  • session คือแฮนเดิลของ XrSession ที่สร้างไว้ก่อนหน้านี้ด้วย xrCreateSession
  • createInfo คือตัวชี้ไปยังโครงสร้าง XrTrackableImageDatabaseCreateInfoANDROID
  • future เป็นตัวชี้ไปยัง XrFutureEXT ที่สร้างขึ้น

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

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables_image ก่อนที่จะเรียกใช้ xrCreateTrackableImageDatabaseAsyncANDROID
  • session ต้องเป็นแฮนเดิล XrSession ที่ถูกต้อง
  • createInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrTrackableImageDatabaseCreateInfoANDROID ที่ถูกต้อง
  • future ต้องเป็นพอยน์เตอร์ไปยังค่า XrFutureEXT

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateTrackableImageDatabaseCompletionANDROID* completion);

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

  • session คือแฮนเดิลของ XrSession ที่สร้างไว้ก่อนหน้านี้ด้วย xrCreateSession
  • future คือ XrFutureEXT แห่งอนาคตที่ต้องทำให้เสร็จสมบูรณ์
  • completion เป็น Pointer ไปยังโครงสร้าง XrCreateTrackableImageDatabaseCompletionANDROID ที่มีผลลัพธ์ของการดำเนินการ

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

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrDestroyTrackableImageDatabaseANDROID(
    XrTrackableImageDatabaseANDROID             database);

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

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

ความปลอดภัยของเธรด

  • การเข้าถึง database และแฮนเดิลย่อยทั้งหมดต้องซิงค์ภายนอก

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

สำเร็จ

  • XR_SUCCESS

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

รูปภาพการติดตาม

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

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

รันไทม์ต้องส่งคืน XR_ERROR_FEATURE_UNSUPPORTED หาก XrTrackableTrackerCreateInfoANDROID :: trackableType เป็น XR_TRACKABLE_TYPE_IMAGE_ANDROID และ XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking ส่งคืน XR_FALSE ผ่าน xrGetSystemProperties

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

typedef struct XrTrackableImageConfigurationANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  databaseCount;
    const XrTrackableImageDatabaseANDROID*    databases;
} XrTrackableImageConfigurationANDROID;

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

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

แอปพลิเคชันต้องกำหนดค่าที่ถูกต้องโดยการเพิ่ม XrTrackableImageConfigurationANDROID ลงในเชน next ของ XrTrackableTrackerCreateInfoANDROID ไม่เช่นนั้น รันไทม์ต้องแสดงผล XR_ERROR_VALIDATION_FAILURE

แอปพลิเคชันต้องระบุโครงสร้าง XrTrackableImageDatabaseANDROID อย่างน้อย 1 รายการเพื่อสร้างเครื่องมือติดตาม

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

การแจงนับ XrTrackableImageTrackingModeANDROID อธิบายโหมดการติดตามที่รองรับของรูปภาพ

typedef enum XrTrackableImageTrackingModeANDROID {
    XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;

คำอธิบายรายการ

  • XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID — โหมดนี้มีความแม่นยำสูงสุดและช่วยให้ติดตามภาพเคลื่อนไหวที่มีเวลาในการตอบสนองต่ำได้ และยังมีการใช้พลังงานสูงสุดด้วย
  • XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID — โหมดนี้ควรใช้กับรูปภาพที่ทราบว่าเป็นรูปภาพนิ่งหรือกึ่งนิ่ง โหมดนี้จะใช้พลังงานน้อยกว่าเมื่อเทียบกับโหมดไดนามิก หากมีการย้ายรูปภาพนิ่ง ระบบจะอัปเดตรูปภาพดังกล่าวโดยมีเวลาในการตอบสนองสูงกว่าการใช้โหมดไดนามิกมาก

การแจงนับ XrTrackableImageFormatANDROID อธิบายรูปแบบของรูปภาพที่รองรับ

typedef enum XrTrackableImageFormatANDROID {
    XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
    XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;

คำอธิบายรายการ

  • XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID — รูปแบบรูปภาพ RGBA ที่มีข้อมูลสีและความโปร่งใส 8 บิตต่อช่อง

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

XrResult xrAddTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

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

เมื่อเพิ่ม XrTrackableImageDatabaseANDROID ลงในเครื่องมือติดตาม ระบบต้องพิจารณารูปภาพอ้างอิงของฐานข้อมูลนั้นเพื่อการตรวจหาและการติดตาม นอกเหนือจากฐานข้อมูลอื่นๆ ที่เพิ่มไว้ก่อนหน้านี้ด้วย xrAddTrackableImageDatabaseANDROID หรือผ่านโครงสร้าง XrTrackableImageConfigurationANDROID เมื่อสร้างเครื่องมือติดตามในครั้งแรก

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

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables_image ก่อนที่จะเรียกใช้ xrAddTrackableImageDatabaseANDROID
  • tracker ต้องเป็นแฮนเดิล XrTrackableTrackerANDROID ที่ถูกต้อง
  • database ต้องเป็นแฮนเดิล XrTrackableImageDatabaseANDROID ที่ถูกต้อง
  • ทั้ง database และ tracker ต้องสร้าง จัดสรร หรือดึงข้อมูลจาก XrSession เดียวกัน

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrRemoveTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

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

เมื่อนำ XrTrackableImageDatabaseANDROID ออกจาก XrTrackableTrackerANDROID โครงสร้าง XrTrackableImageDatabaseEntryANDROID ของฐานข้อมูลนั้นต้องไม่ได้รับการพิจารณาสำหรับการตรวจหาและการติดตามอีกต่อไป ระบบต้องไม่รายงานรายการที่ติดตามอยู่ของฐานข้อมูลนั้นอีกต่อไป ต้องไม่ทำลายแฮนเดิล XrTrackableImageDatabaseANDROID ที่นำออกโดยปริยายเป็นส่วนหนึ่งของการดำเนินการนี้

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

  • ต้องเปิดใช้XR_ANDROID_trackables_imageส่วนขยายก่อนเรียกใช้ xrRemoveTrackableImageDatabaseANDROID
  • tracker ต้องเป็นแฮนเดิล XrTrackableTrackerANDROID ที่ถูกต้อง
  • database ต้องเป็นแฮนเดิล XrTrackableImageDatabaseANDROID ที่ถูกต้อง
  • ทั้ง database และ tracker ต้องสร้าง จัดสรร หรือดึงข้อมูลจาก XrSession เดียวกัน

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

การรับรูปภาพ

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

XrResult xrGetTrackableImageANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableImageANDROID*                    trackable);

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

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

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

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

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables_image ก่อนที่จะเรียกใช้ xrGetTrackableImageANDROID
  • tracker ต้องเป็นแฮนเดิล XrTrackableTrackerANDROID ที่ถูกต้อง
  • getInfo ต้องเป็นตัวชี้ไปยังโครงสร้าง XrTrackableGetInfoANDROID ที่ถูกต้อง
  • trackable ต้องเป็นตัวชี้ไปยังโครงสร้าง XrTrackableImageANDROID

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

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrTrackableImageANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrTrackingStateANDROID             trackingState;
    XrTime                             lastUpdatedTime;
    XrTrackableImageDatabaseANDROID    database;
    uint32_t                           databaseEntryIndex;
    XrPosef                            centerPose;
    XrExtent2Df                        extents;
} XrTrackableImageANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือตัวชี้ไปยังโครงสร้างถัดไปในห่วงโซ่โครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
  • trackingState คือ XrTrackingStateANDROID ของรูปภาพ
  • lastUpdatedTime คือXrTimeของการอัปเดตรูปภาพครั้งล่าสุด
  • database คือแฮนเดิล XrTrackableImageDatabaseANDROID ที่ใช้ติดตามรูปภาพนี้
  • databaseEntryIndex คือดัชนีที่แมปกับอาร์เรย์ XrTrackableImageDatabaseCreateInfoANDROID :: entries ของ database
  • centerPose คือ XrPosef ของรูปภาพที่อยู่ใน XrTrackableGetInfoANDROID :: baseSpace รูปภาพอยู่ในระนาบ XZ โดย X ชี้ไปทางขวาของรูปภาพ และ Z ชี้ไปทางด้านล่างของรูปภาพ
  • extents คือขนาด XrExtent2Df ของรูปภาพ ขอบเขตของกรอบล้อมรอบอยู่ที่จุด centerPose +/- ( extents / 2)

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

การจัดการความล้มเหลว

แอปพลิเคชันต้องสำรวจเหตุการณ์ XrEventDataImageTrackingLostANDROID โดยใช้ xrPollEvent และต้องไม่เพิกเฉยต่อเหตุการณ์ดังกล่าว

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

typedef struct XrEventDataImageTrackingLostANDROID {
    XrStructureType    type;
    const void*        next;
    XrTime             time;
} XrEventDataImageTrackingLostANDROID;

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

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

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

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

ตัวอย่างโค้ดสำหรับการรับรูปภาพที่ติดตามได้

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

XrInstance instance;  // Previously initialized.
XrSession session;    // Previously initialized.
XrSystemId systemId;  // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID;                                        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace;  // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.

// Inspect system capability
XrSystemImageTrackingPropertiesANDROID imageProperty {
  .type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
    // image tracking is not supported.
    return;
}

uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
  {
    .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
    .next = nullptr,
    .trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
    .physicalWidth = 0.1f, // The width of the image in meters.
    .imageWidth = 640,
    .imageHeight = 480,
    .format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
    .bufferSize = imageBufferSize, // RGBA buffer size in bytes.
    .buffer = imageBuffer, // RGBA data.
  }
};

XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
  .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .entryCount = 1,
  .entries = imageDatabaseEntries
};

XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
  XrFuturePollInfoEXT pollInfo{
    .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
    .future = imageDatabaseFuture,
  };
  XrFuturePollResultEXT pollResult{
    .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
  };
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

  if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
    futureReady = true;
    keepLooping = false;
  } else {
    // Throttle the loop to not fully expend this CPU core.
    std::this_thread::yield();
  }
}

XrTrackableImageDatabaseANDROID imageDatabase;

if (futureReady) {
  XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
    .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
    .next = nullptr,
  };

  CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
  CHK_XR(imageDatabaseCompletion.futureResult);
  imageDatabase = imageDatabaseCompletion.database;
}

XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &imageDatabase
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.

// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

while (1) {
  uint32_t trackableCountOutput = 0;

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));

  std::vector<XrTrackableANDROID> allImageTrackables;
  allImageTrackables.resize(trackableCountOutput);

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));

  for (XrTrackableANDROID trackable : allImageTrackables) {
    XrTrackableGetInfoANDROID imageGetInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackable,
      .baseSpace = appSpace,
      .time = updateTime
    };

    XrTrackableImageANDROID trackableImage{
      .type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
    };
    CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));

    // Use XrTrackableImageANDROID data.
    (void)trackableImage.trackingState;
    (void)trackableImage.lastUpdatedTime;
    (void)trackableImage.centerPose;
    (void)trackableImage.extents;

    if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
      // Knowing which image the index of 0 maps to, use the specific image database
      // entry (e.g. rendering A for image A).
    }
    // indices 1+N comparisons for another specific image database entry.
  }

  // Throttle the loop to not fully expend this CPU core.
  std::this_thread::yield();
}

// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

ตัวอย่างโค้ดสำหรับการจัดการฐานข้อมูลรูปภาพที่รันไทม์

โค้ดตัวอย่างต่อไปนี้แสดงวิธีแก้ไขชุดรูปภาพที่ติดตาม

XrSession session; // Previously initialized.

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

PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.

// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 2,
  .databases = imageDatabases
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.

CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.

CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.

CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.

// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &anotherImageDatabase
};

XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &anotherImageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));

// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.

ตัวอย่างโค้ดสำหรับการตอบสนองต่อการติดตามรูปภาพที่ไม่สำเร็จ

โค้ดตัวอย่างต่อไปนี้แสดงวิธีจัดการความล้มเหลวโดยการสำรวจเหตุการณ์ XrEventDataImageTrackingLostANDROID

XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.

// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
  .type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
      const XrEventDataImageTrackingLostANDROID& eventdata =
        *reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);

      // All existing databases and trackers need to be destroyed.
      CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
      CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

      // To resume image tracking, the database(s) and the tracker need to be re-created.

      XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
        .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
        .next = nullptr,
        .entryCount = 1,
        .entries = imageDatabaseEntries
      };

      XrFutureEXT imageDatabaseFuture;
      CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

      while (true) {
        XrFuturePollInfoEXT pollInfo{
          .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
          .future = imageDatabaseFuture,
        };
        XrFuturePollResultEXT pollResult{
          .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
        };
        CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

        if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
          break;
        } else {
          // Throttle the loop to not fully expend this CPU core.
          std::this_thread::yield();
        }
      }

      XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
        .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
        .next = nullptr,
      };

      CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
      CHK_XR(imageDatabaseCompletion.futureResult);
      imageDatabase = imageDatabaseCompletion.database;

      XrTrackableImageConfigurationANDROID imageConfig {
       .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
       .next = nullptr,
       .databaseCount = 1,
       .databases = &imageDatabase
      };

      XrTrackableTrackerCreateInfoANDROID createInfo {
        .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
        .next = &imageConfig,
        .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
      };

      XrTrackableTrackerANDROID imageTrackableTracker;
      CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

      break;
    }
  }
}

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

คำสั่งใหม่

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

Enum ใหม่

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

  • XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAME
  • XR_ANDROID_trackables_image_SPEC_VERSION
  • การขยาย XrObjectType :

    • XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
  • การขยาย XrResult :

    • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • การขยาย XrStructureType :

    • XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID
    • XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
  • การขยาย XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_IMAGE_ANDROID

ปัญหา

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

  • ฉบับแก้ไขที่ 1, 08-04-2025 (Daniel Guttenberg)

    • คำอธิบายส่วนขยายเริ่มต้น