{ } { }

Jetpack SceneCore

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

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

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

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

מגניב

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha04"
    // 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-alpha04"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha04")
    // 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-alpha04")
}

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

משוב

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

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

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

גירסה 1.0

גרסה 1.0.0-alpha04

7 במאי 2025

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

תכונות חדשות

  • מעכשיו, טיפול חוזר יפעל בישויות של חלוניות ללא פעילויות מוטמעות. כדי שהטיפול החוזר יפעל, צריך לציין את הערך android:enableOnBackInvokedCallback= "true" במניפסט של Android.
  • StereoSurfaceEntity תומך עכשיו בהפעלה של MV-HEVC באמצעות שני ערכים חדשים של StereoMode: MULTIVIEW_LEFT_PRIMARY ו-MULTIVIEW_RIGHT_PRIMARY.
  • הפונקציות PanelEntity.setSize ו-PanelEntity.getSize מחזירות עכשיו את הגדלים במרחב ההורה.
  • הפונקציות Entity.setPose,‏ Entity.getPose,‏ Entity.setScale,‏ Entity.getScale,‏ Entity.setAlpha ו-Entity.getAlpha כוללות עכשיו פרמטר חדש, relativeTo, שמאפשר אחזור או הגדרה של ערכים ביחס למרחבים משותפים שונים. הערכים הנתמכים הם 'Parent', 'Activity' ו-'Real World', וערך ברירת המחדל של הפרמטר הזה הוא 'Parent'.
  • שיטות של תוסף קריאה חוזרת (callback) של 'חשיפה מרחבית' שנוספו ל-SessionExt.kt כדי לעקוב אחרי מקרים שבהם תוכן הסצנה עובר לתוך או מחוץ לטווח הראייה של המשתמש.
  • setPointSourceParams נוסף ל-SpatialAudioTrack, וכך אפשר לעדכן את הפרמטרים אחרי היצירה של הטראק.
  • נוספה כיתה חדשה, Scene, עם הפניות לממשקי API של Scenecore. אפשר יהיה לגשת לסצנה כנכס תוסף של סשן. הפונקציות בתוך SessionExt הועברו ל-Scene, כך שיהיה צורך לשנות את הייבוא. לדוגמה, SessionExt.getScene(session).addSpatialCapababilitiesChangedListener לעומת SessionExt.addSpatialCapabilitiesChangedListener.
  • נוספה ActivityPose.hitTestAsync, שמאפשרת hitTest נגד תוכן וירטואלי.
  • נוספ סוג רכיב חדש SpatialPointerComponent, שמאפשר ללקוחות לציין את הסמל שמוצג עבור הסמן או להשבית את הסמל. בשלב הזה אפשר לצרף את הרכיב הזה רק למכונות PanelEntity.
  • אנחנו משיקים את המפעל החדש PanelEntity, שמקבל את מידות הלוח במטרים או בפיקסלים. הוסר המפעל הישן של PanelEntity, שהשתמש בשני פרמטרים מסוג מאפיין לחלונית.

שינויים ב-API

  • הסרת ההגבלה על RequiresApi(34) בכל החבילות של Jetpack XR. המגבלה הזו הייתה מיותרת כי Jetpack XR זמין כרגע רק במכשירים עם רמת API‏ 34 ואילך. (Iae0f8)
  • כדי לצרוך פרויקטים שפורסמו עם Kotlin 2.0, צריך להשתמש ב-KGP 2.0.0 ואילך (Idb6b5)
  • הכיתה PermissionHelper הוסרה.
  • האפשרות PanelEntity.getPixelDensity הוצאה משימוש.
  • השדות PanelEntity.setPixelDimensions ו-PanelEntity.getPixelDimension יוסרו ויוחלפו בשדות setSizeInPixels ו-getSizeInPixels.
  • האפשרות Entity.getActivitySpaceAlpha הוסרה. אפשר להחליף אותו ב-Entity.getAlpha(Space.Activity).
  • האפשרות Entity.getWorldSpaceScale הוסרה. אפשר להחליף אותו ב-Entity.getScale(Space.REAL\_WORLD).
  • הכיתה Session ב-SceneCore נמחקה לטובת הכיתה Session ב-XR Runtime.
  • השם של StereoSurfaceEntity השתנה ל-SurfaceEntity.
  • Entity.setSize ו-Entity.getSize הוסרו, ואותו שיטות נוספו ל-PanelEntity.
  • השם של PointSourceAttributes השתנה ל-PointSourceParams.
  • השם של SpatializerConstants.SOURCE\_TYPE\_BYPASS השתנה ל-SpatializerConstants.SOURCE\_TYPE\_DEFAULT.
  • הישות PointSourceParams שונתה מגישה ציבורית לגישה פנימית.
  • עכשיו צריך להגדיר את PlaneTrackingMode ב-Session.configure() כדי להשתמש ב-AnchorEntity.create.
  • עכשיו צריך להגדיר את HeadTrackingMode ב-Session.configure() כדי להשתמש בממשקי ה-API של SpatialUser.
  • אם לא מצרפים את ResizableComponent, יופיע יומן ברמת INFO במקום יומן ברמת ERROR.
  • הכיתה Fov היא עכשיו כיתה רגילה ב-Kotlin.
  • מחלקים את Entity.kt כדי להציב כל סוג של ישות קונקרטית בקובץ משלו.
  • כשיוצרים PanelEntity חדש, רוב התצוגות המפורטות יועברו לFrameLayout חדש. כך קל יותר להשתמש ב-LayoutInspector עם חלוניות מרחבי.
  • המכונה של XrExtensions שבה אתם משתמשים כרגע תירשם בפלטפורמה, במסגרת המאמצים שלנו לעזור לכם לנפות באגים באפליקציה.

תיקוני באגים

  • נוספה תיקון כדי למנוע קריסה שעלולה להתרחש כשמעבירים PanelEntity עם MovableComponent ו-AnchorPlacement
  • תוקנה בעיה שבה ResizableComponent סיפק גדלים לא עדכניים בקריאה החוזרת (callback) של onResizeStart.
  • תוקנה קריסה שנגרמה כשהתכונה dispose() של JxrPlatformAdapterAxr הופעל כמה פעמים.

גרסה 1.0.0-alpha03

26 בפברואר 2025

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

תכונות חדשות

  • עכשיו יש תמיכה ב-Proguard minification בקוד של Jetpack XR

תיקוני באגים

  • תיקונים נוספים לתמיכה ב-Proguard minification עבור Jetpack XR SceneCore‏ (I4f47e)
  • עדכנו את הכלל ProGuard של Jetpack XR Scenecore כדי למנוע AbstractMethodError בלקוחות שעברו אופטימיזציה. (I91a01)

גרסה 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: פיתוח אפליקציות עם יכולת התאמה מלאה שמנצלות את היכולות של מיקום במרחב כשהן זמינות, כמו מיקום 3D של תוכן בממשק המשתמש. בנוסף, האפליקציה יכולה לעקוב אחרי שינויים ביכולות בזמן שהיא פועלת, כדי לשנות את חוויית השימוש בהתאם לאופן שבו המשתמש משתמש במכשיר 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.