XR_ANDROID_trackables_marker

سلسلة الاسم

XR_ANDROID_trackables_marker

نوع الإضافة

إضافة مثيل

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

708

المراجعة

1

حالة التصديق

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

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

XR_ANDROID_trackables

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

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

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

2025-07-23

حالة عنوان IP

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

المساهمون

كريستوفر دور، Google
دييغو تيبالدي، Google
ليفانا تشين، Google
جاريد فايندر، Google
سبنسر كوين، Google
نيهاف جاين، Google
كين ماكاي، Google
دانيال غوتنبرغ، Qualcomm

نظرة عامة

يتيح هذا الامتداد تتبُّع العلامات المادية، كما يتيح للتطبيقات ربط محتوى الواقع الممتد بالعلامات المادية بطريقة فعّالة.

يتوافق الامتداد مع أنواع العلامات المعروفة، وتحديدًا علامات ArUco وApril. تتيح أوقات التشغيل إمكانية تقدير حجم العلامة بشكل اختياري.

الأذونات

يجب أن تتضمّن تطبيقات Android حتماً الإذن android.permission.SCENE_UNDERSTANDING_COARSE في ملف البيان الخاص بها لأنّ هذا الامتداد يعتمد على XR_ANDROID_trackables ويعرض هندسة البيئة. يُعدّ الإذن android.permission.SCENE_UNDERSTANDING_COARSE إذنًا خطيرًا، أي يجب أن تطلب التطبيقات الإذن بشكلٍ صريح.

(مستوى الحماية: خطير)

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

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

typedef struct XrSystemMarkerTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsMarkerTracking;
    XrBool32           supportsMarkerSizeEstimation;
    uint16_t           maxMarkerCount;
} XrSystemMarkerTrackingPropertiesANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة. لمزيد من التفاصيل حول سلسلة البنية، راجِع البنية التي يتم توسيعها ( XrSystemProperties ).
  • ‫supportsMarkerTracking هي XrBool32 تشير إلى ما إذا كان النظام الحالي يوفّر إمكانية تتبُّع العلامات.
  • ‫supportsMarkerSizeEstimation هي XrBool32 تشير إلى ما إذا كان النظام الحالي يوفّر تقديرًا لحجم العلامة.
  • ‫maxMarkerCount هو الحد الأقصى لعدد العلامات التي يمكن لوقت التشغيل تتبُّعها في الوقت نفسه.

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

إذا كان وقت التشغيل يتيح تتبُّع العلامات، يجب أن تكون قيمة maxMarkerCount 1 على الأقل.

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

علامات التتبُّع

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

ينشئ التطبيق XrTrackableTrackerANDROID من خلال استدعاء xrCreateTrackableTrackerANDROID وتحديد XR_TRACKABLE_TYPE_MARKER_ANDROID كنوع العنصر القابل للتتبُّع في XrTrackableTrackerCreateInfoANDROID :: trackableType، بالإضافة إلى ضبط إعدادات صالحة من خلال إضافة XrTrackableMarkerConfigurationANDROID إلى السلسلة التالية من XrTrackableTrackerCreateInfoANDROID .

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

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

typedef struct XrTrackableMarkerConfigurationANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrTrackableMarkerTrackingModeANDROID       trackingMode;
    uint32_t                                   databaseCount;
    const XrTrackableMarkerDatabaseANDROID*    databases;
} XrTrackableMarkerConfigurationANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • ‫trackingMode هو XrTrackableMarkerTrackingModeANDROID يشير إلى الوضع المطلوب للتتبُّع.
  • ‫databaseCount هو uint32_t يصف عدد العناصر في مصفوفة databases.
  • ‫databases هو مؤشر إلى مصفوفة من XrTrackableMarkerDatabaseANDROID، يحتوي كل منها على العلامات المطلوبة من قاموس معيّن لتتبُّعها.

