XR_ANDROID_spatial_annotation_tracking

Name String

XR_ANDROID_spatial_annotation_tracking

نوع الإضافة

إضافة مثيل

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

795

المراجعة

1

حالة التصديق

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

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

‫XR_EXT_spatial_entity
و
XR_EXT_spatial_image_tracking

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

2026-01-12

حالة عنوان IP

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

المساهمون

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

نظرة عامة

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

توفّر هذه الإضافة نوع تعليق توضيحي أساسي "رباعي"، وهو مضلّع له 4 جوانب بالضبط، أي شكل رباعي محدّب، يمثّل مربّعًا محيطًا عامًا ثنائي الأبعاد ضمن مرجع وقت التشغيل. يتم تمثيل تعليق توضيحي رباعي الأضلاع تم تتبُّعه ككيان مكاني يتضمّن المكوّنات التالية (أو "التي تتضمّن"):

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

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

  • ينشئ التطبيق أولاً معرّفًا لـ XrSpatialReferenceCacheANDROID، والذي يبدأ في تسجيل مراجع وقت التشغيل من المصدر المحدّد.
  • بعد ذلك، يلتقط التطبيق مرجع وقت التشغيل XrSpatialReferenceImageEXT ويحدّد تعليقًا توضيحيًا مطلوبًا ضمن المرجع خلال الفترة الزمنية لذاكرة التخزين المؤقت للمرجع.
  • ينشئ التطبيق بعد ذلك معرّف XrSpatialContextEXT استنادًا إلى XrSpatialReferenceImageEXT الذي يوفّره XrSpatialCapabilityConfigurationAnnotationTrackingANDROID .
  • يمكن للتطبيق محو مؤشر XrSpatialReferenceCacheANDROID لإيقاف تسجيل المراجع في وقت التشغيل من أجل تقليل استخدام الذاكرة، أو انتظار حدث XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID لتأكيد نتيجة عملية الإعداد.
  • بعد ذلك، يطلب التطبيق الحدث XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID لتأكيد نتيجة تهيئة التعليق التوضيحي.
  • في حال نجاح عملية التهيئة، يمكن للتطبيق بعد ذلك طلب الحدث XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT لتتبُّع التعليق التوضيحي.
  • في حال تعذُّر عملية التهيئة، يمكن للتطبيق استخدام رمز الخطأ الذي تم عرضه في الحدث لتحديد سبب التعذُّر، ومحو مؤشر XrSpatialContextEXT الحالي لبدء تعليق توضيحي جديد.
  • بغض النظر عن نتيجة عملية التهيئة، يمكن للتطبيق تحرير مخزن مؤقت للصور لتقليل استخدام الذاكرة بعد تلقّي الحدث.
  • يكتشف التطبيق التعليقات التوضيحية ويطلبها وفقًا لأنماط الوصول إلى الكيانات المكانية.
  • يمكن للتطبيق إنشاء معرّف إضافي XrSpatialContextEXT لتتبُّع التعليقات التوضيحية ضمن مرجع جديد خلال الفترة الزمنية التي يكون فيها XrSpatialReferenceCacheANDROID صالحًا .
  • يمكن للتطبيق إتلاف مقابض XrSpatialContextEXT لتقليل مجموعة التعليقات التوضيحية التي يمكن رصدها وتتبُّعها بشكل ديناميكي في وقت التشغيل.

دعم وقت التشغيل

يجب أن تعلن بيئة التشغيل عن إتاحة ميزة تتبُّع التعليقات التوضيحية باستخدام xrEnumerateSpatialCapabilitiesEXT من خلال إدراج الميزة التالية:

  • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

عندما يتيح وقت التشغيل إمكانية تتبُّع التعليقات التوضيحية:

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

