‫Jetpack SceneCore

إنشاء مخطط المشهد في Android XR وتعديله باستخدام محتوى ثلاثي الأبعاد
آخر الأخبار الإصدار الثابت إصدار محتمل الإصدار التجريبي الإصدار الأوّلي
‫30 يوليو 2025 - - - 1.0.0-alpha05

تعريف التبعيات

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

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

Groovy

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

Kotlin

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

لمزيد من المعلومات حول العناصر التابعة، يُرجى الاطّلاع على إضافة عناصر تابعة للإنشاء.

الملاحظات

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

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

يُرجى الاطّلاع على مستندات Issue Tracker للحصول على مزيد من المعلومات.

الإصدار 1.0

الإصدار 1.0.0-alpha05

‫30 يوليو 2025

تم إصدار androidx.xr.scenecore:scenecore-guava:1.0.0-alpha05 وandroidx.xr.scenecore:scenecore-testing:1.0.0-alpha05 وandroidx.xr.scenecore:scenecore:1.0.0-alpha05. يحتوي الإصدار 1.0.0-alpha05 على عمليات الإيداع هذه.

الميزات الجديدة

  • تمت إضافة واجهة برمجة التطبيقات Perceived Resolution API إلى "كيانات اللوحة" وSurfaceEntities. (I118f6)
  • تمت إضافة طرق معاودة الاتصال PerceivedResolution إلى Scene.kt لمراقبة الدقة المرئية للّوحة الرئيسية للنشاط في "خدمة إدارة تجربة النظام". (I58084)
  • SurfaceEntity - تمت إضافة دعم للتطبيق لطلب أخذ عينات فائقة عند الإنشاء. يسمح ذلك للتطبيقات باستخدام فلتر أخذ العينات الفائق لتنعيم الحواف. (I06913)
  • تمت إضافة الموقع recommendedContentBoxInFullSpace إلى الحساب ActivitySpace. تعرض هذه السمة مربّعًا مقترَحًا لوضع المحتوى فيه عند تفعيل "وضع المساحة الكاملة". (I4cd6f)
  • تم توفير أداة إنشاء محمّلة بشكل زائد للمعدِّل القابل للنقل الذي يسمح بالتثبيت. (Ic0c70)

تغييرات واجهة برمجة التطبيقات

