XR_EXT_spatial_marker_tracking

سلسلة الاسم

XR_EXT_spatial_marker_tracking

نوع الإضافة

إضافة مثيل

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

744

المراجعة

1

حالة التصديق

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

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

XR_EXT_spatial_entity

المساهمون

رون بيسيمز، Meta
نيهاف جاين، Google
ناتالي فلوري، Meta
يويتشي تاغوتشي، Meta
يين لي، Microsoft
جيمي ألامبارامبيل، ByteDance
تشيبينغ ليو، ByteDance
جون يان، ByteDance

نظرة عامة

تستند هذه الإضافة إلى XR_EXT_spatial_entity وتسمح للتطبيقات برصد العلامات وتتبُّعها في بيئتها. العلامات هي رموز ثنائية الأبعاد قد تتضمّن رموز استجابة سريعة أو رموز استجابة سريعة صغيرة أو علامات ArUco أو علامات AprilTag.

يتم تمثيل العلامة التي يتم تتبّعها ككيان مكاني يتضمّن المكوّنات التالية (أو "التي تتضمّن"):

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

دعم وقت التشغيل

يجب أن تعلن بيئة التشغيل عن توافقها مع إمكانات تتبُّع العلامات المختلفة باستخدام xrEnumerateSpatialCapabilitiesEXT من خلال إدراج أيّ من الإمكانات التالية:

  • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT
  • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT
  • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT
  • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

الإعداد

لتفعيل رصد نوع علامة، يجب أن يمرِّر التطبيق بنية الإعدادات المقابلة إلى xrCreateSpatialContextAsyncEXT .

إعدادات أنواع العلامات

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

يتم تعريف بنية XrSpatialCapabilityConfigurationQrCodeEXT على النحو التالي:

typedef struct XrSpatialCapabilityConfigurationQrCodeEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationQrCodeEXT;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • يجب أن يكون capability XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT .
  • ‫enabledComponentCount هي uint32_t تتضمّن عدد العناصر في enabledComponents .
  • enabledComponents هو مؤشر إلى مصفوفة من المكوّنات التي يجب تفعيلها لهذه الإمكانية.

في حال توفّر رموز الاستجابة السريعة، يجب أن يفعّل وقت التشغيل ميزة تتبُّع رموز الاستجابة السريعة عند تمرير بنية XrSpatialCapabilityConfigurationQrCodeEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs عند استدعاء xrCreateSpatialContextAsyncEXT.

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT إذا لم يتم تعداد XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT بواسطة xrEnumerateSpatialCapabilitiesEXT .

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

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

يتم تعريف بنية XrSpatialCapabilityConfigurationMicroQrCodeEXT على النحو التالي:

typedef struct XrSpatialCapabilityConfigurationMicroQrCodeEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationMicroQrCodeEXT;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • يجب أن يكون capability XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT .
  • ‫enabledComponentCount هي uint32_t تتضمّن عدد العناصر في enabledComponents .
  • enabledComponents هو مؤشر إلى مصفوفة من المكوّنات التي يجب تفعيلها لهذه الإمكانية.

في حال توفّر رموز الاستجابة السريعة الصغيرة، يجب أن يفعّل وقت التشغيل تتبُّع رموز الاستجابة السريعة الصغيرة عند تمرير بنية XrSpatialCapabilityConfigurationMicroQrCodeEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs عند استدعاء xrCreateSpatialContextAsyncEXT .

يجب أن يعرض وقت التشغيل القيمة must XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT إذا لم يتم تعداد XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT بواسطة xrEnumerateSpatialCapabilitiesEXT .

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

علامات ArUco

يتم تعريف بنية XrSpatialCapabilityConfigurationArucoMarkerEXT على النحو التالي:

typedef struct XrSpatialCapabilityConfigurationArucoMarkerEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialMarkerArucoDictEXT         arUcoDict;
} XrSpatialCapabilityConfigurationArucoMarkerEXT;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • يجب أن يكون capability XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT .
  • ‫enabledComponentCount هي uint32_t تتضمّن عدد العناصر في enabledComponents .
  • enabledComponents هو مؤشر إلى مصفوفة من المكوّنات التي يجب تفعيلها لهذه الإمكانية.
  • ‫arUcoDict هو قاموس العلامات المطلوب رصده.

