XR_EXT_spatial_persistence

رشته نام

XR_EXT_spatial_persistence

نوع افزونه

افزونه نمونه

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

۷۶۴ عدد

بازنگری

۱

وضعیت تصویب

تصویب شده

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

XR_EXT_spatial_entity
و
XR_EXT_future

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

نیهاو جین، گوگل
جارد فایندر، گوگل
ناتالی فلوری، متا
یویچی تاگوچی، متا
ران بسمس، متا
یین لی، مایکروسافت
جیمی آلمپارامبیل، بایت‌دنس
ژیپنگ لیو، ByteDance
جون یان، بایت‌دنس

نمای کلی

این افزونه به برنامه‌ها اجازه می‌دهد تا موجودیت‌های مکانی را در جلسات برنامه، جلسات OpenXR و چندین زمینه مکانی OpenXR در یک جلسه کشف و مرتبط کنند. افزونه XR_EXT_spatial_entity ثابت کرد که یک موجودیت درون یک XrSpatialContextEXT توسط یک XrSpatialEntityIdEXT نمایش داده می‌شود. این افزونه با تعیین اینکه یک موجودیت، در صورت وجود، توسط یک XrUuid در جلسات برنامه و OpenXR نمایش داده می‌شود، این مفهوم را گسترش می‌دهد، یعنی یک برنامه می‌تواند از XrUuid ارائه شده توسط این افزونه برای شناسایی یک موجودیت در جلسات استفاده کند. این افزونه همچنین همپوشانی‌های مفیدی با افزونه XR_EXT_spatial_entity برای کشف موجودیت‌های مکانی در محیط کاربر و امکان پرس‌وجو از داده‌های مؤلفه آنها ارائه می‌دهد.

زمینه تداوم مکانی

ایجاد یک زمینه پایداری مکانی 

XR_DEFINE_HANDLE(XrSpatialPersistenceContextEXT)

دسته‌ی XrSpatialPersistenceContextEXT نشان‌دهنده‌ی اتصال به یک فضای ذخیره‌سازی موجودیت مکانی پایدار است.

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

XrResult xrCreateSpatialPersistenceContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialPersistenceContextCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

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

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

یک برنامه می‌تواند با استفاده از تابع xrCreateSpatialPersistenceContextAsyncEXT یک دسته XrSpatialPersistenceContextEXT ایجاد کند و دامنه زمینه persistence را در createInfo پیکربندی کند.

اگر scope XrSpatialPersistenceContextCreateInfoEXT :: توسط xrEnumerateSpatialPersistenceScopesEXT شمارش نشده باشد، زمان اجرا باید XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_UNSUPPORTED_EXT را برگرداند.

اگر یک زمان اجرا، یک سیستم مجوز برای کنترل دسترسی برنامه به حافظه‌ی پایداری که با XrSpatialPersistenceContextEXT نمایش داده می‌شود، اعمال کند، در صورتی که آن مجوزها به این برنامه اعطا نشده باشند، زمان اجرا باید XR_ERROR_PERMISSION_INSUFFICIENT برگرداند.

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

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_UNSUPPORTED_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialPersistenceContextCreateInfoEXT {
    XrStructureType                 type;
    const void*                     next;
    XrSpatialPersistenceScopeEXT    scope;
} XrSpatialPersistenceContextCreateInfoEXT;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • scope یک XrSpatialPersistenceScopeEXT است که دامنه ذخیره‌سازی زمینه پایداری را تعریف می‌کند.

ساختار XrSpatialPersistenceContextCreateInfoEXT اطلاعات لازم برای ایجاد یک هندل XrSpatialPersistenceContextEXT را توصیف می‌کند.

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

