{ } { }

Jetpack SceneCore

أنشئ رسمًا بيانيًا للمشهد في Android XR وحرِّكه باستخدام محتوى ثلاثي الأبعاد.
آخر تعديل الإصدار الثابت إصدار محتمل الإصدار التجريبي الإصدار التجريبي
12 شباط (فبراير) 2025 - - - 1.0.0-alpha02

الإعلان عن التبعيات

لإضافة تبعية على XR SceneCore، يجب إضافة مستودع Google Maven إلى مشروعك. اطّلِع على مستودع Maven من Google لمزيد من المعلومات.

أضِف التبعيات للعناصر التي تحتاج إليها في ملف build.gradle ل تطبيقك أو وحدتك:

Groovy

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")
}

لمزيد من المعلومات عن العناصر الاعتمادية، اطّلِع على مقالة إضافة عناصر الاعتماد الخاصة بالإصدار.

الملاحظات

تساعدنا ملاحظاتك في تحسين Jetpack. يُرجى إعلامنا إذا واجهت مشاكل جديدة أو كان لديك أفكار لتحسين هذه المكتبة. يُرجى الاطّلاع على المشاكل الحالية في هذه المكتبة قبل إنشاء مكتبة جديدة. يمكنك إضافة صوتك إلى مشكلة حالية من خلال النقر على زرّ النجمة.

إنشاء مشكلة جديدة

اطّلِع على مستندات أداة تتبُّع المشاكل لمزيد من المعلومات.

الإصدار 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.

التغييرات الأساسية والسلوكية

  • سيكون نصف قطر الزاوية التلقائي لرمزَي PanelEntity وActivityPanelEntity هو 32 بكسل غير مرتبطة بالكثافة أو أقل إذا كان عرض اللوحة أو ارتفاعها أصغر من 32 بكسل غير مرتبطة بالكثافة.

واجهات برمجة التطبيقات والإمكانات الجديدة

  • يوفّر StereoSurface.CanvasShape إمكانية إنشاء لوحات Spherical وHemispherical لعرض الوسائط الغامر.
  • تقبل StereoSurfaceEntity.create() الآن مَعلمة CanvasShape. (يتم تجاهل هذه المَعلمة حاليًا، ولكن سيتم استخدامها في إصدار مستقبلي)
  • لم تعُد StereoSurfaceEntity.create() تأخذ مَعلمة Dimensions. يجب أن تتحكّم التطبيقات في حجم اللوحة من خلال ضبط CanvasShape.
  • يحتوي StereoSurfaceEntity على عضو CanvasShape يمكن ضبطه ديناميكيًا.
  • أصبحت السمة StereoSurfaceEntity.dimensions الآن سمة للقراءة فقط، ويجب أن تضبط التطبيقات السمة CanvasShape لتغيير السمات.
  • يسمح StereoSurfaceEntity الآن بإعادة ضبط StereoMode بعد إنشائه.

التغييرات الأخرى

  • تم خفض الحد الأدنى لإصدار حزمة تطوير البرامج (SDK) في وقت الترجمة إلى 24. لا تزال جميع واجهات برمجة تطبيقات Jetpack XR تتطلّب استخدام المستوى 34 من واجهة برمجة التطبيقات أثناء التشغيل.
  • لم يعُد مصنع الجلسات في SceneCore (Session.create) يطلق نية للحصول على إذن SCENE_UNDERSTANDING. بدلاً من ذلك، يجب أن يطلب تطبيق العميل الأذونات صراحةً من المستخدم قبل محاولة إنشاء نقاط الربط. لن يتمكّن المستخدم من إنشاء إشارة مرجعية إذا لم يمنح الإذن.

إصلاح الأخطاء

  • تم إصلاح getActivitySpacePose() لمراعاة مقياس ActivitySpace من خلال عرض قيم الترجمة بوحدة متر مُعدَّلة بدلاً من عرض متر غير معدَّل دائمًا. يستخدم transformPoseTo الآن أيضًا الوحدات المناسبة لاحتساب تغييرات التنسيقات عندما يكون ActivitySpace مضمّنًا في المصدر أو الوجهة.
  • سيتم الآن ضبط مربّع السماء على مربّع سماء أسود بالكامل عند تمرير إعداد مفضّل مربّع سماء فارغ باستخدام setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). للرجوع إلى الإعدادات التلقائية للنظام في ما يتعلق بصندوق السماء والأشكال الهندسية، استخدِم setSpatialEnvironmentPreference(null)..

الإصدار 1.0.0-alpha01

12 كانون الأول (ديسمبر) 2024

تم إصدار androidx.xr.scenecore:scenecore-* 1.0.0-alpha01.

