Jetpack SceneCore
آخر الأخبار | الإصدار الثابت | إصدار محتمل | الإصدار التجريبي | الإصدار الأوّلي |
---|---|---|---|---|
7 مايو 2025 | - | - | - | 1.0.0-alpha04 |
تعريف التبعيات
لإضافة تبعية إلى XR SceneCore، يجب إضافة مستودع Google Maven إلى مشروعك. اطّلِع على مستودع Maven من Google لمزيد من المعلومات.
أضِف التبعيات الخاصة بالعناصر التي تحتاج إليها في ملف build.gradle
لتطبيقك أو وحدتك:
Groovy
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") }
لمزيد من المعلومات حول العناصر التابعة، يُرجى الاطّلاع على إضافة عناصر تابعة للإنشاء.
الملاحظات
تساعدنا ملاحظاتك في تحسين 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
، ما يتيح الحصول على القيم أو ضبطها بالنسبة إلى مساحات مختلفة. القيم المسموح بها هي "المساحات الرئيسية" و"النشاط" و"العالم الحقيقي"، والقيمة التلقائية لهذه المَعلمة هي "المساحات الرئيسية". - تمت إضافة طرق ملحقة لـ Spatial Visibility Callback إلى
SessionExt.kt
لتتبُّع وقت انتقال محتوى المشهد إلى داخل مجال رؤية المستخدم أو خارجه. - تمت إضافة
setPointSourceParams
إلىSpatialAudioTrack
، ما يتيح تعديل المَعلمات بعد إنشاء مسار التتبُّع. - تمت إضافة فئة جديدة، Scene، مع مراجع إلى واجهات برمجة التطبيقات
Scenecore
. سيكون المشهد متاحًا كسمة إضافية للجلسة. تم نقل الدوال داخلSessionExt
إلى Scene، لذا يجب تعديل عمليات الاستيراد، مثلSessionExt.getScene(session)
."addSpatialCapababilitiesChangedListener
" ضد "SessionExt.addSpatialCapabilitiesChangedListener
". - تمت إضافة
ActivityPose.hitTestAsync
، ما يتيحhitTest
ضد المحتوى الافتراضي. - تمت إضافة نوع "المكوّن" الجديد
SpatialPointerComponent
، ما يتيح للعملاء تحديد الأيقونة المعروضة للمؤشر أو إيقاف الأيقونة. يمكن حاليًا ربط هذا المكوّن بـPanelEntity
مثيل فقط. - نقدّم مصنع
PanelEntity
جديدًا يأخذ أبعاد اللوحة بالمتر أو بالبكسل. تمت إزالة مصنعPanelEntity
القديم الذي يتلقّى مَعلمتَين من نوع "السمة" للوحة.
تغييرات واجهة برمجة التطبيقات
- تمت إزالة القيود المفروضة على
RequiresApi(34)
في جميع حِزم Jetpack XR. كان هذا القيد غير ضروري لأنّ Jetpack XR لا يتوفّر حاليًا إلا على الأجهزة التي تعمل بالإصدار 34 من واجهة برمجة التطبيقات أو الإصدارات الأحدث. (Iae0f8) - تتطلّب المشاريع التي تم إصدارها باستخدام Kotlin 2.0 استخدام الإصدار 2.0.0 أو إصدار أحدث من KGP (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
من إمكانية الوصول العام إلى إمكانية الوصول الداخلي. - يتطلّب
AnchorEntity.create
الآن إعدادPlaneTrackingMode
فيSession.configure()
. - تتطلّب واجهات برمجة التطبيقات في
SpatialUser
الآن ضبطHeadTrackingMode
فيSession.configure()
. - عندما لا يتم إرفاق
ResizableComponent
، سيتم عرض سجلّ على مستوى INFO بدلاً من سجلّ على مستوى ERROR. - أصبح صف Fov الآن صف Kotlin عاديًا.
- قسِّم
Entity.kt
لوضع كل نوع من أنواع العناصر الملموسة في ملف منفصل. - عند إنشاء
PanelEntity
جديد، سيتم إعادة ربط معظم طرق العرض بـFrameLayout
. يسهّل ذلك استخدامLayoutInspector
مع "اللوحات المكانية". - تم الآن تسجيل مثيل
XrExtensions
المستخدَم حاليًا في المنصة، بأقصى جهد ممكن، للمساعدة في تصحيح أخطاء التطبيق.
إصلاح الأخطاء
- تمت إضافة إصلاح لمنع حدوث تعطُّل قد يحدث عند نقل
PanelEntity
يحتوي علىMovableComponent
وAnchorPlacement
- تم إصلاح المشكلة المتمثّلة في أنّ
ResizableComponent
كان يقدّم أحجامًا قديمة في معاودة الاتصال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 متاحة الآن لرمز Jetpack XR
إصلاح الأخطاء
- إصلاحات إضافية لتوفير إمكانية تصغير Proguard في Jetpack XR SceneCore (I4f47e)
- تم تعديل قاعدة Jetpack XR Scenecore
ProGuard
لمنع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
.
التغييرات التي قد تؤدي إلى عطل والتغييرات السلوكية
- سيكون لنص
PanelEntity
وActivityPanelEntity
نصف قطر تلقائي للزاوية يبلغ 32 بكسل غير مرتبط بالكثافة أو أقل إذا كان عرض اللوحة أو ارتفاعها أقل من 32 بكسل غير مرتبط بالكثافة.
واجهات برمجة التطبيقات والإمكانات الجديدة
- يقدّم
StereoSurface.CanvasShape
، ما يتيح إنشاء لوحات عرضSpherical
وHemispherical
لعرض الوسائط الغامرة. - تقبل
StereoSurfaceEntity.create()
الآن المَعلمةCanvasShape
. (يتم تجاهل هذه المَعلمة حاليًا، ولكن سيتم استخدامها في إصدار مستقبلي) - لم يعُد
StereoSurfaceEntity.create()
يقبل المَعلمةDimensions
. يجب أن تتحكّم التطبيقات في حجم لوحة الرسم من خلال ضبطCanvasShape
- يحتوي
StereoSurfaceEntity
على عنصرCanvasShape
يمكن ضبطه بشكل ديناميكي. - أصبحت
StereoSurfaceEntity.dimensions
الآن سمة للقراءة فقط، ويجب أن تضبط التطبيقاتCanvasShape
لتغيير الأبعاد. - يسمح
StereoSurfaceEntity
الآن بإعادة ضبطStereoMode
بعد الإنشاء.
التغييرات الأخرى
- تم خفض الحد الأدنى لـ minSDK في وقت التجميع إلى 24. ستظل جميع واجهات برمجة تطبيقات Jetpack XR تتطلّب استخدام المستوى 34 من واجهة برمجة التطبيقات في وقت التشغيل.
- لم يعُد مصنع الجلسات (
Session.create
) فيSceneCore
يطلق هدفًا للحصول على إذنSCENE_UNDERSTANDING
. بدلاً من ذلك، يجب أن يطلب تطبيق العميل الأذونات صراحةً من المستخدم قبل محاولة إنشاء نقاط الارتكاز. ستتعذّر عملية إنشاء نقاط الارتكاز إذا لم يمنح المستخدم الإذن.
إصلاح الأخطاء
- تم إصلاح
getActivitySpacePose()
لتأخذ في الاعتبار مقياسActivitySpace
من خلال عرض قيم الترجمة بالمترات التي تم تغيير مقياسها بدلاً من عرض المترات التي لم يتم تغيير مقياسها دائمًا. يستخدمtransformPoseTo
الآن أيضًا الوحدات الصحيحة لاحتساب تغييرات الإحداثيات عندما يكونActivitySpace
متضمّنًا في المصدر أو الوجهة. - سيتم الآن ضبط صندوق السماء على صندوق سماء أسود بالكامل كلما تم تمرير إعداد مفضّل لصندوق سماء فارغ باستخدام
setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom))
. للتراجع عن التغييرات والعودة إلى إعدادات skybox والهندسة التلقائية للنظام، استخدِمsetSpatialEnvironmentPreference(null).
الإصدار 1.0.0-alpha01
12 ديسمبر 2024
تم طرح androidx.xr.scenecore:scenecore-* 1.0.0-alpha01
.
ميزات الإصدار الأولي الإصدار الأولي من Jetpack SceneCore للمطوّرين، وهو مكتبة رسومات ثلاثية الأبعاد لإنشاء مشاهد وبيئات غامرة ومعالجتها. تتيح لك هذه المكتبة وضع نماذج ثلاثية الأبعاد ولوحات المحتوى وترتيبها بالنسبة إلى بعضها البعض وإلى بيئاتك الافتراضية أو الواقعية.
- SpatialEnvironment: يمكنك إنشاء تجارب غامرة بالكامل باستخدام صورة skybox و/أو هندسة نموذج ثلاثي الأبعاد كخلفية لمشهد الواقع الممتد الخاص ببيئتك. يمكنك أيضًا تفعيل ميزة "المرور"، حتى يتم دمج المشهد الافتراضي مع بيئة المستخدم في العالم الحقيقي.
- PanelEntity: يمكنك إضافة محتوى ثنائي الأبعاد إلى مشاهدك الثلاثية الأبعاد من خلال تضمين تصميمات وأنشطة Android العادية في لوحات مكانية يمكن أن تطفو أو يتم تثبيتها على أسطح في العالم الحقيقي.
- GltfModelEntity: يمكنك وضع نماذج ثلاثية الأبعاد وتحريكها والتفاعل معها في المشهد. تتوافق SceneCore مع تنسيق ملف glTF لتسهيل عملية الدمج مع التصاميم الحالية.
- SpatialAudio: يمكنك إضافة مصادر صوتية محيطة وموضعية إلى المشهد الثلاثي الأبعاد للحصول على صوت مكاني غامر بالكامل.
- StereoSurfaceEntity: تتيح SceneCore توجيه المحتوى المعروض على Android Surface إلى العين اليسرى أو اليمنى. يمكن استخدام هذه السمة لعرض محتوى مجسّم بتنسيق جنبًا إلى جنب أو من أعلى إلى أسفل، مثل الصور المجسّمة أو الفيديو الثلاثي الأبعاد أو واجهات المستخدم الأخرى التي يتم عرضها بشكل ديناميكي. يجب أن تستخدم التطبيقات MediaPlayer أو ExoPlayer لفك ترميز الفيديو.
- نظام المكوّنات: يوفّر SceneCore نظام مكوّنات قويًا ومرنًا لإضافة إمكانات إلى محتوى الواقع الممتد، بما في ذلك وسائل مساعدة للمستخدمين لنقل النماذج واللوحات وتغيير حجمها والتفاعل معها.
- التثبيت: عند تفعيل ميزة "المرور"، يمكنك ربط اللوحات والنماذج بالأسطح الفعلية، ما يتيح للمستخدمين دمج المحتوى الافتراضي بسلاسة في بيئتهم الواقعية.
- وضعية المستخدم: تتيح لك هذه الإذن الوصول إلى الموقع الجغرافي للمستخدم في المشهد الافتراضي، وذلك لتوجيه المحتوى حول موضع المستخدم.
- SpatialCapabilities: يمكنك إنشاء تطبيقات متكيّفة بالكامل تستفيد من الإمكانات المكانية عند توفّرها، مثل تحديد موضع المحتوى ثلاثي الأبعاد في واجهة المستخدم. بالإضافة إلى ذلك، يمكن لتطبيقك مراقبة التغييرات في الإمكانات أثناء تنفيذه، وذلك لتعديل التجربة استنادًا إلى طريقة استخدام المستخدم لجهاز Android XR.
المشاكل المعروفة
- في الوقت الحالي، يجب أن يكون الإصدار الأدنى لحزمة تطوير البرامج (SDK) هو 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. في الوقت الحالي، إذا أنشأت جلسة وحاولت استخدامها على جهاز XR غير Android، سيظهر لك الخطأ RuntimeException.
- لا يؤدي ضبط صندوق السماء على القيمة الخالية باستخدام 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
كعناصر تابعة متعدية. إذا نتج عن ذلك أخطاء مكرّرة في الصف في الإصدار، يمكن استبعاد هذين العنصرَين التابعَين بأمان. - إذا كان تطبيقك يستخدم SceneCore وتم تفعيل ProGuard، سيتعطّل التطبيق عند إنشاء Session. كحلّ بديل، يمكنك إيقاف ProGuard. يمكنك الاطّلاع على هذا الدليل للحصول على مزيد من المعلومات حول كيفية تفعيل ProGuard.