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

מכשירי XR שמתאימים לשימוש

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

מידע על סוגי מכשירי XR →

מידע על סוגי מכשירי XR →

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

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

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

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

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

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

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

• שילוב של תמונת skybox וגיאומטריית glTF.
• משטח passthrough, שבו הסביבה שמוצגת היא פיד חי מהמצלמות של המכשיר שפונות כלפי חוץ. במצב אטימות מלאה, פני השטח של המעבר מסתירים לחלוטין את תיבת השמיים ואת הגיאומטריה.
• הגדרה מעורבת, שבה השטח של ההעברה לא אטום לחלוטין ולא שקוף לחלוטין. במקרה הזה, המשטח השקוף למחצה הופך לשקוף למחצה, והוא מתמזג עם ה-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

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

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

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

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

המאפיין preferredSpatialEnvironment קובע את סביבת המרחב המועדפת לאפליקציה. כשמשתמשים במאפיין הזה כדי להגדיר העדפה, הוא לא גורם לשינוי מיידי אלא אם isPreferredSpatialEnvironmentActive כבר מוגדר כ-true. ברגע שהמכשיר נכנס למצב שבו אפשר לשנות את הרקע של ה-XR והיכולת SpatialCapabilities.SPATIAL_CAPABILITY_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.
}
Environments.kt

שימוש מתקדם

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

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

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

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

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

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

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