إنشاء محتوى باستخدام الحاويات المكانية

أجهزة XR المشمولة
تساعدك هذه الإرشادات في إنشاء تجارب لهذه الأنواع من أجهزة XR.
مزيد من المعلومات حول أنواع أجهزة XR →
سماعات الرأس بنظام الواقع الممتد
نظارات سلكية بنظام الواقع الممتد
مزيد من المعلومات حول أنواع أجهزة XR →

تتيح ميزة "الحاويات المكانية" استخدام النوافذ الثلاثية الأبعاد في OpenXR. الحاوية المكانية هي منطقة حجمية ثلاثية الأبعاد يديرها النظام في مساحة المستخدم، حيث يعرض تطبيقك المحتوى الثلاثي الأبعاد باستخدام طبقات تركيب OpenXR العادية، ويتم تحديدها من خلال الإضافتَين XR_EXT_spatial_container وXR_EXT_spatial_container_self_rendering في الإصدار 1.1 من OpenXR.

في العادة، تطلب جلسة OpenXR الوصول الحصري إلى مجال الرؤية الكامل للمستخدم. تتيح "الحاويات المكانية" لتطبيقك عرض محتوى OpenXR ثلاثي الأبعاد داخل مربّع ثلاثي الأبعاد محدود في بيئة المستخدم، أو الانتقال إلى تجربة غامرة غير محدودة بملء الشاشة في أي وقت.

لمحة عن الحاويات المكانية

الحاوية المكانية هي منطقة ثلاثية الأبعاد محدودة أو غير محدودة يديرها نظام Android XR ويعرضها تطبيق OpenXR:

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

كيفية تفاعل المستخدمين مع "الحاويات المكانية"

يدير نظام Android XR عناصر التحكّم في نافذة الحاوية المكانية وموضعها في المساحة المادية، ما يوفّر نموذج تفاعل متّسقًا في جميع التطبيقات:

  • النقل وتغيير الموضع: يمكن للمستخدمين الإمساك بمقبض النظام الخاص بالحاوية المكانية باستخدام إيماءات اليد (مثل التصغير أو التكبير بإصبعين) أو وحدات التحكّم في الحركة لتغيير موضعها في المساحة الثلاثية الأبعاد.
  • التصغير والإغلاق: تتيح عناصر التحكّم في نافذة النظام للمستخدمين تصغير أو إغلاق الحاويات المكانية الفردية. عندما يغلق المستخدم حاوية، يرسل النظام إشعارًا إلى تطبيقك ليتمكّن من إزالة الموارد.
  • التثبيت على الأرضية باستخدام ميزة "فهم المشهد": عندما يطلب تطبيقك الحصول على إذن android.permission.SCENE_UNDERSTANDING_COARSE، يفعّل النظام تلقائيًا ميزة "محاذاة السطح" ليتمكّن المستخدمون من وضع حاوية مكانية وتثبيتها على الأرضية الفعلية بدون الحاجة إلى ضبط إعدادات إضافية في التطبيق، كما هو موضّح في حاوية التضاريس البرتقالية في الشكل 1.
  • التفاعل المباشر مع المحتوى الثلاثي الأبعاد: عندما يكون التركيز على حاوية معيّنة وتكون تفاعلية، يمكن للمستخدمين التفاعل مباشرةً مع المحتوى الثلاثي الأبعاد داخل المساحة باستخدام ميزة تتبُّع اليد أو نظرة العين أو وحدات التحكّم التي تتيح الحركة في 6 اتجاهات.
مستخدم يتفاعل مع بطة ثلاثية الأبعاد داخل حاوية مكانية زرقاء محدودة باستخدام ميزة تتبُّع اليد
الشكل 2. مستخدم يتفاعل مع محتوى ثلاثي الأبعاد داخل حاوية مكانية محدودة باستخدام ميزة تتبُّع اليد
  • التبديل بين الوضعَين المحدود والمجسّم: يمكن للمستخدم أو تطبيقك تبديل الحاوية بين مربّع ثلاثي الأبعاد محدود وعرض مجسّم غير محدود بملء الشاشة بدون إعادة تشغيل جلسة OpenXR.
