ردیابی حاشیه‌نویسی فضایی XR_ANDROID

رشته نام

XR_ANDROID_spatial_annotation_tracking

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

۷۹۵ عدد

بازنگری

۱

وضعیت تصویب

تصویب نشده

وابستگی‌های افزونه و نسخه

XR_EXT_spatial_entity
و
XR_EXT_spatial_image_tracking

آخرین تاریخ اصلاح

۲۰۲۶-۰۱-۱۲

وضعیت آی‌پی

هیچ ادعای مالکیت معنوی شناخته‌شده‌ای وجود ندارد.

مشارکت‌کنندگان

لوانا چن، گوگل
کریستوفر فیل، گوگل
مارتین ساندرمایر، گوگل
دیوید جوزف تان، گوگل
جارد فایندر، گوگل
نیهاو جین، گوگل

نمای کلی

این افزونه قابلیت ردیابی حاشیه‌نویسی را برای افزونه XR_EXT_spatial_entity فراهم می‌کند تا حاشیه‌نویسی‌های مختلف در صحنه را ردیابی کند. این افزونه به برنامه‌ها امکان می‌دهد تا روی اشیاء فیزیکی یا مجازی تعریف‌شده توسط ارجاعات زمان اجرا، پوشش‌هایی قرار دهند.

این افزونه یک نوع حاشیه‌نویسی پایه "Quad" ارائه می‌دهد که یک چندضلعی است که دقیقاً ۴ ضلع دارد، یعنی چهارضلعی محدب، که یک جعبه محدودکننده دوبعدی تعمیم‌یافته را در یک مرجع زمان اجرا نشان می‌دهد. یک حاشیه‌نویسی چهارگانه ردیابی‌شده به عنوان یک موجودیت مکانی با (یا "دارای") اجزای زیر نمایش داده می‌شود:

  • 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 است، یا عدد ۰ نشان‌دهنده‌ی درخواستی برای بازیابی ظرفیت مورد نیاز است.
  • sourceCountOutput تعداد منابع یا ظرفیت مورد نیاز در صورتی است که sourceCapacityInput کافی نباشد.
  • sources آرایه‌ای از XrSpatialAnnotationReferenceSourceANDROID است. اگر sourceCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای توضیحات مفصل در مورد بازیابی اندازه 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 منبع مرجعی را توصیف می‌کند که فراداده‌های یک حاشیه‌نویسی را فراهم می‌کند.

enum ها معانی زیر را دارند:

توضیحات شمارشی

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID

تصویر مرجع، یک تصویر برش‌نخورده خروجی از یک API دوربین اندروید است، مثلاً تصویری از یک ImageReader مرتبط با Camera2 CameraDevice یا یک ImageProxy از یک ImageAnalysis مرتبط با CameraX. این معمولاً یکی از دوربین‌های RGB رو به جلو است.

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID

تصویر مرجع، یک خروجی تصویر برش‌نخورده از API اندروید MediaProjection است، مثلاً تصویری از یک 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 بیشتر شود، زمان اجرا باید هنگام فراخوانی xrCreateSpatialContextAsyncEXT، XR_ERROR_VALIDATION_FAILURE برگرداند.

اگر XrSpatialReferenceImageEXT :: height from XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference از maxReferencePixelHeight بیشتر شود، زمان اجرا باید هنگام فراخوانی xrCreateSpatialContextAsyncEXT، XR_ERROR_VALIDATION_FAILURE را برگرداند.

اگر time XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: خارج از بازه زمانی XrSpatialReferenceCacheANDROID :: cache باشد، زمان اجرا باید هنگام فراخوانی xrCreateSpatialContextAsyncEXT XR_ERROR_TIME_INVALID را برگرداند. برنامه می‌تواند دسته XrSpatialContextEXT را با یک ارجاع جدید در بازه زمانی XrSpatialReferenceCacheANDROID بازسازی کند.

اگر تعداد تصاویر مرجع اختصاص داده شده maxReferenceCount بیشتر شود، زمان اجرا باید XR_ERROR_LIMIT_REACHED برگرداند و از طریق XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult شکست مقداردهی اولیه را نشان دهد. برنامه می‌تواند هندل XrSpatialContextEXT را از بین ببرد و پس از تکمیل مقداردهی اولیه در انتظار، دوباره امتحان کند.

اگر تعداد حاشیه‌نویسی‌های فعال از maxAnnotationCount بیشتر شود، زمان اجرا باید هنگام فراخوانی xrCreateSpatialContextAsyncEXT XR_ERROR_VALIDATION_FAILURE را برگرداند.

کاربرد معتبر (ضمنی)

حافظه نهان مرجع زمان اجرا 

XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)

هندل XrSpatialReferenceCacheANDROID نشان‌دهنده‌ی یک حافظه‌ی نهان (cache) از ارجاعات زمان اجرا است که از یک منبع مشخص ثبت شده‌اند.

تابع xrCreateSpatialReferenceCacheAsyncANDROID به صورت زیر تعریف شده است: 

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

توضیحات پارامتر

  • session یک XrSession است که در آن حافظه نهان مرجع فعال خواهد بود.
  • createInfo یک اشاره‌گر به XrSpatialReferenceCacheCreateInfoANDROID است که برای تعیین پارامترهای حافظه نهان مرجع استفاده می‌شود.
  • future یک اشاره‌گر به خروجی یک XrFutureEXT است.

