Jetpack SceneCore

3D içeriklerle Android XR sahne grafiğini oluşturun ve değiştirin.
Son Güncelleme Kararlı sürüm Sürüm Adayı Beta Sürümü Alfa sürümü
7 Mayıs 2025 - - - 1.0.0-alpha04

Bağımlılıkları bildirme

XR SceneCore'a bağımlılık eklemek için Google Maven deposunu projenize eklemeniz gerekir. Daha fazla bilgi için Google'ın Maven deposunu okuyun.

Uygulamanız veya modülünüz için build.gradle dosyasına ihtiyacınız olan yapılarla ilgili bağımlılıkları ekleyin:

Eski

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

Bağımlılıklar hakkında daha fazla bilgi için Derleme bağımlılıkları ekleme başlıklı makaleyi inceleyin.

Geri bildirim

Geri bildiriminiz Jetpack'in iyileştirilmesine yardımcı olur. Yeni sorunlar keşfederseniz veya bu kitaplığı iyileştirmeye yönelik fikirleriniz olursa lütfen bize bildirin. Yeni bir sorun oluşturmadan önce lütfen bu kitaplıktaki mevcut sorunlara göz atın. Yıldız düğmesini tıklayarak mevcut bir soruna oyunuzu ekleyebilirsiniz.

Yeni sorun oluşturma

Daha fazla bilgi için Sorun İzleyici belgelerini inceleyin.

Sürüm 1.0

Sürüm 1.0.0-alpha04

7 Mayıs 2025

androidx.xr.scenecore:scenecore:1.0.0-alpha04 ve androidx.xr.scenecore:scenecore-testing:1.0.0-alpha04 yayınlandı. 1.0.0-alpha04 sürümü bu commit'leri içerir.

Yeni Özellikler

  • Geriye dönük işleme artık yerleştirilmiş etkinlikler içermeyen panel öğelerinde çalışacak. Geriye doğru işleme özelliğinin çalışması için Android manifestinde android:enableOnBackInvokedCallback= "true" belirtmeniz gerekir.
  • StereoSurfaceEntity artık MULTIVIEW_LEFT_PRIMARY ve MULTIVIEW_RIGHT_PRIMARY olmak üzere iki yeni StereoMode değeriyle MV-HEVC oynatmayı destekliyor.
  • PanelEntity.setSize ve PanelEntity.getSize artık üst alandaki boyutları döndürüyor.
  • Entity.setPose, Entity.getPose, Entity.setScale, Entity.getScale, Entity.setAlpha ve Entity.getAlpha artık farklı alanlara göre değerlerin alınmasına/ayarlanmasına olanak tanıyan yeni bir parametre relativeTo alıyor. Desteklenen değerler Parent, Activity ve Real World spaces'tir. Bu parametrenin varsayılan değeri Parent'tır.
  • Sahne içeriğinin kullanıcının görüş alanının içine veya dışına taşındığı zamanı izlemek için SessionExt.kt'ya Spatial Visibility Callback uzantı yöntemleri eklendi.
  • setPointSourceParams, SpatialAudioTrack'ye eklendi. Bu sayede, parça oluşturulduktan sonra parametrelerin güncellenmesine olanak tanındı.
  • Scenecore API'lerine referanslar içeren yeni bir sınıf (Sahne) eklendi. Sahne, oturumun bir uzantı özelliği olarak erişilebilir. SessionExt içindeki işlevler Scene'e taşındı. Bu nedenle, içe aktarmaların ayarlanması gerekecek. Örneğin, SessionExt.getScene(session).addSpatialCapababilitiesChangedListener - SessionExt.addSpatialCapabilitiesChangedListener.
  • ActivityPose.hitTestAsync eklendi. Bu sayede, sanal içeriklere karşı hitTest kullanılabiliyor.
  • Yeni bileşen türü SpatialPointerComponent eklendi. Bu tür, müşterilerin işaretçi için oluşturulan simgeyi belirtmesine veya simgeyi devre dışı bırakmasına olanak tanır. Bu Bileşen şu anda yalnızca PanelEntity örneğe eklenebilir.
  • Yeni PanelEntity fabrika işleviyle tanışın. Bu işlev, panel boyutlarını metre veya piksel cinsinden alır. Panel için iki boyut türü parametresi alan eski PanelEntity fabrikası kaldırıldı.

