برنامه افزودنی OpenXR XR_ANDROID_trackables_qr_code

رشته نام

XR_ANDROID_trackables_qr_code

نوع پسوند

پسوند نمونه

شماره برنامه افزودنی ثبت شده

460

تجدید نظر

1

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

XR_ANDROID_trackables

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

05-02-2025

وضعیت IP

هیچ ادعای IP شناخته شده ای وجود ندارد.

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

کریستوفر دور، گوگل

لوانا چن، گوگل

جارد فایندر، گوگل

اسپنسر کوین، گوگل

نیهاو جین، گوگل

دیگو تیپالدی، گوگل

کن مکی، گوگل

دانیل گوتنبرگ، کوالکام

نمای کلی

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

مجوزها

برنامه‌های Android باید مجوز «android.permission.SCENE_UNDERSTANDING» را داشته باشند که در مانیفست آنها فهرست شده است، زیرا این برنامه افزودنی به «XR_ANDROID_trackables» بستگی دارد و هندسه محیط را نشان می‌دهد. مجوز «android.permission.SCENE_UNDERSTANDING» یک مجوز خطرناک در نظر گرفته می شود.
(سطح حفاظت: خطرناک)

قابلیت سیستم را بررسی کنید

XrSystemQrCodeTrackingPropertiesANDROID

ساختار XrSystemQrCodeTrackingPropertiesANDROID به صورت زیر تعریف می شود:

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint32_t           maxQrCodeCount;
} XrSystemQrCodeTrackingPropertiesANDROID;

توضیحات اعضا

• type XrStructureType این ساختار است.
• next NULL یا اشاره گر به ساختار بعدی در زنجیره ساختار است. چنین ساختاری در هسته OpenXR یا این پسوند تعریف نشده است.
• supportsQrCodeTracking یک XrBool32 است که نشان می دهد آیا سیستم فعلی قابلیت ردیابی کد QR را دارد یا خیر.
• supportsQrCodeSizeEstimation یک XrBool32 است که نشان می دهد آیا سیستم فعلی تخمین اندازه کد QR را ارائه می دهد یا خیر.
• maxQrCodeCount حداکثر تعداد کل کدهای QR است که می توان همزمان ردیابی کرد.

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

اگر یک زمان اجرا از ردیابی کد QR پشتیبانی می کند، باید در هر زمان معین از کدهای QR ردیابی شده maxQrCodeCount پشتیبانی کند.

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

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

• پسوند 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 XrTrackableTrackerANDROID مشخص کردن XR_TRACKABLE_TYPE_QR_CODE_ANDROID به عنوان نوع قابل ردیابی در XrTrackableTrackerCreateInfoANDROID::trackableType برای ردیابی کدهای QR، یک XrTrackableTrackerANDROID ایجاد کند.

اگر XrTrackableTrackerCreateInfoANDROID::trackableType XR_TRACKABLE_TYPE_QR_CODE_ANDROID XrSystemQrCodeTrackingProperties و XrSystemQrCodeTrackingPropertiesANDROID::supportsQrCodeTracking باشد، زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED باشد XR_FALSE xrGetSystemProperties .

XrTrackableQrCodeConfigurationANDROID

ساختار XrTrackableQrCodeConfigurationANDROID به صورت زیر تعریف می شود:

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType               type;
    const 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 تنظیم کند تا میزان استفاده از تخمین اندازه را نشان دهد. در غیر این صورت، برنامه باید XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize روی یک مقدار مثبت تنظیم کند وگرنه XR_ERROR_VALIDATION_FAILURE برگردانده می شود.

زمان اجرا باید خروجی xrGetAllTrackablesANDROID را فیلتر کند تا با trackingMode و qrCodeEdgeSize مطابقت داشته باشد.

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

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

XrQrCodeTrackingModeANDROID

شماره XrQrCodeTrackingModeANDROID حالت های ردیابی پشتیبانی شده کدهای QR را توصیف می کند.

typedef enum XrQrCodeTrackingModeANDROID {
    XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID = 0,
    XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_QR_CODE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrQrCodeTrackingModeANDROID;

| شمارش | توضیحات - | XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID | کد QR ثابت است و حرکت نمی کند. ' | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | کد QR پویا است و ممکن است حرکت کند. |

کدهای QR را دریافت کنید

xrGetTrackableQrCodeANDROID

تابع 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 باشد

XrTrackableQrCodeANDROID

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

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

• پسوند XR_ANDROID_trackables_qr_code باید قبل از استفاده از XrTrackableQrCodeANDROID فعال شود
• type باید XR_TYPE_TRACKABLE_QR_CODE_ANDROID باشد
• next باید NULL یا یک اشاره گر معتبر به ساختار بعدی در یک زنجیره ساختار باشد
• 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);
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    qrCodes[i].type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID;
    qrCodes[i].next = nullptr;
    qrCodes[i].bufferCountOutput = 0;
    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

شمارش XrStructureType با:

• XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
• XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
• XR_TYPE_TRACKABLE_QR_CODE_ANDROID

شمارش XrTrackableTypeANDROID با:

• XR_TRACKABLE_TYPE_QR_CODE_ANDROID

فهرست های جدید

• XrQrCodeTrackingModeANDROID

ساختارهای جدید

• XrSystemQrCodeTrackingPropertiesANDROID
• XrTrackableQrCodeConfigurationANDROID
• XrTrackableQrCodeANDROID

توابع جدید

• xrGetTrackableQrCodeANDROID

مسائل

تاریخچه نسخه

• بازبینی 1، 05-02-2025 (لوانا چن)
  • توضیحات پسوند اولیه

---

OpenXR™ و لوگوی OpenXR علائم تجاری متعلق به The Khronos Group Inc. هستند و به عنوان یک علامت تجاری در چین، اتحادیه اروپا، ژاپن و بریتانیا ثبت شده اند.