XR_EXT_spatial_container

رشته نام

XR_EXT_spatial_container

نوع افزونه

افزونه نمونه

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

811

بازبینی

1

وضعیت تصویب

تصویب‌نشده

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

OpenXR 1.0

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

2026-08-06

وضعیت IP

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

همیاران

Jared Finder،‏ Google
Andreas Loeve Selvik،‏ Meta Platforms
Lachlan Ford،‏ Google
Cass Everitt،‏ Meta Platforms
Adam Gousetis،‏ Meta Platforms
Ankur Agrawal،‏ Unity Technologies
Bjorn Swenson،‏ LÖVR
Denny Rönngren،‏ Varjo Technologies
Fredia Huya-Kouadio،‏ Godot Engine
Guodong Rong،‏ Meta Platforms
Jakob Bornecrantz،‏ NVIDIA
Jian Zhang،‏ ByteDance
John Kearney،‏ Meta Platforms
Jonathan Wright،‏ Meta Platforms
Junfeng She،‏ ByteDance
Kenny Vercaemer،‏ Google
Kurtis Eveleigh،‏ Qualcomm
Mauricio Narvaez،‏ Meta Platforms
Nathan Nuber،‏ Valve Corporation
Nihav Jain،‏ Google
Nikita Lutsenko،‏ Meta Platforms
Praveen Babu J D،‏ ByteDance
Rylie Pavlik،‏ Collabora
Salar Khan،‏ Google
Shuai Liu،‏ ByteDance
Walter Luh،‏ Meta Platforms
Yin Li،‏ Microsoft
Zhipeng Liu،‏ ByteDance

نمای کلی

این افزونه کلاس جدیدی از نهادهای قابل‌نمایش را تعریف می‌کند که «ظروف فضایی» نامیده می‌شوند و مشابه مفهوم «پنجره‌ها» در سیستم‌های پنجره‌بندی دوبعدی رایانه هستند.

در OpenXR 1.x، برنامه‌ها کنترل انحصاری بر هر آنچه کاربر می‌بیند و نحوه ترکیب آن بر روی محیط واقعی یا مجازی کاربر دارند. زمان‌های اجرا فقط تغییرات جزئی در آنچه نمایش داده می‌شود ایجاد می‌کنند تا ایمنی کاربر تضمین شود. این مدل برنامه برای غوطه‌ور کردن کاربر در یک تجربه خوب است، اما به چندین تجربه هم‌زمان گسترش نمی‌یابد. به‌ویژه در محیط‌های واقعیت افزوده و واقعیت ترکیبی، کاربران اغلب می‌خواهند چندین برنامه مختلف را به‌طور هم‌زمان تجربه کنند.

محفظه‌های فضایی مانند پنجره‌هایی هستند که به فضای سه‌بعدی گسترش یافته‌اند. کاربر می‌تواند چندین محفظه فضایی را به‌طور هم‌زمان ببیند و برای زیرمجموعه‌ای از آن‌ها ورودی ارائه دهد. محفظه‌های فضایی قابل‌مشاهده می‌توانند به برنامه‌های مختلف تعلق داشته باشند و زمان‌های اجرا اندازه و جای آن‌ها را ازطرف کاربر مدیریت می‌کنند.

این افزونه علاوه‌بر تجربه‌های فراگیر OpenXR موجود، از این انواع جدید تجربه‌های محدودشده فضایی نیز پشتیبانی می‌کند. تجربه‌های OpenXR محدودشده می‌توانند محتوای کمی سه‌بعدی (پانل‌های تخت با جابه‌جایی‌های جزئی عمق) یا حجم‌هایی داشته باشند که میزبان محتوای کاملاً سه‌بعدی هستند. تجربه‌های فراگیر OpenXR همان برنامه‌های فراگیر تمام‌صفحه موجود هستند که از زمان OpenXR 1.0 پشتیبانی می‌شوند. برنامه‌ها می‌توانند بین دو نوع محتوا جابه‌جا شوند، اگر برنامه این را انتخاب کند.

این افزونه هیچ روشی برای پرداز زدن محتوای برنامه تعریف نمی‌کند. نحوه ترسیم محتوا در افزونه‌های دیگر تعریف شده است: XR_EXT_spatial_container_self_rendering .

استفاده از محفظه‌های فضایی

XrSpatialContainerEXT دسته‌ای است که نشان‌دهنده یک محفظه فضایی است.

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

برنامه با مراحل زیر شروع به رندر کردن ازطریق محفظه فضایی می‌کند:

1. یک محفظه فضایی با xrCreateSpatialContainerEXT ایجاد کنید.
2. هر وضعیتی را در ظرف برای ارائه اولیه تغییر دهید، مثلاً حالت مرزهای آن.
3. درخواست کنید زمان اجرا محفظه را با xrRequestSpatialContainerVisibleEXT نشان دهد.
4. منتظر بمانید تا زمان اجرا برای نمایش محفظه آماده شود. وقتی زمان اجرا آماده شد، رویداد XrEventDataSpatialContainerVisibleChangedEXT را با visible تنظیم‌شده روی XR_TRUE در صف قرار می‌دهد.
5. پرداخت برای ظرف فضایی را شروع کنید.

و ازبین بردن محفظه فضایی به‌صورت زیر است:

1. از زمان اجرا بخواهید محفظه را با xrRequestSpatialContainerVisibleEXT پنهان کند.
2. منتظر بمانید تا زمان اجرا پنهان کردن محفظه را به‌پایان برساند. وقتی زمان اجرا محفظه را کاملاً پنهان کرد، رویداد XrEventDataSpatialContainerVisibleChangedEXT را با visible تنظیم‌شده روی XR_FALSE در صف قرار می‌دهد.
3. پایان پردازش برای محفظه فضایی.
4. محتوی را با xrDestroySpatialContainerEXT ازبین ببرید.

توجه

این افزونه به‌طور پیش‌فرض مدیریت نمایان بودن و تمرکز را به محفظه‌های فضایی مجزا واگذار می‌کند. چون جلسه به‌عنوان یک کل دیگر نشان‌دهنده یک شیء نمایان یا متمرکزشده واحد نیست، جلسه ازطریق ماشین حالت استاندارد OpenXR (آماده، همگام‌سازی‌شده، نمایان، متمرکزشده) انتقال نمی‌یابد. درعوض، جلسه درطول عمر فعال خود در XR_SESSION_STATE_IDLE باقی می‌ماند و قوانین موجود در تغییرات در وضعیت جلسه مشخص می‌کنند که عملیات اصلی OpenXR چگونه به این حالت نگاشت می‌شوند.

ایجاد محفظه فضایی

تابع xrCreateSpatialContainerEXT یک محفظه فضایی جدید ایجاد می‌کند.

XrResult xrCreateSpatialContainerEXT(
    XrSession                                   session,
    const XrSpatialContainerCreateInfoEXT*      createInfo,
    XrSpatialContainerEXT*                      spatialContainer);

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

• ‫session همان XrSession است که محفظه فضایی را ایجاد می‌کند.
• createInfo اشاره‌گری به XrSpatialContainerCreateInfoEXT است که حاوی پارامترهایی برای ایجاد محفظه فضایی است.
• spatialContainer اشاره‌گری به یک دسته است که در آن XrSpatialContainerEXT ایجادشده برگردانده می‌شود.

XrSpatialContainerEXT تازه ایجادشده باید غیرقابل‌مشاهده، غیرقابل‌تعامل، و در حالت مرزهای XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT باشد. برنامه‌ای که می‌خواهد محفظه فضایی در حالت فراگیر شروع شود می‌تواند قبل‌از درخواست نمایش محفظه فضایی، حالت مرزهای XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT را درخواست کند.

اگر هر بُعدی از XrSpatialContainerCreateInfoEXT :: suggestedBounds منفی، بی‌نهایت، یا غیرعددی باشد، زمان‌های اجرا باید XR_ERROR_VALIDATION_FAILURE را برگردانند. اگر برنامه‌ای تلاش کند بیش‌از تعداد مشخص‌شده در XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount ظرف فضایی ایجاد کند، زمان‌های اجرا باید XR_ERROR_LIMIT_REACHED را برگردانند. اگر محفظه‌های فضایی برای این جلسه فعال نشده باشند، زمان‌های اجرا باید XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT را برگردانند.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از فراخوانی xrCreateSpatialContainerEXT فعال شود
• session باید یک دسته XrSession معتبر باشد
• createInfo باید اشاره‌گری به ساختار XrSpatialContainerCreateInfoEXT معتبر باشد
• spatialContainer باید اشاره‌گری به دسته XrSpatialContainerEXT باشد

کدهای برگشتی

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

• 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_CONTAINERS_NOT_ENABLED_EXT
• XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerCreateInfoEXT به xrCreateSpatialContainerEXT منتقل می‌شود تا محفظه فضایی ایجاد شود.

typedef struct XrSpatialContainerCreateInfoEXT {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialContainerGraphicsPresentationEXT    graphicsPresentation;
    XrExtent3Df                                  suggestedBounds;
} XrSpatialContainerCreateInfoEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• ‫graphicsPresentation یک XrSpatialContainerGraphicsPresentationEXT است که نحوه ارائه گرافیک توسط این محفظه فضایی را شرح می‌دهد.
• suggestedBounds یک XrExtent3Df است که ابعاد درخواستی محفظه فضایی را برحسب متر توصیف می‌کند.

