הוספת סביבות מרחביות לאפליקציה

ב-Jetpack XR SDK, סביבות מרחביות הן סביבות סוחפות שאפשר להוסיף לאפליקציה כדי להתאים אישית את הרקע של הסצנה הווירטואלית. סביבות מרחביות גלויות רק כשאפליקציה נמצאת במצב מלא.

סקירה כללית על סביבות מרחבי

SpatialEnvironment משמש לניהול ההעדפות של האפליקציה לגבי הסביבה המרחבית. הוא מורכב מתמונה עצמאית של סביבה ותלת-ממד של glTF. אפשר להגדיר רק תמונה אחת של סביבה ותבנית גיאומטריה אחת של glTF בכל פעם.

קופסת שמיים מייצגת את התמונה שהמשתמש רואה מסביבו בסצנה הווירטואלית, ויוצרת את האשליה של סביבה רחוקה ברקע, כמו שמיים, הרים או נופים עירוניים. המשתמש לא יכול ליצור אינטראקציה עם תיבת השמיים או להתקרב אליה. ‏Jetpack XR SDK תומך ב-skyboxes ספריים בתקן OpenEXR. בנוסף ליצירת רקע immersive לאפליקציה, קובץ skybox בפורמט EXR מספק גם תאורה מבוססת-תמונה (IBL) למודלים תלת-ממדיים שנטענים באפליקציה. למידע נוסף, אפשר לעיין במדריך לעבודה עם מודלים תלת-ממדיים.

סביבות מרחביות יכולות לכלול גם תוכן של גיאומטריה תלת-ממדית בתקן glTF. גיאומטריה של סביבה שנטענת באופן הזה תתאים אוטומטית לקומה בעולם האמיתי. גיאומטריה של סביבה היא דרך מצוינת להוסיף ריאליזם לסביבה באמצעות אלמנטים של חזית ושל חזית אמצעית שמשתלבים בקופסה של השמיים באמצעות אפקט הפרלקס.

בהנחיות לעיצוב של סביבות מרחביות תוכלו לקרוא על הסוגים השונים של נכסים שאפשר להשתמש בהם כדי ליצור סביבות מרחביות, ועל הדרכים ליצור סביבות מרחביות בטוחות ומהנות.

אתם יכולים להגדיר את הסביבה המרחבית של האפליקציה לאחת משלוש ההגדרות הבאות:

• שילוב של תמונה של תיבת שמיים וגיאומטריה של glTF.
• משטח העברה, שבו הסביבה שמוצגת היא פיד בשידור חי מהמצלמות החיצוניות של המכשיר. כשהעובי של פני השטח של העברת ההמשך מלא, הוא מסתיר לחלוטין את תיבת השמיים ואת הגיאומטריה.
• הגדרה משולבת, שבה פני השטח של העברת הערך לא שקופפים לגמרי, אבל גם לא אטומים. במקרה כזה, המשטח של העברת ההעברה הופך למחצית שקוף והאלפא מתמזג עם תיבת השמיים והגיאומטריה שמאחוריו.

יכולות מרחביות לסביבות מרחביות

• SpatialCapabilities: מייצג את היכולות המרחביות של הסשן הנוכחי. יכולות מרחביות מסוימות רלוונטיות לסביבות מרחביות.

• SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL: מציין אם הפעילות יכולה להפעיל או להשבית את העברת הנתונים (passthrough) בשלב הזה.

• SPATIAL_CAPABILITY_APP_ENVIRONMENT: מציין אם הפעילות יכולה להגדיר סביבה מרחבית משלה בזמן הנוכחי או לא.

ייבוא וטעינה של משאבים של סביבה מרחבית

משאבי glTF ו-EXR לסביבות מרחביות נטענים באופן אסינכרוני בכיתה Session. הקבצים האלה חייבים להיות שמורים בתיקיית הנכסים.

יצירת משאב 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 לא null, אבל כל המאפיינים שלו הם null, הסביבה המרחבית תכלול רק קוביית שמיים שחורה ללא גיאומטריה.

כדי לקבל התראות על שינויים במצב של 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 לסביבה המרחבית של האפליקציה

אחד מהרכיבים של הרקע הווירטואלי העשיר של האפליקציה הוא משטח העברה (passthrough). במקרה כזה, הרקע שמוצג הוא פיד בשידור חי מהמצלמות של המכשיר שמכוונות החוצה.

setPassthroughOpacityPreference משמש להגדרת השקיפות המועדפת של העברת הנתונים באפליקציה. השיטה הזו מגדירה רק העדפה ולא גורמת לשינוי מיידי, אלא אם היכולת SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL זמינה. כשהמכשיר נכנס למצב שבו אפשר לשנות את השקיפות של העברת הנתונים, והיכולת SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL זמינה, השקיפות המועדפת של העברת הנתונים באפליקציה תחול באופן אוטומטי.

הערכים של העדפת השקיפות של העברה עוברים מ-0.0f (אפס שקיפות, כאשר משטח העברה לא גלוי) ל-1.0f (שקיפות מלאה, כאשר משטח העברה מסתיר את הסביבה המרחבית). הפרמטר setPassthroughOpacityPreference הוא מספר ממשי שאפשר להגדיר לו ערך null. הגדרת הערך ל-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()

למידע נוסף

• הנחיות לעיצוב סביבות מרחביות