XR_ANDROID_trackables_qr_code

สตริงชื่อ

XR_ANDROID_trackables_qr_code

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

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

หมายเลขส่วนขยายที่ลงทะเบียน

709

การแก้ไข

1

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

ยังไม่ให้สัตยาบัน

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

XR_ANDROID_trackables

สถานะการเลิกใช้งาน

  • เลิกใช้งานโดยส่วนขยาย XR_EXT_spatial_marker_tracking

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

05-02-2025

สถานะ IP

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

ผู้เขียน

Christopher Doer, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Diego Tipaldi, Google
Ken Mackay, Google
Daniel Guttenberg, Qualcomm

ภาพรวม

ส่วนขยายนี้ช่วยให้สามารถติดตามคิวอาร์โค้ดจริงและถอดรหัสข้อมูลคิวอาร์โค้ดได้

สิทธิ์

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

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

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

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

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint16_t           maxQrCodeCount;
} XrSystemQrCodeTrackingPropertiesANDROID;

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

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

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

หากรันไทม์รองรับการติดตามคิวอาร์โค้ด maxQrCodeCount ต้อง มีค่าอย่างน้อย 1 หากรันไทม์ไม่รองรับการติดตามคิวอาร์โค้ด maxQrCodeCount ต้อง มีค่าเป็น 0

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

การติดตามคิวอาร์โค้ด

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

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

รันไทม์ ต้อง แสดงผล XR_ERROR_FEATURE_UNSUPPORTED หาก XrTrackableTrackerCreateInfoANDROID :: trackableType เป็น XR_TRACKABLE_TYPE_QR_CODE_ANDROID และ XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking แสดงผล XR_FALSE ผ่าน xrGetSystemProperties

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

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType                type;
    void*                          next;
    XrQrCodeTrackingModeANDROID    trackingMode;
    float                          qrCodeEdgeSize;
} XrTrackableQrCodeConfigurationANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • trackingMode คือ XrQrCodeTrackingModeANDROID ที่ระบุโหมดที่ต้องการสำหรับการติดตาม
  • qrCodeEdgeSize ระบุขนาดขอบคิวอาร์โค้ดเป็นเมตร หากเป็น 0 รันไทม์จะประมาณขนาดคิวอาร์โค้ดแบบออนไลน์

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

หากรันไทม์รองรับการประมาณขนาดคิวอาร์โค้ด แอปพลิเคชันอาจ ตั้งค่า XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize เป็น 0.0 เพื่อระบุการใช้การประมาณขนาด

หากรันไทม์ไม่รองรับการประมาณขนาดคิวอาร์โค้ด แอปพลิเคชันต้อง ตั้งค่า XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize เป็นค่าบวก ไม่เช่นนั้น รันไทม์ต้อง แสดงผล XR_ERROR_VALIDATION_FAILURE

รันไทม์ ต้อง กรองเอาต์พุตจาก xrGetAllTrackablesANDROID ให้ตรงกับ trackingMode หากไม่ได้ตั้งค่า XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize เป็น 0.0 รันไทม์ต้อง แสดงผลเฉพาะคิวอาร์โค้ดที่มีขนาดตรงกัน หากตั้งค่า XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize เป็น 0.0 รันไทม์ ต้อง แสดงผลคิวอาร์โค้ดทั้งหมดที่มีขนาดโดยประมาณ

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

Enum XrQrCodeTrackingModeANDROID อธิบายโหมดการติดตามคิวอาร์โค้ดที่รองรับ

typedef enum XrQrCodeTrackingModeANDROID {
    XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM = 1000314000,
    XR_QR_CODE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrQrCodeTrackingModeANDROID;

คำอธิบาย Enumerant

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID \- การติดตามคิวอาร์โค้ดแบบไดนามิก โหมดนี้มีความแม่นยำสูงสุดและใช้ได้กับคิวอาร์โค้ดที่เคลื่อนไหวและคงที่ แต่ก็มีการใช้พลังงานสูงสุดด้วย
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID \- การติดตามคิวอาร์โค้ดแบบคงที่ โหมดนี้มีประโยชน์หลักๆ สำหรับคิวอาร์โค้ดที่ทราบว่าคงที่ ซึ่งจะทำให้ใช้พลังงานน้อยกว่าเมื่อเทียบกับโหมดไดนามิก
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM \- โหมดนี้ควรใช้กับคิวอาร์โค้ดที่คงที่ โหมดนี้จะติดตามคิวอาร์โค้ดเพียงครั้งเดียว จากนั้นจะอัปเดตตำแหน่งของอินสแตนซ์ที่ติดตามตามตำแหน่งของอุปกรณ์เท่านั้น ซึ่งแตกต่างจากโหมดคงที่ ด้วยเหตุนี้ การติดตามจึงดำเนินต่อไปแม้ว่าคิวอาร์โค้ดจะอยู่นอกมุมมองของเฟรมอ้างอิง ซึ่งจะทำให้ใช้พลังงานน้อยที่สุดเมื่อติดตามคิวอาร์โค้ดแล้ว (เพิ่มโดยส่วนขยาย XR_QCOM_trackables_qr_code_operations)

รับคิวอาร์โค้ด

ฟังก์ชัน xrGetTrackableQrCodeANDROID กำหนดไว้ดังนี้

XrResult xrGetTrackableQrCodeANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableQrCodeANDROID*                   qrCodeOutput);

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

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

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

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

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables_qr_code ก่อน จึงจะเรียกใช้ xrGetTrackableQrCodeANDROID ได้
  • tracker ต้อง เป็นแฮนเดิล XrTrackableTrackerANDROID ที่ถูกต้อง
  • getInfo ต้อง เป็นพอยน์เตอร์ไปยังโครงสร้าง XrTrackableGetInfoANDROID ที่ถูกต้อง
  • qrCodeOutput ต้อง เป็นพอยน์เตอร์ไปยังโครงสร้าง XrTrackableQrCodeANDROID

