XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

نوع الإضافة

إضافة مثيل

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

709

المراجعة

1

حالة التصديق

لم تتم المصادقة عليها

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

XR_ANDROID_trackables

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

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

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

2025-02-05

حالة الملكية الفكرية

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

المساهمون

"كريستوفر دوير"، 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 إذا كانت قيمة trackableType في XrTrackableTrackerCreateInfoANDROID هي XR_TRACKABLE_TYPE_QR_CODE_ANDROID وكانت قيمة supportsQrCodeTracking في XrSystemQrCodeTrackingPropertiesANDROID تعرض القيمة 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 .

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

رموز الإرجاع

Success

  • 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، بتاريخ 5 فبراير 2025 (ليفانا تشين)

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