XrResult xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    sourceCapacityInput,
    uint32_t*                                   sourceCountOutput,
    XrSpatialAnnotationReferenceSourceANDROID*  sources);

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

  • ‫instance هو معرّف فريد لكائن XrInstance .
  • systemId هو XrSystemId الذي سيتم تعداد مصادره المرجعية.
  • ‫capability هو XrSpatialCapabilityEXT الذي سيتم تعداد مصادر المراجع له.
  • sourceCapacityInput هي سعة مصفوفة sources، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
  • sourceCountOutput هو عدد المصادر أو السعة المطلوبة في حال عدم كفاية sourceCapacityInput.
  • ‫sources هي مصفوفة من XrSpatialAnnotationReferenceSourceANDROID . يمكن أن تكون القيمة NULL إذا كانت قيمة sourceCapacityInput هي 0.
  • راجِع قسم مَعلمات حجم المخزن المؤقت للحصول على وصف تفصيلي حول كيفية استرداد حجم sources المطلوب.

يمكن للتطبيق تعداد قائمة مراجع مصادر التعليقات التوضيحية المكانية المتوافقة مع XrSystemId معيّن باستخدام xrEnumerateSpatialAnnotationReferenceSourcesANDROID .

يجب ألا يسرد وقت التشغيل مصادر المراجع التي لم يتم تفعيل إضافتها لـ instance .

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

رموز الإرجاع

ناجحة

  • 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

typedef enum XrSpatialAnnotationReferenceSourceANDROID {
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationReferenceSourceANDROID;

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

تحمل القيم المُعدّدة المعاني التالية:

وصف التعداد

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID

الصورة المرجعية هي صورة غير مقصوصة تم إخراجها من واجهة برمجة تطبيقات كاميرا Android، مثل صورة من ImageReader مرتبطة بـ CameraDevice في Camera2 أو ImageProxy من ImageAnalysis مرتبطة بـ CameraX. وهي عادةً إحدى كاميرات RGB المتّجهة للأمام.

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID

الصورة المرجعية هي صورة غير مقصوصة تم إخراجها من واجهة برمجة التطبيقات Android MediaProjection API، مثل صورة من ImageReader مرتبطة بشاشة عرض افتراضية MediaProjection. ويمكن أن يشمل محتوًى افتراضيًا وحقيقيًا.

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

typedef struct XrSystemSpatialAnnotationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           referenceCacheTimespan;
    uint32_t           maxReferencePixelWidth;
    uint32_t           maxReferencePixelHeight;
    uint32_t           maxReferenceCount;
    uint32_t           maxAnnotationCount;
} XrSystemSpatialAnnotationPropertiesANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • يشير referenceCacheTimespan إلى الفترة الزمنية بالثواني لمقبض XrSpatialReferenceCacheANDROID صالح.
  • يشير maxReferencePixelWidth إلى الحد الأقصى لعرض حافة الصور المرجعية بالبكسل.
  • يشير maxReferencePixelHeight إلى الحد الأقصى لارتفاع حافة الصور المرجعية بالبكسل.
  • يشير maxReferenceCount إلى الحد الأقصى لعدد الصور المرجعية التي سيتم تخصيصها في الوقت نفسه.
  • يشير maxAnnotationCount إلى الحد الأقصى لعدد التعليقات التوضيحية التي سيتم تتبُّعها في الوقت نفسه.

عندما يتيح وقت التشغيل إمكانية تتبُّع التعليقات التوضيحية، يمكن لأحد التطبيقات فحص خصائص النظام ذات الصلة من خلال ربط بنية XrSystemSpatialAnnotationPropertiesANDROID ببنية XrSystemProperties عند استدعاء xrGetSystemProperties .

إذا كان XrSpatialReferenceImageEXT :: width من XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference يتجاوز maxReferencePixelWidth ، يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE عند استدعاء xrCreateSpatialContextAsyncEXT .

إذا كان XrSpatialReferenceImageEXT :: height من XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference يتجاوز maxReferencePixelHeight ، يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE عند استدعاء xrCreateSpatialContextAsyncEXT .