برنامه‌ای که اولویتی برای اندازه خود ندارد می‌تواند suggestedBounds را روی {0, 0, 0} تنظیم کند. زمان اجرا ممکن است suggestedBounds درخواستی را نادیده بگیرد.

زمان اجرایی که اجازه می‌دهد محفظه‌های فضایی با شکل‌هایی غیراز جعبه‌های جهت‌دار محدود شوند باید از suggestedBounds به‌عنوان جعبه محدودکننده در اطراف شکل‌های دیگر استفاده کند. چارگوش‌های جهت‌دار رایج‌ترین شکل محصورکننده هستند.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrSpatialContainerCreateInfoEXT فعال شود
• type باید XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد
• graphicsPresentation باید مقدار XrSpatialContainerGraphicsPresentationEXT معتبری باشد

وقتی محفظه فضایی دیگر قابل‌استفاده نباشد، زمان‌های اجرا باید رویداد XrEventDataSpatialContainerClosedEXT را در صف قرار دهند.

typedef struct XrEventDataSpatialContainerClosedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerClosedEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• spatialContainer XrSpatialContainerEXT است که این رویداد برای آن است.

دریافت رویداد XrEventDataSpatialContainerClosedEXT نشان می‌دهد که زمان اجرا دیگر قادر به نمایش محفظه فضایی نیست، برای مثال به‌دلیل اینکه کاربر روی دکمه «بستن» کلیک کرده است یا جلسه وارد حالت XR_SESSION_STATE_LOSS_PENDING شده است.

پس‌از دریافت رویداد XrEventDataSpatialContainerClosedEXT، برنامه باید استفاده از آن محفظه فضایی را متوقف کند، هرگونه وضعیت منسوب مانند حلقه رندر را ازبین ببرد، و محفظه را نابود کند. زمان‌های اجرا باید XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT را از همه عملکردهایی که روی آن محفظه اجرا می‌شوند، به‌جز xrDestroySpatialContainerEXT، برگردانند.

اگر محفظه فضایی هنگام صف‌بندی رویداد بستن توسط زمان اجرا قابل‌مشاهده باشد، زمان‌های اجرا باید ابتدا محفظه را به غیرقابل‌مشاهده تغییر دهند و رویداد XrEventDataSpatialContainerVisibleChangedEXT را صف‌بندی کنند.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrEventDataSpatialContainerClosedEXT فعال شود
• type باید XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_CLOSED_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

تابع xrDestroySpatialContainerEXT یک محفظه فضایی موجود را ازبین می‌برد.

XrResult xrDestroySpatialContainerEXT(
    XrSpatialContainerEXT                       spatialContainer);

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

• ‫spatialContainer یک XrSpatialContainerEXT است که قبلاً توسط xrCreateSpatialContainerEXT ایجاد شده است.

پس‌از نابود شدن محفظه فضایی، زمان‌های اجرا نباید دیگر محتوای محفظه را نشان دهند و نباید هیچ رویداد دیگری را درباره محفظه در صف قرار دهند.

برنامه نباید محفظه فضایی قابل‌مشاهده را ازبین ببرد زیرا انجام این کار ممکن است منجر به آرتیفکت‌های گرافیکی شود، درعوض برنامه باید درخواست کند که محفظه فضایی با xrRequestSpatialContainerVisibleEXT پنهان شود، منتظر رویداد XrEventDataSpatialContainerVisibleChangedEXT بماند، و سپس محفظه را ازبین ببرد.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از فراخوانی xrDestroySpatialContainerEXT فعال شود
• spatialContainer باید شناسه مجازی XrSpatialContainerEXT معتبر باشد

ایمنی رشته‌ای

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

کدهای برگشتی

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

• XR_SUCCESS

ناموفق

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

فضای محفظه فضایی

تابع xrCreateSpatialContainerSpaceEXT یک دسته XrSpace برای فضای محفظه فضایی یک محفظه فضایی خاص ایجاد می‌کند.

XrResult xrCreateSpatialContainerSpaceEXT(
    XrSession                                   session,
    const XrSpatialContainerSpaceCreateInfoEXT* createInfo,
    XrSpace*                                    space);

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

• ‫session همان XrSession است که فضا را ایجاد می‌کند.
• ‫createInfo اشاره‌گری به XrSpatialContainerSpaceCreateInfoEXT است که حاوی پارامترهایی برای ایجاد فضا است.
• ‫space اشاره‌گری به یک دسته است که در آن XrSpace ایجادشده برگردانده می‌شود.

«فضای محفظه فضایی» برای هر محفظه فضایی مشخص، یک سیستم مختصات است که مبدأ آن در مرکز مرزهای آن محفظه فضایی قرار دارد. این فضا معمولاً به‌عنوان فضای پایه برای عملکردهایی مانند xrLocateSpace استفاده می‌شود.

‫X+ به سمت راست محفظه، Y+ به سمت بالای محفظه، و Z+ به سمت جلوی محفظه اشاره می‌کند. برای مثال، اگر محتوایی با جاذبه هم‌تراز شده باشد، در مقابل بیننده باشد، و بیننده در حالت هویت نسبت به LOCAL فضا باشد، زمان‌های اجرا باید فضای محتوا را با جهت هویت نسبت به LOCAL فضا جهت‌دهی کنند. زمان‌های اجرا ممکن است وضعیت فضای محتوا را نسبت به فضای LOCAL روی هر وضعیت دلخواهی تنظیم کنند وقتی که آن محتوا نمایان می‌شود.

ext spatial container space convention

شکل ۱۸. قرارداد محورهای فضای محفظه فضایی

فضای محفظه فضایی یک مبدأ قفل‌نشده غیرجهانی است. برنامه‌هایی که در حالت فراگیر به مبدأ قفل‌شده در جهان نیاز دارند می‌توانند از فضای قفل‌شده در جهان مثل XR_REFERENCE_SPACE_TYPE_LOCAL استفاده کنند.

زمان‌های اجرا ممکن است در هر زمانی حالت فضای ظرف فضایی را تغییر دهند، معمولاً برای پشتیبانی از کاربری که ظرف فضایی را به موقعیت یا چرخش دیگری منتقل می‌کند. زمان‌های اجرا ممکن است هنگام انتقال بین حالت‌های مرز XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT و XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT، ژست را نیز تغییر دهند.

فضای محفظه فضایی باید همچنان یک دسته معتبر باقی بماند، حتی اگر محفظه فضایی که برای آن است با xrDestroySpatialContainerEXT نابود شود. وقتی محفظه فضایی قابل‌مشاهده نیست یا ازبین رفته است، فضای محفظه فضایی باید نسبت به فضاهای دیگر غیرقابل‌مکان‌یابی باشد. XrSpaceLocation :: locationFlags و XrViewState ::viewStateFlags برابر با ۰ خواهد بود.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از فراخوانی xrCreateSpatialContainerSpaceEXT فعال شود
• session باید یک دسته XrSession معتبر باشد
• createInfo باید اشاره‌گری به ساختار معتبر XrSpatialContainerSpaceCreateInfoEXT باشد
• space باید اشاره‌گری به دسته XrSpace باشد

کدهای برگشتی

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

• 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_CONTAINER_CLOSED_EXT
• XR_ERROR_VALIDATION_FAILURE

از XrSpatialContainerSpaceCreateInfoEXT به‌همراه xrCreateSpatialContainerSpaceEXT برای ایجاد دسته XrSpace استفاده می‌شود.

typedef struct XrSpatialContainerSpaceCreateInfoEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrSpatialContainerSpaceCreateInfoEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• spatialContainer یک XrSpatialContainerEXT است که باید برای آن فضا ایجاد شود.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrSpatialContainerSpaceCreateInfoEXT فعال شود
• type باید XR_TYPE_SPATIAL_CONTAINER_SPACE_CREATE_INFO_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد
• spatialContainer باید شناسه مجازی XrSpatialContainerEXT معتبر باشد

ارائه کردن محفظه فضایی

ارسال محتوای محفظه فضایی به OpenXR برای نمایش توسط افزونه‌های دیگر انجام می‌شود: XR_EXT_spatial_container_self_rendering .

برای اینکه افزونه‌های دیگر بتوانند روش ارائه گرافیک را برای محفظه فضایی مشخص کنند، این افزونه شمارش XrSpatialContainerGraphicsPresentationEXT را تعریف می‌کند.

