XR_ANDROID_trackables_image

Name String

XR_ANDROID_trackables_image

نوع الإضافة

إضافة مثيل

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

710

المراجعة

1

حالة التصديق

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

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

XR_EXT_future
و
XR_ANDROID_trackables

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

2025-04-08

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

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

المساهمون

"كريستوفر دوير"، 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:

Success

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

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

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

رموز الإرجاع

Success

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

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

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

رموز الإرجاع

Success

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

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

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

أمان Thread

  • يجب مزامنة الوصول إلى database وأي معرّفات فرعية خارجيًا

رموز الإرجاع

Success

  • 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 إذا كانت قيمة XrTrackableTrackerCreateInfoANDROID :: trackableType هي XR_TRACKABLE_TYPE_IMAGE_ANDROID وكانت قيمة XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking تعرض 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 عند إنشاء أداة التتبُّع في البداية.

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

رموز الإرجاع

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_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 الذي تمت إزالته ضمنيًا كجزء من هذه العملية.

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

رموز الإرجاع

Success

  • 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 .

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

رموز الإرجاع

Success

  • 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 هو الفهرس الذي يتم ربطه بصفيف database في XrTrackableImageDatabaseCreateInfoANDROID :: entries.
  • ‫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 (دانيال غوتنبرغ)

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