XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

एक्सटेंशन का टाइप

इंस्टेंस एक्सटेंशन

रजिस्टर किया गया एक्सटेंशन नंबर

709

बदलाव

1

पुष्टि की स्थिति

मंज़ूरी नहीं मिली

एक्सटेंशन और वर्शन डिपेंडेंसी

XR_ANDROID_trackables

बंद होने की स्थिति

  • XR_EXT_spatial_marker_tracking एक्सटेंशन की मदद से बंद किया गया

पिछली बार बदलाव किए जाने की तारीख

2025-02-05

आईपी स्टेटस

बौद्धिक संपत्ति से जुड़े किसी दावे की जानकारी नहीं है.

योगदान देने वाले

क्रिस्टोफ़र डोअर, Google
लेवाना चेन, Google
जेरेड फ़ाइंडर, Google
स्पेंसर क्विन, Google
निहाव जैन, Google
डिएगो टिपाल्डी, Google
केन मैके, Google
डैनियल गटनबर्ग, Qualcomm

खास जानकारी

इस एक्सटेंशन की मदद से, फ़िज़िकल क्यूआर कोड को ट्रैक किया जा सकता है और क्यूआर कोड के डेटा को डिकोड किया जा सकता है.

अनुमतियां

Android ऐप्लिकेशन के मेनिफ़ेस्ट में, android.permission.SCENE_UNDERSTANDING_COARSE अनुमति को शामिल करना ज़रूरी है. ऐसा इसलिए, क्योंकि यह एक्सटेंशन 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, क्यूआर कोड की वह ज़्यादा से ज़्यादा संख्या है जिसे एक ही समय पर ट्रैक किया जा सकता है.

कोई ऐप्लिकेशन यह जांच कर सकता है कि सिस्टम, क्यूआर कोड को ट्रैक कर सकता है या नहीं. इसके लिए, xrGetSystemProperties को कॉल करते समय, XrSystemProperties को XrSystemQrCodeTrackingPropertiesANDROID स्ट्रक्चर के साथ जोड़ना होगा. रनटाइम को क्यूआर कोड ट्रैकर बनाने के लिए, XR_ERROR_FEATURE_UNSUPPORTED ज़रूर दिखाना चाहिए. हालांकि, ऐसा सिर्फ़ तब होना चाहिए, जब supportsQrCodeTracking, XR_FALSE हो.

अगर कोई रनटाइम, क्यूआर कोड ट्रैकिंग के साथ काम करता है, तो maxQrCodeCount कम से कम 1 होना चाहिए. अगर कोई रनटाइम, क्यूआर कोड ट्रैकिंग की सुविधा के साथ काम नहीं करता है, तो maxQrCodeCount ज़रूर 0 होना चाहिए.

सही इस्तेमाल (इंप्लिसिट)

क्यूआर कोड ट्रैक करना

यह एक्सटेंशन, XrTrackableTypeANDROID में XR_TRACKABLE_TYPE_QR_CODE_ANDROID जोड़ता है.

क्यूआर कोड ट्रैक करने के लिए, ऐप्लिकेशन XrTrackableTrackerANDROID बना सकता है. इसके लिए, उसे xrCreateTrackableTrackerANDROID को कॉल करना होगा और XrTrackableTrackerCreateInfoANDROID :: trackableType में ट्रैक किए जा सकने वाले टाइप के तौर पर XR_TRACKABLE_TYPE_QR_CODE_ANDROID को चुनना होगा.

अगर XrTrackableTrackerCreateInfoANDROID :: trackableType, XR_TRACKABLE_TYPE_QR_CODE_ANDROID है और XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking, xrGetSystemProperties के ज़रिए XR_FALSE दिखाता है, तो रनटाइम को XR_ERROR_FEATURE_UNSUPPORTED दिखाना चाहिए.

XrTrackableQrCodeConfigurationANDROID स्ट्रक्चर को इस तरह से तय किया गया है:

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

सदस्यों की जानकारी

  • type, इस स्ट्रक्चर का XrStructureType है.
  • next, NULL है या स्ट्रक्चर चेन में अगले स्ट्रक्चर का पॉइंटर है. OpenXR के मुख्य वर्शन या इस एक्सटेंशन में, इस तरह के स्ट्रक्चर के बारे में नहीं बताया गया है.
  • trackingMode एक XrQrCodeTrackingModeANDROID है, जो ट्रैकिंग के लिए पसंदीदा मोड दिखाता है.
  • qrCodeEdgeSize से, क्यूआर कोड के किनारे का साइज़ मीटर में पता चलता है. अगर यह वैल्यू शून्य है, तो रनटाइम, क्यूआर कोड के साइज़ का अनुमान ऑनलाइन लगाता है.

ऐप्लिकेशन को XrTrackableTrackerCreateInfoANDROID की अगली चेन में XrTrackableQrCodeConfigurationANDROID जोड़कर, मान्य कॉन्फ़िगरेशन सेट करना चाहिए. ऐसा न होने पर, रनटाइम को XR_ERROR_VALIDATION_FAILURE दिखाना चाहिए .

