{ } { }

Jetpack SceneCore

יצירה של תרשים סצנה ב-Android XR ושינוי שלו באמצעות תוכן תלת-ממדי.
העדכון האחרון גרסה יציבה גרסה מועמדת להפצה גרסת בטא גרסת אלפא
12 בפברואר 2025 - - - 1.0.0-alpha02

הצהרת יחסי תלות

כדי להוסיף תלות ב-XR SceneCore, צריך להוסיף את מאגר Google Maven לפרויקט. מידע נוסף זמין במאגר Maven של Google.

מוסיפים את יחסי התלות של הארטיפקטים הנדרשים בקובץ build.gradle של האפליקציה או המודול:

מגניב

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha01"
    // Required for Java
    implementation "com.google.guava:listenableFuture:1.0"
    // Required for Kotlin
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0"

    // Use to write unit tests
    testImplementation "androidx.xr.scenecore:scenecore-testing:1.0.0-alpha01"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha01")
    // Required for Java
    implementation("com.google.guava:listenableFuture:1.0")
    // Required for Kotlin
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0")

    // Use to write unit tests
    testImplementation("androidx.xr.scenecore:scenecore-testing:1.0.0-alpha01")
}

מידע נוסף על יחסי תלות זמין במאמר הוספת יחסי תלות ל-build.

משוב

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

דיווח על בעיה חדשה

מידע נוסף זמין במסמכי התיעוד של Issue Tracker.

גירסה 1.0

גרסה 1.0.0-alpha02

12 בפברואר 2025

androidx.xr.scenecore:scenecore:1.0.0-alpha02 ו-androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02 משוחררים. הגרסה 1.0.0-alpha02 כוללת את ההוספות האלה.

שינוי קריטי שיחול בקרוב וישפיע על אפליקציות שנוצרו לפני 1.0.0-alpha02

  • שיטות המפעל הועברו מהקלאס Session לשיטת לוויה בכל סוג:
    • השדה Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) נמחק והוחלף בשדה ActivityPanelEntity.create(Session, Dimensions, String, Pose)
    • השדה Session.createAnchorEntity(Anchor) נמחק והוחלף בשדה AnchorEntity.create(Session, Anchor)
    • השדה Session.createAnchorEntity(Dimensions, Int, Int, Duration) נמחק והוחלף בשדה AnchorEntity.create(Session, Dimensions, Int, Int, Duration)
    • השדה Session.createEntity(String, Pose) נמחק והוחלף בשדה ContentlessEntity.create(Session, String, Pose)
    • השדה Session.createExrImageResource(String) נמחק והוחלף בשדה ExrImage.create(Session, String)
    • השדה Session.createGltfEntity(GltfModel, Pose) נמחק והוחלף בשדה GltfModelEntity.create(Session, GltfModel, Pose)
    • השדה Session.createGltfModelResource(String) נמחק והוחלף בשדה GltfModel.create(Session, String)
    • השדה Session.createInteractableComponent(Executor, InputEventListener) נמחק והוחלף בשדה InteractableComponent.create(Session, Executor, InputEventListener)
    • השדה Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) נמחק והוחלף בשדה MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
    • השדה Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) נמחק והוחלף בשדה PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose)
    • השדה Session.createResizableComponent(Dimensions, Dimensions) נמחק והוחלף בשדה ResizableComponent.create(Session, Dimensions, Dimensions)
    • השדה Session.createStereoSurfaceEntity(Int, Dimensions, Pose) נמחק והוחלף בשדה StereoSurface.create(Session, Int, Dimensions, Pose)
  • השיטות הבאות שהוצאו משימוש הוסרו:
    • Session.canEmbedActivityPanel(Activity) נמחק. במקום זאת, אתם צריכים להשתמש ב-getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY).
    • Session.hasSpatialCapability(Int) נמחק. הוא הוחלף ב-getSpatialCapabilities().hasCapability() כדרך מחולקת יותר לבדוק את נוכחות היכולות המרחביות, כי הפונקציה getSpatialCapabilities() מחזירה אובייקט SpatialCapabilities.
    • השדה Session.requestFullSpaceMode() נמחק והוחלף בשדה SpatialEnvironment.requestFullSpaceMode()
    • השדה Session.requestHomeSpaceMode() נמחק והוחלף בשדה SpatialEnvironment.requestHomeSpaceMode()
  • הפונקציות Session.setFullSpaceMode(Bundle) ו-Session.setFullSpaceModeWithEnvironmentInherited(Bundle) הועברו לפונקציות תוסף. בקבצים של המפתחים צריך להוסיף את האפשרויות החדשות לייבוא כדי לקבל גישה:
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float) הועבר לפונקציית תוסף. בקבצים של המפתחים צריך להוסיף את הייבוא החדש כדי לקבל גישה:
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • הפונקציות Session.getEntitiesOfType(Class<out T>) ו-Session.getEntityForRtEntity(RtEntity) הועברו לפונקציות תוסף. בקבצים של המפתחים צריך להוסיף את האפשרויות החדשות לייבוא כדי לקבל גישה:
    • import androidx.xr.scenecore.getEntitiesOfType
    • import androidx.xr.scenecore.getEntityForRtEntity
  • המרחב המשותף "Session.unpersistAnchor(Anchor)" נמחק
  • המרחב המשותף "Session.createPersistedAnchorEntity(UUID)" נמחק

