XR_EXT_spatial_container

Name String

XR_EXT_spatial_container

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

811

المراجعة

1

حالة التصديق

لم تتم المصادقة عليها

الاعتماد على الإضافات والإصدارات

OpenXR 1.0

تاريخ آخر تعديل

2026-08-06

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

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

المساهمون

جاريد فايندر، Google
أندرياس لوف سيلفيك، Meta Platforms
لاكلان فورد، Google
كاس إيفريت، Meta Platforms
آدم غوسيتيس، Meta Platforms
أنكور أغراوال، Unity Technologies
بيورن سوينسون، LÖVR
ديني رونغرين، Varjo Technologies
فريديا هويا كواديو، Godot Engine
غودونغ رونغ، Meta Platforms
جاكوب بورنيكرانتز، NVIDIA
جيان تشانغ، ByteDance
جون كيرني، Meta Platforms
جوناثان رايت، Meta Platforms
جونفينغ شي، ByteDance
كيني فيركايمر، Google
كورتيس إيفيلي، Qualcomm
ماوريسيو نارفايز، Meta Platforms
ناثان نوبر، Valve Corporation
نيهاف جين، Google
نيكيتا لوتسينكو، Meta Platforms
برافين بابو جيه دي، ByteDance
رايلي بافليك، Collabora
سالار خان، Google
شواي ليو، ByteDance
والتر لوه، Meta Platforms
يين لي، Microsoft
تشيبينغ ليو، ByteDance

نظرة عامة

تحدّد هذه الإضافة فئة جديدة من العناصر القابلة للعرض، تُسمّى "الحاويات المكانية"، وهي تشبه مفهوم "النوافذ" في أنظمة النوافذ الثنائية الأبعاد على أجهزة الكمبيوتر المكتبي.

في OpenXR 1.x، تتحكّم التطبيقات بشكل حصري في كل ما يراه المستخدم وكيفية دمجه مع بيئته الحقيقية أو الافتراضية. لا تُجري بيئات التشغيل سوى تعديلات طفيفة على ما يتم عرضه لضمان سلامة المستخدمين. يُعدّ نموذج التطبيق هذا جيدًا لغمر المستخدم في تجربة واحدة، ولكنه لا يمتد إلى تجارب متعددة متزامنة. على وجه الخصوص، في بيئات الواقع المعزّز والواقع المختلط، غالبًا ما يريد المستخدمون تجربة تطبيقات مختلفة متعددة في الوقت نفسه.

الحاويات المكانية تشبه النوافذ الممتدة إلى الأبعاد الثلاثية. يمكن للمستخدم رؤية حاويات مكانية متعددة في الوقت نفسه وإدخال البيانات في مجموعة فرعية منها. يمكن أن تنتمي الحاويات المكانية المرئية إلى تطبيقات مختلفة، وتدير بيئات التشغيل حجمها وموضعها نيابةً عن المستخدم.

تتيح هذه الإضافة هذه الأنواع الجديدة من التجارب المحدودة مكانيًا بالإضافة إلى تجارب OpenXR الغامرة الحالية. يُسمح لتجارب OpenXR المحدودة بأن تتضمّن محتوى ثلاثي الأبعاد بشكل طفيف (لوحات مسطّحة مع إزاحات عمق بسيطة) أو وحدات تخزين تستضيف محتوى ثلاثي الأبعاد بالكامل. تجارب OpenXR الغامرة هي تطبيقات غامرة حالية بملء الشاشة تتوافق مع الإصدار 1.0 من OpenXR. ويمكن للتطبيقات التبديل بين نوعَي المحتوى إذا اختار التطبيق ذلك.

لا تحدّد هذه الإضافة أي طريقة ليعرض التطبيق محتواه. يتم تحديد كيفية رسم المحتوى في إضافات أخرى: 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 .

ملاحظة

By design, this extension delegates visibility and focus management to individual spatial containers. بما أنّ الجلسة ككل لم تعُد تمثّل عنصرًا واحدًا مرئيًا أو مركّزًا، لا تنتقل الجلسة من خلال جهاز الحالة العادي في 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 قبل طلب عرض حاوية مكانية.