تم إجراء تغييرات شاملة على واجهة برمجة التطبيقات SceneCore في هذا الإصدار. تمت إعادة تسمية العديد من الفئات و/أو نقلها إلى وحدات مختلفة، وتم استبدال معظم طرق getter/setter بخصائص Kotlin. مع أنّنا نتوقّع إجراء تغييرات غير متوافقة في واجهة برمجة التطبيقات في المستقبل إلى أن يتم إصدار الإصدار التجريبي الأول، لن تكون هذه التغييرات مزعجة أو عديدة.

  • تمت إعادة تسمية و/أو نقل الفئات والواجهات التالية: androidx.xr.scenecore.PixelDimensions إلى androidx.xr.runtime.math.IntSize2d، وandroidx.xr.scenecore.Dimensions إلى androidx.xr.runtime.math.FloatSize3d، وandroidx.xr.scenecore.ActivityPose إلى ScenePose، وandroidx.xr.scenecore.ContentlessEntity إلى GroupEntity، وandroidx.xr.scenecore.PlaneType إلى PlaneOrientation، وandroidx.xr.scenecore.PlaneSemantic إلى PlaneSemanticType. (Ifd405)(I3b622) (If534d)
  • تمت إتاحة عدد من أدوات الضبط لخصائص Scene بشكل خاص، ولم يكن من المفترض أن يتم تغييرها من قِبل عملاء SceneCore: activitySpace وactivitySpaceRoot وmainPanelEntity وperceptionSpace وspatialCapabilities وspatialEnvironment وspatialUser. (I2f506)
  • في الكيان: تم تغيير ما يلي إلى سمات: get/setParent() وsetContentDescription. تم إيقاف Entity.is/setHidden() نهائيًا، يُرجى استخدام Entity.is/setEnabled بدلاً من ذلك. (Ibc4c6)
  • تمت إزالة الفئة androidx.xr.scenecore.BasePanelEntity، يُرجى استخدام PanelEntity مباشرةً بدلاً منها. تم استبدال دوال الجلب والضبط الخاصة بـ PanelEntity بالخصائص. تم تغيير السمة PanelEntity.size من Float3dSize إلى Float2dSize. تمت إزالة الطريقة المتوقّفة نهائيًا androidx.xr.scenecore.PanelEntity.getPixelDimensions، يُرجى استخدام getSizeInPixels بدلاً منها. (Icc174)
  • تم استبدال androidx.xr.scenecore.OnSpaceUpdatedListener بـ Runnable. (I19308)
  • تم استبدال SpatialUser.getCameraViews() بسمة. (Ib0cc5) بالنسبة إلى ExrImage وGltfModel:، تم تغيير طرق create لتصبح دوال تعليق، وتم تعديل مَعلمات الإنشاء لقبول Uri أو Path بدلاً من String. (Id8883) (I0d247)، (I25706)
  • تم نقل SpatialEnvironment.requestFullSpaceMode وSpatialEnvironment.requestHomeSpaceMode إلى "المشهد"، مثلاً استخدِم session.scene.requestFullSpaceMode() بدلاً من session.scene.spatialEnvironment.requestFullSpaceMode(). يتضمّن كل من addOnPassthroughOpacityChangedListener وaddOnSpatialEnvironmentChangedListener الآن عمليات إلغاء تقبل المنفّذين الاختياريين. (I12fe0) (I6b21e)
  • تمت إزالة طرق SpatialEnvironment المتوقّفة نهائيًا التالية: togglePassthrough وsetPassthrough وsetPassthroughOpacity وgetPassthroughMode وgetPassthroughOpacity وsetSkybox وsetGeometry. تمت أيضًا إزالة الفئة المتوقّفة نهائيًا SpatialEnvironment.PassthroughMode (I927bd) (I927bd) (I927bd)
  • تم استبدال دوال الجلب والضبط التالية SpatialEnvironment بخصائص Kotlin: getCurrentPassthroughOpacity() وget/setPassthroughOpacityPreference() وget/setSpatialEnvironmentPreference() وisSpatialEnvironmentPreferenceActive() (I33a7b) (Ie06e2) (Ie06e2)
  • تم تغيير نوع SpatialEnvironmentPreference.preferredPassthroughOpacity من Float? إلى Float. لم يعُد يقبل القيم الفارغة. بدلاً من ذلك، يتم استخدام SpatialEnvironment.NO_PASSTHROUGH_OPACITY_PREFERENCE للإشارة إلى عدم توفّر أي إعداد مفضّل للشفافية. (I40107)
  • تم تعديل المَعلمة windowBoundsPx إلى pixelDimensions وتغيير نوعها من Rect إلى IntSize2d في طريقة الإنشاء. (I1926e)
  • أصبح منشئ SpatialEnvironment داخليًا الآن (I75a51)
  • تم استبدال الفئتين SpatialPointerIconNone وSpatialPointerIconCircle بالكائنين المصاحبين SpatialPointerIcon.NONE وSpatialPointerIcon.CIRCLE (I416d2)
  • لم يعُد الحقل SpatialPointerIcon في SpatialPointerComponent يقبل القيمة الخالية. استخدِم SpatialPointerIcon.DEFAULT بدلاً من القيمة الخالية للإشارة إلى أنّه يجب استخدام رمز المؤشر التلقائي للنظام. (I416d2)
  • تم استبدال androidx.xr.scenecore.AnchorEntity.getState() بسمة للقراءة فقط. تمت إعادة تسمية المَعلمات في الطريقة AnchorEntity.create() لتوضيحها. في طرق AnchorEntity لإعداد المستمعين وإضافتهم، تم نقل المستمع إلى الوسيطة الأخيرة لتفعيل lambdas اللاحقة. تم استبدال androidx.xr.scenecore.OnStateChangedListener بـ AnchorEntity بـ Consumer<AnchorEntity.State>. (I472e0)
  • أصبح GltfModelEntity.getAnimationState() الآن موقعًا إلكترونيًا. (I10b29)
  • تم استبدال ActivitySpace.getBounds() بسمة. تمت إعادة تسمية "ActivitySpace.addBoundsChangedListener" إلى "ActivitySpace.addOnBoundsChangedListener". تم استبدال ActivitySpace.setOnSpaceUpdatedListener بطرق الإضافة/الإزالة. (I4c956)
  • تمت إعادة تسمية AnchorPlacement: planeTypeFilter إلى anchorablePlaneOrientations، وتمت إعادة تسمية planeSemanticFilter إلى anchorablePlaneSemanticTypes. ستعرض إضافة MovableComponent إلى AnchorEntity أو ActivitySpace القيمة false، وتمت إعادة تسمية MoveListener إلى EntityMoveListener shouldDisposeParentAnchor، ثم إلى disposeParentOnReAnchor systemMovable، وتمت إزالتها من الدالة create لصالح creeateCustomMovable وcreateSystemMovable وcreateAnchorable (If11c4)
  • تمت إزالة SurfaceEntity.featherRadiusX/Y وإضافة مفهوم الفئة EdgeFeatheringParams. (Ic78fc)
  • تم استبدال الطريقة PanelEntity.enablePanelDepthTest() بالسمة panelClippingConfig. اضبط Scene.panelClippingConfig = PanelClippingConfig(isDepthTestEnabled = true) لتفعيل اختبار العمق أو اضبطه على PanelClippingConfig(isDepthTestEnabled = false) لإيقافه. (I0cbe0)
  • أصبح نوع Scene.mainPanelEntity الآن MainPanelEntity بدلاً من PanelEntity (I7125a)
  • تمت إعادة تسمية طريقة setFullSpaceMode في Scene إلى configureBundleForFullSpaceModeLaunch وطريقة setFullSpaceModeWithEnvironmentInherited إلى configureBundleForFullSpaceModeLaunchWithEnvironmentInherited. (I0cbe0) (I0cbe0)
  • تمت إعادة تسمية قيم UNKNOWN وOUTSIDE_FOV وPARTIALLY_WITHIN_FOV وWITHIN_FOV في SpatialVisibility إلى SPATIAL_VISIBILITY_UNKNOWN وSPATIAL_VISIBILITY_OUTSIDE_FIELD_OF_VIEW وSPATIAL_VISIBILITY_PARTIALLY_WITHIN_FIELD_OF_VIEW وSPATIAL_VISIBILITY_WITHIN_FIELD_OF_VIEW على التوالي (Ie7e8c)
  • تم استبدال الفئة SpatialVisibility بكائن عام يتضمّن قيم Int ثابتة. تقبل setSpatialVisibilityChangedListener الآن Consumer<Int> بدلاً من Consumer<SpatialVisibility> (Ie7e8c)
  • تمت إعادة تسمية الثوابت PointerCaptureComponent ونقلها إلى العنصر PointerCaptureComponent.PointerCaptureState (I9c7ac)
  • تم استبدال PointerCaptureComponents' StateListener بـ Consumer<Int>. (I9c7ac)
  • تم استبدال "InputEventListener" بـ "Consumer<InputEvent>" (I9c7ac)
  • تم نقل setPreferredAspectRatio من فئة "المشهد" إلى العنصر SpatialWindow، ويتم إدخال الجلسة كمَعلمة أولى. (I7b717)
  • تم استبدال Entity.setHidden() بـ Entity.setEnabled()، وتم استبدال Entity.isHidden() بـ Entity.isEnabled(). setHidden(false) تساوي setEnabled(true) وisHidden() == !isEnabled(). (Icf0de)
  • تم تغيير نوع Entity.contentDescription من "سلسلة" إلى CharSequence. (Ie59be)
  • تعرض الدالتان Session.create وSession.configure الآن الخطأ SecurityException عند عدم منح أذونات كافية بدلاً من عرض SessionCreatePermissionsNotGranted أو SessionConfigurePermissionsNotGranted. (I7c488)
  • يتطلّب ResizableComponent.create الآن Consumer<ResizeEvent> ResizeEventListener تم استبداله بـ Consumer<ResizeEvent> ResizableComponent.size تمت إعادة تسميته إلى ResizableComponent.affordanceSize ResizableComponent.minimumSize تمت إعادة تسميته إلى ResizableComponent.minimumEntitySize ResizableComponent.maximumSize تمت إعادة تسميته إلى ResizableComponent.maximumEntitySize، تمت إعادة تسمية ResizableComponent.autoHideContent إلى ResizableComponent.shouldAutoHideContent تمت إعادة تسمية ResizableComponent.forceShowResizeOverlay إلى ResizableComponent.shouldAlwaysShowOverlay (I97a2d)
  • تم خفض minSDK إلى 24 بالنسبة إلى androidx.xr.scenecore وandroidx.xr.compose. ستظل حِزم XR تتطلّب استخدام الإصدار 34 من واجهة برمجة التطبيقات في وقت التشغيل. (I17224)
  • تمت إزالة القيود المفروضة على RequiresApi(34) في جميع حِزم Jetpack XR. كان هذا القيد غير ضروري لأنّ Jetpack XR لا يتوفّر حاليًا إلا على الأجهزة التي تعمل بالإصدار 34 من واجهة برمجة التطبيقات أو الإصدارات الأحدث. (Iae0f8)
  • سيحتوي العنصر الرئيسي SceneCore (xr:scenecore:scenecore) على واجهات برمجة تطبيقات غير متزامنة بنمط Kotlin فقط. يمكن لمطوّري تطبيقات Java الاعتماد على مكتبة xr:scenecore:scenecore-guava للوصول إلى واجهات برمجة التطبيقات المتوافقة. (If221b)
  • تتطلّب المشاريع التي تم إصدارها باستخدام Kotlin 2.0 استخدام الإصدار 2.0.0 أو إصدار أحدث من KGP (Idb6b5)
  • تستخدم هذه المكتبة الآن تعليقات توضيحية بشأن القيم الخالية في JSpecify، وهي تعليقات توضيحية خاصة بالاستخدام. على مطوّري Kotlin استخدام وسيطة المترجم البرمجي التالية لفرض الاستخدام الصحيح: -Xjspecify-annotations=strict (هذه هي القيمة التلقائية بدءًا من الإصدار 2.1.0 من مترجم Kotlin البرمجي) (Ia8420)
  • تم استبدال جميع الطرق غير المتزامنة التي تعرض ListenableFuture بدوال تعليق في Kotlin. على مطوّري Java الذين يريدون استخدام طرق غير متزامنة مستندة إلى ListenableFuture بدلاً من دوال التعليق في Kotlin استخدام دوال الإضافة في :xr:scenecore-scenecore-guava. على سبيل المثال، يحتوي GuavaExrImage على دوال ExrImage غير المتزامنة المكافئة لـ Guava، ويحتوي GuavaScenePose على دوال ScenePose غير المتزامنة المكافئة لـ Guava، ويحتوي GuavaGltfModel على دوال Guava-equivalent GltfModel غير المتزامنة، وما إلى ذلك. (If7283) (I0af60) (If7283) (Ia8515) (I4efdf) (I54bbf) (I3467a) (I82a33)

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

  • تم تعديل قاعدة Jetpack XR Scenecore ProGuard لمنع AbstractMethodError للعملاء المصغّرين. (I91a01)
  • إصلاحات إضافية لتوفير دعم تصغير Proguard في Jetpack XR SceneCore (I4f47e)
  • تم إصلاح الخطأ الذي قد يتسبّب فيه InteractableComponent في حدوث عُطل إذا كان hitPosition في HitInfo الخاص بـ InputEvent قد يتعطّل إذا كانت قيمة hitPosition التي تم إرجاعها من النظام فارغة (I7a695).
  • تمت إعادة تسمية قيم *Mode في ملف الإعداد لتعكس سلوكها. (I6d247)
  • تم إصلاح المشاكل المتعلّقة بمجال الرؤية وHitTest في SceneCore TestApp. (I2c51e)
  • تم إصلاح الخطأ في SpatialCapabilities.hasCapability() الذي كان يعرض القيمة "صحيح" إذا كانت أي من الإمكانات التي تم تمريرها باستخدام OR على مستوى البت صحيحة، بدلاً من عرض القيمة "صحيح" فقط إذا كانت جميعها صحيحة. (I2cd40)
  • تم تعديل SurfaceEntity.StereoMode.TOP_BOTTOM بحيث تكون الخريطة العلوية للعين اليسرى والخريطة السفلية للعين اليمنى. (I4ae68)

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