typedef enum XrSpatialContainerGraphicsPresentationEXT {
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT = 1000813000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT = 1000814000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1 = 1000815000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerGraphicsPresentationEXT;

شرح شمارشی

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

محفظه فضایی از لایه‌های ترکیب OpenXR استفاده می‌کند (افزوده‌شده توسط افزونه XR_EXT_spatial_container_self_rendering)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT

محفظه فضایی برای آزمایش انطباق ایجاد شده است و مسیر پردازشی ندارد (افزوده‌شده توسط افزونه XR_EXT_spatial_container_conformance_automation)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1

محفظه فضایی از پرداز سیستم OpenXR استفاده می‌کند (افزوده‌شده توسط افزونه XR_EXTX1_system_renderer)

وضعیت محفظه فضایی

وضعیت محفظه فضایی توسط زمان‌های اجرا براساس درخواست‌های برنامه و نیازهای کاربر مدیریت می‌شود. به‌همین دلیل، هر جنبه از وضعیت محفظه فضایی موارد زیر را مستند می‌کند:

• وقتی زمان‌های اجرا مجاز به تغییر وضعیت محفظه فضایی باشند. برای اکثر وضعیت‌های محفظه فضایی، زمان‌های اجرا ممکن است وضعیت را در هر زمانی تغییر دهند.
• نحوه درخواست تغییرات در وضعیت توسط برنامه. زمان‌های اجرا ممکن است هر درخواستی را تا زمانی که فکر کند درخواست مناسب است به‌تعویق بیندازد. زمان‌های اجرا رویدادها را هنگام به‌تعویق افتادن درخواست در صف قرار نمی‌دهند، بنابراین برنامه‌ها نباید برای منطق نامرتبط منتظر چنین رویدادی بمانند.
• وقتی وضعیت محفظه فضایی تغییر می‌کند، چه زمان‌های اجرای رویدادی در صف قرار می‌گیرند. زمان‌های اجرا رویدادها را برای همه تغییرات، ازجمله تغییرات درخواست‌شده برنامه و تغییرات شروع‌شده زمان اجرا، صف‌بندی می‌کنند. زمان‌های اجرا نباید رویدادهای تغییر وضعیت را که نشان‌دهنده تغییر نیستند در صف قرار دهند، مثلاً اگر برنامه‌ای دو درخواست برای پنهان کردن محفظه به‌صورت متوالی و سریع ارسال کند.
• هنگام رد کردن درخواست تغییر برنامه، چه زمان‌های اجرای رویدادی در صف قرار می‌گیرند. زمان‌های اجرا ممکن است درخواست را به هر دلیلی رد کنند، معمولاً به‌دلیل خط‌مشی سیستم مربوط به حفظ تجربه کاربری با کیفیت بالا.

تابع xrGetSpatialContainerStateEXT وضعیت فعلی محفظه فضایی را پرسمان می‌کند.

XrResult xrGetSpatialContainerStateEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerStateGetInfoEXT*    getInfo,
    XrSpatialContainerStateEXT*                 state);

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

• ‫spatialContainer XrSpatialContainerEXT برای پُرسمان است.
• getInfo همان XrSpatialContainerStateGetInfoEXT است که اطلاعات استفاده‌شده برای دریافت وضعیت محفظه فضایی را دارد.
• ‫state اشاره‌گری به XrSpatialContainerStateEXT است که در آن وضعیت محفظه فضایی برگردانده می‌شود.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از فراخوانی xrGetSpatialContainerStateEXT فعال شود
• spatialContainer باید شناسه مجازی XrSpatialContainerEXT معتبر باشد
• اگر getInfo NULL نباشد، getInfo باید اشاره‌گری به ساختار معتبر XrSpatialContainerStateGetInfoEXT باشد
• state باید اشاره‌گری به ساختار XrSpatialContainerStateEXT باشد

کدهای برگشتی

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

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ناموفق

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
• XR_ERROR_VALIDATION_FAILURE

از XrSpatialContainerStateGetInfoEXT به‌همراه xrGetSpatialContainerStateEXT برای پرسمان XrSpatialContainerStateEXT استفاده می‌شود.

typedef struct XrSpatialContainerStateGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerStateGetInfoEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrSpatialContainerStateGetInfoEXT فعال شود
• type باید XR_TYPE_SPATIAL_CONTAINER_STATE_GET_INFO_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

typedef struct XrSpatialContainerStateEXT {
    XrStructureType                    type;
    void*                              next;
    XrBool32                           visible;
    XrBool32                           interactable;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerStateEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• visible نشان می‌دهد که آیا محتوای فضایی قابل‌مشاهده است یا نه.
• interactable نشان می‌دهد که آیا محفظه فضایی درحال‌حاضر می‌تواند هر نوع ورودی را دریافت کند یا نه. این ویژگی شبیه به «تمرکز» برای سیستم‌های پنجره‌بندی دوبعدی رایانه است، با این تفاوت که چند محفظه فضایی ممکن است به‌طور هم‌زمان قابل تعامل باشند.
• ‫boundsMode XrSpatialContainerBoundsModeEXT فعلی محفظه فضایی است.

تغییرات در وضعیت محفظه فضایی ازطریق رویدادها اطلاع‌رسانی می‌شود.

رویداد «فیلد تغییر کرد»

visible

XrEventDataSpatialContainerVisibleChangedEXT

interactable

XrEventDataSpatialContainerInteractableChangedEXT

boundsMode

XrEventDataSpatialContainerBoundsChangedEXT

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrSpatialContainerStateEXT فعال شود
• type باید XR_TYPE_SPATIAL_CONTAINER_STATE_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

نمایان بودن

برنامه‌ها برای نمایش یا پنهان کردن محفظه فضایی با xrRequestSpatialContainerVisibleEXT درخواست می‌دهند.

XrResult xrRequestSpatialContainerVisibleEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerVisibleRequestInfoEXT* info);

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

• ‫spatialContainer XrSpatialContainerEXT است که برای آن درخواست تغییر می‌شود.
• ‫info اشاره‌گری به XrSpatialContainerVisibleRequestInfoEXT است که حاوی وضعیت نمایان درخواست‌شده است.

نمایش یا پنهان کردن محفظه فضایی عملیاتی ناهمگام است.

برنامه‌ها باید قبل‌از تخریب محفظه فضایی، درخواست پنهان کردن آن را بدهند تا زمان‌های اجرا بتوانند انتقال روانی را نمایش دهند. زمان‌های اجرا باید درخواست‌های پنهان کردن محفظه فضایی را بپذیرند.

زمان اجرا ممکن است درخواست‌های نمایش محفظه فضایی را رد کند، که در این صورت زمان اجرا باید رویداد XrEventDataSpatialContainerVisibleRequestDeniedEXT را در صف قرار دهد. برای مثال، برخی‌از زمان‌های اجرا درخواست نمایش محفظه فضایی را که کاربر با تعامل با دکمه «کوچک کردن» ارائه‌شده توسط سیستم پنهان کرده است رد می‌کنند.

زمان‌های اجرا نباید پیش‌از اینکه برنامه حداقل یک‌بار درخواست نمایش محفظه فضایی را بدهد، محفظه فضایی را نشان دهند. پس‌از اولین درخواست برنامه برای نمایش محفظه فضایی، زمان‌های اجرا ممکن است رؤیت‌پذیری آن محفظه فضایی را مستقل از درخواست‌های برنامه تغییر دهند. این کار به برنامه امکان می‌دهد وضعیت اولیه و محتوای محفظه فضایی را کنترل کند و به زمان‌های اجرا امکان می‌دهد میانای کاربری سیستم مانند نوار وظیفه را ارائه دهند که به کاربر اجازه می‌دهد انتخاب کند کدام محفظه‌های فضایی نمایان باشند.

زمان‌های اجرا باید درخواست‌های نمایش محفظه فضایی در حالت مرزهای پشتیبانی‌نشده براساس XrSystemSpatialContainerPropertiesEXT :: supportsBounded و XrSystemSpatialContainerPropertiesEXT :: supportsImmersive را رد کنند. این امر زمانی ممکن است که حالت مرزهای پیش‌فرض، XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT، برای سیستم موردنظر پشتیبانی نشود.

توجه

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

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از فراخوانی xrRequestSpatialContainerVisibleEXT فعال شود
• spatialContainer باید شناسه مجازی XrSpatialContainerEXT معتبر باشد
• info باید اشاره‌گری به ساختار معتبر XrSpatialContainerVisibleRequestInfoEXT باشد

کدهای برگشتی

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

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ناموفق

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
• XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerVisibleRequestInfoEXT با xrRequestSpatialContainerVisibleEXT برای تغییر رؤیت‌پذیری محفظه فضایی استفاده می‌شود.

typedef struct XrSpatialContainerVisibleRequestInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           visible;
} XrSpatialContainerVisibleRequestInfoEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• visible نشان می‌دهد که آیا درخواست شده است محفظه فضایی نشان داده شود یا پنهان شود.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrSpatialContainerVisibleRequestInfoEXT فعال شود
• type باید XR_TYPE_SPATIAL_CONTAINER_VISIBLE_REQUEST_INFO_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

هربار که زمان اجرا نمایان بودن محتوای فضایی را تغییر می‌دهد، زمان اجرا باید رویداد XrEventDataSpatialContainerVisibleChangedEXT را با وضعیت جدید در صف قرار دهد.

typedef struct XrEventDataSpatialContainerVisibleChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 visible;
} XrEventDataSpatialContainerVisibleChangedEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• spatialContainer XrSpatialContainerEXT است که این رویداد برای آن است.
• visible وضعیت نمایان جدید برای محفظه فضایی است.

