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

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

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

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

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

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

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

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

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

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

• ‫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 עבור תיבות השמיים. לפרטים נוספים, אפשר לעיין במדריך שלנו לאופטימיזציה של נכסי סביבה.

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

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

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

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

אם הערך של SpatialEnvironmentPreference שצוין הוא לא null, אבל כל המאפיינים שלו הם null, אז הסביבה המרחבית תכלול 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 לסביבה המרחבית של האפליקציה

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

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

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

שימוש מתקדם

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

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

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

קביעת השקיפות הנוכחית של ההעברה

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

למידע נוסף

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