Jetpack SceneCore

{} {}

Jetpack SceneCore

نمونه کد راهنمای کاربر

مرجع API
androidx.xr.scenecore
androidx.xr.scenecore.testing

نمودار صحنه Android XR را با محتوای سه بعدی بسازید و دستکاری کنید.

آخرین به روز رسانی	انتشار پایدار	کاندید را آزاد کنید	نسخه بتا	انتشار آلفا
12 فوریه 2025	-	-	-	1.0.0-alpha02

اعلام وابستگی ها

برای افزودن وابستگی به 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"
}

کاتلین

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() یک شی SpatialCapabilities را برمی گرداند، به نفع استفاده از getSpatialCapabilities().hasCapability() به عنوان یک روش بخش بندی شده تر برای بررسی وجود قابلیت های فضایی جایگزین شده است.
  • 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 شعاع گوشه پیش فرض 32dp یا کمتر خواهند داشت اگر پانل عرض یا ارتفاع کمتر از 32dp داشته باشد.

API ها و قابلیت های جدید

• StereoSurface.CanvasShape را معرفی می کند که امکان ایجاد بوم های Spherical و Hemispherical برای رندر کردن رسانه های همه جانبه فراهم می کند.
• StereoSurfaceEntity.create() اکنون یک پارامتر CanvasShape را می پذیرد. (این پارامتر در حال حاضر نادیده گرفته شده است، اما در نسخه بعدی استفاده خواهد شد)
• StereoSurfaceEntity.create() دیگر پارامتر Dimensions را نمی گیرد. برنامه ها باید اندازه بوم را از طریق تنظیم CanvasShape کنترل کنند
• StereoSurfaceEntity یک عضو CanvasShape دارد که می تواند به صورت پویا تنظیم شود.
• StereoSurfaceEntity.dimensions اکنون یک ویژگی فقط خواندنی است. برنامه ها باید CanvasShape را برای تغییر ابعاد تنظیم کنند.
• StereoSurfaceEntity اکنون اجازه می دهد تا StereoMode پس از ساخت دوباره تنظیم شود.

تغییرات دیگر

• زمان کامپایل minSDK را به 24 کاهش داد. همه APIهای Jetpack XR همچنان به API 34 در زمان اجرا نیاز دارند.
• کارخانه جلسه SceneCore ( Session.create ) دیگر قصدی برای دریافت مجوز SCENE_UNDERSTANDING راه اندازی نمی کند. در عوض، برنامه سرویس گیرنده باید به صراحت مجوزها را از کاربر، قبل از تلاش برای ایجاد لنگرها درخواست کند. اگر مجوز توسط کاربر اعطا نشود، ایجاد لنگر با شکست مواجه خواهد شد.

رفع اشکال

• getActivitySpacePose() برای محاسبه مقیاس ActivitySpace با برگرداندن مقادیر ترجمه در مترهای مقیاس شده به جای برگرداندن همیشه مترهای غیرمقیاس ثابت شده است. transformPoseTo اکنون همچنین از واحدهای مناسب برای محاسبه تغییرات مختصات زمانی که ActivitySpace در منبع یا مقصد درگیر است استفاده می کند.
• هر زمان که اولویت اسکای باکس تهی با استفاده از setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) منتقل شود، اکنون skybox روی یک skybox کاملا سیاه تنظیم می شود. برای بازگشت به skybox و هندسه پیش فرض سیستم، از setSpatialEnvironmentPreference(null).

نسخه 1.0.0-alpha01

12 دسامبر 2024

androidx.xr.scenecore:scenecore-* 1.0.0-alpha01 منتشر شد.

ویژگی های Initial Release انتشار اولیه Jetpack SceneCore توسط توسعه دهندگان، یک کتابخانه نمودار صحنه سه بعدی برای ایجاد و دستکاری صحنه ها و محیط های غوطه ور. این کتابخانه به شما امکان می دهد مدل های سه بعدی و پنل های محتوا را نسبت به یکدیگر و محیط های مجازی یا دنیای واقعی خود قرار دهید و ترتیب دهید.