مشهد البطة الثلاثي الأبعاد بعد الانتقال من حاوية مكانية محدودة إلى عرض غامر بملء الشاشة غير محدود
الشكل 3. الحاوية المكانية بعد الانتقال من الوضع المحدود إلى الوضع المجسم، ما يملأ مجال رؤية المستخدم
  • وضع التتبُّع أثناء التنقّل: بما أنّ النظام يتحكّم في وضعية كل مساحة إحداثيات للحاوية المكانية (xrCreateSpatialContainerSpaceEXT)، يمكن للمستخدمين تفعيل وضع التتبُّع من عناصر التحكّم في نافذة النظام، ما يتيح لحاوية ثلاثية الأبعاد محدودة تتبُّعهم تلقائيًا والبقاء في مجال رؤيتهم أثناء تنقّلهم، بدون الحاجة إلى أي إعدادات إضافية في تطبيقك.

كيفية استخدام "الحاويات المكانية" على Android XR

عند إنشاء تطبيق باستخدام "الحاويات المكانية"، صمِّم المشهد حول حدود الحاوية وتغييرات الحالة ووضع المزج في الخلفية.

تكييف المحتوى الثلاثي الأبعاد مع حدود الحاوية

في وضع "المساحة المحدودة"، تكون نقطة الأصل (0, 0, 0) لمساحة الحاوية المكانية (xrCreateSpatialContainerSpaceEXT) في مركز المربّع المحيط الثلاثي الأبعاد. بما أنّ النظام يدير وضعية مساحة الحاوية في بيئة المستخدم، يعرض تطبيقك المحتوى الثلاثي الأبعاد بالنسبة إلى (0, 0, 0) بينما يتعامل النظام مع إعادة تحديد موضع المستخدم ووضع المتابعة. يقتطع النظام أي شكل هندسي يتم عرضه خارج عرض الصندوق أو ارتفاعه أو عمقه ليبقى المحتوى ضمن الحجم المخصّص له.

يجب أن يستمع تطبيقك إلى أحداث تغيير الحدود من وقت التشغيل وتغيير حجم المشهد الثلاثي الأبعاد أو تغيير موضعه ليتناسب المحتوى الرئيسي مع الأبعاد الحالية للحاوية. عندما تنتقل الحاوية إلى الوضع المجسم، تصبح الحدود لا نهائية ويمكنك استعادة المشهد إلى مقياسه العالمي الكامل بنسبة 1:1.

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

بدلاً من إدارة مستوى الظهور والتركيز على مستوى التطبيق فقط، يبلّغ كل حاوية مكانية عن حالتها الخاصة حتى يتمكّن تطبيقك من الاستجابة وفقًا لذلك:

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

استخدام الشفافية الممزوجة بألفا في الوضع المحدود

في "الوضع المحدود"، تتيح الخلفية الشفافة للمستخدم رؤية محيطه المادي والنوافذ الأخرى حول النماذج الثلاثية الأبعاد. اضبط الكاميرا أو إطار العرض على خلفية شفافة واستخدِم وضع المزج "alpha-blend" للبيئة. عند التبديل إلى الوضع المجسم، يمكنك إبقاء ميزة "الرؤية من خلال النظارة" مفعَّلة أو التبديل إلى بيئة "صندوق السماء" غير الشفافة.

التحقّق من توفّر الميزة وضبط ملف البيان

تتطلّب الحاويات المكانية جهاز Android XR يتوافق مع المستوى 4 من واجهة برمجة التطبيقات المكانية أو الإصدارات الأحدث. بدلاً من التحقّق من مستوى واجهة برمجة تطبيقات Android مباشرةً، يمكنك الاستعلام من بيئة تشغيل OpenXR لتحديد ما إذا كانت "الحاويات المكانية" متاحة من خلال طلب xrEnumerateInstanceExtensionProperties للتأكّد من أنّ XR_EXT_spatial_container وXR_EXT_spatial_container_self_rendering متاحان، وطلب xrGetSystemProperties باستخدام XrSystemSpatialContainerPropertiesEXT لفحص supportsBounded وsupportsImmersive.