این رویداد جایگزین XR_SESSION_STATE_VISIBLE می‌شود و اجازه می‌دهد مقدار برای هر محفظه متفاوت باشد. رویداد باید برای همه تغییرات، ازجمله تغییرات درخواست‌شده برنامه و تغییرات شروع‌شده در زمان اجرا، در صف قرار گیرد.

زمان اجرا ممکن است برای جلوگیری از نمایش محفظه خالی و دادن زمان به برنامه برای ارسال محتوای اولیه، پس‌از صف‌بندی این رویداد با visible تنظیم‌شده روی XR_TRUE، رندر کردن محفظه را برای چند فریم به‌تأخیر بیندازد. درطول این مدت، XrSpatialContainerStateEXT ::visible برابر با XR_TRUE خواهد بود. زمان‌های اجرا نباید پردازش محفظه را بیش‌از ۰٫۵ ثانیه به‌تأخیر بیندازند.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrEventDataSpatialContainerVisibleChangedEXT فعال شود
• type باید XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_CHANGED_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

هر بار که زمان اجرا درخواست نمایش محفظه را رد می‌کند، زمان اجرا باید رویداد XrEventDataSpatialContainerVisibleRequestDeniedEXT را در صف قرار دهد.

typedef struct XrEventDataSpatialContainerVisibleRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerVisibleRequestDeniedEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• spatialContainer XrSpatialContainerEXT است که این رویداد برای آن است.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrEventDataSpatialContainerVisibleRequestDeniedEXT فعال شود
• type باید XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_REQUEST_DENIED_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

قابل‌تعامل

برنامه نمی‌تواند درخواست کند که محفظه فضایی تعاملی باشد. اینکه کدام محفظه‌های فضایی قابل‌تعامل هستند کاملاً توسط زمان‌های اجرا کنترل می‌شود. محتوای فضایی که قابل‌تعامل است باید قابل‌مشاهده هم باشد.

هر بار که زمان اجرا وضعیت تعاملی محفظه فضایی را تغییر می‌دهد، زمان اجرا باید رویداد XrEventDataSpatialContainerInteractableChangedEXT را با وضعیت جدید در صف قرار دهد.

typedef struct XrEventDataSpatialContainerInteractableChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 interactable;
} XrEventDataSpatialContainerInteractableChangedEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• spatialContainer XrSpatialContainerEXT است که این رویداد برای آن است.
• interactable حالت تعاملی جدید برای محفظه فضایی است.

این رویداد جایگزین XR_SESSION_STATE_FOCUSED می‌شود و اجازه می‌دهد مقدار برای هر محفظه متفاوت باشد. رویداد برای همه تغییرات، ازجمله تغییرات شروع‌شده در زمان اجرا، در صف قرار می‌گیرد.

زمان‌های اجرا ممکن است در هر زمانی تعامل با محفظه فضایی را فعال یا غیرفعال کنند. اگر زمان اجرا فقط از حداکثر یک محفظه فضایی تعاملی در هر زمان پشتیبانی کند، وقتی زمان اجرا محفظه فضایی تعاملی را تغییر می‌دهد، زمان اجرا باید رویداد را برای محفظه فضایی که دیگر تعاملی نیست ( interactable روی false تنظیم شده است) قبل‌از رویداد برای محفظه‌ای که تعاملی می‌شود ( interactable روی true تنظیم شده است) در صف قرار دهد.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید پیش‌از استفاده از XrEventDataSpatialContainerInteractableChangedEXT فعال شود
• type باید XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_INTERACTABLE_CHANGED_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

محدوده

محفظه فضایی دارای حالت مرزها و جعبه مرزبندی است. حالت مرزهای محفظه فضایی نحوه رفتار مرزها را توصیف می‌کند. جعبه مرزی آن چیزی است که محفظه فضایی درون آن ترسیم می‌شود.

شمارش XrSpatialContainerBoundsModeEXT حالت‌های مختلفی را که مرزهای محفظه فضایی می‌تواند داشته باشد شناسایی می‌کند.

typedef enum XrSpatialContainerBoundsModeEXT {
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT = 1,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT = 2,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerBoundsModeEXT;

شرح شمارشی

XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT

ظرف فضایی محدود است. محدوده‌ها یک چارگوش محدود است. محفظه فضایی فقط در این منطقه نشان داده خواهد شد.

XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT

محفظه فضایی فراگیر است و مرزهای بی‌نهایت دارد. محفظه فضایی روی کل صفحه‌نمایش نشان داده می‌شود.

محفظه‌های فضایی که در حالت مرز XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT هستند الزامات دیگری دارند:

• زمان‌های اجرا باید با این محفظه‌های فضایی همانند برنامه تمام‌صفحه و فراگیر ایجادشده بدون استفاده از محفظه فضایی رفتار کنند، به‌جز تغییرات رفتاری که در تغییرات در وضعیت جلسه ذکر شده است.
• زمان‌های اجرا ممکن است افزونه‌های دیگری ارائه دهند که به محفظه‌های فضایی فراگیر امکان می‌دهد متفاوت از برنامه‌های تمام‌صفحه و فراگیر ایجادشده بدون این افزونه رفتار کنند.
• زمان‌های اجرا باید مرزهای بی‌نهایت را برای این محفظه‌های فضایی گزارش کنند.
• زمان‌های اجرا ممکن است وقتی محتوای فضایی فراگیر نمایان است، محتواهای فضایی دیگر را پنهان کنند. ازآنجایی‌که این موضوع ممکن است برای هر زمان اجرا متفاوت باشد، برنامه‌ها نباید به نمایش یا پنهان شدن خودکار محفظه‌های فضایی براساس نمایان بودن محفظه فضایی فراگیر متکی باشند. مانند همه انتقال‌های حالت قابل‌مشاهده دیگر، زمان‌های اجرا باید یک رویداد XrEventDataSpatialContainerVisibleChangedEXT را در صف قرار دهند وقتی که یک محفظه فضایی به‌دلیل قابل‌مشاهده بودن یک محفظه فراگیر پنهان می‌شود.

توجه

الزامات بالا به این معنی است که همه زمان‌های اجرا می‌توانند مسیر OpenXR 1.x را بدون این افزونه با ایجاد ضمنی محفظه فضایی، تنظیم حالت مرزهای محفظه روی فراگیر، و درخواست برای قابل‌مشاهده بودن آن پیاده‌سازی کنند.

برنامه‌ها بااستفاده از xrRequestSpatialContainerBoundsModeEXT درخواست می‌کنند حالت مرزهای محفظه فضایی را تغییر دهند.

XrResult xrRequestSpatialContainerBoundsModeEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsModeRequestInfoEXT* info);

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

• ‫spatialContainer XrSpatialContainerEXT است که برای آن درخواست تغییر می‌شود.
• ‫info اشاره‌گری به XrSpatialContainerBoundsModeRequestInfoEXT است که حاوی حالت مرزهای درخواست‌شده است.

تغییر حالت مرزهای محفظه فضایی عملیاتی ناهمگام است و زمان‌های اجرا ممکن است رویداد تغییریافته یا ردشده را چند ثانیه پس‌از درخواست تغییر توسط برنامه در صف قرار دهند. این به زمان‌های اجرا اجازه می‌دهد واسط کاربری را که برای ورود ایمن کاربر به حالت فراگیر لازم است بالا بیاورند.

زمان‌های اجرا باید درخواست تغییر حالت مرزها را برای محفظه فضایی نامرئی بپذیرند. اگر زمان اجرا درخواست حالت مرزها را برای محفظه غیرقابل‌مشاهده رد کند، درعوض ممکن است درخواست نمایش چنین محفظه فضایی را رد کند یا به‌تعویق بیندازد. این اجازه به برنامه‌ها امکان می‌دهد تا محفظه‌ای را به‌عنوان محفظه فراگیر راه‌اندازی کنند. زمان اجرا ممکن است درخواست‌های تغییر حالت مرزهای محفظه فضایی نمایان را رد کند، که دراین‌صورت زمان اجرا باید رویداد XrEventDataSpatialContainerBoundsModeRequestDeniedEXT را در صف قرار دهد. برای مثال، برخی‌از زمان‌های اجرا درخواست تغییر حالت مرزهای محفظه فضایی قابل‌مشاهده‌ای را که کاربر به‌طور فعال با آن تعامل ندارد رد می‌کنند.

اگر برنامه‌ای حالت مرزهایی را درخواست کند که براساس XrSystemSpatialContainerPropertiesEXT :: supportsBounded و XrSystemSpatialContainerPropertiesEXT :: supportsImmersive پشتیبانی نمی‌شود، زمان‌های اجرا باید XR_ERROR_VALIDATION_FAILURE را برگردانند.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید پیش‌از فراخوانی xrRequestSpatialContainerBoundsModeEXT فعال شود
• spatialContainer باید شناسه مجازی XrSpatialContainerEXT معتبر باشد
• info باید اشاره‌گری به ساختار معتبر XrSpatialContainerBoundsModeRequestInfoEXT باشد

کدهای برگشتی

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

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ناموفق

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
• XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerBoundsModeRequestInfoEXT با xrRequestSpatialContainerBoundsModeEXT برای تغییر حالت مرزهای محفظه فضایی استفاده می‌شود.

