XR_ANDROID_trackables_qr_code

নাম স্ট্রিং

XR_ANDROID_trackables_qr_code

এক্সটেনশন টাইপ

ইনস্ট্যান্স এক্সটেনশন

নিবন্ধিত এক্সটেনশন নম্বর

৭০৯

সংশোধন

অনুমোদনের অবস্থা

অনুমোদিত নয়

এক্সটেনশন এবং সংস্করণ নির্ভরতা

XR_ANDROID_trackables

অবচয় অবস্থা

  • XR_EXT_spatial_marker_tracking এক্সটেনশন দ্বারা বাতিল করা হয়েছে

সর্বশেষ সংশোধনের তারিখ

২০২৫-০২-০৫

আইপি স্ট্যাটাস

কোনো জ্ঞাত আইপি দাবি নেই।

অবদানকারীরা

ক্রিস্টোফার ডোয়ার, গুগল
লেভানা চেন, গুগল
জ্যারেড ফাইন্ডার, গুগল
স্পেন্সার কুইন, গুগল
নিহাব জৈন, গুগল
ডিয়েগো টিপাল্ডি, গুগল
কেন ম্যাকে, গুগল
ড্যানিয়েল গুটেনবার্গ, কোয়ালকম

সংক্ষিপ্ত বিবরণ

এই এক্সটেনশনটি ফিজিক্যাল কিউআর কোড ট্র্যাকিং এবং কিউআর কোড ডেটা ডিকোডিং সক্ষম করে।

অনুমতি

অ্যান্ড্রয়েড অ্যাপ্লিকেশনগুলির ম্যানিফেস্টে অবশ্যই 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 হলো একই সময়ে ট্র্যাক করা যায় এমন QR কোডের মোট সর্বোচ্চ সংখ্যা।

একটি অ্যাপ্লিকেশন xrGetSystemProperties কল করার সময় XrSystemProperties-কে XrSystemQrCodeTrackingPropertiesANDROID স্ট্রাকচার দিয়ে প্রসারিত করে সিস্টেমটি QR কোড ট্র্যাকিং করতে সক্ষম কিনা তা পরীক্ষা করতে পারে । রানটাইমকে অবশ্যই QR কোড ট্র্যাকার তৈরির জন্য XR_ERROR_FEATURE_UNSUPPORTED রিটার্ন করতে হবে যদি এবং শুধুমাত্র যদি supportsQrCodeTracking XR_FALSE হয়।

যদি কোনো রানটাইম কিউআর কোড ট্র্যাকিং সমর্থন করে, তাহলে maxQrCodeCount মান অবশ্যই কমপক্ষে ১ হতে হবে। আর যদি কোনো রানটাইম কিউআর কোড ট্র্যাকিং সমর্থন না করে, তাহলে maxQrCodeCount মান অবশ্যই ০ হতে হবে।

বৈধ ব্যবহার (অন্তর্নিহিত)

ট্র্যাকিং কিউআর কোড

এই এক্সটেনশনটি XrTrackableTypeANDROID-XR_TRACKABLE_TYPE_QR_CODE_ANDROID যোগ করে।

অ্যাপ্লিকেশনটি QR কোড ট্র্যাক করার জন্য xrCreateTrackableTrackerANDROID কল করে এবং XrTrackableTrackerCreateInfoANDROID :: trackableType এ ট্র্যাকযোগ্য প্রকার হিসেবে XR_TRACKABLE_TYPE_QR_CODE_ANDROID নির্দিষ্ট করে একটি XrTrackableTrackerANDROID তৈরি করতে পারে

যদি XrTrackableTrackerCreateInfoANDROID :: trackableType XR_TRACKABLE_TYPE_QR_CODE_ANDROID হয় এবং xrGetSystemProperties- এর মাধ্যমে XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking 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 সেট করা না থাকে, তবে রানটাইমকে শুধুমাত্র এই আকারের সাথে মেলে এমন QR কোডগুলোই ফেরত দিতে হবে । যদি XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize মান 0.0 সেট করা থাকে, তবে রানটাইমকে আনুমানিক আকারের সমস্ত QR কোড ফেরত দিতে হবে

বৈধ ব্যবহার (অন্তর্নিহিত)

XrQrCodeTrackingModeANDROID enum-টি QR কোডের সমর্থিত ট্র্যাকিং মোডগুলো বর্ণনা করে।

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;

