XR_EXT_spatial_image_tracking

Name String

XR_EXT_spatial_image_tracking

نوع الإضافة

إضافة مثيل

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

783

المراجعة

1

حالة التصديق

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

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

XR_EXT_spatial_entity

المساهمون

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

نظرة عامة

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

يتم تمثيل الصورة التي يتم تتبُّعها ككيان مكاني يتضمّن المكوّنات التالية:

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

تستخدم التطبيقات عادةً إضافة تتبُّع الصور المكانية بالنمط التالي:

  • ينشئ التطبيق أولاً معالِجًا واحدًا أو أكثر من معالِجات XrSpatialImageTrackingDatabaseEXT استنادًا إلى مجموعات من بيانات الصور المرجعية المحمَّلة مسبقًا.
  • بعد ذلك، ينشئ التطبيق مؤشر XrSpatialContextEXT استنادًا إلى مؤشرات XrSpatialImageTrackingDatabaseEXT التي تم إنشاؤها سابقًا.
  • بعد ذلك، يحرّر التطبيق بيانات الصورة المرجعية لتقليل استهلاك الذاكرة.
  • يكتشف التطبيق الصور ويستعلم عنها وفقًا لأنماط الوصول إلى الكيانات المكانية.
  • يمكن للتطبيق تحميل مجموعات إضافية من الصور المرجعية وإنشاء XrSpatialImageTrackingDatabaseEXT إضافية، وبالتالي XrSpatialContextEXT منها لتوسيع مجموعة الصور التي يمكن رصدها وتتبُّعها ديناميكيًا في وقت التشغيل.
  • يمكن للتطبيق إتلاف مؤشرات XrSpatialImageTrackingDatabaseEXT لتقليل مجموعة الصور التي يمكن رصدها وتتبُّعها بشكل ديناميكي أثناء التشغيل.
  • يمكن للتطبيق إتلاف مؤشرات XrSpatialContextEXT لتقليل مجموعة الصور التي يمكن رصدها وتتبُّعها ديناميكيًا أثناء التشغيل.

دعم بيئة التشغيل

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

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

الإعداد

لتفعيل رصد الصور المستوية وتتبُّعها، يمكن للتطبيق تمرير بُنى XrSpatialCapabilityConfigurationImageTrackingEXT في XrSpatialContextCreateInfoEXT :: capabilityConfigs عند استدعاء الدالة xrCreateSpatialContextAsyncEXT، وتمرير مصفوفات من بُنى< XrSpatialImageTrackingDatabaseEXT في كل XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases .

إنشاء مجموعة صور مدخَلة

لتحديد الصور المرجعية التي سيتم رصدها وتتبُّعها، يجب أن ينشئ التطبيق مجموعة واحدة على الأقل من الصور المرجعية المُدخلة. يتم تمثيل مجموعة من الصور المرجعية للإدخال بواسطة مؤشر XrSpatialImageTrackingDatabaseEXT وتحتوي على صورة واحدة على الأقل.

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

يمثّل المقبض XrSpatialImageTrackingDatabaseEXT الموارد اللازمة لاكتشاف وتعديل عدد من الصور المكانية في بيئة المستخدم. يمكن للتطبيقات استخدام هذا المعرِّف للعثور على الصور المكانية وتعديلها باستخدام وظائف أخرى في هذه الإضافة.

إنشاء قاعدة بيانات تتبُّع الصور المكانية

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

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

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

  • ‫session هي XrSession ستكون فيها قاعدة بيانات تتبُّع الصور المكانية نشطة.
  • ‫createInfo هو XrSpatialImageTrackingDatabaseCreateInfoEXT المستخدَم لتحديد مَعلمات قاعدة بيانات تتبُّع الصور المكانية.
  • ‫future هو مؤشر إلى XrFutureEXT .

يمكن للتطبيق إنشاء معالِج XrSpatialImageTrackingDatabaseEXT باستخدام دالة xrCreateSpatialImageTrackingDatabaseAsyncEXT وضبط مجموعات الصور المرجعية المُدخلة لقاعدة بيانات تتبُّع الصور باستخدام createInfo .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT إذا لم يتم تعداد XrSpatialReferenceImageEXT :: format لأي من الصور المرجعية للإدخال بواسطة xrEnumerateSpatialReferenceImageFormatsEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_IMAGE_INVALID_EXT إذا تعذّر تقييم مصفوفة planes في XrSpatialReferenceImageEXT لأي من الصور المرجعية المُدخلة وفقًا للبيانات الوصفية للصورة المرجعية في XrSpatialReferenceImageEXT .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_IMAGE_INVALID_EXT إذا كانت مصفوفة planes في XrSpatialReferenceImageEXT لأي من الصور المرجعية المُدخلة لا توفّر عددًا من المستويات يساوي تمامًا عدد قنوات الألوان في format في XrSpatialReferenceImageEXT.

