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

دستگاه‌های XR قابل اجرا

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

درباره انواع دستگاه‌های XR اطلاعات کسب کنید →

درباره انواع دستگاه‌های XR اطلاعات کسب کنید →

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

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

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

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

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

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

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

• ترکیبی از تصویر skybox و هندسه 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

ایجاد یک منبع تصویر EXR

یک منبع تصویر EXR می‌تواند به عنوان یک ExrImage ایجاد شود، که در آن EXR از یک فایل محلی بارگذاری می‌شود. یک ExrImage می‌تواند با cmgen برای ایجاد یک فایل ZIP از IBL برای skybox های شما استفاده شود. برای جزئیات بیشتر به راهنمای ما در مورد بهینه‌سازی دارایی‌های محیطی مراجعه کنید.

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

SpatialEnvironmentPreference را برای برنامه خود تنظیم کنید

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

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

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

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

کاربرد اولیه

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

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 یک عدد اعشاری با قابلیت تهی شدن است. تنظیم مقدار روی تهی نشان می‌دهد که برنامه هیچ ترجیح شفافیت گذرگاهی ندارد و کنترل گذرگاه را به سیستم بازمی‌گرداند.

کاربرد اولیه

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

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 کاربران خود، اطمینان حاصل کنید که فایل‌های شما با حفظ اندازه فایل معقول، وضوح بالایی را ارائه می‌دهند. برای کسب اطلاعات بیشتر، به راهنمای ما در مورد بهینه‌سازی فایل‌های Environment مراجعه کنید.

میزان کدورت فعلی گذرگاه را تعیین کنید

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

همچنین ببینید

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