গণনাকারীর বিবরণ

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID — ডাইনামিক কিউআর কোড ট্র্যাক করার জন্য। এই মোডটির নির্ভুলতা সর্বোচ্চ এবং এটি চলমান ও স্থির উভয় প্রকার কিউআর কোডেই কাজ করে, তবে এর বিদ্যুৎ খরচও সর্বোচ্চ।
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID — স্থির QR কোড ট্র্যাক করার জন্য। এই মোডটি মূলত সেইসব QR কোডের জন্য উপযোগী যেগুলো স্থির বলে পরিচিত, যার ফলে ডাইনামিক মোডের তুলনায় শক্তি খরচ কম হয়।
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM — এই মোডটি স্থির (static) QR কোডগুলির জন্য ব্যবহার করা উচিত। স্ট্যাটিক মোডের (static mode) বিপরীতে, এই মোডটি QR কোডটিকে শুধুমাত্র একবার ট্র্যাক করে এবং তারপর শুধুমাত্র ডিভাইসের অবস্থানের উপর ভিত্তি করে ট্র্যাক করা ইনস্ট্যান্সগুলির অবস্থান আপডেট করে। ফলে, QR কোডটি রেফারেন্স ফ্রেমের (reference frame) দৃষ্টিসীমার বাইরে চলে গেলেও ট্র্যাকিং চলতে থাকে। একবার QR কোডটি ট্র্যাক হয়ে গেলে এর ফলে বিদ্যুৎ খরচ ন্যূনতম হয়। ( 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

ব্যর্থতা

  • 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 হলো QR কোডের XrTrackingStateANDROID
  • lastUpdatedTime হলো QR কোডের সর্বশেষ আপডেটের XrTime । যদি শেষ কলের পর lastUpdatedTime পরিবর্তিত হয়, তাহলে অন্যান্য সমস্ত ফিল্ডও পরিবর্তিত হতে পারে
  • centerPose হলো XrTrackableGetInfoANDROID :: baseSpace এ অবস্থিত QR কোডটির XrPosef । QR কোডটি XZ সমতলে অবস্থিত, যেখানে X অক্ষটি QR কোডটির ডানদিকে, Z অক্ষটি এর নিচের দিকে এবং Y অক্ষটি অভিলম্ব হিসেবে QR কোডটি থেকে বাইরের দিকে নির্দেশ করে।
  • extents হলো QR কোডের XrExtent2Df মাত্রা। বাউন্ডিং বক্সের সীমানাটি centerPose +/- ( extents / 2 ) বিন্দুতে অবস্থিত।
  • bufferCapacityInput হলো buffer ধারণক্ষমতা, অথবা প্রয়োজনীয় ধারণক্ষমতা পেতে 0
  • bufferCountOutput যদি bufferCapacityInput মান 0 হয়, তাহলে bufferCountOutput প্রয়োজনীয় বাফার সাইজটি লিখে দেবে। অন্যথায়, এতে buffer লেখা মোট উপাদানের সংখ্যা থাকবে। যদি QR কোডের ডেটা এখনও ডিকোড করা না হয়ে থাকে, তাহলে রানটাইমকে অবশ্যই bufferCountOutput-এর মান 0 সেট করতে হবে।
  • buffer হলো ডিকোড করা কিউআর কোড ডেটা লেখার জন্য ব্যবহৃত char অ্যারের একটি পয়েন্টার। যদি অ্যাপ্লিকেশনটি ডিকোড করা কিউআর কোড ডেটা নিয়ে আগ্রহী না হয়, তবে এটি nullptr পাস করতে পারে এবং দ্বিতীয় দুই-কলের ধাপটি বাদ দিতে পারে। কিউআর কোড ডেটা একটি নাল-টার্মিনেটেড UTF-8 স্ট্রিং হিসাবে ফেরত দেওয়া হয়।
  • প্রয়োজনীয় buffer সাইজ নির্ধারণের বিস্তারিত বিবরণের জন্য বাফার সাইজ প্যারামিটার বিভাগটি দেখুন।

বৈধ ব্যবহার (অন্তর্নিহিত)

ট্র্যাকযোগ্য QR কোড পাওয়ার জন্য উদাহরণ কোড

নিম্নলিখিত উদাহরণ কোডটি দেখায় কিভাবে ট্র্যাকযোগ্য কিউআর কোড পাওয়া যায়।

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

নতুন কমান্ড

নতুন কাঠামো

নতুন এনাম

নতুন এনাম ধ্রুবক

  • 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, 2025-02-05 (লেভানা চেন)

    • প্রাথমিক সম্প্রসারণের বিবরণ।