يجب أن يضبط التطبيق إعدادًا صالحًا من خلال إضافة XrTrackableMarkerConfigurationANDROID إلى سلسلة XrTrackableTrackerCreateInfoANDROID :: next عند استدعاء xrCreateTrackableTrackerANDROID مع ضبط XrTrackableTrackerCreateInfoANDROID :: trackableType على XR_TRACKABLE_TYPE_MARKER_ANDROID . بخلاف ذلك، إذا تم ضبط نوع أداة التتبُّع على النحو الوارد أعلاه ولكن لم يكن هيكل الإعدادات متوفّرًا أو صالحًا، يجب أن تعرض وقت التشغيل القيمة XR_ERROR_VALIDATION_FAILURE .

إذا كان وقت التشغيل يتيح تقدير حجم العلامة، يمكن للتطبيق ضبط XrTrackableMarkerDatabaseEntryANDROID :: edgeSize على 0 في XrTrackableMarkerDatabaseANDROID :: entries للإشارة إلى استخدام تقدير الحجم. بخلاف ذلك، على التطبيق ضبط XrTrackableMarkerDatabaseEntryANDROID :: edgeSize على قيمة موجبة أو على وقت التشغيل عرض XR_ERROR_VALIDATION_FAILURE .

يجب أن يفلتر وقت التشغيل الناتج من xrGetAllTrackablesANDROID للمطابقة مع trackingMode وXrTrackableMarkerDatabaseEntryANDROID :: edgeSize .

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

يصف التعداد XrTrackableMarkerTrackingModeANDROID أوضاع التتبُّع المتوافقة مع العلامات.