typedef enum XrSpatialPersistenceScopeEXT {
    XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT = 1,
    XR_SPATIAL_PERSISTENCE_SCOPE_LOCAL_ANCHORS_EXT = 1000781000,
    XR_SPATIAL_PERSISTENCE_SCOPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceScopeEXT;

شمارش XrSpatialPersistenceScopeEXT انواع مختلف حوزه‌های زمینه پایداری را مشخص می‌کند.

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

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

XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT

به برنامه دسترسی فقط خواندنی (یعنی برنامه نمی‌تواند مخزن مرتبط با این دامنه را تغییر دهد) به موجودیت‌های مکانی که توسط سیستم ذخیره و مدیریت می‌شوند، می‌دهد. برنامه می‌تواند از UUID در مؤلفه‌ی پایداری برای این دامنه استفاده کند تا موجودیت‌ها را در زمینه‌های مکانی و راه‌اندازی مجدد دستگاه مرتبط سازد.

XR_SPATIAL_PERSISTENCE_SCOPE_LOCAL_ANCHORS_EXT

عملیات پایداری و دسترسی به داده‌ها محدود به لنگرهای مکانی، در همان دستگاه، برای همان کاربر و همان برنامه است (اضافه شده توسط افزونه XR_EXT_spatial_persistence_operations )

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

XrResult xrEnumerateSpatialPersistenceScopesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    persistenceScopeCapacityInput,
    uint32_t*                                   persistenceScopeCountOutput,
    XrSpatialPersistenceScopeEXT*               persistenceScopes);

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

  • instance یک هندل برای XrInstance است.
  • systemId همان XrSystemId است که محدوده‌های پایداری مکانی آن شمارش خواهد شد.
  • persistenceScopeCapacityInput ظرفیت آرایه persistenceScopes است، یا 0 برای نشان دادن درخواستی برای بازیابی ظرفیت مورد نیاز.
  • persistenceScopeCountOutput تعداد محدوده‌های persistence یا ظرفیت مورد نیاز در صورتی است که persistenceScopeCapacityInput کافی نباشد.
  • persistenceScopes آرایه‌ای از XrSpatialPersistenceScopeEXT است. اگر persistenceScopeCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای توضیحات مفصل در مورد بازیابی اندازه مورد نیاز persistenceScopes ، به فصل پارامترهای اندازه بافر مراجعه کنید.

برنامه می‌تواند فهرست محدوده‌های پایداری مکانی پشتیبانی‌شده توسط یک XrSystemId مشخص را با استفاده از xrEnumerateSpatialPersistenceScopesEXT فهرست کند.

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

  • افزونه‌ی XR_EXT_spatial_persistence باید قبل از فراخوانی xrEnumerateSpatialPersistenceScopesEXT فعال شود.
  • instance باید یک شناسه معتبر XrInstance باشد.
  • persistenceScopeCountOutput باید یک اشاره‌گر به مقدار uint32_t باشد.
  • اگر persistenceScopeCapacityInput برابر با 0 نباشد، persistenceScopes باید اشاره‌گری به آرایه‌ای از مقادیر persistenceScopeCapacityInput XrSpatialPersistenceScopeEXT باشد.

کدهای بازگشت

موفقیت

  • XR_SUCCESS

شکست

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

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

XrResult xrCreateSpatialPersistenceContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialPersistenceContextCompletionEXT* completion);

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

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

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

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrCreateSpatialPersistenceContextCompletionEXT {
    XrStructureType                         type;
    void*                                   next;
    XrResult                                futureResult;
    XrSpatialPersistenceContextResultEXT    createResult;
    XrSpatialPersistenceContextEXT          persistenceContext;
} XrCreateSpatialPersistenceContextCompletionEXT;

توضیحات اعضا

کدهای بازگشت آینده

مقادیر futureResult :

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_PERMISSION_INSUFFICIENT

اگر futureResult و createResult هر دو کدهای موفقیت باشند، persistenceContext باید معتبر باشد. اگر persistenceContext معتبر باشد، باید در چرخه حیات xrCreateSpatialPersistenceContextAsyncEXT :: session یا تا زمانی که برنامه از xrDestroySpatialPersistenceContextEXT به همراه persistenceContext استفاده کند، هر کدام که زودتر اتفاق بیفتد، معتبر باقی بماند.

زمان اجرا فقط در صورتی باید createResult تنظیم کند که futureResult یک کد موفقیت باشد.

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