إذا كان XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: time خارج النطاق الزمني لـ XrSpatialReferenceCacheANDROID :: cache ، يجب أن يعرض وقت التشغيل XR_ERROR_TIME_INVALID عند استدعاء xrCreateSpatialContextAsyncEXT . يمكن للتطبيق إعادة إنشاء معرّف XrSpatialContextEXT باستخدام مرجع جديد خلال الفترة الزمنية لـ XrSpatialReferenceCacheANDROID .

إذا تجاوز عدد الصور المرجعية المخصّصة maxReferenceCount ، يجب أن يعرض وقت التشغيل XR_ERROR_LIMIT_REACHED ويشير إلى تعذُّر عملية التهيئة من خلال XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult . يمكن للتطبيق إتلاف معرّف XrSpatialContextEXT وإعادة المحاولة بعد اكتمال عملية التهيئة المعلّقة.

إذا تجاوز عدد التعليقات التوضيحية النشطة maxAnnotationCount ، يجب أن تعرض بيئة التشغيل XR_ERROR_VALIDATION_FAILURE عند استدعاء xrCreateSpatialContextAsyncEXT .

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

ذاكرة التخزين المؤقت للمراجع أثناء التشغيل

XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)

يمثّل معرّف XrSpatialReferenceCacheANDROID ذاكرة تخزين مؤقت للمراجع في وقت التشغيل التي تم تسجيلها من مصدر معيّن.

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

XrResult xrCreateSpatialReferenceCacheAsyncANDROID(
    XrSession                                   session,
    const XrSpatialReferenceCacheCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

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

  • ‫session هو XrSession سيتم فيه تفعيل ذاكرة التخزين المؤقت للمراجع.
  • createInfo هو مؤشر إلى XrSpatialReferenceCacheCreateInfoANDROID يُستخدَم لتحديد مَعلمات ذاكرة التخزين المؤقت للمرجع.
  • ‫future هو مؤشر إلى مقبض الإخراج الخاص بـ XrFutureEXT .

يمكن للتطبيق إنشاء معرّف XrSpatialReferenceCacheANDROID عن طريق استدعاء xrCreateSpatialReferenceCacheAsyncANDROID . قد يستغرق وقت التشغيل بعض الوقت لتهيئة خدمات التتبُّع. يمكن للتطبيق بعد ذلك استدعاء xrCreateSpatialReferenceCacheCompleteANDROID بشكل متكرّر للتحقّق من اكتمال هذه العملية غير المتزامنة.

يجب أن يعرض وقت التشغيل القيمة XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT إذا لم يتم إدراج XrSpatialReferenceCacheCreateInfoANDROID :: capability في xrEnumerateSpatialCapabilitiesEXT.

يجب أن تعرض بيئة التشغيل القيمة XR_ERROR_FEATURE_UNSUPPORTED إذا لم يتم إدراج XrSpatialReferenceCacheCreateInfoANDROID :: source في xrEnumerateSpatialAnnotationReferenceSourcesANDROID للإمكانية المحدّدة.

يمكن للتطبيق إنشاء معرّف واحد فقط لكل مصدر لإمكانية معيّنة. بخلاف ذلك، يجب أن يعرض وقت التشغيل القيمة XR_ERROR_LIMIT_REACHED.

يمكن للتطبيق بعد ذلك تسجيل مراجع وقت التشغيل خلال الفترة الزمنية لمقبض XrSpatialReferenceCacheANDROID من أجل إعداد مقبض XrSpatialContextEXT جديد.

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

رموز الإرجاع

ناجحة

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

فشل

  • XR_ERROR_FEATURE_UNSUPPORTED
  • 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_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialReferenceCacheCreateInfoANDROID {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialCapabilityEXT                       capability;
    XrSpatialAnnotationReferenceSourceANDROID    source;
} XrSpatialReferenceCacheCreateInfoANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو في هذه الإضافة.
  • ‫capability هو XrSpatialCapabilityEXT يصف الميزة التي تم إنشاء ذاكرة التخزين المؤقت المرجعية لها.
  • ‫source هو XrSpatialAnnotationReferenceSourceANDROID يصف مصدر ذاكرة التخزين المؤقت للمرجع.

يصف البنية XrSpatialReferenceCacheCreateInfoANDROID المعلومات اللازمة لإنشاء معرّف XrSpatialReferenceCacheANDROID.

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

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

XrResult xrCreateSpatialReferenceCacheCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialReferenceCacheCompletionANDROID* completion);

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