รหัสแสดงผล

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

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

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

typedef struct XrTrackableQrCodeANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrTime                    lastUpdatedTime;
    XrPosef                   centerPose;
    XrExtent2Df               extents;
    uint32_t                  bufferCapacityInput;
    uint32_t                  bufferCountOutput;
    char*                     buffer;
} XrTrackableQrCodeANDROID;

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

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
  • trackingState คือ XrTrackingStateANDROID ของคิวอาร์โค้ด
  • lastUpdatedTime คือ XrTime ของการอัปเดตคิวอาร์โค้ดครั้งล่าสุด หาก lastUpdatedTime เปลี่ยนไปจากการเรียกใช้ครั้งล่าสุด ช่องอื่นๆ ทั้งหมดอาจ เปลี่ยนไปด้วย
  • centerPose คือ XrPosef ของคิวอาร์โค้ดที่อยู่ใน XrTrackableGetInfoANDROID :: baseSpace คิวอาร์โค้ดอยู่ในระนาบ XZ โดย X ชี้ไปทางขวาของคิวอาร์โค้ด Z ชี้ไปทางด้านล่าง และ Y ชี้ออกจากคิวอาร์โค้ดเป็นปกติ
  • extents คือขนาด XrExtent2Df ของคิวอาร์โค้ด ขอบเขตของกรอบล้อมรอบอยู่ที่จุด centerPose +/- ( extents / 2)
  • bufferCapacityInput คือความสามารถของ buffer หรือ 0 เพื่อดึงข้อมูลความสามารถที่จำเป็น
  • bufferCountOutput หาก bufferCapacityInput เป็น 0 รันไทม์จะเขียนขนาดบัฟเฟอร์ที่จำเป็นลงใน bufferCountOutput ไม่เช่นนั้น จะมีองค์ประกอบทั้งหมดที่เขียนใน buffer หากยังไม่ได้ถอดรหัสข้อมูลคิวอาร์โค้ด รันไทม์ต้อง ตั้งค่า bufferCountOutput เป็น 0
  • buffer คือ Pointer ไปยังอาร์เรย์ของ char เพื่อเขียนข้อมูลคิวอาร์โค้ดที่ถอดรหัสแล้ว หากแอปพลิเคชันไม่สนใจข้อมูลคิวอาร์โค้ดที่ถอดรหัสแล้ว ก็สามารถ ส่ง nullptr และละเว้นการเรียกใช้ครั้งที่ 2 ได้ ระบบจะแสดงผลข้อมูลคิวอาร์โค้ดเป็นสตริง UTF-8 ที่สิ้นสุดด้วยค่า Null
  • ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด buffer ที่จำเป็นในส่วน พารามิเตอร์ขนาดบัฟเฟอร์

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

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

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

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session;   // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // previously initialized
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // previously initialized
PFN_xrGetTrackableQrCodeANDROID xrGetTrackableQrCodeANDROID;           // 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.

// Inspect system capability
XrSystemQrCodeTrackingPropertiesANDROID qrCodeProperty {
  .type = XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &qrCodeProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!qrCodeProperty.supportsQrCodeTracking) {
    // QR code tracking is not supported.
    return;
}

// Create a trackable tracker for QR code tracking.
// If the runtime does not support size estimation, configures QR code edge size of 0.1m.
XrTrackableQrCodeConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID,
  .qrCodeEdgeSize = qrCodeProperty.supportsQrCodeSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_QR_CODE_ANDROID
};
XrTrackableTrackerANDROID qrCodeTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &qrCodeTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get QR codes.
std::vector<XrTrackableANDROID> trackables(qrCodeProperty.maxQrCodeCount);
std::vector<XrTrackableQrCodeANDROID> qrCodes(qrCodeProperty.maxQrCodeCount, {
  .type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID,
  .next = nullptr,
  .bufferCountOutput = 0,
});
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables.at(i),
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
    if (qrCodes[i].bufferCountOutput > 0) {
        // Allocate the buffer if it is not already allocated.
        if (qrCodes[i].bufferCapacityInput == 0) {
            qrCodes[i].buffer = new char[qrCodes[i].bufferCountOutput];
            qrCodes[i].bufferCapacityInput = qrCodes[i].bufferCountOutput;
            CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
        }
    }
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(qrCodeTracker));

คำสั่งใหม่

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

Enum ใหม่

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

  • XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
  • XR_ANDROID_trackables_qr_code_SPEC_VERSION

  • การขยาย XrStructureType :

    • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID

  • การขยาย XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

ปัญหา

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

  • การแก้ไข 1, 05-02-2025 (Levana Chen)

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