ميزات الإصدار الأولي الإصدار الأولي للمطوّرين من Jetpack SceneCore، وهي مكتبة لرسم المخططات الثلاثية الأبعاد للمشاهد لإنشاء المشاهد والبيئات الغامرَين وتعديلهما. تتيح لك هذه المكتبة وضع النماذج الثلاثية الأبعاد ولوحات المحتوى وترتيبها بالنسبة إلى بعضها البعض وبيئتك الافتراضية أو الواقعية.

  • ‫SpatialEnvironment: يمكنك إنشاء تجارب غامرة بالكامل باستخدام صورة صندوق السماء و/أو هندسة النموذج الثلاثي الأبعاد كخلفية لمشهد الواقع المعزّز للبيئة. أو يمكنك تفعيل ميزة "العرض المباشر" لكي يندمج المشهد الافتراضي مع بيئة المستخدم في العالم الواقعي.
  • ‫PanelEntity: يمكنك إضافة محتوى ثنائي الأبعاد إلى مناظرك الثلاثية الأبعاد من خلال تضمين تنسيقات وأنشطة Android العادية في لوحات مجسمة يمكن أن تطفو أو يتم تثبيتها على مساحات في العالم الواقعي.
  • ‫GltfModelEntity: يمكنك وضع النماذج الثلاثية الأبعاد في المشهد وتحريكها والتفاعل معها. يتوافق SceneCore مع تنسيق ملف glTF لتسهيل دمجه مع النماذج الحالية.
  • الصوت المكاني: يمكنك إضافة مصادر صوت محيطية ومصادر صوت نقطية إلى المشهد الثلاثي الأبعاد للحصول على صوت محيطي كامل.
  • ‫StereoSurfaceEntity: تتيح SceneCore توجيه المحتوى المعروض على سطح Android إلى العين اليمنى أو اليسرى. ويمكن استخدام هذا الإجراء لعرض المحتوى المجسم بتنسيق جنبًا إلى جنب أو من الأعلى إلى الأسفل، مثل الصور المجسمة أو الفيديوهات الثلاثية الأبعاد أو واجهات المستخدم الأخرى التي يتم عرضها ديناميكيًا. يجب أن تستخدم التطبيقات MediaPlayer أو ExoPlayer لفك ترميز الفيديو.
  • نظام المكونات: يوفّر SceneCore نظام مكونات قويًا ومرنًا لإضافة إمكانات إلى محتوى الواقع المعزّز، بما في ذلك ميزات تتيح للمستخدمين نقل النماذج ولوحات العرض وتغيير حجمها والتفاعل معها.
  • التثبيت: عند تفعيل ميزة "العرض المباشر"، يمكنك إرفاق اللوحات والنماذج بمساحات العرض الفعلية، ما يتيح للمستخدمين دمج المحتوى الافتراضي بسلاسة في بيئة الواقع.
  • وضع المستخدم: يمكنك الوصول إلى الموقع الجغرافي للمستخدم في المشهد الافتراضي لتوجيه المحتوى حول موضع المستخدم.
  • ‫SpatialCapabilities: يمكنك إنشاء تطبيقات تكيُّفية بالكامل تستفيد من الإمكانات المكانية عند توفّرها، مثل تحديد موضع المحتوى في واجهة المستخدم بالاستناد إلى المساحة الثلاثية الأبعاد. بالإضافة إلى ذلك، يمكن لتطبيقك رصد التغييرات في الإمكانات أثناء تنفيذ التطبيق لتعديل التجربة استنادًا إلى كيفية استخدام المستخدم لجهاز Android XR.

المشاكل المعروفة

  • يجب حاليًا استخدام الإصدار 30 من حزمة تطوير البرامج (SDK) كحد أدنى لاستخدام Jetpack SceneCore. كحل بديل، أضِف إدخال البيان التالي <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> لتتمكّن من إنشاء التطبيق وتشغيله باستخدام الإصدار 23 من حزمة تطوير البرامج (SDK) كحد أدنى.
  • يمكن أن تصبح الجلسة غير صالحة في حالات مختلفة تؤدي إلى إعادة إنشاء النشاط تلقائيًا، بما في ذلك تغيير حجم اللوحة الرئيسية وربط الأجهزة الطرفية والتبديل بين الوضع الفاتح والداكن. إذا واجهت مشاكل في إلغاء صلاحية الجلسة، تشمل الحلول البديلة جعل اللوحة الرئيسية غير قابلة للتغيير، أو استخدام عنصر لوحة ديناميكية، أو إيقاف إعادة إنشاء النشاط لإجراء تغييرات معيّنة في الإعدادات أو إيقاف تغييرات المظهر في الوضع الفاتح/الداكن.
  • لا تتوفّر المكونات القابلة للنقل وتغيير الحجم في 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 كتبعيات ناتجة. إذا أدّى ذلك إلى ظهور أخطاء مكرّرة في الصف في عملية الإنشاء، يمكن استبعاد هذين المكوّنَين التابعَين بأمان.
  • إذا كان تطبيقك يستخدم SceneCore ويفعّل ProGuard، سيتعطّل عند إنشاء Session. كحل بديل، يمكنك إيقاف أداة ProGuard. اطّلِع على هذا الدليل للحصول على مزيد من المعلومات عن كيفية تفعيل ProGuard.