typedef struct XrSpatialContainerBoundsModeRequestInfoEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerBoundsModeRequestInfoEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• boundsMode XrSpatialContainerBoundsModeEXT موردنظر برای محفظه فضایی است.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrSpatialContainerBoundsModeRequestInfoEXT فعال شود
• type باید XR_TYPE_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_INFO_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد
• boundsMode باید مقدار XrSpatialContainerBoundsModeEXT معتبری باشد

هر بار که زمان اجرا مرزها یا حالت مرزهای یک محفظه فضایی را تغییر می‌دهد، زمان اجرا باید یک رویداد XrEventDataSpatialContainerBoundsChangedEXT را با اطلاعات مرزهای جدید در صف قرار دهد.

typedef struct XrEventDataSpatialContainerBoundsChangedEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerEXT              spatialContainer;
    XrExtent3Df                        bounds;
    XrBool32                           infiniteBounds;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrEventDataSpatialContainerBoundsChangedEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• spatialContainer XrSpatialContainerEXT است که این رویداد برای آن است.
• bounds عرض، ارتفاع، و عمق جدید مرزهای محفظه فضایی است.
• اگر محفظه دارای مرزهای بی‌نهایت باشد، infiniteBounds درست است.
• ‫boundsMode XrSpatialContainerBoundsModeEXT جدید محفظه فضایی است.

رویداد برای همه تغییرات، ازجمله تغییرات درخواست‌شده برنامه و تغییرات شروع‌شده زمان اجرا، در صف قرار می‌گیرد.

وقتی کاربر به‌صورت تعاملی درحال تغییر اندازه محفظه فضایی است، زمان‌های اجرا باید به یکی از روش‌های زیر عمل کنند:

• وقتی کاربر اندازه محفظه فضایی را تغییر می‌دهد، رویدادهای زیادی را احتمالاً با نرخ فریم در صف قرار دهید
• صف‌بندی یک رویداد در پایان تغییر اندازه

اگر زمان اجرا فقط یک رویداد را در پایان تغییر اندازه در صف قرار دهد، آن زمان اجرا باید به گزارش کردن حدود قدیمی از xrGetSpatialContainerBoundsEXT ادامه دهد تا زمانی که زمان اجرا رویداد تغییر اندازه را در صف قرار دهد. زمان‌های اجرا باید چندین رویداد تغییر مرزهای نظرسنجی‌نشده را ادغام کنند. به عبارت دیگر، اگر مرزها یا حالت مرزها درحالی‌که رویداد XrEventDataSpatialContainerBoundsChangedEXT هنوز در صف است تغییر کند، زمان‌های اجرا باید فقط یک رویداد حاوی آخرین تغییر مرز رخ‌داده را گزارش کنند. ازآنجایی‌که برنامه‌ها می‌توانند مستقیماً با xrGetSpatialContainerBoundsEXT حدود محفظه فضایی را نظرسنجی کنند، تعداد تغییرات حدود از رویدادها می‌تواند با تعداد تغییرات از نظرسنجی براساس زمان‌بندی تغییرات حدود تولیدشده در زمان اجرا، تماس‌های برنامه با xrPollEvent ، و تماس‌های برنامه با xrGetSpatialContainerBoundsEXT متفاوت باشد.

وقتی مرزهای محفظه فضایی تغییر می‌کند، مبدأ محلی محفظه فضایی ممکن است تغییر کند. برای مثال، اگر زمان اجرا به کاربر اجازه دهد با کشیدن یکی از لبه‌های محفظه فضایی، اندازه مرزهای آن را تغییر دهد، وقتی کاربر یک لبه را می‌کشد، مرزها و مبدأ محلی آن محفظه تغییر خواهد کرد. در چنین شرایطی، زمان اجرا باید مرزها و مبدأ محلی را به‌طور هم‌زمان تغییر دهد.

زمان‌های اجرا باید infiniteBounds را روی XR_TRUE تنظیم کنند و عرض، ارتفاع، و عمق را روی ۰٫۰ تنظیم کنند تا مرزهای نامحدود را نشان دهند. زمان‌های اجرا باید infiniteBounds را روی XR_FALSE تنظیم کنند و عرض، ارتفاع، و عمق را روی اعداد مثبت محدود برای مرزهای محدود تنظیم کنند.

زمان‌های اجرا باید bounds و infiniteBounds را طبق همان قوانین XrSpatialContainerBoundsEXT تنظیم کنند.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrEventDataSpatialContainerBoundsChangedEXT فعال شود
• type باید XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_CHANGED_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

هر بار که زمان اجرا درخواست تغییر حالت مرزهای محفظه را رد می‌کند، زمان اجرا باید رویداد XrEventDataSpatialContainerBoundsModeRequestDeniedEXT را در صف قرار دهد.

typedef struct XrEventDataSpatialContainerBoundsModeRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerBoundsModeRequestDeniedEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• spatialContainer XrSpatialContainerEXT است که این رویداد برای آن است.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrEventDataSpatialContainerBoundsModeRequestDeniedEXT فعال شود
• type باید XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_DENIED_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

ساختار XrSpatialContainerBoundsEXT جعبه مرزی محفظه فضایی را توصیف می‌کند.

typedef struct XrSpatialContainerBoundsEXT {
    XrStructureType    type;
    void*              next;
    XrExtent3Df        bounds;
    XrBool32           infiniteBounds;
} XrSpatialContainerBoundsEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• bounds عرض، ارتفاع، و عمق مرزهای محفظه فضایی است. محدوده‌ها به متر است.
• اگر محفظه دارای مرزهای بی‌نهایت باشد، infiniteBounds درست است.

زمان‌های اجرا باید infiniteBounds را روی XR_TRUE تنظیم کنند و عرض، ارتفاع، و عمق را روی ۰٫۰ تنظیم کنند تا مرزهای نامحدود را نشان دهند. زمان‌های اجرا باید infiniteBounds را روی XR_FALSE تنظیم کنند و عرض، ارتفاع، و عمق را روی اعداد مثبت محدود برای مرزهای محدود تنظیم کنند.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید پیش‌از استفاده از XrSpatialContainerBoundsEXT فعال شود
• type باید XR_TYPE_SPATIAL_CONTAINER_BOUNDS_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

تابع xrGetSpatialContainerBoundsEXT مرزهای فعلی یک محفظه فضایی را جستجو می‌کند.

XrResult xrGetSpatialContainerBoundsEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsGetInfoEXT*   getInfo,
    XrSpatialContainerBoundsEXT*                bounds);

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

• ‫spatialContainer XrSpatialContainerEXT برای پُرسمان است.
• ‫getInfo همان XrSpatialContainerBoundsGetInfoEXT است که اطلاعات استفاده‌شده برای دریافت وضعیت محفظه فضایی را دارد.
• ‫bounds اشاره‌گری به XrSpatialContainerBoundsEXT است که در آن مرزها برگردانده می‌شود.

درحالی‌که محفظه فضایی محدود است، نباید مرزهای بی‌نهایت داشته باشد، درحالی‌که محفظه فضایی فراگیر است، باید مرزهای بی‌نهایت داشته باشد.

زمان‌های اجرا ممکن است در هر زمانی که محفظه فضایی محدود است، مرزهای محفظه فضایی را به هر مقدار مثبت محدودی تغییر دهند. تغییرات در مرزهای محفظه فضایی ازطریق XrEventDataSpatialContainerBoundsChangedEXT اطلاع‌رسانی می‌شود.

با این افزونه، برنامه نمی‌تواند درخواست تغییر در مرزها را بدهد، به‌جز تغییر بین حالت محدود و فراگیر با xrRequestSpatialContainerBoundsModeEXT . افزونه‌های دیگر ممکن است در آینده چنین روشی را ارائه دهند.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از فراخوانی xrGetSpatialContainerBoundsEXT فعال شود
• spatialContainer باید شناسه مجازی XrSpatialContainerEXT معتبر باشد
• اگر getInfo NULL نباشد، getInfo باید اشاره‌گری به ساختار XrSpatialContainerBoundsGetInfoEXT معتبر باشد
• bounds باید اشاره‌گری به ساختار XrSpatialContainerBoundsEXT باشد

کدهای برگشتی

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

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

ناموفق

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
• XR_ERROR_VALIDATION_FAILURE

ساختار XrSpatialContainerBoundsGetInfoEXT یک ساختار ورودی است که برای اهداف توسعه در آینده وجود دارد.

typedef struct XrSpatialContainerBoundsGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerBoundsGetInfoEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrSpatialContainerBoundsGetInfoEXT فعال شود
• type باید XR_TYPE_SPATIAL_CONTAINER_BOUNDS_GET_INFO_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

شمارش XrSpatialContainerVolumeClippingEXT رفتارهای مختلف برش حجم را برای محفظه فضایی شناسایی می‌کند.

