‫Jetpack SceneCore

إنشاء مخطط المشهد في Android XR وتعديله باستخدام محتوى ثلاثي الأبعاد
آخر الأخبار الإصدار الثابت إصدار محتمل الإصدار التجريبي الإصدار الأوّلي
‫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.