في حال توفّر علامات ArUco، يجب أن يفعّل وقت التشغيل ميزة تتبُّع علامات ArUco عند تمرير بنية XrSpatialCapabilityConfigurationArucoMarkerEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs عند استدعاء xrCreateSpatialContextAsyncEXT.

يجب أن تعرض بيئة التشغيل XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT من xrCreateSpatialContextAsyncEXT إذا كان هناك بنية XrSpatialCapabilityConfigurationArucoMarkerEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs ولكن لم يتم تعداد XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT بواسطة xrEnumerateSpatialCapabilitiesEXT .

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

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

typedef enum XrSpatialMarkerArucoDictEXT {
    XR_SPATIAL_MARKER_ARUCO_DICT_4X4_50_EXT = 1,
    XR_SPATIAL_MARKER_ARUCO_DICT_4X4_100_EXT = 2,
    XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT = 3,
    XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT = 4,
    XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT = 5,
    XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT = 6,
    XR_SPATIAL_MARKER_ARUCO_DICT_5X5_250_EXT = 7,
    XR_SPATIAL_MARKER_ARUCO_DICT_5X5_1000_EXT = 8,
    XR_SPATIAL_MARKER_ARUCO_DICT_6X6_50_EXT = 9,
    XR_SPATIAL_MARKER_ARUCO_DICT_6X6_100_EXT = 10,
    XR_SPATIAL_MARKER_ARUCO_DICT_6X6_250_EXT = 11,
    XR_SPATIAL_MARKER_ARUCO_DICT_6X6_1000_EXT = 12,
    XR_SPATIAL_MARKER_ARUCO_DICT_7X7_50_EXT = 13,
    XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT = 14,
    XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT = 15,
    XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT = 16,
    XR_SPATIAL_MARKER_ARUCO_DICT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialMarkerArucoDictEXT;

قاموس ArUco المحدّد مسبقًا والمتوافق:

أوصاف القيم المُعدَّدة

  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_4X4_50_EXT: قاموس علامات Aruco بحجم 4 × 4 بكسل مع 50 معرّفًا
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_4X4_100_EXT — قاموس علامات Aruco بحجم 4 × 4 بكسل يتضمّن 100 معرّف.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_4X4_250_EXT: قاموس علامات Aruco بحجم 4 × 4 بكسل يتضمّن 250 معرّفًا.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_4X4_1000_EXT — قاموس علامات Aruco بحجم 4 × 4 بكسل يتضمّن 1,000 معرّف.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT: قاموس علامات Aruco المكوّنة من 5 × 5 بكسل مع 50 معرّفًا.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_5X5_100_EXT: قاموس علامات Aruco بحجم 5 × 5 بكسل يتضمّن 100 معرّف.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_5X5_250_EXT: قاموس علامات Aruco المكوّنة من 5 × 5 بكسل مع 250 معرّفًا.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_5X5_1000_EXT — قاموس علامات Aruco بحجم 5 × 5 بكسل يتضمّن 1,000 معرّف.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_6X6_50_EXT: قاموس علامات Aruco بحجم 6 × 6 بكسل يتضمّن 50 معرّفًا.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_6X6_100_EXT: قاموس علامات Aruco بحجم 6 × 6 بكسل يتضمّن 100 معرّف.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_6X6_250_EXT: قاموس علامات Aruco بحجم 6 × 6 بكسل مع 250 معرّفًا.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_6X6_1000_EXT: قاموس علامات Aruco بحجم 6 × 6 بكسل مع 1,000 معرّف
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_7X7_50_EXT: قاموس علامات Aruco بحجم 7 × 7 بكسل مع 50 معرّفًا
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_7X7_100_EXT — قاموس علامات Aruco بحجم 7 × 7 بكسل يتضمّن 100 معرّف.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_7X7_250_EXT: قاموس علامات Aruco بحجم 7 × 7 بكسل يتضمّن 250 معرّفًا.
  • ‫XR_SPATIAL_MARKER_ARUCO_DICT_7X7_1000_EXT — قاموس علامات Aruco بحجم 7 × 7 بكسل مع 1,000 معرّف.
AprilTags

يتم تعريف بنية XrSpatialCapabilityConfigurationAprilTagEXT على النحو التالي:

typedef struct XrSpatialCapabilityConfigurationAprilTagEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialMarkerAprilTagDictEXT      aprilDict;
} XrSpatialCapabilityConfigurationAprilTagEXT;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • يجب أن يكون capability XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT .
  • ‫enabledComponentCount هي uint32_t تتضمّن عدد العناصر في enabledComponents .
  • enabledComponents هو مؤشر إلى مصفوفة من المكوّنات التي يجب تفعيلها لهذه الإمكانية.
  • ‫aprilDict هو قاموس العلامات المطلوب رصده.