typedef enum XrSpatialContainerVolumeClippingEXT {
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT = 0,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT = 1,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerVolumeClippingEXT;

شرح شمارشی

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT

هیچ محتوایی به حجم مرزی محفظه فضایی برش داده نمی‌شود. محتوا می‌تواند خارج از مرزهای ظرف فضایی ترسیم شود.

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT

محتوا دقیقاً به حجم مرزی محفظه فضایی برش داده می‌شود.

این شمارش در این افزونه استفاده نمی‌شود. این ویژگی برای این تعریف شده است که به سایر افزونه‌ها اجازه دهد رفتار برش صدا را که مدنظرشان است مشخص کنند. برای مثال، ممکن است برنامه‌ای بخواهد پس‌زمینه‌ای برای محفظه فضایی محدودشده ترسیم کند. نگاشت مکعبی تک‌چشمی روشی مناسب برای مشخص کردن پس‌زمینه است، اما نگاشت مکعبی تک‌چشمی ازنظر مفهومی در بی‌نهایت قرار دارد که خارج از محفظه است.

قابلیت‌های سیستم

برنامه می‌تواند با زنجیر کردن ساختار XrSystemSpatialContainerPropertiesEXT به XrSystemProperties هنگام فراخوانی xrGetSystemProperties، قابلیت‌های سیستم را بررسی کند.

typedef struct XrSystemSpatialContainerPropertiesEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSpatialContainerCount;
    XrBool32           supportsBounded;
    XrBool32           supportsImmersive;
} XrSystemSpatialContainerPropertiesEXT;

شرح عضو

• type XrStructureType این ساختار است.
• ‫next برابر با NULL یا اشاره‌گری به ساختار بعدی در زنجیره ساختار است. چنین ساختارهایی در OpenXR اصلی یا این افزونه تعریف نشده است.
• maxSpatialContainerCount حداکثر تعداد محفظه‌های فضایی است که می‌توان ایجاد کرد.
• اگر محفظه‌های فضایی بتوانند محدود شوند، supportsBounded درست است.
• اگر محفظه‌های فضایی بتوانند فراگیر باشند، supportsImmersive درست است.

زمان‌های اجرایی که از این افزونه پشتیبانی می‌کنند باید از برنامه‌ای که محفظه‌های فضایی زیادی ایجاد می‌کند پشتیبانی کنند، که فقط با تخصیص حافظه محدود می‌شود. زمان اجرا ممکن است محدودیت متفاوتی برای تعداد محفظه‌های فضایی نمایش‌داده‌شده به‌طور هم‌زمان داشته باشد. هیچ راهی برای پرس‌وجو کردن تعداد محفظه‌های نمایش‌داده‌شده به‌طور هم‌زمان در این افزونه وجود ندارد زیرا زمان اجرا ممکن است برنامه‌های جداگانه را براساس وضعیت همه برنامه‌های درحال اجرا محدود کند. فرض بر این است که دستگاه‌های بسیار محدود و دستگاه‌های کمتر محدود، محدودیت‌های متفاوتی برای تعداد محفظه‌های نمایش‌داده‌شده به‌طور هم‌زمان خواهند داشت؛ دستگاه‌های بسیار محدود ممکن است فقط از نمایش یک محفظه فضایی در هر زمان پشتیبانی کنند و دستگاه‌های کمتر محدود ممکن است از نمایش تعداد زیادی محفظه فضایی به‌طور هم‌زمان پشتیبانی کنند، که این امر منوط به محدودیت‌های محاسباتی پردازشی است.

زمان‌های اجرایی که از این افزونه پشتیبانی می‌کنند باید حداقل از یکی از محفظه‌های فضایی محدودشده یا محفظه‌های فضایی غوطه‌ور پشتیبانی کنند.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrSystemSpatialContainerPropertiesEXT فعال شود
• type باید XR_TYPE_SYSTEM_SPATIAL_CONTAINER_PROPERTIES_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

تابع xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT روش‌های ارائه گرافیکی پشتیبانی‌شده در سیستم را برمی‌گرداند.

XrResult xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    graphicsPresentationCapacityInput,
    uint32_t*                                   graphicsPresentationCountOutput,
    XrSpatialContainerGraphicsPresentationEXT*  graphicsPresentations);

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

• ‫instance همان XrInstance است که systemId از آن بازیابی شده است.
• ‫systemId همان XrSystemId است که مورد پُرسمان قرار گرفته است.
• graphicsPresentationCapacityInput ظرفیت آرایه graphicsPresentations است، یا ۰ برای نشان دادن درخواست بازیابی ظرفیت موردنیاز.
• ‫graphicsPresentationCountOutput اشاره‌گری به تعداد ارائه‌های گرافیکی نوشته‌شده است، یا اشاره‌گری به ظرفیت موردنیاز درصورتی‌که graphicsPresentationCapacityInput برابر با ۰ باشد.
• ‫graphicsPresentations اشاره‌گری به آرایه‌ای از مقادیر XrSpatialContainerGraphicsPresentationEXT است، اما اگر graphicsPresentationCapacityInput برابر با ۰ باشد، می‌تواند تهی باشد.
• برای شرح مفصل بازیابی اندازه graphicsPresentations موردنیاز، بخش پارامترهای اندازه میان‌گیر را ببینید.

زمان‌های اجرا باید همیشه محتوای میان‌گیر یکسانی را از این شمارش برای systemId داده‌شده و برای طول عمر نمونه برگردانند.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید پیش‌از فراخوانی xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT فعال شود
• instance باید شناسه XrInstance معتبری باشد
• graphicsPresentationCountOutput باید اشاره‌گری به مقدار uint32_t باشد
• اگر graphicsPresentationCapacityInput 0 نباشد، graphicsPresentations باید اشاره‌گری به آرایه‌ای از مقادیر graphicsPresentationCapacityInput XrSpatialContainerGraphicsPresentationEXT باشد

کدهای برگشتی

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

• 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

تغییرات در وضعیت جلسه

پشتیبانی از محفظه فضایی برای یک جلسه با زنجیر کردن XrSessionCreateInfoSpatialContainersEXT هنگام فراخوانی xrCreateSession فعال می‌شود.

typedef struct XrSessionCreateInfoSpatialContainersEXT {
    XrStructureType    type;
    const void*        next;
} XrSessionCreateInfoSpatialContainersEXT;

وقتی پشتیبانی از محفظه فضایی فعال باشد، XrSession رفتار متفاوتی دارد. دلیلش این است که هنگام استفاده از محفظه‌های فضایی، جلسه دیگر محتوای تصویری را در نمایشگر(ها) ارائه نمی‌دهد، بلکه محفظه‌های فضایی این کار را انجام می‌دهند. بنابراین، وقتی این افزونه فعال باشد، جلسه عملاً «بدون سر» است. برخلاف دیگر افزونه‌های بدون سر، برنامه‌ها می‌توانند داده‌های تصویر را ازطریق محفظه‌های فضایی ارسال کنند.

فعال کردن پشتیبانی از محفظه فضایی، میاناهای برنامه‌سازی کاربردی اصلی OpenXR را به‌صورت زیر تغییر می‌دهد.

زمان اجرا: ازدست دادن سیستم یا دستگاه

زمان اجرا: ازدست دادن سیستم یا دستگاه

xrDestroySession

xrDestroySession

IDLE
(درحال اجرا)

آزاد…

xrGetSystem
xrCreateSession

xrGetSystem...

xrCreateInstance

xrCreateIn...

xrDestroySession

xrDestroySession

LOSS_PENDING
(کار نمی‌کند)

درحال انتظار برای باخت...

xrDestroyInstance

xrDestroyInstance

app: optionally
relaunch XR

app: optionally...

شکل ۱۹. ماشین حالت جلسه جدید

• جلسه هرگز وارد وضعیت‌های XR_SESSION_STATE_VISIBLE، XR_SESSION_STATE_FOCUSED، یا XR_SESSION_STATE_EXITING نمی‌شود. زمان‌های اجرا نباید هرگز رویدادها را برای این وضعیت‌ها در صف قرار دهند. این حالت‌ها به‌ترتیب با رویدادهای محفظه فضایی XrEventDataSpatialContainerVisibleChangedEXT،‏ XrEventDataSpatialContainerInteractableChangedEXT، و XrEventDataSpatialContainerClosedEXT جایگزین می‌شوند.
• همچنین، جلسه هرگز وارد وضعیت‌های XR_SESSION_STATE_READY، XR_SESSION_STATE_SYNCHRONIZED، XR_SESSION_STATE_STOPPING نمی‌شود. زمان‌های اجرا نباید هرگز رویدادها را برای این وضعیت‌ها در صف قرار دهند. هیچ جایگزینی برای این ایالت‌ها وجود ندارد.
• زمان‌های اجرا باید جلسه را درحال اجرا درنظر بگیرند وقتی در وضعیت XR_SESSION_STATE_IDLE باشد.
• زمان‌های اجرا باید با جلسه به‌عنوان متمرکزشده رفتار کنند وقتی در حالت XR_SESSION_STATE_IDLE باشد و حداقل یک ظرف فضایی وجود داشته باشد که قابل‌تعامل باشد.
• دیگر به توابع xrBeginSession و xrEndSession نیازی نیست. زمان‌های اجرا باید هنگام فراخوانی این توابع، XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT را برگردانند. افزونه‌های دیگر ممکن است جایگزین‌هایی برای این توابع ارائه دهند.
• تابع xrRequestExitSession نیز دیگر لازم نیست. زمان‌های اجرا باید هنگام فراخوانی این تابع، XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT را برگردانند. برنامه‌هایی که می‌خواهند از جلسه درحال اجرا خارج شوند، درعوض می‌توانند xrRequestSpatialContainerVisibleEXT را فراخوانی کنند تا محفظه‌هایشان را پنهان کنند و پس‌از اینکه همه محفظه‌ها دیگر قابل‌مشاهده نبودند، جلسه را ازبین ببرند.