בעיות מוכרות

  • יכול להיות שהשינויים ב-PanelEntity.setCornerRadius() וב-ActivityPanelEntity.setCornerRadius() לא ייכנסו לתוקף עד להזזה הבאה של הלוח. כדי למנוע זאת, אפשר להעביר את הלוח למיקום הנוכחי שלו.
  • כשמפעילים את BoundsChanged ב-ActivitySpace, יכול להיות שחלק מה-ActivityPose לא עודכנו כראוי. הוא יעודכן בשיחת OnSpaceUpdated הבאה ב-ActivitySpace

שינויים משמעותיים ושינויים התנהגותיים

  • אם רוחב הלוח או גובהו קטנים מ-32dp, PanelEntity ו-ActivityPanelEntity יקבלו ערך ברירת מחדל של רדיוס פינה של 32dp או פחות.

ממשקי API ויכולות חדשות

  • הוספת StereoSurface.CanvasShape, שמאפשר ליצור קנבסים מסוג Spherical ו-Hemispherical לעיבוד מדיה של חוויית צפייה מעמיקה.
  • עכשיו אפשר להוסיף לפרמטר StereoSurfaceEntity.create() את הפרמטר CanvasShape. (הפרמטר הזה מתעלם כרגע, אבל ישתמש בו בגרסה עתידית)
  • הפרמטר StereoSurfaceEntity.create() לא מקבל יותר פרמטר Dimensions. אפליקציות צריכות לקבוע את גודל הקנבס באמצעות ההגדרה CanvasShape
  • ל-StereoSurfaceEntity יש חבר CanvasShape שאפשר להגדיר באופן דינמי.
  • StereoSurfaceEntity.dimensions הוא עכשיו מאפיין לקריאה בלבד. באפליקציות צריך להגדיר את CanvasShape כדי לשנות מאפיינים.
  • StereoSurfaceEntity מאפשר עכשיו להגדיר מחדש את StereoMode אחרי היצירה.

שינויים אחרים

  • הורדנו את גרסת ה-minSDK בזמן הידור ל-24. כל ממשקי ה-API של Jetpack XR עדיין דורשים API 34 בסביבת זמן הריצה.
  • מפעל הסשנים של SceneCore‏ (Session.create) כבר לא מפעיל כוונה לקבלת ההרשאה SCENE_UNDERSTANDING. במקום זאת, אפליקציית הלקוח צריכה לבקש מהמשתמש את ההרשאות באופן מפורש לפני שתנסה ליצור את הווידג'טים. יצירת הצמד תיכשל אם המשתמש לא יעניק את ההרשאה.

תיקוני באגים

  • getActivitySpacePose() תוקנה כך שתתחשב בסולם של ActivitySpace על ידי החזרת ערכי התרגום במטרים מותאמים ולא תמיד במטרים לא מותאמים. transformPoseTo משתמש עכשיו גם ביחידות המתאימות לחישוב שינויים בקואורדינטות כשה-ActivitySpace מעורב במקור או ביעד.
  • עכשיו, כשמעבירים באמצעות setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) העדפה של תיבת שמיים null, תיבת השמיים מוגדרת כתיבת שמיים שחורה לגמרי. כדי לחזור לגיאומטריה ולקופסת השמיים שמוגדרות כברירת מחדל במערכת, משתמשים ב-setSpatialEnvironmentPreference(null).

גרסה 1.0.0-alpha01

12 בדצמבר 2024