إذا كان وقت التشغيل يفرض نظام أذونات للتحكّم في وصول التطبيق إلى ميزة تتبُّع الصور، يجب أن يعرض وقت التشغيل القيمة XR_ERROR_PERMISSION_INSUFFICIENT إذا لم يتم منح هذه الأذونات لهذا التطبيق.

تبدأ هذه الدالة عملية غير متزامنة وتنشئ XrFutureEXT مقابلة، يمكن استخدامها مع xrPollFutureEXT والدوال ذات الصلة. تشير القيمة المعروضة لهذه الدالة فقط إلى ما إذا كانت المَعلمات مقبولة لجدولة العملية غير المتزامنة. دالة الإكمال المقابلة هي xrCreateSpatialImageTrackingDatabaseCompleteEXT، ويمكن استخدامها عندما تكون دالة مستقبلية من هذه الدالة في الحالة READY، مع تعبئة المخرجات بواسطة هذه الدالة في بنية الإكمال XrCreateSpatialImageTrackingDatabaseCompletionEXT .

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

رموز الإرجاع

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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

يتم تحديد بنية XrSpatialImageTrackingDatabaseCreateInfoEXT على النحو التالي:

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

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

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • ‫spatialReferenceImageCount هو عدد العناصر في مصفوفة spatialReferenceImages.
  • spatialReferenceImages هو مصفوفة من XrSpatialReferenceImageEXT .

تصف بنية XrSpatialImageTrackingDatabaseCreateInfoEXT المعلومات اللازمة لإنشاء مؤشر XrSpatialImageTrackingDatabaseEXT.

يجب إنشاء كل XrSpatialImageTrackingDatabaseEXT باستخدام XrSpatialReferenceImageEXT واحد على الأقل في مصفوفة XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

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

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

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

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

تُكمِل الدالة xrCreateSpatialImageTrackingDatabaseCompleteEXT العملية غير المتزامنة التي بدأتها الدالة xrCreateSpatialImageTrackingDatabaseAsyncEXT .

يجب ألّا يصل وقت التشغيل إلى أيّ مؤشرات XrSpatialReferenceImagePlaneEXT :: buffer التي تم توفيرها من خلال مصفوفة الإدخال XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages لطلب xrCreateSpatialImageTrackingDatabaseAsyncEXT هذا بعد اكتماله. يمكن للتطبيق إخلاء أي بيانات XrSpatialReferenceImagePlaneEXT :: buffer بعد اكتمال xrCreateSpatialImageTrackingDatabaseAsyncEXT لتقليل استهلاك الذاكرة.

يجب أن يعرض وقت التشغيل XR_ERROR_FUTURE_PENDING_EXT إذا لم يكن future في حالة الاستعداد. يجب أن يعرض وقت التشغيل القيمة XR_ERROR_FUTURE_INVALID_EXT إذا سبق أن تم إكمال future أو إلغاؤه.

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

رموز الإرجاع

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

يتم تحديد بنية XrCreateSpatialImageTrackingDatabaseCompletionEXT على النحو التالي:

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

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

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

قيم 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
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

إذا كان futureResult رمز نجاح، database يجب أن يكون معرّفًا صالحًا. إذا كانت السمة database صالحة، فستظل كذلك فقط خلال مراحل نشاط xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session أو إلى أن يتلف التطبيق السمة database باستخدام xrDestroySpatialImageTrackingDatabaseEXT، أيهما يحدث أولاً.

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

تدمير قاعدة بيانات تتبُّع الصور المكانية

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

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

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

يمكن للتطبيق استدعاء الدالة xrDestroySpatialImageTrackingDatabaseEXT لإلغاء المقبض database والموارد الأساسية عند الانتهاء من مهام اكتشاف الصور المكانية وتعديلها.

يمكن للتطبيق استدعاء الدالة xrDestroySpatialImageTrackingDatabaseEXT قبل استدعاء xrDestroySpatialContextEXT . يجب ألا يعرض وقت التشغيل الصور التي تديرها قاعدة البيانات XrSpatialImageTrackingDatabaseEXT التي تم تدميرها. يجب أن تواصل بيئة التشغيل إعداد تقارير عن الصور التي تديرها قواعد بيانات أخرى.