• افزونه‌هایی که رویدادهای اضافی را هنگام شروع اجرای جلسه در صف قرار می‌دهند، اکنون باید آن رویدادها را پس‌از ایجاد جلسه در صف قرار دهند. این افزونه‌ها در زیر ذکر شده‌اند.

  رویداد افزونه

XR_EXT_user_presence

XrEventDataUserPresenceChangedEXT

XR_META_boundary_visibility

XrEventDataBoundaryVisibilityChangedMETA

• تابع xrLocateViews برای فراخوانی جلسه معتبر نیست. زمان‌های اجرا باید XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT را از xrLocateViews برگردانند. افزونه‌های دیگر ممکن است روش‌هایی برای پیدا کردن نماهای یک ظرف فضایی خاص ارائه دهند.
• تابع xrWaitFrame باید همیشه XrFrameState :: shouldRender را روی false تنظیم کند. افزونه‌های دیگر ممکن است روش‌هایی برای اطلاع از اینکه آیا یک محفظه فضایی خاص باید لایه‌های ترکیب‌بندی خود را به‌روز کند یا نه ارائه دهند.
• تابع xrEndFrame روش معتبری برای ارسال لایه‌های ترکیب‌بندی نیست. اگر برنامه‌ای XrFrameEndInfo :: layerCount را روی مقدار غیرصفر تنظیم کند، زمان‌های اجرا باید XR_ERROR_VALIDATION_FAILURE را برگردانند. افزونه‌های دیگر ممکن است روش‌هایی برای ارسال لایه‌های ترکیب‌بندی برای یک محفظه فضایی خاص ارائه دهند.
• ورود به حالت XR_SESSION_STATE_LOSS_PENDING همه محفظه‌های فضایی را نیز می‌بندد. زمان‌های اجرا باید قبل‌از صف‌بندی تغییر وضعیت جلسه برای XR_SESSION_STATE_LOSS_PENDING ، یک رویداد XrEventDataSpatialContainerClosedEXT را برای هر محفظه فضایی فعال صف‌بندی کنند.
• تابع xrCreateSession دیگر به ساختار اتصال میانای برنامه‌سازی کاربردی گرافیک نیاز ندارد. افزونه‌های دیگر ممکن است به اتصال گرافیکی نیاز داشته باشند، برای مثال برای اینکه یک محفظه فضایی بااستفاده از میانای برنامه‌سازی کاربردی گرافیکی رندر شود.

رفتار بالا کمی با رفتار در XR_MND_headless متفاوت است. زمان‌های اجرا نباید رفتار جلسه بدون واسط را از XR_MND_headless فعال کنند وقتی پشتیبانی از محفظه فضایی برای آن جلسه فعال است.

توجه

وقتی محفظه‌های فضایی فعال باشند، جلسه فقط بین دو حالت جابه‌جا می‌شود: XR_SESSION_STATE_IDLE (درحال اجرا) و XR_SESSION_STATE_LOSS_PENDING (درحال اجرا نیست). درنتیجه، زمان‌های اجرا دیگر XR_ERROR_SESSION_RUNNING یا XR_ERROR_SESSION_NOT_RUNNING را برنمی‌گردانند. درعوض، وقتی جلسه‌ای درحال اجرا نیست، زمان‌های اجرا طبق قوانین هسته OpenXR، XR_ERROR_SESSION_LOST یا XR_SESSION_LOSS_PENDING را برمی‌گردانند. علاوه‌براین، xrBeginSession ، تنها عملکردی که XR_ERROR_SESSION_RUNNING را برمی‌گرداند، اکنون همیشه XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT را برمی‌گرداند.

استفاده معتبر (ضمنی)

• افزونه XR_EXT_spatial_container باید قبل‌از استفاده از XrSessionCreateInfoSpatialContainersEXT فعال شود
• type باید XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT باشد
• ‫ next باید NULL یا اشاره‌گر معتبری به ساختار بعدی در زنجیره ساختار باشد

ورودی‌های مانیفست Android

زمان‌های اجرای مبتنی بر AOSP ممکن است براساس وضعیت محفظه فضایی اولیه که قبل‌از اجرای هرگونه کد برنامه شروع می‌شود، رفتار سفارشی داشته باشند. برای مثال، زمان اجرا ممکن است منابع اختصاص‌داده‌شده برای فعالیت، پویانمایی‌های راه‌اندازی، یا نمایش صفحه اسپلش را تغییر دهد. ویژگی‌های زیر برای این منظور ارائه شده است. این برچسب‌ها جایگزین برچسب <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> می‌شوند که برنامه‌های مبتنی بر محفظه فضایی نباید آن را مشخص کنند، مگر برای سازگاری با زمان‌های اجرای مبتنی بر AOSP قدیمی‌تر.

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
          android:value="list of modes" />

این ویژگی به زمان‌های اجرا اشاره می‌کند که حالت‌های مرز استفاده‌شده توسط یک فعالیت است. به‌طور پیش‌فرض، این فهرست خالی است که به‌معنای نبودن راهنمایی است.

رشته‌های زیر برای این مشخصه معتبر است. مقادیر متعدد با | از هم جدا می‌شوند، مثل "bounded|immersive" .

مقدار

شرح

"2d_panel"

فعالیت بااستفاده از چارچوب نمای دوبعدی Android نمایش داده می‌شود.

"bounded"

این فعالیت از XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT استفاده می‌کند.

"immersive"

این فعالیت از XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT استفاده می‌کند.

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
          android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED" />

این ویژگی به زمان‌های اجرا اشاره می‌کند که XrSpatialContainerBoundsModeEXT اولیه فعالیت را هنگام ایجاد اولیه آن اجرا کنند. به‌طور پیش‌فرض، این رشته XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED است که به‌معنای عدم وجود راهنمایی است.

زمان‌های اجرا نباید برنامه‌ها را ملزم کنند که این ویژگی‌ها را داشته باشند تا طبق این مشخصات رفتار کنند. زمان‌های اجرا نباید رفتار قابل‌مشاهده برنامه را براساس این ویژگی‌ها تغییر دهند. همه این فراداده‌ها باید در سطح <activity> یا سطح <application> قابل‌تعیین باشند. اگر در سطح <application> مشخص شده باشد، برای همه فعالیت‌های برنامه که مقادیر خودشان را مشخص نمی‌کنند اعمال می‌شود.

کد نمونه

کد زیر نحوه استفاده از این افزونه را برای موارد استفاده فقط ادراکی بدون هیچ‌گونه پردازشی نشان می‌دهد.

XrInstance instance;    // Already initialized


// Create the session with spatial containers enabled
XrSession session;

XrSessionCreateInfoSpatialContainersEXT spatialContainerCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT,
};
XrSessionCreateInfo sessionCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO,
  .next = &spatialContainerCreateInfo,   // Enable spatial containers
};
(void)sessionCreateInfo.systemId;                             // Other create fields set in usual way

CHK_XR(xrCreateSession(instance, &sessionCreateInfo, &session));


// Because spatial containers are enabled, the session is considered
// running. App is able to query perception data such as head poses and hand
// poses.


// Based on app logic or when a system lost event happens, destroy the
// session
CHK_XR(xrDestroySession(session));

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

• XrSpatialContainerEXT

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

• xrCreateSpatialContainerEXT
• xrCreateSpatialContainerSpaceEXT
• xrDestroySpatialContainerEXT
• xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT
• xrGetSpatialContainerBoundsEXT
• xrGetSpatialContainerStateEXT
• xrRequestSpatialContainerBoundsModeEXT
• xrRequestSpatialContainerVisibleEXT

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

• XrEventDataSpatialContainerBoundsChangedEXT
• XrEventDataSpatialContainerBoundsModeRequestDeniedEXT
• XrEventDataSpatialContainerClosedEXT
• XrEventDataSpatialContainerInteractableChangedEXT
• XrEventDataSpatialContainerVisibleChangedEXT
• XrEventDataSpatialContainerVisibleRequestDeniedEXT
• XrSpatialContainerBoundsEXT
• XrSpatialContainerBoundsGetInfoEXT
• XrSpatialContainerBoundsModeRequestInfoEXT
• XrSpatialContainerCreateInfoEXT
• XrSpatialContainerSpaceCreateInfoEXT
• XrSpatialContainerStateEXT
• XrSpatialContainerStateGetInfoEXT
• XrSpatialContainerVisibleRequestInfoEXT

• درحال گسترش دادن XrSessionCreateInfo :

  • XrSessionCreateInfoSpatialContainersEXT

• درحال گسترش دادن XrSystemProperties :

  • XrSystemSpatialContainerPropertiesEXT

Enums جدید