अगर रनटाइम, क्यूआर कोड के साइज़ का अनुमान लगाने की सुविधा के साथ काम करता है, तो ऐप्लिकेशन शायद XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize को 0.0 पर सेट करे, ताकि साइज़ के अनुमान के इस्तेमाल का पता चल सके.

अगर रनटाइम में क्यूआर कोड के साइज़ का अनुमान लगाने की सुविधा काम नहीं करती है, तो ऐप्लिकेशन को XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize को पॉज़िटिव वैल्यू पर सेट करना होगा. ऐसा न करने पर, रनटाइम को XR_ERROR_VALIDATION_FAILURE दिखाना होगा.

रनटाइम को xrGetAllTrackablesANDROID से मिले आउटपुट को फ़िल्टर करना होगा, ताकि वह trackingMode से मैच हो सके. अगर XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize को 0.0 पर सेट नहीं किया गया है, तो रनटाइम को सिर्फ़ इस साइज़ से मैच होने वाले क्यूआर कोड दिखाने चाहिए. अगर XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize को 0.0 पर सेट किया गया है, तो रनटाइम को अनुमानित साइज़ के साथ सभी क्यूआर कोड ज़रूर दिखाने चाहिए.

सही इस्तेमाल (इंप्लिसिट)

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 Descriptions

  • 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 स्ट्रक्चर का पॉइंटर है. इसमें ट्रैक किया जा सकने वाला क्यूआर कोड दिखाया जाता है.

अगर XrTrackableANDROID का ट्रैक किया जा सकने वाला टाइप XR_TRACKABLE_TYPE_QR_CODE_ANDROID नहीं है या XrTrackableTrackerANDROID का ट्रैक किया जा सकने वाला टाइप XR_TRACKABLE_TYPE_QR_CODE_ANDROID नहीं है, तो रनटाइम को XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID दिखाना चाहिए.

सही इस्तेमाल (इंप्लिसिट)

  • xrGetTrackableQrCodeANDROID को कॉल करने से पहले, XR_ANDROID_trackables_qr_code एक्सटेंशन को चालू करना ज़रूरी है
  • tracker एक मान्य XrTrackableTrackerANDROID हैंडल होना चाहिए
  • getInfo को मान्य XrTrackableGetInfoANDROID स्ट्रक्चर का पॉइंटर होना चाहिए
  • qrCodeOutput को XrTrackableQrCodeANDROID स्ट्रक्चर का पॉइंटर होना चाहिए

रिटर्न कोड

सफलता

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • 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, XrTrackableGetInfoANDROID :: baseSpace में मौजूद क्यूआर कोड का XrPosef है. क्यूआर कोड, XZ प्लेन में होता है. इसमें X, क्यूआर कोड की दाईं ओर और Z, इसके निचले हिस्से की ओर इशारा करता है. वहीं, Y, क्यूआर कोड से बाहर की ओर इशारा करता है.
  • extents, क्यूआर कोड का XrExtent2Df डाइमेंशन है. बाउंडिंग बॉक्स की सीमा इन पॉइंट पर है: centerPose +/- ( extents / 2).
  • bufferCapacityInput, buffer की क्षमता है. इसके अलावा, ज़रूरी क्षमता को वापस पाने के लिए 0 का इस्तेमाल किया जा सकता है.
  • bufferCountOutput अगर bufferCapacityInput की वैल्यू 0 है, तो रनटाइम, ज़रूरी बफ़र साइज़ को bufferCountOutput में लिखेगा. अगर ऐसा नहीं है, तो इसमें buffer में लिखे गए कुल एलिमेंट शामिल होते हैं. अगर क्यूआर कोड का डेटा अब तक डिकोड नहीं हुआ है, तो रनटाइम को bufferCountOutput को 0 पर सेट करना चाहिए.
  • buffer, char के कलेक्शन का एक पॉइंटर है. इसका इस्तेमाल, डिकोड किए गए क्यूआर कोड के डेटा को लिखने के लिए किया जाता है. अगर ऐप्लिकेशन को डिकोड किए गए क्यूआर कोड के डेटा से कोई फ़र्क़ नहीं पड़ता, तो वह nullptr को पास कर सकता है और दूसरे टू-कॉल कॉल को छोड़ सकता है. क्यूआर कोड का डेटा, UTF-8 स्ट्रिंग के तौर पर दिखता है. यह स्ट्रिंग, नल-टर्मिनेटेड होती है.
  • ज़रूरी buffer साइज़ को वापस पाने के बारे में ज़्यादा जानकारी के लिए, बफ़र साइज़ पैरामीटर सेक्शन देखें.

सही इस्तेमाल (इंप्लिसिट)

  • XrTrackableQrCodeANDROID का इस्तेमाल करने से पहले, XR_ANDROID_trackables_qr_code एक्सटेंशन चालू करना ज़रूरी है
  • 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));

नए निर्देश

नए स्ट्रक्चर

नए 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

समस्याएं

वर्शन हिस्ट्री

  • पहला बदलाव, 05-02-2025 (लेवाना चेन)

    • एक्सटेंशन का शुरुआती ब्यौरा.