API Değişiklikleri

  • Tüm Jetpack XR paketlerindeki RequiresApi(34) kısıtlaması kaldırıldı. Jetpack XR şu anda yalnızca API düzeyi 34 ve üzeri olan cihazlarda kullanılabildiğinden bu kısıtlama gereksizdi. (Iae0f8)
  • Kotlin 2.0 ile yayınlanan projelerin kullanılabilmesi için KGP 2.0.0 veya daha yeni bir sürüm gerekir (Idb6b5).
  • PermissionHelper sınıfı kaldırıldı.
  • PanelEntity.getPixelDensity desteği sonlandırıldı.
  • PanelEntity.setPixelDimensions ve PanelEntity.getPixelDimension kaldırıldı, yerini setSizeInPixels ve getSizeInPixels aldı.
  • Entity.getActivitySpaceAlpha kaldırıldı. Entity.getAlpha(Space.Activity) ile değiştirilebilir.
  • Entity.getWorldSpaceScale kaldırıldı. Entity.getScale(Space.REAL\_WORLD) ile değiştirilebilir.
  • SceneCore içindeki Oturum sınıfı, XR Runtime'daki Oturum sınıfı lehine silindi.
  • StereoSurfaceEntity, SurfaceEntity olarak yeniden adlandırıldı.
  • Entity.setSize ve Entity.getSize kaldırıldı ve aynı yöntemler PanelEntity'ye eklendi.
  • PointSourceAttributes, PointSourceParams olarak yeniden adlandırıldı.
  • SpatializerConstants.SOURCE\_TYPE\_BYPASS, SpatializerConstants.SOURCE\_TYPE\_DEFAULT olarak yeniden adlandırıldı.
  • PointSourceParams öğesinin erişimi herkese açık yerine kuruluş içi olarak değiştirildi.
  • AnchorEntity.create artık Session.configure() içinde PlaneTrackingMode yapılandırılmasını gerektiriyor.
  • SpatialUser API'leri artık Session.configure() içinde HeadTrackingMode yapılandırılmasını gerektiriyor.
  • ResizableComponent eklenmediğinde HATA düzeyinde günlük yerine BİLGİ düzeyinde günlük verilir.
  • Fov sınıfı artık normal bir Kotlin sınıfıdır.
  • Her somut varlık türünü kendi dosyasına yerleştirmek için Entity.kt öğesini bölün.
  • Yeni bir PanelEntity oluştururken çoğu görünüm FrameLayout olarak yeniden üst öğe atanır. Bu, LayoutInspector ile Spatial Panels'in kullanımını kolaylaştırır.
  • Şu anda kullanılan XrExtensions örneği, uygulama hata ayıklamasına yardımcı olmak için platforma en iyi şekilde kayıtlıdır.

Hata Düzeltmeleri

  • MovableComponent ve AnchorPlacement içeren bir PanelEntity taşındığında oluşabilecek kilitlenmeyi önlemek için düzeltme eklendi.
  • ResizableComponent öğesinin onResizeStart geri çağırmasında eski boyutlar sağlaması sorunu düzeltildi.
  • JxrPlatformAdapterAxr'nın dispose() işlevi birden çok kez çağrıldığında yaşanan kilitlenme sorunu düzeltildi.

Sürüm 1.0.0-alpha03

26 Şubat 2025

androidx.xr.scenecore:scenecore:1.0.0-alpha03 ve androidx.xr.scenecore:scenecore-testing:1.0.0-alpha03 yayınlandı. Sürüm 1.0.0-alpha03, bu commit'leri içerir.

Yeni Özellikler

  • Proguard sadeleştirme artık Jetpack XR kodu için destekleniyor

Hata Düzeltmeleri

  • Jetpack XR SceneCore için Proguard küçültmesini destekleyen ek düzeltmeler (I4f47e)
  • Küçültülmüş istemcilerde AbstractMethodError sorununu önlemek için güncellenmiş Jetpack XR Scenecore ProGuard kuralı. (I91a01)

Sürüm 1.0.0-alpha02

12 Şubat 2025

androidx.xr.scenecore:scenecore:1.0.0-alpha02 ve androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02 yayınlandı. 1.0.0-alpha02 sürümü bu commit'leri içerir.