• محیط فضایی : با یک تصویر skybox و/یا هندسه مدل سه بعدی به عنوان پس‌زمینه صحنه XR محیط خود، تجربیات کاملاً فراگیر ایجاد کنید. یا عبور را فعال کنید تا صحنه مجازی شما بتواند با محیط دنیای واقعی کاربر ادغام شود.
• PanelEntity : با قرار دادن طرح‌بندی‌ها و فعالیت‌های استاندارد اندروید در پانل‌های فضایی که می‌توانند شناور شوند یا به سطوح واقعی متصل شوند، محتوای دو بعدی را به صحنه‌های سه بعدی خود اضافه کنید.
• GltfModelEntity : قرار دادن، متحرک سازی و تعامل با مدل های سه بعدی در صحنه خود. SceneCore از فرمت فایل glTF برای سهولت ادغام با مدل های موجود پشتیبانی می کند.
• SpatialAudio : منابع صوتی محیطی و نقطه‌ای را به صحنه سه‌بعدی خود اضافه کنید تا صدایی کاملاً فراگیر و فضایی.
• StereoSurfaceEntity : SceneCore از مسیریابی چشم چپ/راست محتوای ارائه شده بر روی Surface اندروید پشتیبانی می کند. این می تواند برای ارائه محتوای استریوسکوپی در قالب کنار هم یا از بالا به پایین، مانند عکس های استریو، ویدیوهای سه بعدی یا سایر رابط های کاربری که به صورت پویا ارائه می شوند، استفاده شود. برنامه ها باید از MediaPlayer یا ExoPlayer برای رمزگشایی ویدیو استفاده کنند.
• سیستم مؤلفه: SceneCore یک سیستم مؤلفه قوی و منعطف را برای افزودن قابلیت‌هایی به محتوای XR شما ارائه می‌کند، از جمله امکاناتی برای جابجایی، تغییر اندازه و تعامل با مدل‌ها و پانل‌ها برای کاربران.
• Anchor : با فعال کردن گذر، می‌توانید پانل‌ها و مدل‌ها را به سطوح واقعی متصل کنید و به کاربران اجازه دهید محتوای مجازی را در محیط واقعی خود یکپارچه کنند.
• موقعیت کاربر: به موقعیت مکانی کاربر در صحنه مجازی دسترسی پیدا کنید تا محتوای خود را حول موقعیت کاربر جهت دهید.
• قابلیت‌های فضایی : برنامه‌های کاملاً تطبیقی ​​بسازید که در صورت در دسترس بودن از قابلیت‌های فضایی مانند موقعیت‌یابی سه‌بعدی محتوای UI استفاده می‌کنند. نه تنها این، بلکه برنامه شما می‌تواند تغییرات در قابلیت‌ها را در حین اجرای برنامه کنترل کند تا تجربه را بر اساس نحوه استفاده کاربر از دستگاه Android XR خود تغییر دهد.

مسائل شناخته شده

• در حال حاضر برای استفاده از Jetpack SceneCore یک minSDK 30 مورد نیاز است. به عنوان یک راه حل، ورودی مانیفست زیر را اضافه کنید <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> تا بتوانید با minSDK 23 بسازید و اجرا کنید.
• Session می‌تواند در موقعیت‌های مختلف که به طور خودکار فعالیت را دوباره ایجاد می‌کنند، نامعتبر شود، از جمله تغییر اندازه پانل اصلی، اتصال وسایل جانبی، و تغییر بین حالت روشن و تاریک. اگر با مشکلات عدم اعتبار جلسه مواجه شدید، راه‌حل‌ها عبارتند از غیرقابل تغییر اندازه پانل اصلی، استفاده از یک موجودیت پانل پویا، غیرفعال کردن بازآفرینی فعالیت برای تغییرات پیکربندی خاص یا غیرفعال کردن تغییرات تم حالت روشن/تاریک.
• اجزای متحرک و قابل تغییر اندازه در GltfEntity پشتیبانی نمی شوند.
• Entity.getSize() در GltfEntity پشتیبانی نمی شود.
• برنامه‌های Jetpack XR برای درخواست مجوز android.permission.SCENE_UNDERSTANDING در AndroidManifest مورد نیاز است.
• ایجاد یک جلسه فقط در دستگاه Android XR پشتیبانی می شود. در این زمان، اگر یک Session ایجاد کنید و سعی کنید از آن در دستگاه غیر Android XR استفاده کنید، یک RuntimeException دریافت خواهید کرد.
• تنظیم skybox به تهی از طریق `SpatialEnvironment.setSpatialEnvironmentPreference() منجر به ایجاد یک skybox سیاه و سفید ثابت نمی شود. ممکن است منجر به skybox پیش فرض سیستم یا عدم تغییر در skybox فعلی شود.
• مشتریان SceneCore باید implementation(“com.google.guava:listenablefuture-1.0”) به پیکربندی Gradle خود برای وابستگی های برنامه خود اضافه کنند. در نسخه‌های بعدی، منظره این کتابخانه را به‌عنوان یک وابستگی api در بر می‌گیرد، بنابراین مشتریان نیازی به اعلام صریح آن ندارند.
• SceneCore به اشتباه com.google.guava:guava-31.1-android و com.google.protobuf:protobuf-javalite را به عنوان وابستگی های گذرا شامل می شود. اگر این منجر به خطاهای کلاس تکراری در ساخت شما شود، این دو وابستگی را می توان با خیال راحت حذف کرد.
• اگر برنامه شما از SceneCore استفاده می کند و ProGuard را فعال می کند، هنگام ایجاد Session از کار می افتد. به عنوان یک راه حل، ProGuard را غیرفعال کنید. برای اطلاعات بیشتر در مورد نحوه فعال کردن ProGuard به این راهنما مراجعه کنید.