في حال توفُّر دعم AprilTag، يجب أن يفعّل وقت التشغيل تتبُّع AprilTag عند تمرير بنية XrSpatialCapabilityConfigurationAprilTagEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs عند استدعاء xrCreateSpatialContextAsyncEXT.

يجب أن تعرض بيئة التشغيل XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT من xrCreateSpatialContextAsyncEXT إذا كان هناك بنية XrSpatialCapabilityConfigurationAprilTagEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs ولكن لم يتم تعداد XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT بواسطة xrEnumerateSpatialCapabilitiesEXT .

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

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

typedef enum XrSpatialMarkerAprilTagDictEXT {
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_16H5_EXT = 1,
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_25H9_EXT = 2,
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H10_EXT = 3,
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT = 4,
    XR_SPATIAL_MARKER_APRIL_TAG_DICT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialMarkerAprilTagDictEXT;

قائمة قواميس AprilTag المحدّدة مسبقًا والمتوافقة:

أوصاف القيم المُعدَّدة

  • ‫XR_SPATIAL_MARKER_APRIL_TAG_DICT_16H5_EXT — 4 × 4 بت، الحد الأدنى لمسافة هامينغ بين أي رمزين = 5، 30 رمزًا
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_25H9_EXT — 5 × 5 بت، الحدّ الأدنى لمسافة هامينغ بين أي رمزين = 9، 35 رمزًا
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H10_EXT — 6 × 6 بت، الحدّ الأدنى لمسافة هامينغ بين أي رمزين يساوي 10، وعدد الرموز 2320.
  • XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT — 6 × 6 بت، الحدّ الأدنى لمسافة هامينغ بين أي رمزين يساوي 11، وعدد الرموز 587.

إعدادات العلامات الاختيارية

يجب أن تستدعي التطبيقات xrEnumerateSpatialCapabilityFeaturesEXT للحصول على قائمة بالميزات الاختيارية المتوافقة.

راجِع XrSpatialCapabilityFeatureEXT للحصول على قائمة كاملة بجميع ميزات إمكانات تحديد الموقع المكاني التي تتيحها أي إضافة.

حجم العلامة

يتم تعريف بنية XrSpatialMarkerSizeEXT على النحو التالي:

typedef struct XrSpatialMarkerSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              markerSideLength;
} XrSpatialMarkerSizeEXT;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • markerSideLength هو حجم جميع العلامات بالمتر.

إذا تم تعداد XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT بواسطة xrEnumerateSpatialCapabilityFeaturesEXT لإحدى الإمكانات، وإذا ربط التطبيق XrSpatialMarkerSizeEXT ببنية الإعدادات المقابلة لهذه الإمكانية، يجب أن يفترض وقت التشغيل أنّ جميع العلامات التي تم رصدها لها عرض وارتفاع يبلغ markerSideLength . يسمح توفير هذه المعلومات لوقت التشغيل بعرض وضع وحجم أكثر دقة. يجب ربط هذه البنية بسلسلة next من XrSpatialCapabilityConfigurationQrCodeEXT أو XrSpatialCapabilityConfigurationMicroQrCodeEXT أو XrSpatialCapabilityConfigurationArucoMarkerEXT أو XrSpatialCapabilityConfigurationAprilTagEXT.

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

