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

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

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

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

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

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

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

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

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

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

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

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

  • ‫SpatialCapability.PASSTHROUGH_CONTROL: מציין אם הפעילות יכולה להפעיל או להשבית את המעבר בזמן הנוכחי.

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

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

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

יצירת משאב glTF

אפשר ליצור משאב glTF בתור GltfModel, שבו ה-glTF נטען מקובץ מקומי. אפשר להשתמש ב-GltfModel כחלק מסביבת אפליקציה מרחבית.

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

יצירת משאב תאורה מבוססת-תמונה

אפשר ליצור משאב תאורה מבוסס-תמונה בתור ImageBasedLightingAsset, שבו התאורה נטענת מקובץ מקומי. אפשר להשתמש ב-ImageBasedLightingAsset עם cmgen כדי ליצור קובץ ZIP של ה-IBL לתיבות השמיים. פרטים נוספים זמינים במדריך שלנו לאופטימיזציה של נכסי סביבה.

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

הגדרת SpatialEnvironmentPreference לאפליקציה

המאפיין preferredSpatialEnvironment קובע את הסביבה המרחבית המועדפת לאפליקציה. כשמשתמשים במאפיין הזה כדי להגדיר העדפה, הוא לא גורם לשינוי מיידי, אלא אם isPreferredSpatialEnvironmentActive כבר מוגדר כ-true. כשהמכשיר נכנס למצב שבו אפשר לשנות את הרקע של ה-XR והיכולת SpatialCapability.APP_ENVIRONMENT זמינה, הסביבה המרחבית המועדפת לאפליקציה תוצג באופן אוטומטי.

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

אם הערך של SpatialEnvironmentPreference הוא לא null, אבל כל המאפיינים שלו הם null, הסביבה המרחבית תכלול תיבת שמיים שחורה בלי גיאומטריה.

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

שימוש מתקדם

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

הגדרת PassthroughOpacityPreference לסביבה המרחבית של האפליקציה

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

הפונקציה setPassthroughOpacityPreference משמשת להגדרת רמת האטימות המועדפת של ה-passthrough באפליקציה. השיטה הזו רק מגדירה העדפה ולא גורמת לשינוי מיידי, אלא אם היכולת SpatialCapability.PASSTHROUGH_CONTROL זמינה. כשהמכשיר נכנס למצב שבו אפשר לשנות את אטימות המעבר, והיכולת SpatialCapability.PASSTHROUGH_CONTROL זמינה, אטימות המעבר המועדפת לאפליקציה תופעל באופן אוטומטי.

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

שימוש מתקדם

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

אופטימיזציה של נכסים

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

בדיקת האטימות הנוכחית של המעבר

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

עוד באותו הקשר