افزودن محیط‌های فضایی به برنامه

دستگاه‌های XR قابل‌اعمال

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

آشنایی با انواع دستگاه‌های XR →

آشنایی با انواع دستگاه‌های XR →

در Jetpack XR SDK، محیط‌های فضایی محیط‌های فراگیری هستند که می‌توانید به برنامه‌تان اضافه کنید تا پس‌زمینه صحنه مجازی را سفارشی‌سازی کنید. محیط‌های فضایی فقط زمانی قابل‌مشاهده‌اند که برنامه در «فضای کامل» باشد.

نمای کلی محیط‌های فضایی

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

جعبه آسمان نشان‌دهنده تصویری است که کاربر در صحنه مجازی اطراف خود می‌بیند و توهم محیط پس‌زمینه دوردست، مانند آسمان، کوهستان، یا شهر را ایجاد می‌کند. کاربر نمی‌تواند با جعبه آسمان تعامل داشته باشد یا به آن نزدیک شود. «کیت توسعه نرم‌افزار Jetpack XR» از آسمان‌نمای کروی در استاندارد OpenEXR پشتیبانی می‌کند. علاوه‌بر ارائه پس‌زمینه‌ای فراگیر برای برنامه شما، آسمان‌نمای EXR همچنین نورپردازی مبتنی بر تصویر (IBL) را برای مدل‌های سه‌بعدی بارگذاری‌شده توسط برنامه شما ارائه می‌دهد. برای اطلاعات بیشتر، به راهنمای کار با مدل‌های سه‌بعدی مراجعه کنید.

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

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

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

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

قابلیت‌های فضایی برای محیط‌های فضایی

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

• SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL: نشان می‌دهد که آیا فعالیت می‌تواند در زمان فعلی عبور را فعال یا غیرفعال کند یا نه.

• SPATIAL_CAPABILITY_APP_ENVIRONMENT: نشان می‌دهد که آیا فعالیت می‌تواند در زمان فعلی محیط فضایی خود را تنظیم کند یا نه.

وارد کردن و بار کردن منابع محیط فضایی

منابع glTF و EXR برای محیط‌های فضایی به‌صورت ناهمزمان بااستفاده از کلاس Session بارگیری می‌شوند.

ایجاد منبع glTF

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

val environmentGeometry = GltfModel.create(session, Paths.get("DayGeometry.glb"))
Environments.kt

ایجاد منبع نورپردازی مبتنی بر تصویر

منبع نورپردازی مبتنی بر تصویر می‌تواند به‌صورت ImageBasedLightingAsset ایجاد شود، که در آن نورپردازی از یک فایل محلی بار می‌شود. از ImageBasedLightingAsset می‌توان با cmgen برای ایجاد فایل ZIP از ‫IBL برای آسمان‌نمای شما استفاده کرد. برای جزئیات بیشتر، راهنمای ما درباره بهینه‌سازی دارایی‌های محیط را ببینید.

val lightingForSkybox = ImageBasedLightingAsset.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))
Environments.kt

‫SpatialEnvironmentPreference را برای برنامه‌تان تنظیم کنید

دارایی preferredSpatialEnvironment محیط فضایی ترجیحی را برای برنامه کنترل می‌کند. وقتی از این دارایی برای تنظیم ترجیح استفاده می‌شود، تا زمانی که isPreferredSpatialEnvironmentActive ازقبل true نباشد، باعث تغییر فوری نمی‌شود. وقتی دستگاه به حالتی می‌رود که پس‌زمینه واقعیت گسترده می‌تواند تغییر کند و قابلیت SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT دردسترس باشد، محیط فضایی ترجیحی برای برنامه به‌طور خودکار نمایش داده می‌شود.

تنظیم اولویت روی null باعث غیرفعال شدن محیط فضایی ترجیحی برای برنامه می‌شود، یعنی به‌جای آن محیط سیستم پیش‌فرض نمایش داده خواهد شد.

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

برای دریافت اعلان تغییرات وضعیت SpatialEnvironment، از addOnSpatialEnvironmentChangedListener استفاده کنید.

استفاده پایه

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

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
session.scene.spatialEnvironment.preferredSpatialEnvironment = spatialEnvironmentPreference
if (session.scene.spatialEnvironment.isPreferredSpatialEnvironmentActive) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the SPATIAL_CAPABILITY_APP_ENVIRONMENT capability.
    // Then, any listeners specified using addOnSpatialEnvironmentChangedListener
    // will be notified.
}
Environments.kt

استفاده پیشرفته

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

‫PassthroughOpacityPreference را برای محیط فضایی برنامه‌تان تنظیم کنید

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

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

مقادیر اولویت شفافیت انتقال از 0.0f (شفافیت صفر، جایی که سطح انتقال قابل‌مشاهده نیست) تا 1.0f (شفافیت کامل، جایی که سطح انتقال محیط فضایی را پنهان می‌کند) متغیر است. پارامتر setPassthroughOpacityPreference یک شناور تهی‌پذیر است. تنظیم مقدار روی null نشان می‌دهد که برنامه اولویت کدورت گذرگاه ندارد و کنترل گذرگاه را به سیستم برمی‌گرداند.

استفاده پایه

این تکه‌کد اولویت شفافیت عبور را تنظیم می‌کند. این اولویت به‌خاطر سپرده می‌شود و وقتی برنامه قابلیت تنظیم کدورت عبور را داشته باشد اعمال خواهد شد.

session.scene.spatialEnvironment.preferredPassthroughOpacity = 1.0f
if (session.scene.spatialEnvironment.currentPassthroughOpacity == 1.0f) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the
    // SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL capability.
    // Then, any listeners specified using addOnPassthroughOpacityChangedListener
    // will be notified.
}
Environments.kt

استفاده پیشرفته

برای موارد استفاده پیشرفته‌تر که در آن‌ها به کنترل دقیق‌تری روی کدبند شفافیت نیاز دارید، می‌توانید بررسی‌های SpatialCapabilities را ادغام کنید و بااستفاده از addOnPassthroughOpacityChangedListener شنونده‌ای اضافه کنید تا تعیین کنید چه زمانی می‌خواهید اولویت شفافیت کدبند را تنظیم کنید.

بهینه‌سازی دارایی

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

تعیین ماتی عبوردهی فعلی

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity
Environments.kt

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

• راهنمایی طراحی محیط‌های فضایی