تحسين العلامات الثابتة

يتم تعريف بنية XrSpatialMarkerStaticOptimizationEXT على النحو التالي:

typedef struct XrSpatialMarkerStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticMarker;
} XrSpatialMarkerStaticOptimizationEXT;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • تشير optimizeForStaticMarker إلى ما إذا كان من المتوقّع ألا تتحرّك جميع العلامات في المساحة.

إذا تم تعداد XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT بواسطة xrEnumerateSpatialCapabilityFeaturesEXT لإحدى الإمكانات، وإذا ربط التطبيق XrSpatialMarkerStaticOptimizationEXT ببنية الإعدادات المقابلة لهذه الإمكانية، يجب أن يفترض وقت التشغيل أنّ جميع العلامات التي تم رصدها ثابتة إذا تم ضبط optimizeForStaticMarker على XR_TRUE . ويسمح ذلك لوقت التشغيل بإنشاء وضع وحجم أكثر دقةً. يجب ربط هذه البنية بسلسلة next من XrSpatialCapabilityConfigurationQrCodeEXT أو XrSpatialCapabilityConfigurationMicroQrCodeEXT أو XrSpatialCapabilityConfigurationArucoMarkerEXT أو XrSpatialCapabilityConfigurationAprilTagEXT.

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

المكوّنات المضمونة

يجب أن يوفّر وقت التشغيل الذي يتوافق مع XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT أو XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT أو XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT أو XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT ما يلي من المكوّنات المكانية كمكوّنات مضمونة لجميع الكيانات التي يتم رصدها من خلال هذه الإمكانات، ويجب إدراجها في xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

مكوّن العلامة

بيانات المكوّن

يتم تعريف بنية XrSpatialMarkerDataEXT على النحو التالي:

typedef struct XrSpatialMarkerDataEXT {
    XrSpatialCapabilityEXT    capability;
    uint32_t                  markerId;
    XrSpatialBufferEXT        data;
} XrSpatialMarkerDataEXT;

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

  • ‫capability هو XrSpatialCapabilityEXT الذي رصد العلامة.
  • ‫markerId هو المعرّف المرمّز من العلامة. بالنسبة إلى علامات ArUco وAprilTag، يجب أن يكون هذا الحقل صالحًا وأن يتم ملؤه برقم التعريف المشفّر. بالنسبة إلى رموز الاستجابة السريعة، يجب أن تكون قيمة هذا الحقل صفرًا.
  • ‫data هو معرّف المخزن المؤقت ونوع المعلومات الإضافية الواردة في العلامة.

تتيح السمتان XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT وXR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT بيانات إضافية. إذا كان capability أحد هذه الرموز:

  • إذا تمكّن وقت التشغيل من فك ترميز البيانات الخاصة بالعلامة بنجاح، يجب ضبط نوع المخزن المؤقت data على XR_SPATIAL_BUFFER_TYPE_UINT8_EXT أو XR_SPATIAL_BUFFER_TYPE_STRING_EXT، وذلك استنادًا إلى البيانات الواردة في العلامة. يجب أن يضبط وقت التشغيل أيضًا رقم تعريف صالحًا للمخزن المؤقت في data يمكن للتطبيق استخدامه مع الدالة المناسبة xrGetSpatialBuffer* للحصول على البيانات.
  • إذا لم يسبق لوقت التشغيل فك ترميز بيانات العلامة، يجب ضبط معرّف المخزن المؤقت data على XR_NULL_SPATIAL_BUFFER_ID_EXT ونوع المخزن المؤقت على XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT .

لا تتوافق XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT وXR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT مع البيانات الإضافية، ويجب أن يضبط وقت التشغيل معرّف المخزن المؤقت data على XR_NULL_SPATIAL_BUFFER_ID_EXT.

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

بنية قائمة المكوّنات لطلب البيانات

يتم تعريف بنية XrSpatialComponentMarkerListEXT على النحو التالي:

typedef struct XrSpatialComponentMarkerListEXT {
    XrStructureType            type;
    void*                      next;
    uint32_t                   markerCount;
    XrSpatialMarkerDataEXT*    markers;
} XrSpatialComponentMarkerListEXT;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
  • markerCount هو عدد العناصر في العضو markers.
  • ‫markers هي مصفوفة من XrSpatialMarkerDataEXT .