يجب أن تعرض بيئات التشغيل XR_ERROR_VALIDATION_FAILURE إذا كان أي بُعد من XrSpatialContainerCreateInfoEXT :: suggestedBounds سالبًا أو لا نهائيًا أو ليس رقمًا. يجب أن تعرض بيئات التشغيل XR_ERROR_LIMIT_REACHED إذا حاول أحد التطبيقات إنشاء حاويات مكانية أكثر من المحدّد في XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount . إذا لم تكن الحاويات المكانية مفعَّلة لهذه الجلسة، يجب أن تعرض بيئات التشغيل XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT .

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

• يجب تفعيل إضافة XR_EXT_spatial_container قبل استدعاء xrCreateSpatialContainerEXT
• يجب أن يكون session اسم معرِّف XrSession صالحًا
• createInfo يجب أن يكون مؤشرًا إلى بنية XrSpatialContainerCreateInfoEXT صالحة
• يجب أن يكون spatialContainer مؤشرًا إلى اسم معرِّف XrSpatialContainerEXT

رموز الإرجاع

Success

• 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

أمان Thread

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

رموز الإرجاع

Success

• 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

الشكل 18: اصطلاح المحاور لمساحة الحاوية المكانية

مساحة الحاوية المكانية هي نقطة أصل غير مقفلة في العالم. يمكن للتطبيقات التي تتطلّب مصدرًا ثابتًا في العالم أثناء استخدام الوضع المجسم استخدام مساحة ثابتة في العالم، مثل XR_REFERENCE_SPACE_TYPE_LOCAL .

قد تغيّر بيئات التشغيل وضعية مساحة الحاوية المكانية في أي وقت، وذلك عادةً للسماح للمستخدم بنقل حاوية مكانية إلى موضع أو اتجاه مختلفَين. قد تغيّر بيئات التشغيل أيضًا الوضعية عند الانتقال بين وضعَي الحدود XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT وXR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT.

يجب أن تظل مساحة الحاوية المكانية معرِّفًا صالحًا حتى إذا تم تدمير الحاوية المكانية المخصّصة لها باستخدام xrDestroySpatialContainerEXT . عندما تكون الحاوية المكانية غير مرئية أو تم تدميرها، يجب أن تكون مساحة الحاوية المكانية غير قابلة للتحديد بالنسبة إلى المساحات الأخرى. XrSpaceLocation :: locationFlags وXrViewState ::viewStateFlags ستكون قيمتهما 0.

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

• يجب تفعيل الإضافة XR_EXT_spatial_container قبل استدعاء xrCreateSpatialContainerSpaceEXT
• يجب أن يكون session اسم معرِّف XrSession صالحًا
• createInfo يجب أن يكون مؤشرًا إلى بنية XrSpatialContainerSpaceCreateInfoEXT صالحة
• space يجب أن يكون مؤشرًا إلى مقبض XrSpace

رموز الإرجاع

Success

• 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

رموز الإرجاع

Success

• 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 صالحة

رموز الإرجاع

Success

• 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 . يجب ألا تؤخر بيئات التشغيل عرض الحاوية لأكثر من 0.5 ثانية.

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

• يجب تفعيل إضافة 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 على "خطأ") قبل الحدث للحاوية التي تبدأ في أن تكون قابلة للتفاعل (تم ضبط interactable على "صحيح").

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

• يجب تفعيل إضافة 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 في قائمة الانتظار. على سبيل المثال، سترفض بعض بيئات التشغيل طلبًا لتغيير وضع الحدود لحاوية مكانية مرئية لا يتفاعل معها المستخدم بشكل نشط.

يجب أن تعرض بيئات التشغيل XR_ERROR_VALIDATION_FAILURE إذا طلب أحد التطبيقات وضع حدود غير متوافق استنادًا إلى XrSystemSpatialContainerPropertiesEXT :: supportsBounded وXrSystemSpatialContainerPropertiesEXT :: supportsImmersive .

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

• يجب تفعيل الإضافة XR_EXT_spatial_container قبل طلب xrRequestSpatialContainerBoundsModeEXT
• يجب أن يكون spatialContainer اسمًا معرِّفًا صالحًا لـ XrSpatialContainerEXT
• info يجب أن يكون مؤشرًا إلى بنية XrSpatialContainerBoundsModeRequestInfoEXT صالحة

رموز الإرجاع

Success

