ساختن با 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 بسازید. برای دیدن پیش‌نیازها، راه‌اندازی ویرایشگر، و نمونه کد برای محیط دلخواهتان، برگه‌ای را انتخاب کنید:

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);
}

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
    )

// 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);

همچنین مراجعه کنید به

• استفاده از Spatial Containers در Unity
• استفاده از Spatial Containers در Godot
• آشنایی با اجازه‌های XR

‫OpenXR™‎ و نشان‌واره OpenXR علامت‌های تجاری متعلق به The Khronos Group Inc. ‎ هستند و به‌عنوان علامت تجاری در چین، اتحادیه اروپا، ژاپن، و پادشاهی متحد (UK) ثبت شده‌اند.