XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

نوع الإضافة

إضافة مثيل

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

708

المراجعة

1

حالة التصديق

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

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

XR_ANDROID_trackables

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

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

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

2025-07-23

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

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

المساهمون

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

نظرة عامة

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

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

الأذونات

يجب أن تتضمّن تطبيقات 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_ANDROID_trackables_marker قبل استخدام XrSystemMarkerTrackingPropertiesANDROID
• يجب أن يكون type XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية

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

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

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

يجب أن يعرض وقت التشغيل XR_ERROR_FEATURE_UNSUPPORTED إذا كانت قيمة trackableType في XrTrackableTrackerCreateInfoANDROID هي XR_TRACKABLE_TYPE_MARKER_ANDROID وكانت قيمة supportsMarkerTracking في XrSystemMarkerTrackingPropertiesANDROID هي 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 .

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

• يجب تفعيل الإضافة XR_ANDROID_trackables_marker قبل استخدام XrTrackableMarkerConfigurationANDROID
• يجب أن يكون type XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية
• trackingMode يجب أن تكون قيمة صالحة لـ XrTrackableMarkerTrackingModeANDROID
• يجب أن يكون databases مؤشرًا إلى مصفوفة من بُنى databaseCount صالحة من نوع XrTrackableMarkerDatabaseANDROID
• يجب أن تكون المَعلمة databaseCount أكبر من 0

يصف التعداد 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، ويحتوي كل منها على إعدادات علامة لتتبُّعها.

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

• يجب تفعيل الإضافة XR_ANDROID_trackables_marker قبل استخدام XrTrackableMarkerDatabaseANDROID
• يجب أن تكون قيمة dictionary صالحة لـ XrTrackableMarkerDictionaryANDROID
• إذا لم تكن قيمة entryCount هي 0، entries يجب أن تكون مؤشرًا إلى مصفوفة من هياكل entryCount 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 .

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

• يجب تفعيل الإضافة XR_ANDROID_trackables_marker قبل استخدام XrTrackableMarkerDatabaseEntryANDROID

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

يتم تعريف الدالة 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_ANDROID_trackables_marker قبل استدعاء xrGetTrackableMarkerANDROID
• يجب أن يكون tracker اسم معرِّف XrTrackableTrackerANDROID صالحًا
• getInfo يجب أن يكون مؤشرًا إلى بنية XrTrackableGetInfoANDROID صالحة
• markerOutput يجب أن يكون مؤشرًا إلى بنية XrTrackableMarkerANDROID

رموز الإرجاع

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_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).

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

• يجب تفعيل الإضافة XR_ANDROID_trackables_marker قبل استخدام XrTrackableMarkerANDROID
• يجب أن يكون type XR_TYPE_TRACKABLE_MARKER_ANDROID
• next يجب أن تكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية
• يجب أن تكون قيمة trackingState صالحة لـ XrTrackingStateANDROID
• يجب أن تكون قيمة dictionary صالحة لـ XrTrackableMarkerDictionaryANDROID

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

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

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

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

• xrGetTrackableMarkerANDROID

منشآت جديدة

• XrTrackableMarkerANDROID
• XrTrackableMarkerDatabaseANDROID
• XrTrackableMarkerDatabaseEntryANDROID

• توسيع XrSystemProperties :

  • XrSystemMarkerTrackingPropertiesANDROID

• توسيع XrTrackableTrackerCreateInfoANDROID :

  • XrTrackableMarkerConfigurationANDROID

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

• XrTrackableMarkerDictionaryANDROID
• XrTrackableMarkerTrackingModeANDROID

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

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

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