قبل إنشاء تطبيق يستخدم "الحاويات المكانية"، عليك ضبط وضع بدء النشاط وأي أذونات خاصة بالميزات في AndroidManifest.xml.

تفعيل وضع "مساحات كاملة" في AndroidManifest.xml

تتطلّب "الحاويات المكانية" وضع "المساحة الكاملة المُدارة"، حتى بالنسبة إلى تطبيقات OpenXR المستقلة. تُعلن تطبيقات OpenXR التقليدية التي تعمل بملء الشاشة عن XR_ACTIVITY_START_MODE_FULL_SPACE_UNMANAGED للتحكّم الحصري في الشاشة بدون إدارة نوافذ النظام. في المقابل، يعتمد التطبيق الذي يستخدم "الحاويات المكانية" على أداة تركيب نظام Android XR لإدارة الأحجام المحدودة الثلاثية الأبعاد وعناصر التحكّم في النوافذ والموضع المكاني في "وضع المساحة الكاملة"، ويجب ضبط android.window.PROPERTY_XR_ACTIVITY_START_MODE على XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application ...>
        <!-- Spatial Containers require Full Space Managed mode -->
        <property
            android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
            android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED" />

        <activity android:name=".MainActivity" ...>
            <!-- Optional hint declaring which bounds modes the activity uses -->
            <property
                android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
                android:value="XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT|XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT" />
        </activity>
    </application>
</manifest>

الإفصاح عن الأذونات الخاصة بالميزات وطلبها

لا يتطلّب إنشاء حاوية مكانية أساسية وعرضها أذونات تشغيل خطيرة. ومع ذلك، تتطلّب ميزات معيّنة الإفصاح عن أذونات Android XR المقابلة وطلبها:

  • لقفل حاوية مكانية وتثبيتها على الأرضية الفعلية باستخدام ميزة "فهم المشهد"، يجب الإعلان عن إذن android.permission.SCENE_UNDERSTANDING_COARSE الخطير وطلبه أثناء التشغيل.
  • لتتبُّع وضعية رأس المستخدم في OpenXR، يجب الإعلان عن android.permission.HEAD_TRACKING وطلبها.
<uses-permission android:name="android.permission.HEAD_TRACKING" />
<uses-permission android:name="android.permission.SCENE_UNDERSTANDING_COARSE" />

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

تفعيل ميزة "الحاويات المكانية" في مشروعك

يمكنك إنشاء تطبيقات باستخدام Spatial Containers من خلال Unity أو Godot أو مباشرةً باستخدام OpenXR في C++‎. اختَر علامة تبويب للاطّلاع على المتطلبات الأساسية وإعدادات المحرِّر ومثال الرمز البرمجي لبيئتك المفضّلة:

Unity

المتطلّبات الأساسية

ضبط مشروعك

  1. انتقِل إلى Edit (تعديل) > Project Settings (إعدادات المشروع) > XR Plug-in Management (إدارة المكوّنات الإضافية للواقع الممتد) > OpenXR.
  2. انقر على الإعدادات بجانب Android XR (الإضافات): إدارة الجلسات (Android XR (Extensions): Session Management) وأزِل العلامة من المربّع بجانب الواقع الممتد الغامر (Immersive XR).
  3. في قائمة مجموعات ميزات OpenXR (OpenXR Feature Groups)، فعِّل الحاوية المكانية (Spatial Container).

استخدِم XRSpatialContainerFeature في C# ‎ لطلب الحدود والاستجابة لأحداث الحاوية والتبديل بين الوضعَين المحدود والمجسّم:

void OnEnable()
{
    XRSpatialContainerFeature.OnSpatialContainerBoundsChanged += OnBoundsChanged;
}

