ساختن با Spatial Containers

دستگاه‌های XR واجدشرایط
این راهنمایی به شما کمک می‌کند برای این نوع دستگاه‌های واقعیت گسترده تجربه بسازید.
آشنایی با انواع دستگاه‌های XR →
هدست‌های واقعیت گسترده
عینک واقعیت گسترده سیمی
آشنایی با انواع دستگاه‌های XR →

«محفظه‌های فضایی» پنجره‌بندی حجمی را به OpenXR می‌آورند. همان‌طور که توسط افزونه‌های XR_EXT_spatial_container و XR_EXT_spatial_container_self_rendering در OpenXR نسخه ۱.۱ تعریف شده است، محفظه فضایی یک منطقه حجمی سه‌بعدی مدیریت‌شده توسط سیستم در فضای کاربر است که در آن برنامه شما محتوای سه‌بعدی را بااستفاده از لایه‌های ترکیب‌بندی استاندارد OpenXR ارائه می‌دهد.

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

درباره «محتوی‌های فضایی»

محفظه فضایی یک منطقه سه‌بعدی محدود یا نامحدود است که توسط سیستم Android XR مدیریت می‌شود و توسط برنامه OpenXR شما رندر می‌شود:

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

نحوه تعامل کاربران با «محفظه‌های فضایی»

سیستم Android XR کنترل‌های پنجره محفظه فضایی و قرارگیری آن در فضای فیزیکی را مدیریت می‌کند و مدل تعامل ثابتی را در برنامه‌ها ارائه می‌دهد:

  • جابه‌جا کردن و تغییر موقعیت: کاربران می‌توانند بااستفاده از اشاره‌های دست (مانند نیشگون گرفتن) یا کنترل‌کننده‌های حرکتی، دسته سیستم محفظه فضایی را بگیرند و موقعیت آن را در فضای سه‌بعدی تغییر دهند.
  • کوچک کردن و بستن: کنترل‌های پنجره سیستم به کاربران اجازه می‌دهد تا محفظه‌های فضایی جداگانه را کوچک یا بسته کنند. وقتی کاربر محفظه‌ای را می‌بندد، سیستم به برنامه شما اطلاع می‌دهد تا بتواند منابع را پاک‌سازی کند.
  • قفل کردن به کف با درک صحنه: وقتی برنامه‌تان اجازه android.permission.SCENE_UNDERSTANDING_COARSE را اعلام و درخواست می‌کند، سیستم به‌طور خودکار چسباندن به سطح را فعال می‌کند تا کاربران بتوانند بدون پیکربندی اضافی برنامه، محفظه فضایی را روی کف فیزیکی قرار دهند و قفل کنند، همان‌طور که با محفظه نارنجی‌رنگ زمین در شکل ۱ نشان داده شده است.
  • تعامل سه‌بعدی مستقیم: وقتی محفظه متمرکز و تعاملی است، کاربران می‌توانند مستقیماً با محتوای سه‌بعدی داخل حجم بااستفاده از ردگیری دست، نگاه چشم، یا کنترل‌کننده‌های 6DoF تعامل داشته باشند.
کاربری که بااستفاده از ردیابی دست با اردک سه‌بعدی در داخل محفظه فضایی آبی‌رنگ محدودشده تعامل می‌کند.
شکل ۲. کاربری که بااستفاده از ردیابی دست با محتوای سه‌بعدی در داخل یک محفظه فضایی محدود تعامل دارد.
  • انتقال بین حالت‌های محدود و فراگیر: کاربر یا برنامه شما می‌تواند بدون راه‌اندازی مجدد جلسه OpenXR، محفظه را بین جعبه سه‌بعدی محدود و نمای فراگیر تمام‌صفحه نامحدود جابه‌جا کند.
