XR_ANDROID_trackables_qr_code

سلسلة الاسم

XR_ANDROID_trackables_qr_code

نوع الإضافة

إضافة مثيل

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

709

المراجعة

1

حالة التصديق

لم تتم المصادقة

الاعتماديات على الإضافات والإصدارات

XR_ANDROID_trackables

حالة الإيقاف النهائي

  • تم إيقافها نهائيًا من خلال الإضافة XR_EXT_spatial_marker_tracking

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

2025-02-05

حالة عنوان IP

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

المساهمون

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

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

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

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

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

يجب أن تعرض بيئة التشغيل القيمة XR_ERROR_FEATURE_UNSUPPORTED إذا كانت قيمة XrTrackableTrackerCreateInfoANDROID :: trackableType هي XR_TRACKABLE_TYPE_QR_CODE_ANDROID وكانت قيمة XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking هي XR_FALSE من خلال xrGetSystemProperties .

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

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

يصف تعداد XrQrCodeTrackingModeANDROID أوضاع التتبُّع المتوافقة لرموز الاستجابة السريعة.

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 التي يتم فيها عرض رمز الاستجابة السريعة القابل للتتبُّع.

يجب أن يعرض وقت التشغيل XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID إذا لم يكن نوع العنصر القابل للتتبُّع في XrTrackableANDROID هو XR_TRACKABLE_TYPE_QR_CODE_ANDROID، أو إذا لم يكن نوع العنصر القابل للتتبُّع في XrTrackableTrackerANDROID هو XR_TRACKABLE_TYPE_QR_CODE_ANDROID .

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

رموز الإرجاع

تم بنجاح

  • 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 على 0.
  • ‫buffer هو مؤشر إلى مصفوفة من char لكتابة بيانات رمز الاستجابة السريعة الذي تم فك ترميزه. إذا لم يكن التطبيق يهتم ببيانات رمز الاستجابة السريعة التي تم فك تشفيرها، يمكنه تمرير nullptr وحذف المكالمة الثانية المكوّنة من مكالمتَين. يتم عرض بيانات رمز الاستجابة السريعة كسلسلة UTF-8 تنتهي بقيمة فارغة.
  • راجِع قسم مَعلمات حجم المخزن المؤقت للحصول على وصف تفصيلي حول استرداد حجم buffer المطلوب.

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

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

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

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

الأوامر الجديدة

بنى جديدة

عمليات التعداد الجديدة

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

  • 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، 2025-02-05 (ليفانا تشين)

    • الوصف الأوّلي للإضافة