Jetpack SceneCore

הפניית API
androidx.xr.scenecore
androidx.xr.scenecore.testing

יצירה של תרשים סצנה ב-Android XR ושינוי שלו באמצעות תוכן תלת-ממדי.

העדכון האחרון	גרסה יציבה	גרסה מועמדת להפצה	גרסת בטא	גרסה אלפא
12 בדצמבר 2024	-	-	-	1.0.0-alpha01

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

כדי להוסיף תלות ב-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-alpha01

12 בדצמבר 2024

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

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

SpatialEnvironment: יצירת חוויות immersive מלאות באמצעות תמונה של סביבה מוצקה ו/או גיאומטריה של מודל תלת-ממדי כרקע לסצנת XR של הסביבה. אפשר גם להפעיל את התכונה Passthrough כדי שהסצנה הווירטואלית תוכל להשתלב בסביבה של המשתמש בעולם האמיתי.
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() לא מובילה לתיבת שמיים שחורה מוצקה כפי שמתואר במסמכים. כתוצאה מכך, יכול להיות שיוצג ברירת המחדל של מערכת ה-Skybox או שלא יתבצע שינוי ב-Skybox הנוכחי.
לקוחות 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.