1.0.0-alpha02 sürümünden önce oluşturulan uygulamaları etkileyecek önemli değişiklik

  • Fabrika yöntemleri, Session sınıfından her bir ilgili türdeki yardımcı yönteme taşındı:
    • Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) silindi ve ActivityPanelEntity.create(Session, Dimensions, String, Pose) ile değiştirildi
    • Session.createAnchorEntity(Anchor) silindi ve AnchorEntity.create(Session, Anchor) ile değiştirildi
    • Session.createAnchorEntity(Dimensions, Int, Int, Duration) silindi ve AnchorEntity.create(Session, Dimensions, Int, Int, Duration) ile değiştirildi
    • Session.createEntity(String, Pose) silindi ve ContentlessEntity.create(Session, String, Pose) ile değiştirildi
    • Session.createExrImageResource(String) silindi ve ExrImage.create(Session, String) ile değiştirildi
    • Session.createGltfEntity(GltfModel, Pose) silindi ve GltfModelEntity.create(Session, GltfModel, Pose) ile değiştirildi
    • Session.createGltfModelResource(String) silindi ve GltfModel.create(Session, String) ile değiştirildi
    • Session.createInteractableComponent(Executor, InputEventListener) silindi ve InteractableComponent.create(Session, Executor, InputEventListener) ile değiştirildi
    • Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) silindi ve MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean) ile değiştirildi
    • Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) silindi ve PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose) ile değiştirildi
    • Session.createResizableComponent(Dimensions, Dimensions) silindi ve ResizableComponent.create(Session, Dimensions, Dimensions) ile değiştirildi
    • Session.createStereoSurfaceEntity(Int, Dimensions, Pose) silindi ve StereoSurface.create(Session, Int, Dimensions, Pose) ile değiştirildi
  • Desteği sonlandırılan aşağıdaki yöntemler kaldırıldı:
    • Session.canEmbedActivityPanel(Activity) silindi. Bunun yerine getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY) politikasını kullanın.
    • Session.hasSpatialCapability(Int) silindi. getSpatialCapabilities(), SpatialCapabilities nesnesi döndürdüğünden, getSpatialCapabilities().hasCapability()'nın uzamsal özelliklerin varlığını kontrol etmek için daha bölümlere ayrılmış bir yöntem olarak kullanılması tercih edilerek bu yöntem değiştirildi.
    • Session.requestFullSpaceMode() silindi ve SpatialEnvironment.requestFullSpaceMode() ile değiştirildi
    • Session.requestHomeSpaceMode() silindi ve SpatialEnvironment.requestHomeSpaceMode() ile değiştirildi
  • Session.setFullSpaceMode(Bundle) ve Session.setFullSpaceModeWithEnvironmentInherited(Bundle), uzantı işlevlerine taşındı. Geliştirici dosyalarının erişim için yeni içe aktarmaları eklemesi gerekir:
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float), uzantı işlevine taşındı. Geliştirici dosyalarının erişim için yeni içe aktarma işlemini eklemesi gerekir:
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Session.getEntitiesOfType(Class<out T>) ve Session.getEntityForRtEntity(RtEntity), uzantı işlevlerine taşındı. Geliştirici dosyalarının erişim için yeni içe aktarmaları eklemesi gerekir:
    • import androidx.xr.scenecore.getEntitiesOfType
    • import androidx.xr.scenecore.getEntityForRtEntity
  • Session.unpersistAnchor(Anchor) silindi
  • Session.createPersistedAnchorEntity(UUID) silindi

Bilinen sorunlar

  • PanelEntity.setCornerRadius() ve ActivityPanelEntity.setCornerRadius(), panel bir sonraki taşıma işlemine kadar geçerli olmayabilir. Bu durum, paneli mevcut konumuna taşıyarak giderilebilir.
  • BoundsChanged, ActivitySpace cihazında arandığında bazı ActivityPose cihazları doğru şekilde güncellenmemiş olabilir. ActivitySpace tarihinde yapılacak OnSpaceUpdated görüşmesinde güncellenecektir.

Kırılma ve davranış değişiklikleri

  • Panelin genişliği veya yüksekliği 32 dp'den küçükse PanelEntity ve ActivityPanelEntity için varsayılan köşe yarıçapı 32 dp veya daha küçük olur.