• 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 وأن تضبط العرض والارتفاع والعمق على 0.0 لتمثيل حدود لا نهائية. يجب أن تضبط بيئات التشغيل السمة 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 وأن تضبط العرض والارتفاع والعمق على 0.0 لتمثيل حدود لا نهائية. يجب أن تضبط بيئات التشغيل السمة 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

رموز الإرجاع

Success

• 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، أو 0 للإشارة إلى طلب استرداد السعة المطلوبة.
• ‫graphicsPresentationCountOutput هو مؤشر لعدد عروض الرسومات المكتوبة، أو مؤشر للسعة المطلوبة في حال كانت قيمة graphicsPresentationCapacityInput تساوي 0.
• ‫graphicsPresentations هو مؤشر إلى مصفوفة من قيم XrSpatialContainerGraphicsPresentationEXT، ولكن يمكن أن يكون فارغًا إذا كانت قيمة graphicsPresentationCapacityInput هي 0.
• يُرجى الاطّلاع على قسم مَعلمات حجم ذاكرة التخزين المؤقت للحصول على وصف تفصيلي لاسترداد حجم graphicsPresentations المطلوب.

يجب أن تعرض بيئات التشغيل دائمًا محتوى مخزن مؤقت متطابقًا من هذا التعداد لـ systemId المحدّد وطوال مدة تشغيل المثيل.

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

• يجب تفعيل الإضافة XR_EXT_spatial_container قبل استدعاء xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT
• يجب أن يكون instance مقبض XrInstance صالحًا
• يجب أن يكون graphicsPresentationCountOutput مؤشرًا إلى قيمة uint32_t
• إذا لم تكن قيمة graphicsPresentationCapacityInput هي 0، يجب أن تكون قيمة graphicsPresentations مؤشرًا إلى مصفوفة من قيم graphicsPresentationCapacityInput XrSpatialContainerGraphicsPresentationEXT

رموز الإرجاع

Success

• XR_SUCCESS

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

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

التغييرات في حالة الجلسة

يتم تفعيل ميزة "الحاويات المكانية" لجلسة معيّنة من خلال ربط XrSessionCreateInfoSpatialContainersEXT عند طلب xrCreateSession .

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

عند تفعيل ميزة "الحاويات المكانية"، يختلف سلوك XrSession. والسبب هو أنّه عند استخدام الحاويات المكانية، لا تعرض الجلسة محتوى الصور على الشاشات، بل تتولى الحاويات المكانية ذلك بدلاً منها. لذلك، عندما تكون هذه الإضافة مفعّلة، تكون الجلسة "بدون واجهة مستخدم" بشكل فعّال. على عكس الإضافات الأخرى التي تعمل بلا واجهة مستخدم رسومية، يمكن للتطبيقات إرسال بيانات الصور من خلال الحاويات المكانية.

يؤدي تفعيل ميزة "الحاوية المكانية" إلى تغيير واجهات برمجة تطبيقات OpenXR الأساسية بالطريقة التالية.

runtime: losing system or device

runtime: losing system or device

xrDestroySession

xrDestroySession

IDLE
(قيد التشغيل)

غير نشِط...

xrGetSystem
xrCreateSession

xrGetSystem...

xrCreateInstance

xrCreateIn...

xrDestroySession

xrDestroySession

LOSS_PENDING
(غير قيد التشغيل)

LOSS_PENDING...

xrDestroyInstance

xrDestroyInstance

app: optionally
relaunch XR

app: optionally...

الشكل 19: جهاز حالة الجلسة الجديد

• لا تدخل الجلسة مطلقًا في الحالات 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 على "خطأ". قد توفّر الإضافات الأخرى طرقًا لمعرفة ما إذا كان يجب على حاوية مكانية معيّنة تعديل طبقات التركيب.
• لا تُعدّ الدالة xrEndFrame طريقة صالحة لإرسال طبقات التركيب. إذا ضبط أحد التطبيقات XrFrameEndInfo :: layerCount على قيمة غير صفرية، يجب أن تعرض بيئات التشغيل XR_ERROR_VALIDATION_FAILURE . قد توفّر الإضافات الأخرى طرقًا لإرسال طبقات التركيب لحاوية مكانية معيّنة.
• يؤدي الدخول إلى الحالة XR_SESSION_STATE_LOSS_PENDING أيضًا إلى إغلاق جميع الحاويات المكانية. يجب أن تضع بيئات التشغيل حدث XrEventDataSpatialContainerClosedEXT في قائمة الانتظار لكل حاوية مكانية نشطة قبل وضع تغيير حالة الجلسة في قائمة الانتظار لـ XR_SESSION_STATE_LOSS_PENDING .
• لم تعُد دالة 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 . بدلاً من ذلك، عندما لا تكون الجلسة قيد التشغيل، تعرض بيئات التشغيل إما XR_ERROR_SESSION_LOST أو XR_SESSION_LOSS_PENDING باتّباع القواعد في OpenXR core. بالإضافة إلى ذلك، ستعرض الدالة 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