يجب أن يضمن وقت التشغيل أنّ لقطات الاستكشاف التي تعرضها الدالة xrCreateSpatialDiscoverySnapshotCompleteEXT لا تحتوي على صور تتعلّق بمؤشرات XrSpatialImageTrackingDatabaseEXT التي تم تدميرها أو غير الصالحة، حتى إذا تم تدمير المؤشر بعد أن استدعى التطبيق الدالة xrCreateSpatialDiscoverySnapshotAsyncEXT . بما أنّ البيانات في اللقطة المكانية غير قابلة للتغيير، يجب أن يتلف التطبيق أيّ مؤشرات XrSpatialSnapshotEXT تم إنشاؤها قبل أن يتلف database ، وإلا قد يتلقّى التطبيق مؤشرات XrSpatialImageTrackingDatabaseEXT غير صالحة عند استخدام xrQuerySpatialComponentDataEXT .

يمكن للتطبيق استدعاء الدالة xrDestroySpatialContextEXT لإلغاء المقبض XrSpatialContextEXT قبل إتلاف أي من مقابض XrSpatialImageTrackingDatabaseEXT التي تم إنشاء XrSpatialContextEXT باستخدامها. يجب ألّا يتلف وقت التشغيل بشكل ضمني مؤشرات XrSpatialImageTrackingDatabaseEXT هذه عند تلف XrSpatialContextEXT.

تتيح إدارة عمر XrSpatialContextEXT وXrSpatialImageTrackingDatabaseEXT بشكل مستقل للتطبيقات إعادة استخدام مؤشرات XrSpatialImageTrackingDatabaseEXT التي تم إنشاؤها سابقًا بدون الحاجة إلى إعادة تنفيذ إجراء الإنشاء المكلف.

على سبيل المثال، يؤدي تدمير XrSpatialContextEXT ثم إعادة إنشاء XrSpatialContextEXT آخر باستخدام XrSpatialImageTrackingDatabaseEXT نفسه إلى إيقاف تتبُّع الصور مؤقتًا واستئنافه بدون الحاجة إلى تنفيذ إجراء إعداد آخر.

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

أمان Thread

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

رموز الإرجاع

Success

  • XR_SUCCESS

تعذّر الإجراء

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

تنسيقات الصور المتوافقة

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

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

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

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

  • ‫instance هو اسم حساب لـ XrInstance .
  • ‫systemId هو XrSystemId الذي سيتم تعداد تنسيقات الصور المرجعية المُدخلة له.
  • ‫capability هي XrSpatialCapabilityEXT التي سيتم تعداد تنسيقات الصور المرجعية المُدخلة لها.
  • ‫formatCapacityInput هي سعة مصفوفة formats، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
  • ‫formatCountOutput هو عدد التنسيقات أو السعة المطلوبة في حال عدم كفاية formatCapacityInput.
  • ‫formats هي مصفوفة من XrSpatialReferenceImageFormatEXT . يمكن أن تكون القيمة NULL إذا كانت قيمة formatCapacityInput هي 0.
  • يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم formats المطلوب.

يمكن للتطبيق تعداد قائمة تنسيقات الصور المرجعية للإدخال التي يتيحها XrSystemId معيّن لـ XrSpatialCapabilityEXT معيّن باستخدام xrEnumerateSpatialReferenceImageFormatsEXT .

يجب ألا يعدد وقت التشغيل تنسيقات الإضافات غير المفعّلة لـ "instance".

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

  • يجب تفعيل الإضافة XR_EXT_spatial_image_tracking قبل استدعاء xrEnumerateSpatialReferenceImageFormatsEXT
  • يجب أن يكون instance مقبض XrInstance صالحًا
  • capability يجب أن تكون قيمة XrSpatialCapabilityEXT صالحة
  • يجب أن يكون formatCountOutput مؤشرًا إلى قيمة uint32_t
  • إذا لم تكن قيمة formatCapacityInput هي 0، يجب أن تكون قيمة formats مؤشرًا لمصفوفة من قيم formatCapacityInput XrSpatialReferenceImageFormatEXT

رموز الإرجاع

Success

  • XR_SUCCESS

تعذّر الإجراء

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

يمكنك الاطّلاع على XrSpatialReferenceImageFormatEXT للحصول على قائمة كاملة بجميع تنسيقات الصور المرجعية المتوافقة مع أي إضافة.

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