يمكن للتطبيق الاستعلام عن مكوّن العلامة الخاص بالكيانات المكانية في XrSpatialSnapshotEXT من خلال إضافة XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT في XrSpatialComponentDataQueryConditionEXT :: componentTypes وإضافة XrSpatialComponentMarkerListEXT إلى سلسلة المؤشر التالية في XrSpatialComponentDataQueryResultEXT .

يجب أن تعرض بيئة التشغيل القيمة XR_ERROR_VALIDATION_FAILURE من xrQuerySpatialComponentDataEXT إذا كانت XrSpatialComponentMarkerListEXT في السلسلة التالية من XrSpatialComponentDataQueryResultEXT :: next ولكن لم يتم تضمين XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT في XrSpatialComponentDataQueryConditionEXT :: componentTypes .

يجب أن تعرض بيئة التشغيل القيمة XR_ERROR_SIZE_INSUFFICIENT من xrQuerySpatialComponentDataEXT إذا كانت قيمة markerCount أقل من XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

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

الإعداد

إذا تم تعداد XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT في XrSpatialCapabilityComponentTypesEXT :: componentTypes لبعض الإمكانات، يمكن لأحد التطبيقات تفعيلها من خلال تضمين القيمة المُعدَّدة في قائمة XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents الخاصة ببنية XrSpatialCapabilityConfigurationBaseHeaderEXT المشتقة من الإمكانية التي تتوافق مع هذا المكوّن.

لا يتطلّب هذا المكوّن أي إعدادات خاصة ليتم تضمينه في سلسلة XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

مكوّن ثنائي الأبعاد محدود

يوفّر المكوّن الثنائي الأبعاد المحدود مركز العلامة ونطاقها الممثَّلة بالعنصر الذي تظهر عليه. اطّلِع على Bounded 2D لمزيد من التفاصيل حول مكوّن Bounded 2D.

يجب أن يشير XrSpatialBounded2DDataEXT :: center إلى مركز العلامة. عند النظر إلى الوجه الأمامي للعلامة، يجب أن يشير المحور X إلى اليمين، ويجب أن يشير المحور Y إلى أعلى العلامة. يجب أن يتبع وقت التشغيل الأسلوب المتّبع في نظام الإحداثيات اليمنى، وبالتالي يخرج المحور Z من الوجه الأمامي للعلامة. يعني هذا أنّ العلامة التي تتضمّن موضعًا {0, 0, 0} ودورانًا {0, 0, 0, 1} (بدون دوران) ومدى {1, 1} تشير إلى علامة تبلغ أبعادها مترًا واحدًا × مترًا واحدًا، وتتمركز في {0, 0, 0} مع توجيه متجهها العمودي للوجه الأمامي نحو الاتجاه +Z في مساحة المكوّن.

يظهر أدناه تمثيل لاتجاه العلامة.

xr ml marker understanding axis

الشكل 25. علامة رمز الاستجابة السريعة مع محور

رموز الاختبار

يجب أن يكون مستوى X-Y للرموز التالية داخل المستند وأن يشير المحور Z إلى المشاهد. يجب أن يظهر موضع بدء المحور في وسط كل علامة. يجب أن يشير المحور السيني إلى اليمين، ويجب أن يشير المحور الصادي إلى أعلى المستند.

ext marker tracking qr

الشكل 26 رمز استجابة سريعة يتضمّن النص OpenXR

ext marker tracking apriltag

الشكل 27 ‫AprilTag XR_SPATIAL_MARKER_APRIL_TAG_DICT_36H11_EXT برقم التعريف 42

ext marker tracking aruco

الشكل 28. علامة ArUco XR_SPATIAL_MARKER_ARUCO_DICT_5X5_50_EXT التي تحمل المعرّف 43

مثال على الشفرة

ضبط إعدادات إمكانية تتبُّع رمز الاستجابة السريعة

يوضّح نموذج الرمز البرمجي التالي كيفية ضبط إمكانية تتبُّع رمز الاستجابة السريعة عند إنشاء سياق مكاني.