يمكن للتطبيق استدعاء الدالة xrCreateSpatialReferenceCacheCompleteANDROID للانتظار إلى حين اكتمال العملية غير المتزامنة التي بدأتها الدالة xrCreateSpatialReferenceCacheAsyncANDROID .

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

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

رموز الإرجاع

ناجحة

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

فشل

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

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

typedef struct XrCreateSpatialReferenceCacheCompletionANDROID {
    XrStructureType                   type;
    void*                             next;
    XrResult                          futureResult;
    XrSpatialReferenceCacheANDROID    referenceCache;
} XrCreateSpatialReferenceCacheCompletionANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو في هذه الإضافة.
  • futureResult هو XrResult لعملية إنشاء ذاكرة التخزين المؤقت للمرجع.
  • ‫referenceCache هو معرّف XrSpatialReferenceCacheANDROID في حال نجاح العملية.

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

قيم futureResult:

ناجحة

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

فشل

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

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

عندما تكون قيمة referenceCache صالحة، يتم تسجيل عمليات التخزين المؤقت ضمن XrSystemSpatialAnnotationPropertiesANDROID :: referenceCacheTimespan .

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

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

XrResult xrDestroySpatialReferenceCacheANDROID(
    XrSpatialReferenceCacheANDROID              cacheHandle);

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

يمكن للتطبيق استدعاء الدالة xrDestroySpatialReferenceCacheANDROID لإيقاف معرّف cacheHandle والموارد الأساسية عند الانتهاء من إنشاء السياق المكاني.

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

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

  • يجب مزامنة الوصول إلى cacheHandle وأي أسماء مستخدمين للأطفال خارجيًا

رموز الإرجاع

ناجحة

  • XR_SUCCESS

فشل

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

الإعدادات

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

typedef struct XrSpatialCapabilityConfigurationAnnotationTrackingANDROID {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialReferenceCacheANDROID      cache;
    XrTime                              time;
    XrSpatialReferenceImageEXT          reference;
} XrSpatialCapabilityConfigurationAnnotationTrackingANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • ‫capability هو XrSpatialCapabilityEXT ويجب أن يكون XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .
  • enabledComponentCount هو uint32_t يصف عدد العناصر في مصفوفة enabledComponents.
  • ‫enabledComponents هو مؤشر إلى مصفوفة من XrSpatialComponentTypeEXT .
  • ‫cache هو XrSpatialReferenceCacheANDROID تم إنشاؤه سابقًا لتسجيل مراجع وقت التشغيل لإعدادات reference.
  • time هو XrTime الذي يتم فيه تسجيل reference.
  • ‫reference هي XrSpatialReferenceImageEXT مع تعليقات توضيحية مرتبطة بمؤشرها التالي.

يمكن للتطبيقات تفعيل إمكانية XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID المكانية من خلال إضافة مؤشر إلى بنية XrSpatialCapabilityConfigurationAnnotationTrackingANDROID في XrSpatialContextCreateInfoEXT :: capabilityConfigs .

يجب أن تعرض قيمة وقت التشغيل XR_ERROR_VALIDATION_FAILURE إذا لم تكن قيمة capability هي XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID .

يجب أن تعرض بيئة التشغيل XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT إذا لم يكن reference يحتوي على أي تعليقات توضيحية.

يجب أن تعرض وقت التشغيل القيمة XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT إذا كان مكوّن التعليق التوضيحي مُدرَجًا في enabledComponents ولكن لم يتم ربط أي تعليقات توضيحية مقابلة بـ reference .

