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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

یک منبع glTF ایجاد کنید

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

// assume that session is a Session that has been previously created
val environmentGeometryFuture = session.createGltfResourceAsync("DayGeometry.glb")

val environmentGeometry = environmentGeometryFuture.await()

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

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

// assume that session is a Session that has been previously created
val skyboxExrFuture = session.createExrImageResourceAsync("BlueSkybox.exr")

val skyboxExr = skyboxExrFuture.await()

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

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

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

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

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

استفاده اساسی

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

// Assume that session is a Session that has been previously created

// Create a GLTFResource
val environmentGeometry = session.createGltfResourceAsync("DayGeometry.glb").await()

// Create an ExrImage for the skybox
val skyboxExr = session.createExrImageResourceAsync("BlueSkybox.exr").await()

val spatialEnvironmentPreference = SpatialEnvironmentPreference(skyboxExr, environmentGeometry)

val preferenceResult = session.spatialEnvironment.setSpatialEnvironmentPreference(spatialEnvironmentPreference)

if (preferenceResult ==  SpatialEnvironment.SetSpatialEnvironmentPreferenceChangeApplied()) {
   // The environment was successfully updated and is now visible, and any listeners
   // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangePending()) {
    // The environment is in the process of being updated. Once visible, any listeners
   // specified using addOnSpatialEnvironmentChangedListener will be notified.
}

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

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

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

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

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

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

استفاده اساسی

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

// Assume that session is a Session that has been previously created

val preferenceResult = session.spatialEnvironment.setPassthroughOpacityPreference(1.0f)

if (preferenceResult ==  SpatialEnvironment.SetPassthroughOpacityPreferenceChangeApplied()) {
  // The passthrough opacity request succeeded and should be visible now, and any listeners specified using addOnPassthroughOpacityChangedListener
  // will be notified
} else if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangePending()) {
  // 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
}

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

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

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

هنگام ایجاد دارایی برای تنظیم SpatialEnvironment کاربران خود، باید اطمینان حاصل کنید که دارایی های شما به وضوح با کیفیت بالا و در عین حال حفظ اندازه فایل معقول می رسد. باید مطمئن شوید که glb شما از mipmaps و بافت‌های ktx2 استفاده می‌کند. همچنین می‌خواهید نسبت به چند شمارش در فایل‌های glb خود حساس باشید، زیرا چند شمارش بالا می‌تواند منجر به مصرف انرژی غیرضروری شود. اکثر حجم فایل برای اکثر نمونه های SpatialEnvironment از تصویر استفاده شده برای Skybox می آید. برای اطمینان از بهینه‌سازی تصاویر، دارایی‌ها را از طریق یک ابزار بهینه‌سازی (مثلا ktx ) اجرا کنید.

کدورت عبور فعلی را تعیین کنید

val currentPassthroughOpacity =  session.spatialEnvironment.getCurrentPassthroughOpacity()

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

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