کد QR قابل ردیابی XR_ANDROID

رشته نام

XR_ANDROID_trackables_qr_code

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

709

بازنگری

۱

وضعیت تصویب

تصویب نشده

وابستگی‌های افزونه و نسخه

XR_ANDROID_trackables

وضعیت منسوخ‌شده

• توسط افزونه‌ی XR_EXT_spatial_marker_tracking منسوخ شده است

آخرین تاریخ اصلاح

۲۰۲۵-۰۲-۰۵

وضعیت آی‌پی

هیچ ادعای مالکیت معنوی شناخته‌شده‌ای وجود ندارد.

مشارکت‌کنندگان

کریستوفر دوئر، گوگل
لوانا چن، گوگل
جارد فایندر، گوگل
اسپنسر کوئین، گوگل
نیهاو جین، گوگل
دیه‌گو تیپالدی، گوگل
کن مک‌کی، گوگل
دنیل گوتنبرگ، کوالکام

نمای کلی

این افزونه امکان ردیابی کد QR فیزیکی و رمزگشایی داده‌های کد QR را فراهم می‌کند.

مجوزها

برنامه‌های اندروید باید مجوز 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 است که می‌توان همزمان ردیابی کرد.

یک برنامه می‌تواند با بسط XrSystemProperties با ساختار XrSystemQrCodeTrackingPropertiesANDROID هنگام فراخوانی xrGetSystemProperties ، بررسی کند که آیا سیستم قادر به ردیابی کد QR است یا خیر. زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED برای ایجاد ردیاب کد QR برگرداند، اگر و فقط اگر supportsQrCodeTracking XR_FALSE باشد.

اگر یک زمان اجرا از ردیابی کد QR پشتیبانی کند، maxQrCodeCount باید حداقل ۱ باشد. اگر یک زمان اجرا از ردیابی کد QR پشتیبانی نکند، maxQrCodeCount باید ۰ باشد.

کاربرد معتبر (ضمنی)

• افزونه‌ی XR_ANDROID_trackables_qr_code باید قبل از استفاده از XrSystemQrCodeTrackingPropertiesANDROID فعال شود.
• type باید XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID باشد.
• next باید NULL یا یک اشاره‌گر معتبر به ساختار بعدی در یک زنجیره ساختار باشد.

ردیابی کدهای QR

این افزونه XR_TRACKABLE_TYPE_QR_CODE_ANDROID را به XrTrackableTypeANDROID اضافه می‌کند.

برنامه می‌تواند با فراخوانی xrCreateTrackableTrackerANDROID و تعیین XR_TRACKABLE_TYPE_QR_CODE_ANDROID به عنوان نوع قابل ردیابی در XrTrackableTrackerCreateInfoANDROID :: trackableType برای ردیابی کدهای QR، یک XrTrackableTrackerANDROID ایجاد کند.

اگر 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 را به صورت آنلاین تخمین می‌زند.

برنامه باید با اضافه کردن XrTrackableQrCodeConfigurationANDROID به زنجیره بعدی XrTrackableTrackerCreateInfoANDROID ، یک پیکربندی معتبر تنظیم کند. در غیر این صورت، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.

اگر زمان اجرا از تخمین اندازه کد QR پشتیبانی کند، برنامه ممکن است XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize را روی 0.0 تنظیم کند تا استفاده از تخمین اندازه را نشان دهد.

اگر زمان اجرا از تخمین اندازه کد QR پشتیبانی نکند، برنامه باید XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize را روی یک مقدار مثبت تنظیم کند، در غیر این صورت زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.

زمان اجرا باید خروجی xrGetAllTrackablesANDROID را فیلتر کند تا با trackingMode مطابقت داشته باشد. اگر XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize روی 0.0 تنظیم نشده باشد، زمان اجرا باید فقط کدهای QR را که با این اندازه مطابقت دارند، برگرداند. اگر XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize روی 0.0 تنظیم شده باشد، زمان اجرا باید تمام کدهای QR را با اندازه تخمینی برگرداند.

کاربرد معتبر (ضمنی)

• افزونه‌ی XR_ANDROID_trackables_qr_code باید قبل از استفاده از XrTrackableQrCodeConfigurationANDROID فعال شود.
• type باید XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID باشد.
• next باید NULL یا یک اشاره‌گر معتبر به ساختار بعدی در یک زنجیره ساختار باشد. همچنین ببینید: XrTrackableQrCodeVersionFilterQCOM
• trackingMode باید یک مقدار معتبر XrQrCodeTrackingModeANDROID باشد.

شمارشگر XrQrCodeTrackingModeANDROID حالت‌های ردیابی پشتیبانی‌شده توسط کدهای 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 — ردیابی کدهای 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 را برگرداند.

کاربرد معتبر (ضمنی)

• افزونه‌ی 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 کد QR است.
• lastUpdatedTime XrTime آخرین به‌روزرسانی کد QR است. اگر lastUpdatedTime از آخرین فراخوانی تغییر کند، ممکن است تمام فیلدهای دیگر تغییر کرده باشند.
• centerPose ، XrPosef کد QR واقع در XrTrackableGetInfoANDROID :: baseSpace است. کد QR در صفحه XZ قرار دارد که X به سمت راست کد QR، Z به پایین آن و Y به صورت عادی از کد QR خارج می‌شود.
• extents ابعاد XrExtent2Df کد QR است. مرز کادر مرزی در نقاط زیر قرار دارد: centerPose +/- ( extents / 2).
• bufferCapacityInput قابلیت buffer یا 0 برای بازیابی قابلیت مورد نیاز است.
• bufferCountOutput اگر bufferCapacityInput برابر با 0 باشد، زمان اجرا اندازه بافر مورد نیاز را در bufferCountOutput می‌نویسد. در غیر این صورت، شامل کل عناصر نوشته شده در buffer است. اگر داده‌های کد QR هنوز رمزگشایی نشده باشند، زمان اجرا باید bufferCountOutput را روی ۰ تنظیم کند.
• buffer یک اشاره‌گر به آرایه‌ای از char برای نوشتن داده‌های کد QR رمزگشایی شده است. اگر برنامه به داده‌های کد QR رمزگشایی شده اهمیتی ندهد، می‌تواند nullptr ارسال کند و فراخوانی دو فراخوانی دوم را حذف کند. داده‌های کد QR به صورت رشته 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 باشد.

کد نمونه برای دریافت کدهای 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));

دستورات جدید

• xrGetTrackableQrCodeANDROID

سازه‌های جدید

• XrTrackableQrCodeاندروید

• بسط XrSystemProperties :

  • ویژگی‌های ردیابی XrSystemQrCodeاندروید

• توسعه‌ی XrTrackableTrackerCreateInfoANDROID :

  • پیکربندی XrTrackableQrCodeاندروید

Enum های جدید

• حالت ردیابی XrQrCode اندروید

ثابت‌های شمارشی جدید

• 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، 05-02-2025 (لوانا چن)

  • توضیحات اولیه افزونه