يجب أن تعرض بيئة التشغيل القيمة XR_ERROR_VALIDATION_FAILURE إذا لم يكن cache مملوكًا لجلسة XrSession نفسها التي يتم تمريرها إلى xrCreateSpatialContextAsyncEXT .

يجب أن تعرض بيئة التشغيل XR_ERROR_TIME_INVALID إذا كان time خارج النطاق الزمني لـ cache .

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

أحداث تتبُّع التعليقات التوضيحية

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

typedef struct XrEventDataSpatialAnnotationTrackingANDROID {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
    uint32_t               annotationIndex;
    XrResult               initializationResult;
} XrEventDataSpatialAnnotationTrackingANDROID;

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

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية.
  • ‫spatialContext هو XrSpatialContextEXT الذي تم تفعيل ميزة تتبُّع التعليقات التوضيحية له.
  • يتم ربط annotationIndex بالفهرس من مصفوفة التعليقات التوضيحية المرتبطة بـ XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference .
  • يشير initializationResult إلى نتيجة تهيئة التعليق التوضيحي. إذا لم يكن XR_SUCCESS ، يمكن للتطبيق إتلاف مقبض XrSpatialContextEXT وإعادة إنشائه لإعادة تهيئة التعليق التوضيحي، أو مواصلة استخدام spatialContext لتتبُّع التعليقات التوضيحية الأخرى.

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

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

يجب أن يملأ وقت التشغيل initializationResult بالقيمة XR_SUCCESS إذا تم إعداد التعليق التوضيحي بنجاح. يمكن للتطبيق بعد ذلك استرداد الحدث XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT لتتبُّع التعليق التوضيحي.

وفي ما عدا ذلك، يجب أن يملأ وقت التشغيل initializationResult برمز خطأ مناسب للإشارة إلى سبب الخطأ. يمكن للتطبيق إتلاف معرّف XrSpatialContextEXT لبدء تعليق توضيحي جديد أو مواصلة استخدام spatialContext لتتبُّع التعليقات التوضيحية الأخرى.

التعليق التوضيحي الرباعي

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

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

المرجع الرباعي

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

typedef struct XrSpatialAnnotationQuadReferenceANDROID {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 quadCount;
    const XrSpatialAnnotationQuadANDROID*    quads;
} XrSpatialAnnotationQuadReferenceANDROID;

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

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

عندما يتيح وقت التشغيل استخدام التعليقات التوضيحية الرباعية، يمكن لأحد التطبيقات ضبط التعليقات التوضيحية من خلال ربط بنية XrSpatialAnnotationQuadReferenceANDROID ببنية XrSpatialReferenceImageEXT :: next، وضبط المرجع في XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference عند إنشاء معرّف XrSpatialContextEXT.

يجب أن يعرض وقت التشغيل القيمة XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT من xrCreateSpatialContextAsyncEXT إذا كانت قيمة quadCount هي 0.

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

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

typedef struct XrSpatialAnnotationQuadANDROID {
    XrSpatialAnnotationQuadAlignmentANDROID    alignment;
    XrVector2f                                 upperLeft;
    XrVector2f                                 upperRight;
    XrVector2f                                 lowerRight;
    XrVector2f                                 lowerLeft;
} XrSpatialAnnotationQuadANDROID;

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

  • ‫alignment هو XrSpatialAnnotationQuadAlignmentANDROID للرباعي.
  • ‫upperLeft هو XrVector2f يصف إحداثيات الزاوية العلوية اليسرى للشكل الرباعي المرتبط بنقطة الأصل.
  • ‫upperRight هو XrVector2f يصف إحداثيات الزاوية العلوية اليسرى من الشكل الرباعي المرتبط بنقطة الأصل.
  • ‫lowerRight هو XrVector2f يصف إحداثيات الزاوية السفلية اليسرى من الشكل الرباعي المرتبط بنقطة الأصل.
  • ‫lowerLeft هو XrVector2f يصف إحداثيات الزاوية السفلية اليسرى من الشكل الرباعي المرتبط بنقطة الأصل.