يحدّد تعداد XrSpatialReferenceImageFormatEXT تنسيقات الصور المرجعية التي قد يتيحها وقت التشغيل.

يجب أن تكون قيمة XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT وقيمة XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT على الأقل متوافقتَين.

في ما يلي معنى القيم المحدّدة:

أوصاف التعداد

  • ‫XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT: مخزن مؤقت لنموذج RGBA لا يقدّم التنسيق أي ضمانات بشأن تخطيط بيانات وحدات البكسل في الذاكرة. يجب الوصول إلى وحدات البكسل باستخدام البيانات الوصفية التي توفّرها هياكل XrSpatialReferenceImagePlaneEXT المقابلة. يبلغ حجم كل قناة لون بكسل 8 بت، ما يجعل حجم كل بكسل 32 بت.
  • ‫XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT: مخزن مؤقت للنموذج اللوني أحمر أخضر أزرق لا يقدّم التنسيق أي ضمانات بشأن تخطيط بيانات وحدات البكسل في الذاكرة. يجب الوصول إلى وحدات البكسل باستخدام البيانات الوصفية التي توفّرها هياكل XrSpatialReferenceImagePlaneEXT المقابلة. يبلغ حجم كل قناة لون بكسل 8 بت، مما يجعل حجم كل بكسل 24 بت.
  • ‫XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT: مخزن مؤقت لنموذج YUV يتضمّن اختزالاً لونيًا بنمط 4:2:0 لا يقدّم التنسيق أي ضمانات بشأن تخطيط بيانات وحدات البكسل في الذاكرة. يجب الوصول إلى وحدات البكسل باستخدام البيانات الوصفية التي توفّرها هياكل XrSpatialReferenceImagePlaneEXT المقابلة. يبلغ حجم كل قناة لون بكسل RGB تم فك ترميزها 8 بت، ما يجعل حجم كل بكسل 24 بت.

إعدادات تتبُّع الصور المكانية

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

تحسين الصور الثابتة

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

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

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

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • ‫optimizeForStaticImage هي سمة XrBool32 تشير إلى ما إذا كانت الصور تتحرك أم لا. تشير القيمة XR_TRUE إلى أنّ الصور لا تتحرك.

إذا تم تعداد XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT بواسطة xrEnumerateSpatialCapabilityFeaturesEXT لإمكانية XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT، يمكن للتطبيق ربط XrSpatialImageStaticOptimizationEXT بسلسلة XrSpatialImageTrackingDatabaseCreateInfoEXT :: next أو XrSpatialReferenceImageEXT :: next .

إذا ربط التطبيق XrSpatialImageStaticOptimizationEXT ببنية XrSpatialImageTrackingDatabaseCreateInfoEXT، يجب أن يفترض وقت التشغيل أنّ جميع صور XrSpatialImageTrackingDatabaseEXT ثابتة إذا تم ضبط optimizeForStaticImage على XR_TRUE . وبالمثل، يجب أن يفترض وقت التشغيل أنّ جميع صور XrSpatialImageTrackingDatabaseEXT ليست ثابتة إذا تم ضبط optimizeForStaticImage على XR_FALSE .

إذا ربط التطبيق XrSpatialImageStaticOptimizationEXT ببنية XrSpatialReferenceImageEXT، يجب أن يفترض وقت التشغيل أنّ هذه الصورة المرجعية ثابتة إذا تم ضبط optimizeForStaticImage على XR_TRUE . وبالمثل، يجب أن يفترض وقت التشغيل أنّ هذه الصورة المرجعية ليست ثابتة إذا تم ضبط السمة optimizeForStaticImage على XR_FALSE . إنّ ربط بنية XrSpatialImageStaticOptimizationEXT ببنية XrSpatialReferenceImageEXT له الأولوية على ربطها ببنية XrSpatialImageTrackingDatabaseCreateInfoEXT.

إذا لم يتم تعداد XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT بواسطة xrEnumerateSpatialCapabilityFeaturesEXT لإمكانية XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT، وكان التطبيق يربط بنية XrSpatialImageStaticOptimizationEXT بأي من السلاسل التالية السارية، يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE من xrCreateSpatialImageTrackingDatabaseAsyncEXT .

قد يسمح ذلك لوقت التشغيل بإنشاء وضعية وحجم أكثر دقة.

قد يسمح ذلك لوقت التشغيل بتقليل استهلاك الطاقة.

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

عرض الصورة المرجعية

يتم تحديد بنية XrSpatialImageSizeEXT على النحو التالي:

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

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

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • ‫physicalWidth هي قيمة من النوع float تمثّل العرض الفعلي المطلوب ضبطه بالمتر.

