XR_ANDROID_trackables_qr_code

رشته نام

XR_ANDROID_trackables_qr_code

نوع افزونه

افزونه نمونه

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

709

بازبینی

1

وضعیت تصویب

تصویب‌نشده

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

XR_ANDROID_trackables

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

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

تاریخ آخرین تغییر

2025-02-05

وضعیت 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

نمای کلی

این افزونه امکان ردیابی فیزیکی رمزینه پاسخ‌سریع و رمزگشایی داده‌های رمزینه پاسخ‌سریع را فراهم می‌کند.

اجازه‌ها

برنامه‌های 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 حداکثر تعداد کل رمزینه‌های پاسخ‌سریعی است که می‌توان به‌طور هم‌زمان ردیابی کرد.

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

اگر زمان اجرا از ردیابی رمزینه پاسخ‌سریع پشتیبانی کند، maxQrCodeCount باید حداقل ۱ باشد. اگر زمان اجرا از ردیابی رمزینه پاسخ‌سریع پشتیبانی نکند، maxQrCodeCount باید ۰ باشد.

استفاده معتبر (ضمنی)

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

ردیابی رمزینه‌های پاسخ‌سریع

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

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

اگر XrTrackableTrackerCreateInfoANDROID :: trackableType برابر با XR_TRACKABLE_TYPE_QR_CODE_ANDROID باشد و XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking مقدار XR_FALSE را ازطریق xrGetSystemProperties برگرداند، زمان اجرا باید 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 اندازه لبه رمزینه پاسخ‌سریع را به متر نشان می‌دهد. اگر صفر باشد، زمان اجرا اندازه رمزینه پاسخ‌سریع را به‌صورت آنلاین تخمین می‌زند.

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

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

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

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

استفاده معتبر (ضمنی)

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

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;

شرح‌های شمارشی

• 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 را برگرداند.

استفاده معتبر (ضمنی)

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

استفاده معتبر (ضمنی)

• افزونه XR_ANDROID_trackables_qr_code باید قبل‌از استفاده از XrTrackableQrCodeANDROID فعال شود
• 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));

فرمان‌های جدید

• xrGetTrackableQrCodeANDROID

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

• XrTrackableQrCodeANDROID

• درحال گسترش دادن XrSystemProperties :

  • XrSystemQrCodeTrackingPropertiesANDROID

• درحال گسترش دادن XrTrackableTrackerCreateInfoANDROID :

  • XrTrackableQrCodeConfigurationANDROID

Enums جدید

• XrQrCodeTrackingModeANDROID

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

• 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

مشکلات

سابقه نسخه

• بازبینی ۱، ‎۲۰۲۵-۰۲-۰۵ (Levana Chen)

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