ส่วนขยาย XR_ANDROID_trackables_qr_code OpenXR

Name String

XR_ANDROID_trackables_qr_code

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

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

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

460

การแก้ไข

1

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

XR_ANDROID_trackables

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

2025-02-05

สถานะ 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

ภาพรวม

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

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

XrSystemQrCodeTrackingPropertiesANDROID

XrSystemQrCodeTrackingPropertiesANDROID มีโครงสร้างดังนี้

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

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

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

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

หากรันไทม์รองรับการติดตามคิวอาร์โค้ด รันไทม์ต้องรองรับ maxQrCodeCountคิวอาร์โค้ดที่ติดตามได้ทุกเมื่อ

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

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

  • คุณต้องเปิดใช้ส่วนขยาย 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 เพื่อติดตาม QR code

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

XrTrackableQrCodeConfigurationANDROID

XrTrackableQrCodeConfigurationANDROID มีโครงสร้างดังนี้

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType               type;
    const 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 เพื่อ ระบุการใช้การประมาณขนาด ไม่เช่นนั้น แอปพลิเคชันต้องตั้งค่า XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize เป็นค่าบวก หรือระบบจะแสดงผล XR_ERROR_VALIDATION_FAILURE

รันไทม์ต้องกรองเอาต์พุตจาก xrGetAllTrackablesANDROID เพื่อให้ตรงกับ trackingMode และ qrCodeEdgeSize

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

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

XrQrCodeTrackingModeANDROID

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

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

| Enum | Description XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID ' | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | คิวอาร์โค้ดเป็นแบบไดนามิกและอาจมีการย้ายตำแหน่ง |

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

xrGetTrackableQrCodeANDROID

ฟังก์ชัน 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

XrTrackableQrCodeANDROID

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 ของการอัปเดตคิวอาร์โค้ดครั้งล่าสุด
  • centerPose คือ XrPosef ของคิวอาร์โค้ดที่อยู่ใน XrTrackableGetInfoANDROID::baseSpace คิวอาร์โค้ดอยู่ในระนาบ XZ โดย X ชี้ไปทางขวาของคิวอาร์โค้ดและ Z ชี้ไปทางด้านล่างของคิวอาร์โค้ด
  • extents คือขนาด XrExtent2Df ของคิวอาร์โค้ด ขอบเขตของกรอบล้อมรอบอยู่ที่จุด centerPose +/- (extents / 2)
  • bufferCapacityInput คือความสามารถของ buffer หรือ 0 ในการ เรียกความสามารถที่จำเป็น
  • bufferCountOutput หาก bufferCapacityInput เป็น 0 รันไทม์จะเขียนขนาดบัฟเฟอร์ที่จำเป็นลงใน bufferCountOutput มิฉะนั้น จะมีองค์ประกอบทั้งหมดที่เขียนใน buffer
  • buffer เป็นตัวชี้ไปยังอาร์เรย์ของ char เพื่อเขียนข้อมูลคิวอาร์โค้ดที่ถอดรหัสแล้ว แอปพลิเคชันสามารถส่ง nullptr เพื่อกำหนดขนาดบัฟเฟอร์ที่จำเป็น หรือหากไม่ได้ขอข้อมูลคิวอาร์โค้ดที่ถอดรหัสแล้ว ระบบจะแสดงผลข้อมูลคิวอาร์โค้ดเป็นสตริง UTF-8 ที่สิ้นสุดด้วยค่า Null
  • ดูคำอธิบายโดยละเอียดเกี่ยวกับการดึงข้อมูลขนาด buffer ที่จำเป็นได้ในส่วนพารามิเตอร์ขนาดบัฟเฟอร์

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

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

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

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

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);
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    qrCodes[i].type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID;
    qrCodes[i].next = nullptr;
    qrCodes[i].bufferCountOutput = 0;
    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 ใหม่

การแจงนับ XrStructureType จะขยายออกไปโดยมีรายการต่อไปนี้

  • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_ANDROID

การแจงนับ XrTrackableTypeANDROID จะขยายออกไปโดยมีรายการต่อไปนี้

  • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Enums ใหม่

  • XrQrCodeTrackingModeANDROID

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

  • XrSystemQrCodeTrackingPropertiesANDROID
  • XrTrackableQrCodeConfigurationANDROID
  • XrTrackableQrCodeANDROID

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

  • xrGetTrackableQrCodeANDROID

ปัญหา

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

  • ฉบับแก้ไข 1, 2025-02-05 (Levana Chen)
    • คำอธิบายส่วนขยายเริ่มต้น

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