إضافة XR_ANDROID_trackables_qr_code OpenXR

سلسلة الاسم

XR_ANDROID_trackables_qr_code

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

460

المراجعة

1

متطلبات الإضافة والإصدار

XR_ANDROID_trackables

تاريخ آخر تعديل

2025-02-05

حالة عنوان IP

ما مِن مطالبات معروفة بشأن الملكية الفكرية.

المساهمون

كريستوفر دور، Google

ليفانا تشين، Google

Jared Finder, Google

سبنسر كوين، Google

"نيهاف جاين"، Google

دييغو تيبالدي، Google

كين ماكاي، Google

"دانيال غوتنبرغ"، شركة Qualcomm

نظرة عامة

يتيح هذا الامتداد تتبُّع رموز الاستجابة السريعة المادية وفك تشفير بيانات رموز الاستجابة السريعة.

فحص إمكانات النظام

XrSystemQrCodeTrackingPropertiesANDROID

يتم تحديد بنية XrSystemQrCodeTrackingPropertiesANDROID على النحو التالي:

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

أوصاف الأعضاء

• type هو XrStructureType هذا الهيكل.
• next هو NULL أو مؤشر إلى البنية التالية في سلسلة بنيات. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
• ‫supportsQrCodeTracking هو XrBool32 يشير إلى ما إذا كان النظام الحالي يوفّر إمكانية تتبُّع رمز الاستجابة السريعة.
• ‫supportsQrCodeSizeEstimation هو XrBool32 يشير إلى ما إذا كان النظام الحالي يوفّر تقديرًا لحجم رمز الاستجابة السريعة.
• maxQrCodeCount هو الحدّ الأقصى لعدد رموز الاستجابة السريعة التي يمكن تتبُّعها في الوقت نفسه.

يمكن لأي تطبيق التحقّق مما إذا كان النظام قادرًا على تتبُّع رموز الاستجابة السريعة من خلال توسيع XrSystemProperties باستخدام بنية XrSystemQrCodeTrackingPropertiesANDROID عند استدعاء xrGetSystemProperties. يجب أن تعرض بيئة التشغيل القيمة XR_ERROR_FEATURE_UNSUPPORTED لإنشاء أداة تتبُّع رمز الاستجابة السريعة إذا وفقط إذا كانت قيمة supportsQrCodeTracking هي XR_FALSE.

إذا كان وقت التشغيل يتيح تتبُّع رموز الاستجابة السريعة، يجب أن يتيح تتبُّع maxQrCodeCount رموز الاستجابة السريعة في أي وقت.

إذا كانت بيئة التشغيل تتيح تقدير حجم رمز الاستجابة السريعة، يمكن للتطبيق ضبط 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 أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنى

تتبُّع رموز الاستجابة السريعة

تضيف هذه الإضافة XR_TRACKABLE_TYPE_QR_CODE_ANDROID إلى XrTrackableTypeANDROID.

قد ينشئ التطبيق XrTrackableTrackerANDROID من خلال استدعاء xrCreateTrackableTrackerANDROID وتحديد XR_TRACKABLE_TYPE_QR_CODE_ANDROID كنوع قابل للتتبّع في XrTrackableTrackerCreateInfoANDROID::trackableType لتتبُّع رموز QR.

يجب أن تعرض بيئة التشغيل القيمة XR_ERROR_FEATURE_UNSUPPORTED إذا كانت قيمة XrTrackableTrackerCreateInfoANDROID::trackableType هي XR_TRACKABLE_TYPE_QR_CODE_ANDROID وعرضت XrSystemQrCodeTrackingPropertiesANDROID::supportsQrCodeTracking القيمة 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 إلى حجم حافة رمز الاستجابة السريعة بالأمتار. إذا كان صفرًا، سيتم تقدير حجم رمز الاستجابة السريعة على الإنترنت.

يجب أن يضبط التطبيق إعدادًا صالحًا من خلال إضافة XrTrackableQrCodeConfigurationANDROID إلى السلسلة التالية من XrTrackableTrackerCreateInfoANDROID. بخلاف ذلك، يجب أن يعرض وقت التشغيل القيمة XR_ERROR_VALIDATION_FAILURE.

