XR_ANDROID_trackables_image

سلسلة الاسم

XR_ANDROID_trackables_image

نوع الإضافة

إضافة مثيل

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

710

المراجعة

1

حالة التصديق

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

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

XR_EXT_future
و
XR_ANDROID_trackables

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

2025-04-08

حالة عنوان IP

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

المساهمون

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

نظرة عامة

يتيح هذا الامتداد تتبُّع الصور المستوية على النحو المحدّد من خلال مجموعات من الصور المرجعية المدخلة.

الأذونات

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

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

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

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

typedef struct XrSystemImageTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsImageTracking;
    XrBool32           supportsPhysicalSizeEstimation;
    uint32_t           maxTrackedImageCount;
    uint32_t           maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;

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

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

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

إذا كان وقت التشغيل يتيح تتبُّع الصور، يجب أن يتيح تتبُّع maxTrackedImageCount صورة في أي وقت.

إذا كان وقت التشغيل يتيح تتبُّع الصور، يجب أن يتيح maxLoadedImageCount من الصور المحمَّلة في أي وقت.

إذا كان وقت التشغيل يتيح تقدير حجم الصورة، يمكن للتطبيق ضبط XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0 للإشارة إلى استخدام تقدير الحجم. بخلاف ذلك، على التطبيق ضبط XrTrackableImageDatabaseEntryANDROID :: physicalWidth على قيمة موجبة، وإلا سيتم عرض XR_ERROR_VALIDATION_FAILURE.

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

إنشاء قواعد بيانات

يمكن للتطبيق إنشاء معرّف XrTrackableImageDatabaseANDROID من خلال إنشاء بنية واحدة أو أكثر من بنى XrTrackableImageDatabaseEntryANDROID وتمريرها إلى الدالة xrCreateTrackableImageDatabaseAsyncANDROID من خلال بنية XrTrackableImageDatabaseCreateInfoANDROID.

يجب أن يوفّر التطبيق على الأقل إدخالاً واحدًا من XrTrackableImageDatabaseEntryANDROID عند إنشاء معرّف XrTrackableImageDatabaseANDROID.

XrTrackableImageDatabaseANDROID هو معرّف يمثّل مجموعة من الصور المرجعية التي تمت معالجتها والتي يمكن رصدها وتتبُّعها في البيئة.

XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)

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

typedef struct XrTrackableImageDatabaseEntryANDROID {
    XrStructureType                        type;
    const void*                            next;
    XrTrackableImageTrackingModeANDROID    trackingMode;
    float                                  physicalWidth;
    uint32_t                               imageWidth;
    uint32_t                               imageHeight;
    XrTrackableImageFormatANDROID          format;
    uint32_t                               bufferSize;
    const uint8_t*                         buffer;
} XrTrackableImageDatabaseEntryANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
  • trackingMode هو XrTrackableImageTrackingModeANDROID يشير إلى الوضع المطلوب للتتبُّع.
  • يشير physicalWidth إلى عرض الصورة بالأمتار. إذا كانت القيمة صفرًا، سيتم تقدير حجم الصورة على الإنترنت.
  • تشير imageWidth إلى عرض الصورة بالبكسل.
  • يمثّل imageHeight ارتفاع الصورة بالبكسل.
  • format هو XrTrackableImageFormatANDROID يشير إلى تنسيق بيانات الصورة في buffer .
  • يشير bufferSize إلى طول البايت في buffer .
  • buffer هي المخزن المؤقت uint8_t الذي يحتوي على بيانات وحدات البكسل الخاصة بالصورة المرجعية. يجب أن تكون محتويات buffer صالحة طوال مدة عملية إنشاء قاعدة البيانات غير المتزامنة، والتي تبدأ بالدالة xrCreateTrackableImageDatabaseAsyncANDROID وتكتمل بالدالة xrCreateTrackableImageDatabaseCompleteANDROID .

يمكن للتطبيق ضبط physicalWidth على 0 لطلب تقدير الحجم على الإنترنت إذا كانت قيمة XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation هي XR_TRUE .

قد تعرض بيئة التشغيل القيمة XR_ERROR_VALIDATION_FAILURE من xrCreateTrackableImageDatabaseAsyncANDROID إذا لم يتطابق bufferSize مع الحجم المتوقّع استنادًا إلى imageWidth وimageHeight وformat في الإدخال .

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

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

typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
    XrStructureType                                type;
    const void*                                    next;
    uint32_t                                       entryCount;
    const XrTrackableImageDatabaseEntryANDROID*    entries;
} XrTrackableImageDatabaseCreateInfoANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
  • entryCount هو uint32_t يحدّد عدد العناصر في مصفوفة entries.
  • entries هي مصفوفة من بنى XrTrackableImageDatabaseEntryANDROID.

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

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

typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
    XrStructureType                    type;
    void*                              next;
    XrResult                           futureResult;
    XrTrackableImageDatabaseANDROID    database;
} XrCreateTrackableImageDatabaseCompletionANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
  • futureResult هي XrResult للعملية غير المتزامنة.
  • database هو معرّف XrTrackableImageDatabaseANDROID الذي تم إنشاؤه.

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

قيم futureResult:

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

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

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

XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
    XrSession                                   session,
    const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateTrackableImageDatabaseCompletionANDROID* completion);

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrDestroyTrackableImageDatabaseANDROID(
    XrTrackableImageDatabaseANDROID             database);

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

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

أمان سلاسل المحادثات

  • يجب مزامنة حساب database وأي أسماء مستخدمين للأطفال بشكل خارجي

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS

تعذُّر

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

تتبُّع الصور

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

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

يجب أن تعرض بيئة التشغيل القيمة XR_ERROR_FEATURE_UNSUPPORTED إذا كانت قيمة trackableType في XrTrackableTrackerCreateInfoANDROID هي XR_TRACKABLE_TYPE_IMAGE_ANDROID، وكانت قيمة supportsImageTracking في XrSystemImageTrackingPropertiesANDROID هي XR_FALSE من خلال xrGetSystemProperties .

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

typedef struct XrTrackableImageConfigurationANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  databaseCount;
    const XrTrackableImageDatabaseANDROID*    databases;
} XrTrackableImageConfigurationANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
  • databaseCount هي uint32_t تحدّد عدد العناصر في databases
  • databases هي مصفوفة من XrTrackableImageDatabaseANDROID تحدّد قواعد البيانات التي سيتم إنشاء أداة التتبُّع بها.

يجب أن يضبط التطبيق إعدادًا صالحًا من خلال إضافة XrTrackableImageConfigurationANDROID إلى سلسلة next من XrTrackableTrackerCreateInfoANDROID . وفي الحالات الأخرى، يجب أن يعرض وقت التشغيل القيمة XR_ERROR_VALIDATION_FAILURE .

يجب أن يوفّر التطبيق بنية واحدة على الأقل من XrTrackableImageDatabaseANDROID لإنشاء أداة التتبُّع.

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

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

typedef enum XrTrackableImageTrackingModeANDROID {
    XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;

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

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

يصف تعداد XrTrackableImageFormatANDROID تنسيقات الصور المتوافقة.

typedef enum XrTrackableImageFormatANDROID {
    XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
    XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;

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

  • XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID: تنسيق صور RGBA مع 8 بت لكل قناة لون وبيانات الشفافية

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

XrResult xrAddTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

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

عند إضافة XrTrackableImageDatabaseANDROID إلى أداة التتبُّع، يجب أخذ الصور المرجعية لقاعدة البيانات هذه في الاعتبار عند الرصد والتتبُّع بالإضافة إلى أي قواعد بيانات أخرى تمت إضافتها سابقًا باستخدام xrAddTrackableImageDatabaseANDROID أو من خلال بنية XrTrackableImageConfigurationANDROID عند إنشاء أداة التتبُّع في البداية.

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrRemoveTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

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

عند إزالة XrTrackableImageDatabaseANDROID من XrTrackableTrackerANDROID، يجب عدم أخذ بنى XrTrackableImageDatabaseEntryANDROID الخاصة بقاعدة البيانات هذه في الاعتبار عند الرصد والتتبُّع. يجب عدم إعداد تقارير عن أي إدخالات يتم تتبُّعها بنشاط في قاعدة البيانات هذه. يجب عدم إتلاف مقبض XrTrackableImageDatabaseANDROID الذي تمت إزالته ضمنيًا كجزء من هذه العملية.

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

الحصول على صور

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

XrResult xrGetTrackableImageANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableImageANDROID*                    trackable);

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

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

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

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

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrTrackableImageANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrTrackingStateANDROID             trackingState;
    XrTime                             lastUpdatedTime;
    XrTrackableImageDatabaseANDROID    database;
    uint32_t                           databaseEntryIndex;
    XrPosef                            centerPose;
    XrExtent2Df                        extents;
} XrTrackableImageANDROID;

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

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

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

التعامل مع حالات الفشل

يجب أن يطلب التطبيق بشكل متكرّر الحدث XrEventDataImageTrackingLostANDROID باستخدام xrPollEvent، ويجب ألا يتجاهله.

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

typedef struct XrEventDataImageTrackingLostANDROID {
    XrStructureType    type;
    const void*        next;
    XrTime             time;
} XrEventDataImageTrackingLostANDROID;

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

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

يشير تلقّي الحدث XrEventDataImageTrackingLostANDROID إلى حدوث مشكلة في تتبُّع الصور وفشل داخلي أدّى إلى إبطال صحة الموارد الحالية. يجب أن يدمّر التطبيق جميع مقابض XrTrackableImageDatabaseANDROID ويعيد إنشاءها إذا أراد مواصلة تتبُّع الصور. يجب أيضًا أن يدمّر التطبيق جميع مقابض XrTrackableTrackerANDROID المرتبطة بتتبُّع الصور، وأن يعيد إنشاءها إذا أراد مواصلة تتبُّع الصور.

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

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

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

