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

دستگاه‌های XR واجدشرایط

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• SpatialCapability.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 باشد. وقتی دستگاه وارد وضعیتی شود که پس‌زمینه واقعیت گسترده قابل‌تغییر باشد و قابلیت SpatialCapability.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

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

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

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

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

setPassthroughOpacityPreference برای تنظیم کردن شفافیت ترجیحی حالت شفاف برای برنامه استفاده می‌شود. این روش فقط اولویت را تنظیم می‌کند و تغییر فوری ایجاد نمی‌کند، مگراینکه قابلیت SpatialCapability.PASSTHROUGH_CONTROL دردسترس باشد. وقتی دستگاه وارد وضعیتی شود که در آن بتوان شفافیت عبور را تغییر داد و قابلیت SpatialCapability.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

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

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

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

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

تعیین کردن ماتی فعلی حالت شفاف

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

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

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