إذا تم تعداد XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT بواسطة xrEnumerateSpatialCapabilityFeaturesEXT لإمكانية XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT، يمكن للتطبيق ربط XrSpatialImageSizeEXT بـ XrSpatialImageTrackingDatabaseCreateInfoEXT :: next أو XrSpatialReferenceImageEXT :: next .

إذا ربط التطبيق XrSpatialImageSizeEXT ببنية XrSpatialImageTrackingDatabaseCreateInfoEXT، يجب أن يفترض وقت التشغيل أنّ جميع صور XrSpatialImageTrackingDatabaseEXT لها عرض يبلغ physicalWidth متر وارتفاع وفقًا لنسبة العرض إلى الارتفاع كما هو موضّح ضمنيًا من خلال XrSpatialReferenceImageEXT :: width وXrSpatialReferenceImageEXT :: height .

إذا ربط التطبيق XrSpatialImageSizeEXT ببنية XrSpatialReferenceImageEXT، يجب أن يفترض وقت التشغيل أنّ هذه الصورة المرجعية يبلغ عرضها physicalWidth متر وارتفاعها وفقًا لنسبة العرض إلى الارتفاع كما هو موضّح ضمنيًا من خلال XrSpatialReferenceImageEXT :: width وXrSpatialReferenceImageEXT :: height . إنّ ربط بنية XrSpatialImageSizeEXT ببنية XrSpatialReferenceImageEXT له الأولوية على ربطها ببنية XrSpatialImageTrackingDatabaseCreateInfoEXT.

قد يسمح ذلك لوقت التشغيل بعرض وضعية وحجم أكثر دقة.

يجب أن يحدّد وقت التشغيل إما XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT أو XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT أو كليهما.

إذا تم تعداد XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT بواسطة xrEnumerateSpatialCapabilityFeaturesEXT، يجب أن يوفّر وقت التشغيل أحجام الصور تلقائيًا للصور التي لم يوفّر التطبيق لها أيّ هياكل XrSpatialImageSizeEXT كجزء من أيّ من السلاسل التالية السارية.

لكي يتمكّن وقت التشغيل من إنشاء أحجام الصور تلقائيًا وبدقة، قد تكون هناك حاجة إلى بعض إمكانات الجهاز والمتطلبات الأساسية، مثل الكاميرات المجسّمة والمعايير الخارجية والداخلية للكاميرا التي تمت معايرتها بدقة.

إذا لم يتم تعداد XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT بواسطة xrEnumerateSpatialCapabilityFeaturesEXT، يجب أن يربط التطبيق هياكل XrSpatialImageSizeEXT بالسلاسل التالية المناسبة بحيث يكون لجميع الصور حجم صريح، وإلا يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT من xrCreateSpatialImageTrackingDatabaseAsyncEXT .

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

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

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

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

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • capability هو XrSpatialCapabilityEXT ويجب أن يكون XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT .
  • ‫enabledComponentCount هي uint32_t تحدّد عدد العناصر في enabledComponents .
  • ‫enabledComponents هي مصفوفة من XrSpatialComponentTypeEXT تحدّد المكوّنات التي يجب تفعيلها لهذه الميزة.
  • ‫imageTrackingDatabaseCount هي unint32_t تحدّد عدد العناصر في imageTrackingDatabases .
  • ‫imageTrackingDatabases هي مصفوفة من مؤشرات XrSpatialImageTrackingDatabaseEXT التي تحدّد قواعد بيانات تتبُّع الصور التي يجب تفعيلها للسياق المكاني.

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

تتيح بنية XrSpatialCapabilityConfigurationImageTrackingEXT للتطبيق العثور على الصور المرجعية التي تمثّلها مؤشرات XrSpatialImageTrackingDatabaseEXT في imageTrackingDatabases .

يجب أن يعرض وقت التشغيل XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT إذا لم يتم تعداد XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT من خلال xrEnumerateSpatialCapabilitiesEXT .

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

صورة مرجعية مكانية

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

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

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

  • ‫bufferSize هو حجم الصفيفة buffer.
  • ‫buffer هي مصفوفة من بيانات uint8_t تمثّل بيانات المستوى.
  • ‫rowStride هي المسافة بالبايت بين موضعَي بداية صفَّين متتاليَين من بيانات وحدات البكسل.
  • ‫pixelStride هي المسافة بالبايت بين بكسلَين متتاليَين.