Yeni API'ler ve özellikler

  • StereoSurface.CanvasShape özelliğini kullanıma sunar. Bu özellik, etkileyici medya oluşturmak için Spherical ve Hemispherical tuvallerinin oluşturulmasına olanak tanır.
  • StereoSurfaceEntity.create() artık CanvasShape parametresini kabul ediyor. (Bu parametre şu anda yoksayılmaktadır ancak gelecekteki bir sürümde kullanılacaktır.)
  • StereoSurfaceEntity.create() artık Dimensions parametresini kullanmıyor. Uygulamalar, CanvasShape ayarını yaparak tuvalin boyutunu kontrol etmelidir.
  • StereoSurfaceEntity, dinamik olarak ayarlanabilen CanvasShape üyesine sahiptir.
  • StereoSurfaceEntity.dimensions artık salt okunur bir özelliktir. Uygulamalar, boyutları değiştirmek için CanvasShape değerini ayarlamalıdır.
  • StereoSurfaceEntity artık StereoMode'ın yapılandırmadan sonra yeniden ayarlanmasına izin veriyor.

Diğer değişiklikler

  • Derleme zamanı minSDK 24'e düşürüldü. Tüm Jetpack XR API'leri, çalışma zamanında API 34 gerektirmeye devam eder.
  • SceneCore'nın oturum fabrikası (Session.create) artık SCENE_UNDERSTANDING iznini almak için bir amaç başlatmıyor. Bunun yerine, istemci uygulaması, bağlantı oluşturmaya çalışmadan önce izinleri kullanıcıdan açıkça istemelidir. Kullanıcı izin vermezse bağlantı oluşturma işlemi başarısız olur.

Hata düzeltmeleri

  • getActivitySpacePose(), her zaman ölçeklendirilmemiş metreler yerine ölçeklendirilmiş metrelerde çeviri değerleri döndürerek ActivitySpace ölçeğini hesaba katacak şekilde düzeltildi. transformPoseTo artık kaynak veya hedefte ActivitySpace olduğunda koordinat değişikliklerini hesaplamak için doğru birimleri de kullanıyor.
  • Artık setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) kullanılarak boş bir gökyüzü kutusu tercihi iletildiğinde gökyüzü kutusu tamamen siyah bir gökyüzü kutusu olarak ayarlanacak. Sistemin varsayılan gökyüzü kutusuna ve geometrisine geri dönmek için setSpatialEnvironmentPreference(null). kullanın.

Sürüm 1.0.0-alpha01

12 Aralık 2024

androidx.xr.scenecore:scenecore-* 1.0.0-alpha01 iptal edilir.

İlk Sürümün Özellikleri Etkileyici sahneler ve ortamlar oluşturup bunları düzenlemek için kullanılan 3D sahne grafiği kitaplığı Jetpack SceneCore'un ilk geliştirici sürümü. Bu kitaplık, 3D modelleri ve içerik panellerini birbirlerine ve sanal ya da gerçek dünya ortamlarınıza göre yerleştirip düzenlemenize olanak tanır.

  • SpatialEnvironment: Ortamınızın XR sahnesinin arka planı olarak gökyüzü resmi ve/veya 3D model geometrisiyle tamamen sürükleyici deneyimler oluşturun. Alternatif olarak, sanal sahnenizin kullanıcının gerçek dünya ortamıyla entegre olabilmesi için geçişi etkinleştirin.
  • PanelEntity: Standart Android düzenlerini ve etkinliklerini, gerçek dünyadaki yüzeylere sabitlenebilen veya yüzeylerde kaydırılabilen, uzamsallaştırılmış panellere yerleştirerek 3D sahnelerinize 2D içerik ekleyin.
  • GltfModelEntity: Sahnenizdeki 3D modelleri yerleştirin, canlandırın ve bunlarla etkileşimde bulunun. SceneCore, mevcut modellerle kolay entegrasyon için glTF dosya biçimini destekler.
  • SpatialAudio: Tamamen etkileyici ve uzamsallaştırılmış ses için 3D sahnenize ortam ve nokta ses kaynakları ekleyin.
  • StereoSurfaceEntity: SceneCore, Android Surface'e işlenen içeriğin sol/sağ göz yönlendirmesini destekler. Bu, yan yana veya üst-alt biçiminde stereoskopik içerik oluşturmak için kullanılabilir. Örneğin, stereo fotoğraflar, 3D video veya dinamik olarak oluşturulan diğer kullanıcı arayüzleri. Uygulamalar, video kod çözme için MediaPlayer veya ExoPlayer'ı kullanmalıdır.
  • Bileşen sistemi: SceneCore, kullanıcıların modeller ve panellerle hareket etme, yeniden boyutlandırma ve etkileşim kurma gibi olanaklar da dahil olmak üzere XR içeriğinize özellikler eklemek için güçlü ve esnek bir bileşen sistemi sunar.
  • Sabitleme: Geçiş etkinleştirildiğinde panelleri ve modelleri gerçek yüzeylere ekleyebilir, böylece kullanıcılar sanal içeriği gerçek dünya ortamlarına sorunsuz bir şekilde entegre edebilir.
  • Kullanıcı Pozu: İçeriğinizi kullanıcının konumuna göre yönlendirmek için sanal sahnedeki kullanıcının konumuna erişin.
  • SpatialCapabilities: Kullanılabilir olduğunda, kullanıcı arayüzü içeriğinin 3D konumlandırılması gibi uzamsallaştırılmış özelliklerden yararlanan, tamamen uyarlanabilir uygulamalar oluşturun. Bununla da kalmayıp uygulamanız, kullanıcıların Android XR cihazlarını kullanma şekillerine göre deneyimi değiştirmek için uygulama yürütülürken özelliklerdeki değişiklikleri izleyebilir.