المربّع في مساحة ثنائية الأبعاد هو شكل رباعي الأضلاع محدّب بترتيب في اتجاه عقارب الساعة. ترتبط قيمة الزوايا الأربع بنقطة الأصل (0, 0) التي يرتبط بها الشكل الرباعي.

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

typedef enum XrSpatialAnnotationQuadAlignmentANDROID {
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationQuadAlignmentANDROID;

يصف التعداد XrSpatialAnnotationQuadAlignmentANDROID محاذاة التعليق التوضيحي الرباعي.

تحمل القيم المُعدّدة المعاني التالية:

وصف التعداد

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID

يكون المربّع الحاشية التوضيحية موازيًا لمستوى الشاشة، بينما يظل تدويره في المستوى مقفلاً على جاذبية العالم. يظهر الناتج على شكل مربّع إحاطة عادي ومستقيم.

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID

يتم تثبيت المضلّع الرباعي الخاص بالتعليق التوضيحي مباشرةً على العنصر، ما يتيح مطابقة المحاذاة المحدّدة في الصورة المرجعية. المخرجات هي شكل رباعي محدّب، يتم تعديل شكله ليتطابق مع منظور الكائن.

مكوّنات رباعية

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

typedef struct XrSpatialAnnotationQuadDataANDROID {
    uint32_t                          annotationIndex;
    XrSpaceLocationData               origin;
    XrSpatialAnnotationQuadANDROID    quad;
} XrSpatialAnnotationQuadDataANDROID;

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

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

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

typedef struct XrSpatialComponentAnnotationQuadListANDROID {
    XrStructureType                        type;
    void*                                  next;
    uint32_t                               quadCount;
    XrSpatialAnnotationQuadDataANDROID*    quads;
} XrSpatialComponentAnnotationQuadListANDROID;

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

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

يمكن للتطبيق طلب البحث عن مكوّن التعليق التوضيحي الرباعي للأشكال المكانية في XrSpatialSnapshotEXT من خلال إضافة XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID في XrSpatialComponentDataQueryConditionEXT :: componentTypes وإضافة XrSpatialComponentAnnotationQuadListANDROID إلى سلسلة المؤشر التالي في XrSpatialComponentDataQueryResultEXT .

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

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

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

مثال على الرمز

التحقّق من توفّر بيئة التشغيل

يوضّح نموذج الرمز البرمجي التالي كيفية التحقّق مما إذا كانت بيئة التشغيل تتيح إمكانية تتبُّع التعليقات التوضيحية.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrEnumerateSpatialCapabilitiesEXT xrEnumerateSpatialCapabilitiesEXT;
PFN_xrEnumerateSpatialAnnotationReferenceSourcesANDROID xrEnumerateSpatialAnnotationReferenceSourcesANDROID;
PFN_xrEnumerateSpatialReferenceImageFormatsEXT xrEnumerateSpatialReferenceImageFormatsEXT;
PFN_xrEnumerateSpatialCapabilityComponentTypesEXT xrEnumerateSpatialCapabilityComponentTypesEXT;

// Check spatial annotation tracking capability
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0,
                                         &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount,
                                         &capabilityCount,
                                         capabilities.data()));
if (std::find(capabilities.begin(), capabilities.end(),
              XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID) ==
    capabilities.end()) {
  // System does not support spatial annotation tracking.
  return;
}

// Inspect system properties for annotation tracking variables
XrSystemSpatialAnnotationPropertiesANDROID annotationSystemProperties{
    XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{.type = XR_TYPE_SYSTEM_PROPERTIES,
                                    .next = &annotationSystemProperties,
                                    .systemId = systemId};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (annotationSystemProperties.maxAnnotationCount == 0) {
  // System does not support any active annotations.
  return;
}

// Enumerate supported reference sources
uint32_t sourceCountOutput = 0;
XrSpatialAnnotationReferenceSourceANDROID desiredSource =
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID;
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    0, &sourceCountOutput, nullptr));
std::vector<XrSpatialAnnotationReferenceSourceANDROID> sources(sourceCountOutput);
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    sourceCountOutput, &sourceCountOutput, sources.data()));
if (std::find(sources.begin(), sources.end(), desiredSource) == sources.end()) {
  // The desired source is not supported.
  return;
}