إذا كانت بيئة التشغيل تتيح تقدير حجم رمز الاستجابة السريعة، يمكن للتطبيق ضبط 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 أوضاع التتبُّع المتوافقة لرموز الاستجابة السريعة.

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;

| Enum | Description XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID ' | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | رمز الاستجابة السريعة ديناميكي وقد يتحرّك. |

الحصول على رموز الاستجابة السريعة

xrGetTrackableQrCodeANDROID

يتم تعريف الدالة xrGetTrackableQrCodeANDROID على النحو التالي:

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

أوصاف المَعلمات

• tracker هو XrTrackableTrackerANDROID الذي سيتم البحث فيه.
• getInfo هو XrTrackableGetInfoANDROID الذي يتضمّن المعلومات المستخدَمة للحصول على رمز الاستجابة السريعة القابل للتتبُّع.
• ‫qrCodeOutput هو مؤشر إلى بنية XrTrackableQrCodeANDROID التي يتم فيها عرض رمز الاستجابة السريعة القابل للتتبُّع.

يجب أن تعرض وقت التشغيل القيمة XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID إذا لم يكن نوع العنصر القابل للتتبّع XrTrackableANDROID هو XR_TRACKABLE_TYPE_QR_CODE_ANDROID، أو إذا لم يكن نوع العنصر القابل للتتبّع XrTrackableTrackerANDROID هو XR_TRACKABLE_TYPE_QR_CODE_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 لرمز الاستجابة السريعة.
• ‫lastUpdatedTime هو XrTime لآخر تعديل على رمز الاستجابة السريعة.
• ‫centerPose هو XrPosef لرمز الاستجابة السريعة الذي يقع في XrTrackableGetInfoANDROID::baseSpace. يقع رمز الاستجابة السريعة في المستوى XZ، حيث يشير المحور X إلى يمين رمز الاستجابة السريعة، ويشير المحور Z إلى أسفله.
• extents هو أبعاد XrExtent2Df لرمز الاستجابة السريعة. يقع حدّ المربّع المحيط عند النقاط: centerPose +/- (extents / 2).
• bufferCapacityInput هي إمكانية buffer أو 0 في استرداد الإمكانية المطلوبة.
• bufferCountOutput إذا كانت قيمة bufferCapacityInput هي 0، سيكتب وقت التشغيل حجم المخزن المؤقت المطلوب في bufferCountOutput. بخلاف ذلك، تحتوي على إجمالي العناصر المكتوبة في buffer.
• ‫buffer هو مؤشر إلى مصفوفة من char لكتابة بيانات رمز الاستجابة السريعة الذي تم فك ترميزه. يمكن للتطبيق تمرير nullptr لتحديد حجم المخزن المؤقت المطلوب أو ما إذا كان سيطلب بيانات فك ترميز رمز الاستجابة السريعة. يتم عرض بيانات رمز الاستجابة السريعة كسلسلة UTF-8 تنتهي بقيمة فارغة.
• راجِع قسم مَعلمات حجم المخزن المؤقت للحصول على وصف تفصيلي حول كيفية استرداد حجم buffer المطلوب.

الاستخدام الصحيح (الضمني)

• يجب تفعيل إضافة XR_ANDROID_trackables_qr_code قبل استخدام XrTrackableQrCodeANDROID
• يجب أن يكون type XR_TYPE_TRACKABLE_QR_CODE_ANDROID
• يجب أن تكون قيمة next NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنى
• يجب أن تكون قيمة trackingState صالحة XrTrackingStateANDROID
• إذا لم تكن قيمة bufferCapacityInput هي 0، buffer يجب أن يكون مؤشرًا إلى مصفوفة من قيم bufferCapacityInput char

مثال على الرمز البرمجي للحصول على رموز استجابة سريعة قابلة للتتبّع

يوضّح نموذج الرمز البرمجي التالي كيفية الحصول على رموز استجابة سريعة قابلة للتتبّع.

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

ثوابت التعداد الجديدة

تمت إضافة ما يلي إلى تعداد 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، 2025-02-05 (Levana Chen)
  • وصف الإضافة الأوّلي

‫OpenXR™ وشعار OpenXR هما علامتان تجاريتان مملوكتان لشركة The Khronos Group Inc. ومسجّلتان كعلامة تجارية في الصين والاتحاد الأوروبي واليابان والمملكة المتحدة.