Bilinen Sorunlar

  • Jetpack SceneCore'un kullanılabilmesi için şu anda minimum SDK sürümü 30 olmalıdır. Geçici çözüm olarak, 23 minSDK ile derleme ve çalıştırma yapabilmek için aşağıdaki manifest girişini <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> ekleyin.
  • Oturum, ana paneli yeniden boyutlandırma, çevre birimleri bağlama ve açık ile koyu mod arasında geçiş yapma gibi Etkinliğin otomatik olarak yeniden oluşturulduğu çeşitli durumlarda geçersiz hale gelebilir. Oturum geçersiz kılma sorunlarıyla karşılaşırsanız geçici çözümler arasında ana panelinizi yeniden boyutlandırılamaz hale getirme, dinamik panel öğesi kullanma, belirli yapılandırma değişiklikleri için etkinlik yeniden oluşturmayı devre dışı bırakma veya açık/koyu mod tema değişikliklerini devre dışı bırakma yer alır.
  • GltfEntity'de taşınabilir ve yeniden boyutlandırılabilir bileşenler desteklenmez.
  • Entity.getSize() işlevi, GltfEntity'de desteklenmez.
  • Jetpack XR uygulamalarının AndroidManifest'te android.permission.SCENE_UNDERSTANDING izni istemesi gerekir.
  • Oturum oluşturma yalnızca Android XR cihazlarda desteklenir. Şu anda bir oturum oluşturup Android XR olmayan bir cihazda kullanmaya çalışırsanız RuntimeException hatası alırsınız.
  • `SpatialEnvironment.setSpatialEnvironmentPreference()` ile gökyüzü kutusunun null olarak ayarlanması, belgelendiği gibi tamamen siyah bir gökyüzü kutusuyla sonuçlanmıyor. Bu durumda sistemin varsayılan gökyüzü kutusu gösterilebilir veya mevcut gökyüzü kutusunda değişiklik yapılmayabilir.
  • SceneCore istemcileri, uygulamalarının bağımlılıkları için Gradle yapılandırmalarına implementation(“com.google.guava:listenablefuture-1.0”) eklemelidir. Gelecekteki bir sürümde, scenecore bu kitaplığı api bağımlılık olarak içerecek. Böylece istemcilerin bunu açıkça bildirmesi gerekmeyecek.
  • SceneCore, com.google.guava:guava-31.1-android ve com.google.protobuf:protobuf-javalite öğelerini yanlışlıkla geçişli bağımlılık olarak içeriyor. Bu durum, derlemenizde yinelenen sınıf hatalarına neden olursa bu iki bağımlılık güvenli bir şekilde hariç tutulabilir.
  • Uygulamanız SceneCore kullanıyor ve ProGuard'ı etkinleştiriyorsa oturum oluşturduğunuzda uygulama çöker. Geçici çözüm olarak ProGuard'ı devre dışı bırakın. ProGuard'ı etkinleştirme hakkında daha fazla bilgi için bu kılavuza bakın.