XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

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

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

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

709

การแก้ไข

1

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

ไม่ได้รับการให้สัตยาบัน

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

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 หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน OpenXR หลักหรือส่วนขยายนี้
• supportsQrCodeTracking คือ XrBool32 ที่ระบุว่าระบบปัจจุบันมีความสามารถในการติดตามคิวอาร์โค้ดหรือไม่
• supportsQrCodeSizeEstimation คือ XrBool32 ที่ระบุว่าระบบปัจจุบันมีการประมาณขนาดคิวอาร์โค้ดหรือไม่
• maxQrCodeCount คือจำนวนคิวอาร์โค้ดสูงสุดทั้งหมดที่สามารถติดตามได้พร้อมกัน

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

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

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables_qr_code ก่อนใช้ XrSystemQrCodeTrackingPropertiesANDROID
• type ต้องเป็น XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง

คิวอาร์โค้ดสำหรับการติดตาม

ส่วนขยายนี้จะเพิ่ม 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 หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน 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 รันไทม์ต้องแสดงผลคิวอาร์โค้ดทั้งหมดพร้อมขนาดโดยประมาณ

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables_qr_code ก่อนใช้ XrTrackableQrCodeConfigurationANDROID
• type ต้องเป็น XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง ดูเพิ่มเติม: XrTrackableQrCodeVersionFilterQCOM
• trackingMode ต้องเป็นค่า XrQrCodeTrackingModeANDROID ที่ถูกต้อง

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

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 คือตัวชี้ไปยังโครงสร้าง 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 หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน 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 เป็นตัวชี้ไปยังอาร์เรย์ของ char เพื่อเขียนข้อมูลคิวอาร์โค้ดที่ถอดรหัสแล้ว หากแอปพลิเคชันไม่สนใจข้อมูลคิวอาร์โค้ดที่ถอดรหัสแล้ว ก็สามารถส่ง nullptr และละเว้นการเรียกใช้การเรียก 2 ครั้งครั้งที่ 2 ได้ ระบบจะแสดงผลข้อมูลคิวอาร์โค้ดเป็นสตริง UTF-8 ที่สิ้นสุดด้วยค่า Null
• ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด buffer ที่จำเป็นได้ที่ส่วนพารามิเตอร์ขนาดบัฟเฟอร์

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

• ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables_qr_code ก่อนใช้ XrTrackableQrCodeANDROID
• type ต้องเป็น XR_TYPE_TRACKABLE_QR_CODE_ANDROID
• next ต้องเป็น NULL หรือพอยน์เตอร์ที่ถูกต้องไปยังโครงสร้างถัดไปในเชนโครงสร้าง ดูเพิ่มเติม: XrTrackableQrCodeVersionQCOM
• trackingState ต้องเป็นค่า XrTrackingStateANDROID ที่ถูกต้อง
• หาก bufferCapacityInput ไม่ใช่ 0 buffer ต้องเป็นพอยน์เตอร์ไปยังอาร์เรย์ของค่าอักขระ bufferCapacityInput

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

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

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

คำสั่งใหม่

• xrGetTrackableQrCodeANDROID

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

• XrTrackableQrCodeANDROID

• การขยาย XrSystemProperties :

  • XrSystemQrCodeTrackingPropertiesANDROID

• การขยาย XrTrackableTrackerCreateInfoANDROID :

  • XrTrackableQrCodeConfigurationANDROID

Enum ใหม่

• XrQrCodeTrackingModeANDROID

ค่าคงที่ 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

ปัญหา

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

• Revision 1, 2025-02-05 (Levana Chen)

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