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

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

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

المساهمون

ليفانا تشين، 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 .

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

رموز الإرجاع

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

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 إذا لم تكن السمة capability مدرَجة في XrSpatialReferenceCacheCreateInfoANDROID من خلال xrEnumerateSpatialCapabilitiesEXT .

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

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

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

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

رموز الإرجاع

Success

  • 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 أو إلغاؤه.

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

رموز الإرجاع

Success

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

Success

  • 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 والموارد الأساسية عند الانتهاء من إنشاء السياق المكاني.

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

أمان Thread

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

رموز الإرجاع

Success

  • XR_SUCCESS

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

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

الإعداد

يتم تعريف بنية 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

مرجع Quad

يتم تعريف بنية 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_SURFACE_ANDROID = 2,
    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

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

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SURFACE_ANDROID

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

مكوّنات Quad

يتم تعريف بنية 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 (ليفانا تشين)

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