typedef enum XrTrackableMarkerTrackingModeANDROID {
    XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_TRACKABLE_MARKER_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerTrackingModeANDROID;

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

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID: تتبُّع العلامات الديناميكية يوفّر هذا الوضع أعلى دقة ويعمل على العلامات المتحركة والثابتة، ولكنّه يستهلك أيضًا أكبر قدر من الطاقة.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID: تتبُّع العلامات الثابتة يكون هذا الوضع مفيدًا بشكل أساسي للعناصر التي يُعرف أنّها ثابتة، ما يؤدي إلى استهلاك أقل للطاقة مقارنةً بالوضع الديناميكي.

يحدّد البنية XrTrackableMarkerDatabaseANDROID قاموسًا ومعرّفات العلامات المقابلة التي سيتم تتبّعها.

typedef struct XrTrackableMarkerDatabaseANDROID {
    XrTrackableMarkerDictionaryANDROID              dictionary;
    uint32_t                                        entryCount;
    const XrTrackableMarkerDatabaseEntryANDROID*    entries;
} XrTrackableMarkerDatabaseANDROID;

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

  • ‫dictionary هو XrTrackableMarkerDictionaryANDROID الذي تنتمي إليه جميع entries.
  • ‫entryCount هو uint32_t يصف عدد العناصر في مصفوفة entries. يمكن للتطبيق ضبط entryCount 0 لتتبُّع جميع العلامات في dictionary .
  • ‫entries هو مؤشر إلى مصفوفة من XrTrackableMarkerDatabaseEntryANDROID، يحتوي كل منها على إعدادات علامة يمكن تتبُّعها.

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

يصف تعداد XrTrackableMarkerDictionaryANDROID قواميس العلامات المتوافقة.

typedef enum XrTrackableMarkerDictionaryANDROID {
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID = 0,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_100_ANDROID = 1,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_250_ANDROID = 2,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_1000_ANDROID = 3,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_50_ANDROID = 4,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_100_ANDROID = 5,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_250_ANDROID = 6,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_1000_ANDROID = 7,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_50_ANDROID = 8,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_100_ANDROID = 9,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_250_ANDROID = 10,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_1000_ANDROID = 11,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_50_ANDROID = 12,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_100_ANDROID = 13,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_250_ANDROID = 14,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_1000_ANDROID = 15,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_16H5_ANDROID = 16,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_25H9_ANDROID = 17,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H10_ANDROID = 18,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H11_ANDROID = 19,
    XR_TRACKABLE_MARKER_DICTIONARY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerDictionaryANDROID;

يضبط بنية XrTrackableMarkerDatabaseEntryANDROID معرّفًا واحدًا للعلامة في قاموس.

typedef struct XrTrackableMarkerDatabaseEntryANDROID {
    int32_t    id;
    float      edgeSize;
} XrTrackableMarkerDatabaseEntryANDROID;

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

  • ‫id هو معرّف العلامة كما هو موضّح في القاموس.
  • يمثّل edgeSize حجم حافة العلامة بالمتر. إذا كان وقت التشغيل يتيح تقدير حجم العلامة، يمكن للتطبيق ضبط هذه القيمة على صفر وسيتم تقدير حجم العلامة على الإنترنت. إذا تم ضبط هذه القيمة على صفر ولكن وقت التشغيل لا يتيح تقدير حجم العلامة، يجب أن يعرض وقت التشغيل القيمة XR_ERROR_VALIDATION_FAILURE .

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

الحصول على علامات

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

XrResult xrGetTrackableMarkerANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableMarkerANDROID*                   markerOutput);

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

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

يجب أن يعرض وقت التشغيل XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID إذا لم يكن نوع العنصر القابل للتتبُّع في XrTrackableANDROID هو XR_TRACKABLE_TYPE_MARKER_ANDROID، أو إذا لم يكن نوع العنصر القابل للتتبُّع في XrTrackableTrackerANDROID هو XR_TRACKABLE_TYPE_MARKER_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_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrTrackableMarkerANDROID {
    XrStructureType                       type;
    void*                                 next;
    XrTrackingStateANDROID                trackingState;
    XrTime                                lastUpdatedTime;
    XrTrackableMarkerDictionaryANDROID    dictionary;
    int32_t                               markerId;
    XrPosef                               centerPose;
    XrExtent2Df                           extents;
} XrTrackableMarkerANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
  • ‫trackingState هي XrTrackingStateANDROID للعلامة.
  • ‫lastUpdatedTime هو XrTime لآخر تعديل على العلامة.
  • ‫dictionary هو XrTrackableMarkerDictionaryANDROID الخاص بالعلامة.
  • ‫markerId هو معرّف العلامة كما هو موضّح في القاموس.
  • ‫centerPose هو XrPosef الخاص بالعلامة في XrTrackableGetInfoANDROID :: baseSpace . يقع العلامة في مستوى XZ مع توجيه X إلى يمين العلامة وتوجيه Z إلى أسفلها وتوجيه Y إلى خارج العلامة كالمتجه العمودي.
  • ‫extents هي أبعاد XrExtent2Df للعلامة. يقع حدّ المربّع المحيط عند النقاط: centerPose +/- ( extents / 2).

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

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

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

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_xrGetTrackableMarkerANDROID xrGetTrackableMarkerANDROID;           // 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
XrSystemMarkerTrackingPropertiesANDROID markerProperty {
  .type = XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &markerProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!markerProperty.supportsMarkerTracking) {
    // Marker tracking is not supported.
    return;
}

// Create a trackable tracker for marker tracking.
// If the runtime does not support size estimation, configures marker edge size of 0.1m.
XrTrackableMarkerDatabaseEntryANDROID markerEntries {
  .id = 0,
  .edgeSize = markerProperty.supportsMarkerSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableMarkerDatabaseANDROID markerDatabases {
  .dictionary = XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID,
  .entryCount = 1,
  .entries = &markerEntries,
};
XrTrackableMarkerConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID,
  .databaseCount = 1,
  .databases = &markerDatabases,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_MARKER_ANDROID,
};
XrTrackableTrackerANDROID markerTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &markerTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get markers.
std::vector<XrTrackableANDROID> trackables(markerProperty.maxMarkerCount);
std::vector<XrTrackableMarkerANDROID> markers(markerProperty.maxMarkerCount, {
  .type = XR_TYPE_TRACKABLE_MARKER_ANDROID,
  .next = nullptr,
});
uint32_t markerSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(markerTracker, markerProperty.maxMarkerCount, &markerSize,
                                 trackables.data()));
for (int i = 0; i < markerSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables[i],
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableMarkerANDROID(markerTracker, &getInfo, &markers[i]));
    // Handle markers.
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(markerTracker));

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

بنى جديدة

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

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

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • تمديد XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • تمديد XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

المشاكل

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

  • المراجعة 1، 23-07-2025 (Levana Chen)

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