// Check if marker tracking capability is supported
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT) == capabilities.end()) {
  return;
}

uint32_t featureCount = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT, 0, &featureCount, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(featureCount);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT, featureCount, &featureCount, capabilityFeatures.data()));

bool supportsFixedMarkerSize = std::find(capabilityFeatures.begin(), capabilityFeatures.end(), XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT) != capabilityFeatures.end();

// Create a spatial context
XrSpatialContextEXT spatialContext{};

// Enable the 2 guaranteed components of the qr code tracking capability
std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT,
};
XrSpatialCapabilityConfigurationQrCodeEXT markerConfiguration{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_QR_CODE_EXT};
markerConfiguration.capability = XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT;
markerConfiguration.enabledComponentCount = static_cast<uint32_t>(enabledComponents.size());
markerConfiguration.enabledComponents = enabledComponents.data();

// only chained if features.markerSideLength is true.
XrSpatialMarkerSizeEXT markerSize{XR_TYPE_SPATIAL_MARKER_SIZE_EXT};
markerSize.markerSideLength = 0.10f;
if (supportsFixedMarkerSize) {
  markerConfiguration.next = &markerSize;
}


std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
  reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&markerConfiguration),
};

XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
XrFutureEXT createContextFuture;
CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

waitUntilReady(createContextFuture);

XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
if (completion.futureResult != XR_SUCCESS) {
  return;
}

spatialContext = completion.spatialContext;

// ...
// Discovery entities with the spatial context
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

استكشاف الكيانات المكانية وبيانات عناصر طلب البحث

يوضّح نموذج الرمز التالي كيفية العثور على عناصر مكانية لسياق تم إعداده باستخدام XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT وطلب بيانات المكوّنات الخاصة به.

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the bounded2D and marker component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2D(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT bounded2DList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    bounded2DList.boundCount = bounded2D.size();
    bounded2DList.bounds = bounded2D.data();
    queryResult.next = &bounded2DList;

    std::vector<XrSpatialMarkerDataEXT> markers;
    XrSpatialComponentMarkerListEXT markerList{XR_TYPE_SPATIAL_COMPONENT_MARKER_LIST_EXT};
    markers.resize(queryResult.entityIdCountOutput);
    markerList.markerCount = markers.size();
    markerList.markers = markers.data();
    bounded2DList.next = &markerList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] != XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        continue;
      }

      // 2D bounds for entity entityIds[i] is bounded2D[i].extents centered on bounded2D[i].center.

      if (markers[i].capability == XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT) {
        // Check if marker data has been decoded.
        if (markers[i].data.bufferId != XR_NULL_SPATIAL_BUFFER_ID_EXT) {
          if (markers[i].data.bufferType == XR_SPATIAL_BUFFER_TYPE_STRING_EXT) {
            // Qr Code data can be queried using
            // XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
            // info.bufferId = markers[i].data.bufferId;
            // xrGetSpatialBufferStringEXT(completion.snapshot, &getInfo, ...)
          } else if (markers[i].data.bufferType == XR_SPATIAL_BUFFER_TYPE_UINT8_EXT) {
            // Qr Code data can be queried using
            // XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
            // info.bufferId = markers[i].data.bufferId;
            // xrGetSpatialBufferUint8(completion.snapshot, &getInfo, ...)
          }
        }
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

بنى جديدة

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

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

  • XR_EXT_SPATIAL_MARKER_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_marker_tracking_SPEC_VERSION

  • تمديد XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT
    • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT
    • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT
    • XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

  • تمديد XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

  • تمديد XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

  • تمديد XrStructureType :

    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_APRIL_TAG_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ARUCO_MARKER_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_MICRO_QR_CODE_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_QR_CODE_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MARKER_LIST_EXT
    • XR_TYPE_SPATIAL_MARKER_SIZE_EXT
    • XR_TYPE_SPATIAL_MARKER_STATIC_OPTIMIZATION_EXT

سجلّ الإصدارات

  • المراجعة 1، ‎29-07-2024 (رون بيسيمز، Meta)

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