برنامه می‌تواند با فراخوانی xrCreateSpatialReferenceCacheAsyncANDROID، یک هندل XrSpatialReferenceCacheANDROID ایجاد کند. ممکن است زمان اجرا برای مقداردهی اولیه سرویس‌های ردیابی کمی طول بکشد. سپس برنامه می‌تواند xrCreateSpatialReferenceCacheCompleteANDROID را بارها و بارها فراخوانی کند تا تکمیل این عملیات ناهمزمان را بررسی کند.

اگر capability XrSpatialReferenceCacheCreateInfoANDROID :: توسط xrEnumerateSpatialCapabilitiesEXT فهرست نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT را برگرداند.

اگر source XrSpatialReferenceCacheCreateInfoANDROID :: توسط xrEnumerateSpatialAnnotationReferenceSourcesANDROID برای قابلیت داده شده فهرست نشده باشد، زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED برگرداند.

برنامه فقط می‌تواند برای هر منبع و برای یک قابلیت مشخص، یک هندل ایجاد کند. در غیر این صورت، زمان اجرا باید 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 بماند.

اگر future در حالت آماده نباشد، زمان اجرا باید XR_ERROR_FUTURE_PENDING_EXT برگرداند. اگر future قبلاً تکمیل یا لغو شده باشد، زمان اجرا باید XR_ERROR_FUTURE_INVALID_EXT را برگرداند.

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • 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 و هر handler فرزندی باید به صورت خارجی هماهنگ‌سازی شود.

کدهای بازگشت

موفقیت

  • 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 فعال کنند.

اگر capability XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID نباشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.

اگر reference حاوی هیچ حاشیه‌نویسی نباشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT را برگرداند.

اگر کامپوننت annotation در enabledComponents فهرست شده باشد اما هیچ annotation متناظری با reference مرتبط نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT را برگرداند.

اگر cache متعلق به همان XrSession ارسالی به xrCreateSpatialContextAsyncEXT نباشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.

اگر time خارج از بازه زمانی cache باشد، زمان اجرا باید XR_ERROR_TIME_INVALID برگرداند.

کاربرد معتبر (ضمنی)

رویدادهای ردیابی حاشیه‌نویسی

ساختار XrEventDataSpatialAnnotationTrackingANDROID به صورت زیر تعریف شده است: 

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

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است.
  • spatialContext همان XrSpatialContextEXT است که ردیابی حاشیه‌نویسی برای آن فعال شده است.
  • annotationIndex به اندیس آرایه annotation مرتبط با XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference می‌کند.
  • initializationResult نتیجه‌ی مقداردهی اولیه‌ی حاشیه‌نویسی (annotation) برابر 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 ، حاشیه‌نویسی‌ها را پیکربندی کند و هنگام ایجاد هندل XrSpatialContextEXT ، reference را در مرجع XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: تنظیم کند.

اگر quadCount برابر با ۰ باشد، زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT از xrCreateSpatialContextAsyncEXT برگرداند.

کاربرد معتبر (ضمنی)

ساختار 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 است که مختصات گوشه پایین سمت چپ چهارضلعی مربوط به مبدا را توصیف می‌کند.

یک چهارضلعی در فضای دوبعدی، یک چهارضلعی محدب با ترتیب عقربه‌های ساعت است. مقدار ۴ گوشه به مبدأ (۰، ۰) که چهارضلعی به آن مرتبط است، مربوط می‌شود.

کاربرد معتبر (ضمنی)

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 ترازبندی حاشیه‌نویسی چهارگانه را توصیف می‌کند.

enum ها معانی زیر را دارند:

توضیحات شمارشی

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 است.

برنامه می‌تواند با اضافه کردن XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID در XrSpatialComponentDataQueryConditionEXT :: componentTypes و اضافه کردن XrSpatialComponentAnnotationQuadListANDROID به زنجیره اشاره‌گر بعدی XrSpatialComponentDataQueryResultEXT ، کامپوننت quad annotation مربوط به موجودیت‌های مکانی در XrSpatialSnapshotEXT را جستجو کند.

اگر XrSpatialComponentAnnotationQuadListANDROID در زنجیره بعدی XrSpatialComponentDataQueryResultEXT :: next باشد، اما XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID در XrSpatialComponentDataQueryConditionEXT :: componentTypes گنجانده نشده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE از xrQuerySpatialComponentDataEXT بازگرداند.

اگر quadCount کمتر از XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput باشد، زمان اجرا باید XR_ERROR_SIZE_INSUFFICIENT از xrQuerySpatialComponentDataEXT برگرداند.

کاربرد معتبر (ضمنی)

کد مثال

بررسی پشتیبانی از زمان اجرا

کد مثال زیر نحوه بررسی پشتیبانی زمان اجرا از قابلیت ردیابی حاشیه‌نویسی را نشان می‌دهد. 

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

انواع شیء جدید

دستورات جدید

سازه‌های جدید

Enum های جدید

ثابت‌های شمارشی جدید

  • 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 (لوانا چن)

    • توضیحات اولیه افزونه