XrInstance instance;  // Previously initialized.
XrSession session;    // Previously initialized.
XrSystemId systemId;  // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID;                                        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // 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
XrSystemImageTrackingPropertiesANDROID imageProperty {
  .type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
    // image tracking is not supported.
    return;
}

uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
  {
    .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
    .next = nullptr,
    .trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
    .physicalWidth = 0.1f, // The width of the image in meters.
    .imageWidth = 640,
    .imageHeight = 480,
    .format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
    .bufferSize = imageBufferSize, // RGBA buffer size in bytes.
    .buffer = imageBuffer, // RGBA data.
  }
};

XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
  .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .entryCount = 1,
  .entries = imageDatabaseEntries
};

XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
  XrFuturePollInfoEXT pollInfo{
    .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
    .future = imageDatabaseFuture,
  };
  XrFuturePollResultEXT pollResult{
    .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
  };
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

  if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
    futureReady = true;
    keepLooping = false;
  } else {
    // Throttle the loop to not fully expend this CPU core.
    std::this_thread::yield();
  }
}

XrTrackableImageDatabaseANDROID imageDatabase;

if (futureReady) {
  XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
    .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
    .next = nullptr,
  };

  CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
  CHK_XR(imageDatabaseCompletion.futureResult);
  imageDatabase = imageDatabaseCompletion.database;
}

XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &imageDatabase
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.

// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

while (1) {
  uint32_t trackableCountOutput = 0;

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));

  std::vector<XrTrackableANDROID> allImageTrackables;
  allImageTrackables.resize(trackableCountOutput);

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));

  for (XrTrackableANDROID trackable : allImageTrackables) {
    XrTrackableGetInfoANDROID imageGetInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackable,
      .baseSpace = appSpace,
      .time = updateTime
    };

    XrTrackableImageANDROID trackableImage{
      .type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
    };
    CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));

    // Use XrTrackableImageANDROID data.
    (void)trackableImage.trackingState;
    (void)trackableImage.lastUpdatedTime;
    (void)trackableImage.centerPose;
    (void)trackableImage.extents;

    if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
      // Knowing which image the index of 0 maps to, use the specific image database
      // entry (e.g. rendering A for image A).
    }
    // indices 1+N comparisons for another specific image database entry.
  }

  // Throttle the loop to not fully expend this CPU core.
  std::this_thread::yield();
}

// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

مثال على الرمز البرمجي لإدارة قواعد بيانات الصور في وقت التشغيل

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

XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.

// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 2,
  .databases = imageDatabases
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.

CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.

CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.

CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.

// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &anotherImageDatabase
};

XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &anotherImageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));

// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.

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

يوضّح نموذج الرمز البرمجي التالي كيفية التعامل مع الخطأ من خلال طلب البيانات بشكل متكرّر للحدث XrEventDataImageTrackingLostANDROID.

XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.

// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
  .type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
      const XrEventDataImageTrackingLostANDROID& eventdata =
        *reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);

      // All existing databases and trackers need to be destroyed.
      CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
      CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

      // To resume image tracking, the database(s) and the tracker need to be re-created.

      XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
        .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
        .next = nullptr,
        .entryCount = 1,
        .entries = imageDatabaseEntries
      };

      XrFutureEXT imageDatabaseFuture;
      CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

      while (true) {
        XrFuturePollInfoEXT pollInfo{
          .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
          .future = imageDatabaseFuture,
        };
        XrFuturePollResultEXT pollResult{
          .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
        };
        CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

        if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
          break;
        } else {
          // Throttle the loop to not fully expend this CPU core.
          std::this_thread::yield();
        }
      }

      XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
        .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
        .next = nullptr,
      };

      CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
      CHK_XR(imageDatabaseCompletion.futureResult);
      imageDatabase = imageDatabaseCompletion.database;

      XrTrackableImageConfigurationANDROID imageConfig {
       .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
       .next = nullptr,
       .databaseCount = 1,
       .databases = &imageDatabase
      };

      XrTrackableTrackerCreateInfoANDROID createInfo {
        .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
        .next = &imageConfig,
        .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
      };

      XrTrackableTrackerANDROID imageTrackableTracker;
      CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

      break;
    }
  }
}

أنواع العناصر الجديدة

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

بنى جديدة

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

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

  • XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAME
  • XR_ANDROID_trackables_image_SPEC_VERSION
  • تمديد XrObjectType :

    • XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
  • تمديد XrResult :

    • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • تمديد XrStructureType :

    • XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID
    • XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
  • تمديد XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_IMAGE_ANDROID

المشاكل

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

  • التعديل 1، ‎08-04-2025 (دانيال غوتنبرغ)

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