private void OnBoundsChanged(Vector3 bounds, bool infiniteBounds)
{
    float minScale = Mathf.Min(bounds.x, bounds.y, bounds.z);
    transform.localScale = infiniteBounds ? Vector3.one : Vector3.one * minScale;
}

public void SetImmersiveMode(bool immersive)
{
    XRSpatialContainerFeature.TryRequestBoundsMode(immersive);
}

للاطّلاع على الخطوات الكاملة لإعداد المشروع وضبط ملف البيان ومعالجة الأذونات، يُرجى الاطّلاع على مقالة استخدام الحاويات المكانية في Unity.

Godot

المتطلّبات الأساسية

ضبط مشروعك

  1. انتقِل إلى Project (المشروع) > Project Settings (إعدادات المشروع)، وفعِّل Advanced Settings (الإعدادات المتقدّمة)، ثم انتقِل إلى General (الإعدادات العامة) > XR > OpenXR > Extensions (الإضافات).
  2. ضمن الفقرة الفرعية الحاوية المكانية، اختَر مفعَّلة واضبط وضع الحدود والحدود.
  3. انتقِل إلى Project (المشروع) > Export... (تصدير...) > Android واختَر Use Experimental Features ضمن Android XR Features.

استخدِم العنصر الفردي OpenXRSpatialContainerExtension في GDScript للاستجابة لحدود الحاوية وتغييرات الوضع:

func _ready() -> void:
    if OpenXRSpatialContainerExtension.is_enabled():
        OpenXRSpatialContainerExtension.spatial_container_bounds_changed.connect(
            _on_bounds_changed
        )

func _on_bounds_changed(_rid: RID, bounds: Vector3) -> void:
    scale = Vector3.ONE * min(bounds.x, bounds.y, bounds.z)

func set_immersive_mode() -> void:
    OpenXRSpatialContainerExtension.request_main_spatial_container_bounds_mode(
        OpenXRSpatialContainerState.IMMERSIVE
    )

للاطّلاع على إعدادات المشروع الكاملة وأذونات التصدير وأمثلة على GDScript، يُرجى مراجعة مقالة استخدام الحاويات المكانية في Godot.

OpenXR

المتطلّبات الأساسية

فعِّل XR_EXT_spatial_container وXR_EXT_spatial_container_self_rendering عند إنشاء XrInstance، ثم أنشئ الحاوية المكانية وعالِجها:

// 1. Enable the Spatial Container extensions during xrCreateInstance
const char* enabledExtensions[] = {
    XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME,
    XR_EXT_SPATIAL_CONTAINER_SELF_RENDERING_EXTENSION_NAME,
};

// 2. Configure and create a self-rendering spatial container
XrSpatialContainerConfigurationSelfRenderingEXT selfRenderingConfig{
    .type = XR_TYPE_SPATIAL_CONTAINER_CONFIGURATION_SELF_RENDERING_EXT,
    .next = nullptr,
    .viewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO,
    .suggestedBounds = {1.5f, 1.5f, 1.5f}, // Width, height, depth in meters
};

XrSpatialContainerCreateInfoEXT createInfo{
    .type = XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT,
    .next = &selfRenderingConfig,
    .spatialContainerConfig =
        reinterpret_cast<const XrSpatialContainerConfigurationBaseHeaderEXT*>(
            &selfRenderingConfig),
};

XrSpatialContainerEXT spatialContainer = XR_NULL_HANDLE;
xrCreateSpatialContainerEXT(session, &createInfo, &spatialContainer);

// 3. Request bounded mode and make the container visible
xrRequestSpatialContainerBoundsModeEXT(
    spatialContainer, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT);
xrRequestSpatialContainerVisibilityEXT(spatialContainer, XR_TRUE);

انظر أيضًا

‫OpenXR™‎ وشعار OpenXR هما علامتان تجاريتان تملكهما شركة The Khronos Group Inc. ‎ ومسجَّلتان كعلامة تجارية في الصين والاتحاد الأوروبي واليابان والمملكة المتحدة.