قد يكون لبيئات التشغيل المستندة إلى مشروع Android المفتوح المصدر (AOSP) سلوك مخصّص استنادًا إلى حالة الحاوية المكانية الأولية التي تبدأ قبل تشغيل أي رمز برمجي للتطبيق. على سبيل المثال، قد تغيّر بيئة التشغيل الموارد المخصّصة للنشاط أو الصور المتحركة عند التشغيل أو عرض شاشة البداية. يتم توفير السمات التالية لهذا الغرض. وهي تحلّ محلّ علامة <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" /> التي يجب ألّا تحدّدها التطبيقات المستندة إلى الحاويات المكانية، إلّا لضمان التوافق مع بيئات التشغيل السابقة المستندة إلى مشروع Android المفتوح المصدر (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

عمليات تعداد جديدة

• 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 حدث تغيير في قائمة الانتظار، بل يؤدي ذلك إلى حدوث تشويش لمطوّر التطبيق ويسهل على بيئات التشغيل فلترته. إذا تم رفض طلبات متعددة مرئية، يجب أن تنشئ كل بيئة تشغيل حدث رفض مطابق.

• كيف يُتوقّع تحديد إضافة التشغيل الآلي للامتثال بحيث يظلّ كل نص المواصفات الاختياري لسلوكيات السياسة قابلاً للاختبار من خلال مجموعة أدوات اختبار التوافق (CTS)؟

  • تم حلّ المشكلة. إضافة اختبار منفصلة سيتم تنفيذ بيئات تشغيل إضافات الاختبار لمجموعة أدوات CTS فقط، ما يسمح لمجموعة أدوات CTS بالتحكّم في جميع سياسات النظام.

• هل نحتاج إلى حدث عندما يتغيّر موضع حاوية مكانية؟

  • تم حلّ المشكلة. لا، فمساحة الحاوية المكانية غير مقفلة على العالم، والمساحات الأخرى المماثلة، مثل XR_REFERENCE_SPACE_TYPE_VIEW، لا تتضمّن أحداثًا عند تغييرها.

• كيف تعمل السمة xrSyncActions في حال توفّر حاويات مكانية متعددة؟

  • تم حلّ المشكلة. لا حاجة إلى إجراء أي تغيير، إذ سيتم تطبيق xrSyncActions على جميع الحاويات المكانية في الجلسة. إذا أراد تطبيق توجيه إجراءات الإدخال إلى حاوية مكانية معيّنة، يمكنه الاطّلاع على حالة كل حاوية قابلة للتفاعل لاختيار الحاويات التي تُعدّ أهدافًا صالحة. إذا أراد أحد التطبيقات مزامنة حالة إجراء الإدخال فقط لحاوية مكانية واحدة، سيتطلّب ذلك إضافة أخرى. ومع ذلك، نتوقّع التركيز بدلاً من ذلك على إضافة تتيح للتطبيقات أن تكون مستندة بالكامل إلى الأحداث وتجنُّب الحاجة إلى طلب xrSyncActions في حلقة إطار.

• كيف تتعامل التطبيقات التي يتم تحديثها بشكل غير متكرر مع الإدخال؟

  • تم حلّ المشكلة. لا حاجة إلى إجراء أي تغيير. على الرغم من أنّها مفيدة لـ EXT_spatial_container، فهي مفيدة أيضًا خارج الحاويات المكانية. يمكن التعامل مع ذلك من خلال إضافة قناة الأحداث والعمل في كلتا الحالتين. بالنسبة إلى الحاويات المكانية، سنضيف طرقًا أخرى لفلترة الأحداث لحاوية مكانية واحدة.