androidx.xr.scenecore:scenecore-* 1.0.0-alpha01 משוחרר.

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

  • SpatialEnvironment: יצירת חוויות immersive מלאות באמצעות תמונה של סביבה מוצקה ו/או גיאומטריה של מודל תלת-ממדי כרקע לסצנת XR של הסביבה. אפשר גם להפעיל את התכונה 'מעבר', כדי שהסצנה הווירטואלית תוכל להשתלב בסביבה של המשתמש בעולם האמיתי.
  • PanelEntity: הוספת תוכן דו-ממדי לסצנות תלת-ממדיות על ידי הטמעת פריסות ופעילויות רגילות של Android בחלוניות מרחביות שיכולות לצוף או להיות מוצמדות למשטחים בעולם האמיתי.
  • GltfModelEntity: מיקום, הנפשה ואינטראקציה עם מודלים תלת-ממדיים בסצנה. SceneCore תומך בפורמט הקובץ glTF כדי להקל על השילוב עם מודלים קיימים.
  • SpatialAudio: הוספת מקורות אודיו של אווירה ומקורות אודיו ספציפיים לסצנה תלת-ממדית כדי ליצור אודיו מרחבי ומהפנט.
  • StereoSurfaceEntity: ‏SceneCore תומך בחיבור של תוכן שעבר עיבוד ל-Android Surface לעיניים ימין/שמאל. אפשר להשתמש באפשרות הזו כדי ליצור עיבוד (רנדור) של תוכן סטריאופוני בפורמט 'צד לצד' או 'למעלה-למטה', כמו תמונות סטריאו, סרטוני 3D או ממשקי משתמש אחרים עם עיבוד דינמי. באפליקציות צריך להשתמש ב-MediaPlayer או ב-ExoPlayer לפענוח סרטונים.
  • מערכת רכיבים: SceneCore מציעה מערכת רכיבים חזקה וגמישה להוספת יכולות לתוכן XR, כולל תכונות שמאפשרות למשתמשים להזיז, לשנות את הגודל שלהן ולנהל אינטראקציה עם מודלים ולוחות.
  • הצמדה: כשהתכונה 'מעבר אוטומטי' מופעלת, אפשר לצרף לוחות ומודלים למשטחים אמיתיים, וכך המשתמשים יכולים לשלב תוכן וירטואלי בסביבה שלהם בעולם האמיתי בצורה חלקה.
  • תנוחת המשתמש: גישה למיקום של המשתמש בסצנה הווירטואלית, כדי לכוון את התוכן לפי המיקום של המשתמש.
  • SpatialCapabilities: פיתוח אפליקציות עם יכולת התאמה מלאה שמנצלות את היכולות של מיקום במרחב כשהן זמינות, כמו מיקום תלת-ממדי של תוכן בממשק המשתמש. בנוסף, האפליקציה יכולה לעקוב אחרי שינויים ביכולות בזמן שהיא פועלת, כדי לשנות את חוויית השימוש בהתאם לאופן שבו המשתמש משתמש במכשיר Android XR שלו.

בעיות מוכרות

  • נכון לעכשיו, נדרש minSDK של 30 כדי להשתמש ב-Jetpack SceneCore. כפתרון עקיף, מוסיפים את רשומת המניפסט הבאה <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> כדי שאפשר יהיה ליצור ולרוץ עם minSDK של 23.
  • סשן יכול להפוך ללא תקף במצבים שונים שבהם הפעילות נוצרת מחדש באופן אוטומטי, כולל שינוי הגודל של לוח ראשי, חיבור ציוד היקפי ושינוי בין מצב בהיר למצב כהה. אם נתקלת בבעיות של ביטול תוקף סשן, אפשר להשתמש בפתרונות זמניים כמו אי אפשרות לשנות את הגודל של הלוח הראשי, שימוש בישויות של לוחות דינמיים, השבתה של יצירת מחדש של פעילות עבור שינויים ספציפיים בהגדרות או השבתה של שינויים בנושא של מצב בהיר/כהה.
  • אין תמיכה ברכיבים שניתן להזיז או לשנות את הגודל שלהם ב-GltfEntity.
  • אין תמיכה ב-Entity.getSize() ב-GltfEntity.
  • אפליקציות Jetpack XR נדרשות לבקש הרשאה android.permission.SCENE_UNDERSTANDING ב-AndroidManifest.
  • אפשר ליצור סשן רק במכשיר Android XR. בשלב זה, אם יוצרים סשן ומנסים להשתמש בו במכשיר שאינו Android XR, מתקבלת הודעת RuntimeException.
  • הגדרת תיבת השמיים כ-null באמצעות `SpatialEnvironment.setSpatialEnvironmentPreference() לא יוצרת תיבת שמיים שחורה מוצקה כפי שמתואר במסמכים. כתוצאה מכך, יכול להיות שיוצג רק שמיים של ברירת המחדל של המערכת או שלא יתבצע שינוי בשמיים הנוכחיים.
  • לקוחות SceneCore צריכים להוסיף את implementation(“com.google.guava:listenablefuture-1.0”) להגדרות Gradle של יחסי התלות של האפליקציה. במהדורה עתידית, ספריית scenecore תכלול את הספרייה הזו כיחס תלות מסוג api, כך שללקוחות לא יהיה צורך להצהיר עליה באופן מפורש.
  • SceneCore כולל בטעות את com.google.guava:guava-31.1-android ו-com.google.protobuf:protobuf-javalite כיחסי תלות טרנזיטיביים. אם הפעולה הזו תגרום לשגיאות כפולות של כיתות ב-build, אפשר להחריג בבטחה את שתי יחסי התלות האלה.
  • אם האפליקציה שלכם משתמשת ב-SceneCore ומפעילה את ProGuard, היא תקרוס כשתיצרו סשן. כפתרון עקיף, משביתים את ProGuard. במדריך הזה מוסבר איך מפעילים את ProGuard.