typedef enum XrSpatialPersistenceContextResultEXT {
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT = 0,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT = -1000781001,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_PERSIST_UUID_NOT_FOUND_EXT = -1000781002,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceContextResultEXT;

شمارش XrSpatialPersistenceContextResultEXT انواع مختلف کدهای نتیجه را برای یک عملیات ماندگاری شناسایی می‌کند. شکست‌ها در طول عملیات ماندگاری همیشه تحت کنترل برنامه نیستند و این شمارش برای انتقال چنین مواردی استفاده می‌شود. مشابه XrResult ، کدهای موفقیت در شمارش XrSpatialPersistenceContextResultEXT مقادیر غیر منفی هستند و کدهای شکست مقادیر منفی هستند.

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

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

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT

عملیات زمینه پایداری با موفقیت انجام شد.

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT

عملیات ماندگاری با شکست مواجه شد زیرا موجودیت توسط زمان اجرا قابل ردیابی نبود. (توسط افزونه XR_EXT_spatial_persistence_operations اضافه شده است)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_PERSIST_UUID_NOT_FOUND_EXT

UUID پایدار ارائه شده در حافظه یافت نشد. (با افزونه XR_EXT_spatial_persistence_operations اضافه شده است)

زمینه ماندگاری مکانی را از بین ببرید

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

XrResult xrDestroySpatialPersistenceContextEXT(
    XrSpatialPersistenceContextEXT              persistenceContext);

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

برنامه می‌تواند پس از اتمام وظایف مربوط به پایداری مکانی، از xrDestroySpatialPersistenceContextEXT برای آزادسازی هندل persistenceContext استفاده کند.

اگر هرگونه هندل معتبر XrSpatialContextEXT که persistenceContext از طریق XrSpatialContextPersistenceConfigEXT به آن لینک شده است، وجود داشته باشد، زمان اجرا نباید منابع زیربنایی persistenceContext را هنگام فراخوانی xrDestroySpatialPersistenceContext از بین ببرد. دلیل این امر آن است که منابع persistence context هنوز توسط spatial context برای کشف موجودیت‌های persistented استفاده می‌شوند. از بین بردن هندل persistence context در چنین شرایطی فقط دسترسی برنامه به این منابع را از بین می‌برد.

منابع مربوط به یک XrSpatialPersistenceContextEXT نابود شده باید زمانی آزاد شوند که تمام هندل‌های XrSpatialContextEXT که زمینه پایداری به آنها متصل بوده است، نابود شوند.

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

ایمنی رزوه

  • دسترسی به persistenceContext و هر handler فرزندی باید به صورت خارجی همگام‌سازی شود.

کدهای بازگشت

موفقیت

  • XR_SUCCESS

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

کشف موجودیت‌های پایدار

مؤلفه‌ی پایداری

موجودیت‌های مکانی پایدار، مؤلفه پایداری را روی خود دارند که اگر XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT در طول ایجاد XrSpatialContextEXT فعال شده و در XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes یا XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes گنجانده شده باشد، زمان اجرا باید آن را در اسنپ‌شات‌های کشف و به‌روزرسانی لحاظ کند.

داده‌های کامپوننت

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

typedef struct XrSpatialPersistenceDataEXT {
    XrUuid                          persistUuid;
    XrSpatialPersistenceStateEXT    persistState;
} XrSpatialPersistenceDataEXT;

توضیحات اعضا

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

typedef enum XrSpatialPersistenceStateEXT {
    XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT = 1,
    XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT = 2,
    XR_SPATIAL_PERSISTENCE_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceStateEXT;

شمارش XrSpatialPersistenceStateEXT حالت‌های مختلف uuid پایدار را مشخص می‌کند.

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

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

XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT

UUID ثبت‌شده با موفقیت از حافظه بارگذاری شد.

XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT

UUID باقی‌مانده در حافظه یافت نشد و یا از آن حذف شده یا هرگز در آن نبوده است.

ساختار لیست کامپوننت برای پرس و جو از داده‌ها

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

typedef struct XrSpatialComponentPersistenceListEXT {
    XrStructureType                 type;
    void*                           next;
    uint32_t                        persistDataCount;
    XrSpatialPersistenceDataEXT*    persistData;
} XrSpatialComponentPersistenceListEXT;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • persistDataCount یک uint32_t است که تعداد عناصر موجود در آرایه persistData را توصیف می‌کند.
  • persistData آرایه‌ای از XrSpatialPersistenceDataEXT است.

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

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

برخلاف سایر کامپوننت‌ها، زمان اجرا باید داده‌ها را برای XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT صرف نظر از XrSpatialEntityTrackingStateEXT تنظیم کند.

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

پیکربندی

اگر XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT برای برخی قابلیت‌ها در XrSpatialCapabilityComponentTypesEXT :: componentTypes شمارش شده باشد، برنامه می‌تواند با قرار دادن enum در لیست XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents ، آن را فعال کند. این کامپوننت برای قرار گرفتن در زنجیره بعدی XrSpatialCapabilityConfigurationBaseHeaderEXT نیازی به پیکربندی خاصی ندارد. اگر برنامه XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT را در لیست کامپوننت‌های فعال‌شده قرار می‌دهد، باید XrSpatialContextPersistenceConfigEXT را نیز در زنجیره بعدی XrSpatialContextCreateInfoEXT قرار دهد، در غیر این صورت زمان اجرا باید XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT از xrCreateSpatialContextAsyncEXT برگرداند.

پیکربندی زمینه مکانی با زمینه‌های پایداری

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

typedef struct XrSpatialContextPersistenceConfigEXT {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 persistenceContextCount;
    const XrSpatialPersistenceContextEXT*    persistenceContexts;
} XrSpatialContextPersistenceConfigEXT;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • persistenceContextCount یک uint32_t است که تعداد عناصر موجود در آرایه persistenceContexts را توصیف می‌کند.
  • persistenceContexts آرایه‌ای از XrSpatialPersistenceContextEXT است.

یک برنامه می‌تواند XrSpatialContextPersistenceConfigEXT را به زنجیره بعدی XrSpatialContextCreateInfoEXT اضافه کند. این کار XrSpatialContextEXT ایجاد شده را با persistenceContexts پیکربندی می‌کند و به برنامه اجازه می‌دهد تا موجودیت‌های مکانی موجود در فضای ذخیره‌سازی را که توسط دستگیره‌های XrSpatialPersistenceContextEXT در persistenceContexts نمایش داده می‌شوند، کشف کند.

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

ایجاد تصویر لحظه‌ای از اکتشاف

کشف موجودیت‌ها با UUID های خاص

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

typedef struct XrSpatialDiscoveryPersistenceUuidFilterEXT {
    XrStructureType    type;
    const void*        next;
    uint32_t           persistedUuidCount;
    const XrUuid*      persistedUuids;
} XrSpatialDiscoveryPersistenceUuidFilterEXT;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • persistedUuidCount یک uint32_t است که تعداد عناصر موجود در آرایه persistedUuids توصیف می‌کند.
  • persistedUuids آرایه‌ای از XrUuid است.

برنامه می‌تواند از XrSpatialDiscoveryPersistenceUuidFilterEXT در زنجیره بعدی XrSpatialDiscoverySnapshotCreateInfoEXT استفاده کند تا عملیات کشف را فقط به موجودیت‌هایی محدود کند که UUIDهای پایدار آنها در مجموعه UUIDهای ارائه شده در persistedUuids قرار دارند.

اگر برنامه XrSpatialDiscoveryPersistenceUuidFilterEXT را در زنجیره بعدی XrSpatialDiscoverySnapshotCreateInfoEXT اضافه کند اما xrCreateSpatialDiscoverySnapshotAsyncEXT :: spatialContext با هیچ XrSpatialPersistenceContextEXT با استفاده از XrSpatialContextPersistenceConfigEXT پیکربندی نشده باشد، زمان اجرا باید XR_ERROR_VALIDATION_FAILURE از xrCreateSpatialDiscoverySnapshotAsyncEXT برگرداند.

زمان اجرا باید با فیلتر XrSpatialDiscoveryPersistenceUuidFilterEXT به عنوان یک شرط 'AND' برای هر فیلتر دیگری که در XrSpatialDiscoverySnapshotCreateInfoEXT یا زنجیره بعدی آن ارائه شده است، رفتار کند. زمان اجرا باید با خود آرایه persistedUuids به عنوان یک شرط 'OR' یعنی فیلتر برای موجودیت‌هایی که هر یک از UUIDهای ارائه شده در آن آرایه را دارند، رفتار کند.

زمان اجرا باید برای هر یک از UUIDهای موجود در persistedUuids که در حال حاضر قادر به تعیین وضعیت XrSpatialPersistenceStateEXT بوده است، یک ورودی در اسنپ‌شات ایجاد شده داشته باشد.

  • اگر زمان اجرا با موفقیت UUID را در حافظه خود پیدا کرده باشد، آنگاه -

    • زمان اجرا باید XrSpatialPersistenceStateEXT را در XrSpatialPersistenceDataEXT این موجودیت روی XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT تنظیم کند.
    • زمان اجرا باید شامل یک XrSpatialEntityIdEXT معتبر برای این موجودیت در اسنپ‌شات ایجاد شده باشد.
    • اگر زمان اجرا به طور فعال موجودیت را ردیابی می‌کند و داده‌های معتبری برای اجزای آن دارد، باید XrSpatialEntityTrackingStateEXT آن موجودیت را روی XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT تنظیم کند. در غیر این صورت، زمان اجرا باید XrSpatialEntityTrackingStateEXT را روی XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT تنظیم کند.

  • اگر زمان اجرا تشخیص داده باشد که UUID در حافظه‌اش موجود نیست (صرف نظر از اینکه آن UUID هرگز در حافظه نبوده یا زمانی وجود داشته اما از آن زمان تاکنون حذف شده است)، آنگاه -

    • زمان اجرا باید XrSpatialPersistenceStateEXT را در XrSpatialPersistenceDataEXT این موجودیت روی XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT تنظیم کند تا به برنامه نشان دهد که این UUID دیگر در فضای ذخیره‌سازی وجود ندارد.
    • زمان اجرا باید XrSpatialEntityIdEXT را برای این موجودیت در اسنپ‌شات ایجاد شده روی XR_NULL_SPATIAL_ENTITY_ID_EXT تنظیم کند.
    • زمان اجرا باید XrSpatialEntityTrackingStateEXT آن موجودیت را روی XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT تنظیم کند تا به برنامه نشان دهد که این موجودیت هرگز ردیابی نخواهد شد.

  • اگر زمان اجرا قادر به تشخیص وجود یا عدم وجود UUID در حافظه خود نبود، نباید آن را در snapshot قرار دهد.

برنامه همچنین می‌تواند از XrSpatialDiscoveryPersistenceUuidFilterEXT در زنجیره بعدی XrSpatialComponentDataQueryConditionEXT برای جستجوی موجودیت‌های UUID خاص در اسنپ‌شات‌های موجود استفاده کند. هنگام استفاده از XrSpatialComponentDataQueryConditionEXT ، اگر XrSpatialDiscoveryPersistenceUuidFilterEXT :: persistedUuids حاوی هر XrUuid باشد که در XrSpatialSnapshotEXT نیست، زمان اجرا نباید ورودی برای آن XrUuid در نتیجه پرس‌وجو داشته باشد. همچنین، ترتیب (دنباله) موجودیت‌ها در نتیجه پرس‌وجو ممکن است با ترتیب UUIDهای ارائه شده در XrSpatialDiscoveryPersistenceUuidFilterEXT :: persistedUuids مطابقت نداشته باشد. برنامه باید XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT را در XrSpatialComponentDataQueryConditionEXT :: componentTypes و XrSpatialComponentPersistenceListEXT را در زنجیره بعدی XrSpatialComponentDataQueryResultEXT قرار دهد و سپس XrSpatialPersistenceDataEXT :: persistUuid هر شاخص نتیجه پرس و جو را بررسی کند تا بفهمد شاخص نتیجه فعلی با کدام UUID مطابقت دارد.

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

  • افزونه‌ی XR_EXT_spatial_persistence باید قبل از استفاده از XrSpatialDiscoveryPersistenceUuidFilterEXT فعال شود.
  • type باید XR_TYPE_SPATIAL_DISCOVERY_PERSISTENCE_UUID_FILTER_EXT باشد.
  • next باید NULL یا یک اشاره‌گر معتبر به ساختار بعدی در یک زنجیره ساختار باشد.
  • persistedUuids باید اشاره‌گری به آرایه‌ای از ساختارهای persistedUuidCount XrUuid باشد.
  • پارامتر persistedUuidCount باید بزرگتر از 0 باشد.
کشف تمام موجودیت‌های پایدار

اگر برنامه از xrCreateSpatialDiscoverySnapshotAsyncEXT بدون XrSpatialDiscoveryPersistenceUuidFilterEXT و با یک XrSpatialContextEXT که با XrSpatialPersistenceContextEXT پیکربندی شده است، استفاده کند، آنگاه زمان اجرا باید آن موجودیت‌هایی را در snapshot ایجاد شده شامل کند که در فضای ذخیره‌سازی نمایش داده شده توسط XrSpatialPersistenceContextEXT ذخیره شده‌اند و فیلترهای ارائه شده در XrSpatialDiscoverySnapshotCreateInfoEXT را برآورده می‌کنند. برای آن موجودیت‌ها -

  • زمان اجرا باید XrSpatialPersistenceStateEXT را در XrSpatialPersistenceDataEXT این موجودیت روی XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT تنظیم کند.
  • زمان اجرا باید شامل یک XrSpatialEntityIdEXT معتبر برای این موجودیت در اسنپ‌شات ایجاد شده باشد.
  • اگر زمان اجرا به طور فعال موجودیت را ردیابی می‌کند و داده‌های معتبری برای اجزای آن دارد، باید XrSpatialEntityTrackingStateEXT آن موجودیت را روی XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT تنظیم کند. در غیر این صورت، زمان اجرا باید XrSpatialEntityTrackingStateEXT را روی XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT تنظیم کند.

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

دستورات جدید

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

Enum های جدید

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

  • XR_EXT_SPATIAL_PERSISTENCE_EXTENSION_NAME
  • XR_EXT_spatial_persistence_SPEC_VERSION

  • بسط XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_PERSISTENCE_CONTEXT_EXT

  • بسط XrResult :

    • XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_UNSUPPORTED_EXT

  • بسط XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

  • گسترش XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_PERSISTENCE_CONTEXT_COMPLETION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_PERSISTENCE_CONFIG_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_PERSISTENCE_UUID_FILTER_EXT
    • XR_TYPE_SPATIAL_PERSISTENCE_CONTEXT_CREATE_INFO_EXT

کد مثال

ایجاد زمینه پایداری 

// Check if the required persistence scope supported
uint32_t scopeCount;
CHK_XR(xrEnumerateSpatialPersistenceScopesEXT(instance, systemId, 0, &scopeCount, nullptr));
std::vector<XrSpatialPersistenceScopeEXT> persistenceScopes(scopeCount);
CHK_XR(xrEnumerateSpatialPersistenceScopesEXT(instance, systemId, scopeCount, &scopeCount, persistenceScopes.data()));

if (std::find(persistenceScopes.begin(), persistenceScopes.end(), XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT) == persistenceScopes.end()) {
  return;
}

XrSpatialPersistenceContextEXT persistenceContext{};

XrSpatialPersistenceContextCreateInfoEXT persistenceContextCreateInfo{XR_TYPE_SPATIAL_PERSISTENCE_CONTEXT_CREATE_INFO_EXT};
persistenceContextCreateInfo.scope = XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT;
XrFutureEXT createContextFuture;
CHK_XR(xrCreateSpatialPersistenceContextAsyncEXT(session, &persistenceContextCreateInfo, &createContextFuture));

waitUntilReady(createContextFuture);

XrCreateSpatialPersistenceContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_PERSISTENCE_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialPersistenceContextCompleteEXT(session, createContextFuture, &completion));
if (completion.futureResult != XR_SUCCESS || completion.createResult != XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT) {
  return;
}

persistenceContext = completion.persistenceContext;

// ...
// Connect persistence context to a spatial context and discover persisted entities.
// ...

CHK_XR(xrDestroySpatialPersistenceContextEXT(persistenceContext));

زمینه پایداری را به یک زمینه مکانی متصل کنید 

// Note: Anchor capability is just used as an example here. Persistence can be
// supported by other capabilities too. xrEnumerateSpatialCapabilityComponentTypesEXT() can
// be used to check if a certain capability supports persistence.
if (!isSpatialCapabilitySupported(instance, systemId, XR_SPATIAL_CAPABILITY_ANCHOR_EXT)) {
  return;
}

const bool supportsPersistenceComponent = isSpatialComponentSupported(instance, systemId, XR_SPATIAL_CAPABILITY_ANCHOR_EXT, XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT);

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{

  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  if (supportsPersistenceComponent) {
    enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT);
  }

  XrSpatialCapabilityConfigurationAnchorEXT anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

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

  XrSpatialContextPersistenceConfigEXT persistenceConfig{XR_TYPE_SPATIAL_CONTEXT_PERSISTENCE_CONFIG_EXT};
  persistenceConfig.persistenceContextCount = 1;
  persistenceConfig.persistenceContexts = &persistenceContext;

  if (supportsPersistenceComponent) {
    spatialContextCreateInfo.next = &persistenceConfig;
  }

  XrFutureEXT createContextFuture;
  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) {
    return;
  }

  spatialContext = completion.spatialContext;
}