يجب أن يصل وقت التشغيل إلى buffer وفقًا للأنماط التي توفّرها المَعلمتان rowStride وpixelStride.

يجب أن يضبط التطبيق rowStride وpixelStride بحيث لا يستخرج وقت التشغيل سوى وحدات البكسل المفيدة من XrSpatialReferenceImagePlaneEXT.

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

  • يجب تفعيل إضافة XR_EXT_spatial_image_tracking قبل استخدام XrSpatialReferenceImagePlaneEXT
  • buffer يجب أن يكون مؤشرًا إلى مصفوفة من قيم bufferSize uint8_t
  • يجب أن تكون المَعلمة bufferSize أكبر من 0

يتم تحديد بنية XrSpatialReferenceImageEXT على النحو التالي:

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

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

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • ‫width هو عرض الصورة المرجعية بالبكسل.
  • ‫height هو ارتفاع الصورة المرجعية بالبكسل.
  • ‫format هو XrSpatialReferenceImageFormatEXT يمثّل تنسيق الصورة.
  • ‫planeCount هو عدد العناصر في مصفوفة planes.
  • ‫planes هي مصفوفة من بُنى XrSpatialReferenceImagePlaneEXT التي تمثّل مستويات بيانات الصورة.

يمكن للتطبيق إنشاء بنية واحدة أو أكثر من XrSpatialReferenceImageEXT، بحيث تمثّل كل منها صورة مرجعية واحدة يتم تمريرها إلى دالة xrCreateSpatialImageTrackingDatabaseAsyncEXT من خلال XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages عند إنشاء مؤشر XrSpatialImageTrackingDatabaseEXT.

يجب أن يوفّر التطبيق بيانات XrSpatialReferenceImagePlaneEXT :: buffer بترتيب بكسل من اليسار إلى اليمين ومن الأعلى إلى الأسفل.

يجب أن يوفّر التطبيق بنية XrSpatialReferenceImagePlaneEXT في مصفوفة XrSpatialReferenceImageEXT :: planes لكل قناة لون في XrSpatialReferenceImageEXT :: format .

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

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

يجب أن توفّر بيئة التشغيل التي تتيح استخدام XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT المكوّنات المكانية التالية كمكوّنات مضمونة لجميع الكيانات التي تكتشفها هذه الإمكانات، ويجب تعدادها في xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

مكوّن صورة ثنائي الأبعاد

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

يتم تحديد بنية XrSpatialComponentImage2DListEXT على النحو التالي:

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

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

  • ‫type هو XrStructureType لهذه البنية.
  • ‫next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنى.
  • ‫imageCount هو عدد العناصر في مصفوفة images.
  • images هو مصفوفة من XrSpatialImage2DDataEXT .

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

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

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

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

يتم تحديد بنية XrSpatialImage2DDataEXT على النحو التالي:

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

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

  • ‫imageTrackingDatabase هي XrSpatialImageTrackingDatabaseEXT التي رصدت الصورة أو تتبّعتها.
  • ‫referenceImageIndex هو الفهرس الذي يربط مصفوفة spatialReferenceImages من الصور المرجعية للإدخال التي تم إنشاء imageTrackingDatabase باستخدامها بـ XrSpatialImageTrackingDatabaseCreateInfoEXT.

يمكن للتطبيق استخدام imageTrackingDatabase لتحديد أيّ من XrSpatialImageTrackingDatabaseEXT التي تم إنشاؤها سابقًا تحتوي على الصورة المرجعية لبنية XrSpatialImage2DDataEXT هذه. بالنسبة إلى XrSpatialImageTrackingDatabaseEXT، يمكن للتطبيق استخدام referenceImageIndex لتحديد XrSpatialReferenceImageEXT لبنية XrSpatialImage2DDataEXT هذه من خلال مطابقتها مع ترتيب الإدخال لمصفوفة XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

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

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

الإعداد

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

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

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

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

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

يوضّح الرمز البرمجي في المثال التالي كيفية اكتشاف الكيانات المكانية لميزة تتبُّع الصور والاستعلام عن بيانات المكوّنات الخاصة بها.

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

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

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

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components
  std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

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

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

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

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

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

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

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

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

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

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

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

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

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

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

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

منشآت جديدة

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

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

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • توسيع XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • توسيع XrResult :

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • توسيع XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

  • توسيع XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

  • توسيع XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

  • توسيع XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
    • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
    • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
    • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

المشاكل

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

  • الإصدار 1، ‏22-04-2025 (دانيال غوتنبرغ، Qualcomm)

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