• XrSpatialContainerBoundsModeEXT
• XrSpatialContainerGraphicsPresentationEXT
• XrSpatialContainerVolumeClippingEXT

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

• XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME
• XR_EXT_spatial_container_SPEC_VERSION

• درحال گسترش دادن XrObjectType :

  • XR_OBJECT_TYPE_SPATIAL_CONTAINER_EXT

• درحال گسترش دادن XrResult :

  • XR_ERROR_COMPATIBLE_SPATIAL_CONTAINER_MISSING_EXT
  • XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT
  • XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT

• درحال گسترش دادن XrStructureType :

  • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_CHANGED_EXT
  • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_DENIED_EXT
  • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_INTERACTABLE_CHANGED_EXT
  • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_CHANGED_EXT
  • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_REQUEST_DENIED_EXT
  • XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT
  • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_EXT
  • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_GET_INFO_EXT
  • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_INFO_EXT
  • XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT
  • XR_TYPE_SPATIAL_CONTAINER_SPACE_CREATE_INFO_EXT
  • XR_TYPE_SPATIAL_CONTAINER_STATE_EXT
  • XR_TYPE_SPATIAL_CONTAINER_STATE_GET_INFO_EXT
  • XR_TYPE_SPATIAL_CONTAINER_VISIBLE_REQUEST_INFO_EXT
  • XR_TYPE_SYSTEM_SPATIAL_CONTAINER_PROPERTIES_EXT

مشکلات

• چگونه چندین درخواست معوقه قابل‌مشاهده را مدیریت می‌کنیم؟ آیا برنامه باید یک تغییر / رد شدن را دریافت کند یا چند تغییر؟ اگر تماس‌ها در چند قاب باشد، ممکن است پاسخ متفاوت باشد. اگر درخواست‌های متعدد منجر به noop شود، ممکن است پاسخ متفاوت باشد، یعنی درخواست برای قابل‌مشاهده بودن محفظه فضایی، سپس غیرقابل‌مشاهده بودن برای محفظه‌ای که در ابتدا غیرقابل‌مشاهده است.

  • حل‌وفصل شد. انتخاب‌های مختلف برای رویدادهای تغییر و رویدادهای ردشده. درخواست‌های Noop رویداد تغییر را در صف قرار نمی‌دهند، این کار فقط برای توسعه‌دهنده برنامه نویز ایجاد می‌کند و فیلتر کردن آن برای زمان‌های اجرا آسان است. اگر چند درخواست قابل‌مشاهده رد شود، هرکدام از زمان‌های اجرا باید یک رویداد ردشده متناظر ایجاد کنند.

• چگونه انتظار می‌رود که افزونه خودکارسازی انطباق تعریف شود تا همه متن مشخصات اختیاری برای رفتارهای خط‌مشی همچنان توسط CTS قابل‌تست باشد؟

  • حل‌وفصل شد. افزونه آزمایشی جداگانه. یک زمان اجرای افزونه آزمایشی فقط برای CTS اجرا خواهد شد که به CTS اجازه می‌دهد همه خط‌مشی‌های سیستم را کنترل کند.

• Do we need an event for when a spatial container’s position changes?

  • حل‌وفصل شد. نه. فضای محفظه فضایی قفل‌نشده است و دیگر فضاهای مشابه، مانند XR_REFERENCE_SPACE_TYPE_VIEW، هنگام تغییر رویدادی ندارند.

• اگر چندین محفظه فضایی وجود داشته باشد، xrSyncActions چگونه کار می‌کند؟

  • حل‌وفصل شد. نیازی به تغییر نیست. xrSyncActions برای همه محفظه‌های فضایی در جلسه اعمال می‌شود. اگر برنامه‌ای بخواهد کنش‌های ورودی را به محفظه فضایی خاصی هدایت کند، می‌تواند به وضعیت تعاملی هر محفظه نگاه کند تا انتخاب کند کدام محفظه‌ها اهداف معتبری هستند. اگر برنامه‌ای بخواهد فقط وضعیت کنش ورودی را برای یک محفظه فضایی همگام‌سازی کند، به افزونه دیگری نیاز خواهد بود. بااین‌حال، انتظار داریم که درعوض روی افزونه‌ای تمرکز کنیم که به برنامه‌ها اجازه می‌دهد کاملاً مبتنی بر رویداد باشند و از نیاز به فراخوانی xrSyncActions در حلقه قاب جلوگیری کند.

• برنامه‌هایی که به‌ندرت به‌روز می‌شوند چگونه با ورودی برخورد می‌کنند؟

  • حل‌وفصل شد. تغییری لازم نیست. While valuable to EXT_spatial_container, it is also valuable outside of spatial containers. این مورد را می‌توان ازطریق افزونه کانال رویداد مدیریت کرد و در هر دو حالت کار می‌کند. برای محفظه‌های فضایی، روش‌های بیشتری برای فیلتر کردن رویدادها برای یک محفظه فضایی اضافه خواهیم کرد.

• آیا برای برنامه‌هایی که حلقه‌های ورودی و بازپرداخت مجزا دارند، باید برای کنترل زمان‌بندی حلقه ورودی منتظر بمانیم؟

  • حل‌وفصل شد. تغییری لازم نیست. انتظار می‌رود این موضوع ازطریق کانال رویداد و افزونه‌های درخواست فعلی مدیریت شود. افزونه درخواست فعلی به پردازش اجازه می‌دهد تا مبتنی بر رویداد باشد و از حلقه قاب جدا شود.

• آیا محفظه فضایی می‌تواند حالت خود را نسبت به محفظه‌های فضایی دیگر دریافت کند؟ نکات کلیدی در اینجا: آیا مورد استفاده‌ای برای این داریم؟ و اگر این‌طور است، فضاهای محفظه فضایی چگونه به LOCAL متصل می‌شوند؟

  • حل‌وفصل شد. بله. This is already possible for spatial containers within the same session by going through XR_REFERENCE_SPACE_TYPE_VIEW and supporting view-dependent content is desirable. برای هم‌رسانی حالت‌های محفظه فضایی در جلسه‌ها (مانند فرایند دیگر)، مسیر موردانتظار استفاده از XR_EXT_spatial_anchor و الگوهای پایداری و هم‌رسانی موجود آن است.

• آیا فضای محتوای فضایی درصورت قابل‌مشاهده نبودن قابل‌مکان‌یابی است؟

  • حل‌وفصل شد. نه. وقتی محفظه فضایی نمایان نباشد، فضای محفظه فضایی قابل‌مکان‌یابی نیست. این نشان می‌دهد که صدای فضایی ندارد و برنامه نمی‌تواند محتوای وابسته به نما را زمانی که spatial_container قابل مشاهده نیست، «آماده‌سازی» کند. هر دو مورد قابل‌قبول است زیرا وقتی محفظه فضایی قابل‌مشاهده نیست، انتظار می‌رود برنامه هرگونه بار واحد پردازش مرکزی / واحد پردازش گرافیکی را که برای آن محفظه فضایی استفاده می‌شود متوقف کند.

• انتظار می‌رود فضای محفظه فضایی در کجای محفظه فضایی قرار گیرد؟ پیشنهادها مرکز یا نقطه کمینه (minX،‏ minY،‏ minZ) بوده‌اند.

  • حل‌وفصل شد. در مرکز. هیچ مکانی وجود ندارد که در اکثر روش‌هایی که انتظار می‌رود اندازه ظرف فضایی تغییر کند (لبه‌های متحرک) حرکت نکند. «مرکز» معمولاً در بخش‌های دیگر OpenXR استفاده می‌شود. ما با پنجره‌ها در محاسبات دوبعدی که از حداقل مختصات استفاده می‌کنند هم‌راستا نشدیم، زیرا نمایشگرهای مدل سه‌بعدی اغلب از این قرارداد پیروی نمی‌کنند.

• چه زمانی انتظار می‌رود زمان اجرا منابعی را ایجاد کند که زیربنای محفظه فضایی هستند؟ این کار گاهی شامل IPC با سرویس‌های سیستم می‌شود.

  • حل‌وفصل شد. به‌طور هم‌زمان به‌عنوان بخشی از xrCreateSpatialContainerEXT . اگرچه ممکن است IPC درگیر باشد، اما ایجاد واقعی یک کانتینر معمولاً ارزان است. برخی‌از فروشندگان دارای انحصار متقابل سراسری برای مدیریت محفظه‌ها هستند، اما معمولاً انتظار نمی‌رود که این امر باعث انتظار طولانی شود. مشکلات مربوط به رقابت mutex اشکال‌های مختص ارائه‌دهنده هستند که انتظار می‌رود هر ارائه‌دهنده به آن‌ها رسیدگی کند.

• آیا به سیگنالی نیاز داریم که نشان دهد XrSession محفظه‌های فضایی ایجاد خواهد کرد و بنابراین از مسیر پردازش قدیمی پشتیبانی نمی‌کند؟

  • حل‌وفصل شد. بله. ما ماشین حالت جلسه را به‌طور اساسی تغییر می‌دهیم.

سابقه نسخه

• بازبینی ۱،‏ ۲۰۲۶/۰۸/۰۶ (جارد فایندر، Google)

  • شرح اولیه افزونه