XR_ANDROID_spatial_annotation_tracking

رشته نام

XR_ANDROID_spatial_annotation_tracking

نوع افزونه

افزونه نمونه

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

795

بازبینی

1

وضعیت تصویب

تصویب‌نشده

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

XR_EXT_spatial_entity
و
XR_EXT_spatial_image_tracking

تاریخ آخرین تغییر

2026-01-12

وضعیت IP

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

همیاران

Levana Chen،‏ Google
Christopher Feil،‏ Google
Martin Sundermeyer،‏ Google
David Joseph Tan،‏ Google
Jared Finder،‏ Google
Nihav Jain،‏ Google

نمای کلی

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

مقادیر شمارشی معانی زیر را دارند:

شرح شمارشی

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID

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

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

اگر XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: time خارج از بازه زمانی 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 نشان‌دهنده حافظه نهان ارجاع‌های زمان اجرا است که از منبعی مشخص ضبط شده است.

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

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

شرح پارامترها

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

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

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

اگر XrSpatialReferenceCacheCreateInfoANDROID :: source توسط 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 و هرگونه دسته فرزند باید به‌صورت خارجی همگام‌سازی شود

کدهای برگشتی

موفقیت‌آمیز بود

  • 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 است که حاشیه‌نویسی‌ها به اشاره‌گر بعدی آن زنجیر شده‌اند.

برنامه‌ها می‌توانند با افزودن اشاره‌گر به ساختار XrSpatialCapabilityConfigurationAnnotationTrackingANDROID در XrSpatialContextCreateInfoEXT :: capabilityConfigs ، قابلیت فضایی XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID را فعال کنند.

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

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

اگر مؤلفه حاشیه‌نویسی در enabledComponents فهرست شده باشد اما هیچ حاشیه‌نویسی متناظری با 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 به نمایه از آرایه حاشیه‌نویسی مرتبط با 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 پیکربندی کند و هنگام ایجاد دسته XrSpatialContextEXT، مرجع را در XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference تنظیم کند.

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

برنامه می‌تواند با افزودن XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID در XrSpatialComponentDataQueryConditionEXT :: componentTypes و افزودن XrSpatialComponentAnnotationQuadListANDROID به زنجیره اشاره‌گر بعدی XrSpatialComponentDataQueryResultEXT، مؤلفه حاشیه‌نویسی چهارگوش نهادهای فضایی را در 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));

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

فرمان‌های جدید

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

Enums جدید

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

  • 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

مشکلات

سابقه نسخه

  • بازبینی ۱،‏ ۲۰۲۵-۰۹-۱۷ (لوانا چن)

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