// Enumerate supported reference image formats, provided by XR_EXT_spatial_image_tracking.
uint32_t formatCountOutput = 0;
XrSpatialReferenceImageFormatEXT desiredFormat =
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT; // Or XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT for screenshot.
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID, 0,
    &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    formats.size(), &formatCountOutput, formats.data()));
if (std::find(formats.begin(), formats.end(), desiredFormat) == formats.end()) {
  // The desired format is not supported
  return;
}

// Enumerate supported components for annotation tracking capability.
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes{
    XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));
std::vector<XrSpatialComponentTypeEXT>
    annotationTypes(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = annotationTypes.size();
capabilityComponentTypes.componentTypes = annotationTypes.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));

// Check supported annotation components.
XrSpatialComponentTypeEXT desiredComponent =
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID;
const auto supportedComponent = [&annotationTypes](
                                    XrSpatialComponentTypeEXT component) {
  return std::find(annotationTypes.begin(), annotationTypes.end(), component) !=
         annotationTypes.end();
};
if (!supportedComponent(desiredComponent)) {
  // The desired annotation is not supported.
  return;
}

ضبط التعليق التوضيحي الرباعي

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

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrCreateSpatialReferenceCacheAsyncANDROID xrCreateSpatialReferenceCacheAsyncANDROID;
PFN_xrCreateSpatialReferenceCacheCompleteANDROID xrCreateSpatialReferenceCacheCompleteANDROID;
PFN_xrDestroySpatialReferenceCacheANDROID xrDestroySpatialReferenceCacheANDROID;
PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialReferenceImageFormatEXT desiredFormat;
XrSpatialAnnotationReferenceSourceANDROID desiredSource;
XrSpatialComponentTypeEXT desiredComponent;

// Create and start reference cache to prepare for capturing reference images.
XrSpatialReferenceCacheANDROID referenceCache;
XrSpatialReferenceCacheCreateInfoANDROID cacheCreateInfo{
  .type = XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
  .source = desiredSource,
};
XrFutureEXT cacheFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialReferenceCacheAsyncANDROID(session, &cacheCreateInfo, &cacheFuture));

waitUntilReady(cacheFuture);

XrCreateSpatialReferenceCacheCompletionANDROID cacheCompletion{
    XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID};
CHK_XR(xrCreateSpatialReferenceCacheCompleteANDROID(session, cacheFuture,
                                                     &cacheCompletion));
if (cacheCompletion.futureResult != XR_SUCCESS) {
  // Error, reference cache creation failed
  return;
}

referenceCache = cacheCompletion.referenceCache;

// Create the reference image with quad annotations

