XR_ANDROID_trackables_qr_code

নামের স্ট্রিং

XR_ANDROID_trackables_qr_code

এক্সটেনশনের ধরন

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

রেজিস্টার করা এক্সটেনশন নম্বর

709

সংশোধন

1

অনুমোদনের স্ট্যাটাস

অনুমোদিত নয়

এক্সটেনশন ও ভার্সন ডিপেন্ডেন্সি

XR_ANDROID_trackables

বন্ধ হয়ে যাওয়ার স্ট্যাটাস

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

শেষবার পরিবর্তন করার তারিখ

2025-02-05

IP স্ট্যাটাস

IP সংক্রান্ত কোনও দাবি নেই।

কন্ট্রিবিউটর

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

এক নজরে

এই এক্সটেনশন ফিজিক্যাল QR কোড ট্র্যাকিং ও QR কোড ডেটা ডিকোডিং চালু করে।

অনুমতি

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 যা বর্তমান সিস্টেমে QR কোড ট্র্যাকিংয়ের ক্ষমতা আছে কিনা তা নির্দেশ করে।
  • supportsQrCodeSizeEstimation হল একটি XrBool32 যা বর্তমান সিস্টেম QR কোডের সাইজ অনুমান করে কিনা তা নির্দেশ করে।
  • maxQrCodeCount হল QR কোডের মোট সর্বাধিক সংখ্যা যা একই সময়ে ট্র্যাক করা যেতে পারে।

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

রানটাইম QR কোড ট্র্যাকিং সাপোর্ট করলে, maxQrCodeCount অবশ্যই অন্তত ১ হতে হবে। রানটাইম QR কোড ট্র্যাকিং সাপোর্ট না করলে, maxQrCodeCount অবশ্যই 0 হতে হবে।

সঠিক ব্যবহার (অন্তর্নিহিত)

QR কোড ট্র্যাক করা

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

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

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 মিটারে QR কোডের প্রান্তের সাইজ নির্দেশ করে। শূন্য হলে, রানটাইম অনলাইনে QR কোডের সাইজ অনুমান করে।

অ্যাপ্লিকেশনটিকে XrTrackableTrackerCreateInfoANDROID-এর পরবর্তী চেনে XrTrackableQrCodeConfigurationANDROID যোগ করে একটি সঠিক কনফিগারেশন সেট করতেই হবে। অন্যথায়, রানটাইম অবশ্যই XR_ERROR_VALIDATION_FAILURE রিটার্ন করবে।

রানটাইম QR কোডের সাইজ অনুমান করা সাপোর্ট করলে, অ্যাপ্লিকেশন হয়ত XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize থেকে 0.0 সেট করতে পারে যাতে সাইজ অনুমান করার ব্যবহার দেখানো যায়।

রানটাইম QR কোডের সাইজ অনুমান করতে না পারলে, অ্যাপ্লিকেশনকে অবশ্যই XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize-কে পজিটিভ ভ্যালুতে সেট করতে হবে, অন্যথায় রানটাইমকে অবশ্যই XR_ERROR_VALIDATION_FAILURE রিটার্ন করতে হবে।

trackingMode-এর সাথে ম্যাচ করার জন্য রানটাইমকে xrGetAllTrackablesANDROID থেকে আউটপুট অবশ্যই ফিল্টার করতে হবে। 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;

Enumerant-এর বিবরণ

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID — ডায়নামিক QR কোড ট্র্যাক করা। এই মোডে সবচেয়ে বেশি নির্ভুলভাবে স্ক্যান করা যায় এবং এটি চলমান ও স্থির QR কোডের ক্ষেত্রে কাজ করে, তবে এতে সবচেয়ে বেশি বিদ্যুৎ খরচ হয়।
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID — স্ট্যাটিক QR কোড ট্র্যাক করা। এই মোডটি মূলত QR কোডের জন্য উপযোগী যা স্ট্যাটিক বলে পরিচিত, যার ফলে ডাইনামিক মোডের তুলনায় কম বিদ্যুৎ খরচ হয়।
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM — এই মোডটি স্ট্যাটিক QR কোডের জন্য ব্যবহার করা উচিত। স্ট্যাটিক মোডের বিপরীতে, এই মোডটি শুধুমাত্র একবার QR কোড ট্র্যাক করবে এবং তারপরে শুধুমাত্র ডিভাইসের অবস্থানের উপর ভিত্তি করে ট্র্যাক করা ইনস্ট্যান্সের অবস্থান আপডেট করবে। এর ফলে, QR কোড রেফারেন্স ফ্রেমের বাইরে চলে গেলেও ট্র্যাকিং চলতে থাকে। এর ফলে QR কোড ট্র্যাক করার পরে খুব কম পাওয়ার খরচ হয়। (XR_QCOM_trackables_qr_code_operations এক্সটেনশন দ্বারা যোগ করা হয়েছে)

QR কোড পান

xrGetTrackableQrCodeANDROID ফাংশনটি এইভাবে সংজ্ঞায়িত করা হয়েছে:

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

প্যারামিটারের বিবরণ

  • tracker হল কোয়েরি করার জন্য XrTrackableTrackerANDROID।
  • getInfo হল XrTrackableGetInfoANDROID, যার মধ্যে ট্র্যাক করা যায় এমন QR কোড পাওয়ার জন্য ব্যবহৃত তথ্য থাকে।
  • qrCodeOutput হল XrTrackableQrCodeANDROID স্ট্রাকচারের একটি পয়েন্টার, যেখানে ট্র্যাক করা যায় এমন QR কোড রিটার্ন করা হয়।

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-এর অ্যারের একটি পয়েন্টার যা ডিকোড করা QR কোড ডেটা লেখার জন্য ব্যবহার করা হয়। অ্যাপ্লিকেশনটি ডিকোড করা QR কোড ডেটা সম্পর্কে চিন্তা না করলে, এটি nullptr পাস করতে পারে এবং দ্বিতীয় টু-কল কলটি বাদ দিতে পারে। QR কোড ডেটা নাল-টার্মিনেটেড UTF-8 স্ট্রিং হিসেবে ফেরত দেওয়া হয়।
  • প্রয়োজনীয় buffer সাইজ ফিরিয়ে আনার বিস্তারিত বিবরণের জন্য বাফার সাইজ প্যারামিটার বিভাগ দেখুন।

সঠিক ব্যবহার (অন্তর্নিহিত)

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

ট্র্যাক করা যায় এমন 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));

নতুন কমান্ড

নতুন স্ট্রাকচার

নতুন 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

ইস্যু

ভার্সনের ইতিহাস

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

    • এক্সটেনশনের প্রাথমিক বিবরণ।