// ...
// Discover persisted anchors.
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

کشف تمام موجودیت‌های پایدار 

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

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

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    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.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialPersistenceDataEXT> persistenceData(queryResult.entityIdCountOutput);
    XrSpatialComponentPersistenceListEXT persistenceDataList{XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT};
    persistenceDataList.persistDataCount = persistenceData.size();
    persistenceDataList.persistData = persistenceData.data();
    queryResult.next = &persistenceDataList;

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

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      // persistenceData[i].persistUuid is the UUID of the persisted entity whose entity ID is entityIds[i].
      // The persistenceData array is essentially the uuids persisted in the scope that the current
      // XrSpatialPersistenceContextEXT is configured with.
    }

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

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

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

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

  // ...
  // Finish frame loop
  // ...
}

کشف موجودیت‌ها با UUID های خاص 

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// Load up the uuids that the app has stored on its own i.e. the uuids it is interested in.
std::vector<XrUuid> uuidsStoredByApp = loadPersistedUuids();

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoveryPersistenceUuidFilterEXT persistenceFilter{XR_TYPE_SPATIAL_DISCOVERY_PERSISTENCE_UUID_FILTER_EXT};
  persistenceFilter.persistedUuidCount = uuidsStoredByApp.size();
  persistenceFilter.persistedUuids = uuidsStoredByApp.data();

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  snapshotCreateInfo.next = &persistenceFilter;

  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

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

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    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.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialPersistenceDataEXT> persistenceData(queryResult.entityIdCountOutput);
    XrSpatialComponentPersistenceListEXT persistenceDataList{XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT};
    persistenceDataList.persistDataCount = persistenceData.size();
    persistenceDataList.persistData = persistenceData.data();
    queryResult.next = &persistenceDataList;

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

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (persistenceData[i].persistState == XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT) {
        // persistenceData[i].persistUuid, requested by the app, is present in the persistence scope
        // and its corresponding entity ID and state are entityIds[i] & entityStates[i] respectively.
      } else if (persistenceData[i].persistState == XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT) {
        // persistenceData[i].persistUuid, requested by the app, is NOT present in the persistence scope
        // and its corresponding entity ID (entityIds[i]) would be XR_NULL_SPATIAL_ENTITY_ID_EXT
        // and tracking state (entityStates[i]) would be XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT.
      }
    }

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

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

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

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

  // ...
  // Finish frame loop
  // ...
}

مسائل

تاریخچه نسخه

  • نسخه ۱، ۲۰۲۴-۰۸-۲۹ (نیهاو جین، گوگل)

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