//  YUV 4:2:0 Planar:
// ----------------------
// |     Y      |Cb |Cr |
// ----------------------
XrSpatialReferenceImagePlaneEXT cameraImagePlanes[3];
// for each plane (0=Y, 1=U(cb), 2=V(Cr)) return by Image#getPlanes().
for (int i = 0; i < 3; ++i) {
  cameraImagePlanes[i].buffer; // read from Plane#getBuffer().
  cameraImagePlanes[i].bufferSize; // set each buffer size. Y = width * height (bytes); U = Y / 4 (bytes); V = Y / 4 (bytes).
  cameraImagePlanes[i].rowStride; // read from Plane#getRowStride().
  cameraImagePlanes[i].pixelStride; // read from Plane#getPixelStride().
}
XrSpatialReferenceImageEXT referenceImage{
      XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
referenceImage.width = 640;
referenceImage.height = 480;
referenceImage.format = desiredFormat;
referenceImage.planeCount = 3;
referenceImage.planes = cameraImagePlanes;

XrSpatialAnnotationQuadANDROID
    quad; // quad coordinates within the reference image.
quad.alignment = XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID;
// Set unnormalized pixel coordinates of 4 corners.
quad.upperLeft = {0.0, 0.0};
quad.upperRight = {0.0, 100.0};
quad.lowerRight = {100.0, 100.0};
quad.lowerLeft = {0.0, 100.0};

XrSpatialAnnotationQuadReferenceANDROID quadReference{
    XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID};
quadReference.quads = &quad;
quadReference.quadCount = 1;
referenceImage.next = &quadReference;

// Create the spatial context with annotation configuration.
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
      desiredComponent,
  };

  // Configure annotation tracking
  XrSpatialCapabilityConfigurationAnnotationTrackingANDROID annotationConfig{
      XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID};
  annotationConfig.capability =
      XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID;
  annotationConfig.enabledComponentCount = enabledComponents.size();
  annotationConfig.enabledComponents = enabledComponents.data();
  annotationConfig.cache = referenceCache;
  annotationConfig.time; // The time when this reference image is captured.
  annotationConfig.reference = referenceImage;

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

  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
    return;
  }

  spatialContext = completion.spatialContext;
  CHK_XR(xrDestroySpatialReferenceCacheANDROID(referenceCache));
}

اكتشاف التعليقات التوضيحية النشطة

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

XrInstance instance;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL
XrSpatialContextEXT spatialContext; // previously created

PFN_xrCreateSpatialDiscoverySnapshotAsyncEXT xrCreateSpatialDiscoverySnapshotAsyncEXT;
PFN_xrCreateSpatialDiscoverySnapshotCompleteEXT xrCreateSpatialDiscoverySnapshotCompleteEXT;
PFN_xrQuerySpatialComponentDataEXT xrQuerySpatialComponentDataEXT;
PFN_xrDestroySpatialSnapshotEXT xrDestroySpatialSnapshotEXT;
PFN_xrPollEvent xrPollEvent;
PFN_xrDestroySpatialContextEXT xrDestroySpatialContextEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialComponentTypeEXT desiredComponent; // e.g. XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

auto discoverAnnotations = [&](XrSpatialContextEXT spatialContext, XrTime time,
                               XrSpace baseSpace) {
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{desiredComponent};
  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 = baseSpace;
  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 desired annotation data, e.g. quad.
    XrSpatialComponentTypeEXT componentsToQuery[] = {
        XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID};
    XrSpatialComponentDataQueryConditionEXT queryCond{
        XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = 1;
    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<XrSpatialAnnotationQuadDataANDROID> quads(
        queryResult.entityIdCountOutput);
    XrSpatialComponentAnnotationQuadListANDROID quadList{
        XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID};
    quadList.quadCount = quads.size();
    quadList.quads = quads.data();
    queryResult.next = &quadList;

    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 XrSpatialAnnotationQuadDataANDROID &currentQuad = quads[i];
        // Rendering quad in the view.
      }
    }

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

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

  XrSpace space;           // Application's play space.
  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_ANNOTATION_TRACKING_ANDROID: {
      const XrEventDataSpatialAnnotationTrackingANDROID &eventdata =
          *reinterpret_cast<XrEventDataSpatialAnnotationTrackingANDROID *>(
              &event);
      if (eventdata.initializationResult != XR_SUCCESS) {
        // handle initialization failure.
        // e.g. CHK_XR(xrDestroySpatialContextEXT(spatialContext));
      }
      break;
    }
    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, space);
      break;
    }
    }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

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

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

المنشآت الجديدة

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

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

  • XR_ANDROID_SPATIAL_ANNOTATION_TRACKING_EXTENSION_NAME
  • XR_ANDROID_spatial_annotation_tracking_SPEC_VERSION

  • تمديد XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_REFERENCE_CACHE_ANDROID

  • تمديد XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

  • تمديد XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

  • توسيع XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID
    • XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID
    • XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID
    • XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID

المشاكل

سجلّ التعديلات

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

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