صحنه سه‌بعدی اردک پس‌از انتقال از محفظه فضایی محدود به نمای فراگیر تمام‌صفحه نامحدود.
شکل ۳. محفظه فضایی پس‌از انتقال از حالت محدود به حالت فراگیر، میدان دید کاربر را پر می‌کند.
  • حالت «دنبال کردن» درحال حرکت: چون سیستم وضعیت فضای مختصات هر محفظه فضایی (xrCreateSpatialContainerSpaceEXT) را کنترل می‌کند، کاربران می‌توانند حالت «دنبال کردن» را از کنترل‌های پنجره سیستم فعال کنند تا محفظه سه‌بعدی محدودشده به‌طور خودکار آن‌ها را دنبال کند و درحالی‌که راه می‌روند در میدان دید آن‌ها باقی بماند—بدون نیاز به پیکربندی اضافی در برنامه شما.

نحوه استفاده کردن از «محفظه‌های فضایی» در Android XR

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

محتوای سه‌بعدی‌تان را با مرزهای محفظه تطبیق دهید

در حالت محدود، مبدأ (0, 0, 0) فضای محفظه فضایی (xrCreateSpatialContainerSpaceEXT) در مرکز چارگوش محدودکننده سه‌بعدی قرار دارد. ازآنجایی‌که سیستم حالت فضای محفظه را در محیط کاربر مدیریت می‌کند، برنامه شما محتوای سه‌بعدی خود را نسبت به (0, 0, 0) ارائه می‌دهد، درحالی‌که سیستم تغییر موقعیت کاربر و حالت دنبال کردن را مدیریت می‌کند. سیستم هر هندسه‌ای را که خارج از عرض، ارتفاع، یا عمق جعبه رندر شده باشد برش می‌دهد تا محتوا در حجم اختصاص‌داده‌شده به آن باقی بماند.

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

پاسخ دادن به تغییرات وضعیت محفظه

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

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

استفاده از شفافیت ترکیب آلفا در حالت محدود

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

بررسی دردسترس بودن ویژگی و پیکربندی مانیفست

«محفظه‌های فضایی» به دستگاه Android XR نیاز دارند که از سطح ای‌پی‌آی فضایی ۴ یا بالاتر پشتیبانی کند. به‌جای بررسی مستقیم سطح میانای برنامه‌سازی کاربردی 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++‎، با Spatial Containers بسازید. برای دیدن پیش‌نیازها، راه‌اندازی ویرایشگر، و نمونه کد برای محیط دلخواهتان، برگه‌ای را انتخاب کنید:

Unity

پیش‌نیازها

پیکربندی کردن پروژه

  1. به ویرایش > تنظیمات پروژه > مدیریت افزایه XR > OpenXR بروید.
  2. روی تنظیمات در کنار Android XR (افزونه‌ها): مدیریت جلسه کلیک کنید و Immersive XR را پاک کنید.
  3. در فهرست گروه‌های ویژگی OpenXR، 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);
}

برای اطلاع از مراحل کامل راه‌اندازی پروژه، پیکربندی مانیفست، و مدیریت اجازه، به استفاده از Spatial Containers در Unity مراجعه کنید.

Godot

پیش‌نیازها

پیکربندی کردن پروژه

  1. به Project (پروژه) > Project Settings (تنظیمات پروژه) بروید، Advanced Settings (تنظیمات پیشرفته) را فعال کنید، و به General (کلی) > XR > OpenXR > Extensions (افزونه‌ها) بروید.
  2. در بخش فرعی Spatial Container، گزینه Enabled را انتخاب کنید و Bounds Mode و Bounds را پیکربندی کنید.
  3. به پروژه > صادر کردن... بروید > Android بروید و استفاده از ویژگی‌های آزمایشی را در بخش ویژگی‌های Android XR انتخاب کنید.

از تک‌نمونه 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، استفاده از Spatial Containers در Godot را ببینید.

OpenXR

پیش‌نیازها

هنگام ایجاد XrInstance، XR_EXT_spatial_container و XR_EXT_spatial_container_self_rendering را فعال کنید، سپس محفظه فضایی‌تان را ایجاد و رندر کنید:

// 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. ‎ هستند و به‌عنوان علامت تجاری در چین، اتحادیه اروپا، ژاپن، و پادشاهی متحد (UK) ثبت شده‌اند.