• هل نحتاج إلى الانتظار لتقييد/التحكّم في توقيت حلقة الإدخال للتطبيقات التي تتضمّن حلقات إدخال وعرض منفصلة؟

  • تم حلّ المشكلة. لا حاجة إلى إجراء أي تغيير. ومن المتوقّع أن تتم معالجة ذلك من خلال قناة الأحداث وإضافات الطلبات الحالية. تسمح إضافة طلب العرض بأن يكون العرض مستندًا إلى الأحداث ومنفصلاً عن تكرار اللقطات.

• هل يمكن لحاوية مكانية الحصول على وضعيتها بالنسبة إلى الحاويات المكانية الأخرى؟ الأفكار الرئيسية هنا: هل لدينا حالة استخدام لهذا؟ وإذا كان الأمر كذلك، فكيف ترتبط مساحات الحاويات المكانية بـ LOCAL؟

  • تم حلّ المشكلة. نعم. يمكن تنفيذ ذلك من خلال الحاويات المكانية ضمن الجلسة نفسها من خلال XR_REFERENCE_SPACE_TYPE_VIEW، ومن الأفضل إتاحة المحتوى الذي يعتمد على العرض. لمشاركة أوضاع الحاويات المكانية في جميع الجلسات (مثل عملية أخرى)، من المتوقّع استخدام XR_EXT_spatial_anchor وأنماط الثبات والمشاركة الحالية.

• هل يمكن تحديد موقع مساحة الحاوية المكانية إذا لم تكن مرئية؟

  • تم حلّ المشكلة. لا، لا يمكن تحديد موقع مساحة الحاوية المكانية عندما لا تكون الحاوية المكانية مرئية. ويعني ذلك أنّ التطبيق لا يتضمّن صوتًا مكانيًا ولا يمكنه "تجهيز" المحتوى المستنِد إلى العرض عندما لا يكون spatial_container مرئيًا. كلا الخيارَين مقبولان لأنّه عندما لا تكون الحاوية المكانية مرئية، من المتوقّع أن يوقف التطبيق أي حِمل على وحدة المعالجة المركزية أو وحدة معالجة الرسومات يُستخدم لهذه الحاوية المكانية.

• أين من المتوقع أن يتم وضع مساحة الحاوية المكانية في الحاوية المكانية؟ كانت الاقتراحات هي المركز أو الحد الأدنى للنقطة (minX وminY وminZ).

  • تم حلّ المشكلة. في الوسط لا يوجد موقع لا يتحرك في معظم الطرق التي من المتوقع أن يتم فيها تغيير حجم حاوية مكانية (حواف متحركة). يُستخدم المركز عادةً في أجزاء أخرى من OpenXR. لم نستخدم النوافذ في الحوسبة الثنائية الأبعاد، والتي تستخدم الحد الأدنى من الإحداثيات، لأنّ برامج عرض النماذج الثلاثية الأبعاد لا تتبع هذه القاعدة في كثير من الأحيان.

• متى يُتوقّع أن تنشئ بيئة التشغيل موارد أساسية للحاوية المكانية؟ يتضمن ذلك أحيانًا الاتصال بين العمليات (IPC) مع خدمات النظام.

  • تم حلّ المشكلة. بشكل متزامن كجزء من xrCreateSpatialContainerEXT . على الرغم من احتمال وجود IPC، من المتوقع أن يكون إنشاء الحاوية الفعلي منخفض التكلفة بشكل عام. يستخدم بعض المورّدين الاستبعادات المتبادلة العامة لإدارة الحاويات، ولكن من غير المتوقّع أن يستغرق ذلك وقتًا طويلاً. إنّ المشاكل المتعلّقة بتزاحم الاستبعاد المتبادل هي أخطاء خاصة بالمورّدين ومن المتوقّع أن يعالجها كل مورّد.

• هل نحتاج إلى إشارة إلى أنّ XrSession سينشئ حاويات مكانية وبالتالي لن يتيح مسار العرض القديم؟

  • تم حلّ المشكلة. نعم. نغيّر جهاز حالة الجلسة بطريقة أساسية.

سجلّ الإصدارات

• المراجعة 1، ‏06-08-2026 (جاريد فايندر، Google)

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