{ } { }

Jetpack SceneCore

3D içerikle Android XR sahne grafiği oluşturun ve bu grafiği 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ı beyan etme

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

Uygulamanızın veya modülünüzün build.gradle dosyasına ihtiyacınız olan yapıların bağımlılıklarını 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ştirmek için fikirleriniz varsa lütfen bize bildirin. Yeni bir kitaplık oluşturmadan önce lütfen bu kitaplıktaki mevcut sorunlara göz atın. Yıldız düğmesini tıklayarak mevcut bir soruna oy verebilirsiniz.

Yeni bir sorun oluşturma

Daha fazla bilgi için Sorun İzleyici belgelerine bakın.

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 taahhütleri içerir.

Yeni Özellikler

  • Geri işleme artık yerleşik etkinlikleri olmayan panel varlıkları üzerinde çalışacak. Geri işleme özelliğinin çalışması için Android manifest dosyasında android:enableOnBackInvokedCallback= "true" belirtmeniz gerekir.
  • StereoSurfaceEntity artık iki yeni StereoMode değeriyle (MULTIVIEW_LEFT_PRIMARY ve MULTIVIEW_RIGHT_PRIMARY) MV-HEVC oynatmayı destekliyor.
  • PanelEntity.setSize ve PanelEntity.getSize artık boyutları üst alanda döndürüyor.
  • Entity.setPose, Entity.getPose, Entity.setScale, Entity.getScale, Entity.setAlpha ve Entity.getAlpha artık farklı alanlara göre değer alma/ayarlama olanağı sunan yeni bir parametre relativeTo alıyor. Desteklenen değerler üst, etkinlik ve gerçek dünya alanlarıdır. Bu parametrenin varsayılan değeri üsttür.
  • Sahne içeriğinin kullanıcının görüş alanının içine veya dışına ne zaman taşındığını izlemek için SessionExt.kt'e eklenen Mekansal Görünürlüğü Geri Çağırma uzantı yöntemleri.
  • setPointSourceParams, SpatialAudioTrack'a eklendi. Bu sayede, kanal oluşturulduktan sonra parametrelerin güncellenmesi sağlandı.
  • Scenecore API'lerine referanslar içeren yeni bir sınıf (Scene) eklendi. Sahne, Oturum'un bir uzantı mülkü olarak erişilebilir. SessionExt içindeki işlevler Scene'e taşındığı için içe aktarma işlemlerinin (ör. SessionExt.getScene(session)) düzenlenmesi gerekir.addSpatialCapababilitiesChangedListener - SessionExt.addSpatialCapabilitiesChangedListener.
  • ActivityPose.hitTestAsync eklendi. Bu, sanal içeriklere karşı hitTest yapılmasına olanak tanır.
  • İstemcilerin işaretçi için oluşturulan simgeyi belirtmesine veya simgeyi devre dışı bırakmasına olanak tanıyan yeni bileşen türü SpatialPointerComponent eklendi. Bu bileşen şu anda yalnızca PanelEntity örneklerine eklenebilir.
  • Panel boyutlarını metre veya piksel cinsinden alan yeni PanelEntity fabrikasını kullanıma sunuyoruz. Panel için iki Boyut türü parametresi alan eski PanelEntity fabrikası kaldırıldı.

API Değişiklikleri

  • Tüm Jetpack XR paketlerinde RequiresApi(34) kısıtlaması kaldırıldı. Jetpack XR şu anda yalnızca API düzeyi 34 ve sonraki sürümleri çalıştıran cihazlarda kullanılabildiğinden bu kısıtlama gereksiz hale gelmişti. (Iae0f8)
  • Kotlin 2.0 ile yayınlanan projelerin kullanılması 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ılır, yerlerine setSizeInPixels ve getSizeInPixels gelir.
  • 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'teki Session sınıfı, XR Runtime'daki Session 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 herkese açık erişimi, şirket içi erişim olarak değiştirildi.
  • AnchorEntity.create için artık PlaneTrackingMode'nin Session.configure()'de yapılandırılması gerekiyor.
  • SpatialUser API'leri artık HeadTrackingMode'nin Session.configure()'de yapılandırılmasını gerektiriyor.
  • ResizableComponent eklenmediğinde ERROR düzeyinde günlük yerine INFO 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 dosyasını bölün.
  • Yeni bir PanelEntity oluşturulduğunda çoğu görünüm, FrameLayout ile yeniden ilişkilendirilir. Bu, LayoutInspector'ün Spatial Paneller ile kullanımını kolaylaştırır.
  • Şu anda kullanılan XrExtensions örneği, uygulama hata ayıklama işlemine yardımcı olmak için mümkün olduğunca platforma kaydedilir.

Hata Düzeltmeleri

  • MovableComponent ve AnchorPlacement içeren bir PanelEntity taşınırken oluşabilecek kilitlenmeyi önlemek için bir düzeltme eklendi
  • ResizableComponent'ün onResizeStart geri çağırma işlevinde eski boyutlar sağlaması sorunu düzeltildi.
  • JxrPlatformAdapterAxr nesnesinin dispose() işlevi birden çok kez çağrıldığında yaşanan kilitlenme 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ı. 1.0.0-alpha03 sürümü bu taahhütleri içerir.

Yeni Özellikler

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

Hata Düzeltmeleri

  • Jetpack XR SceneCore (I4f47e) için Proguard küçültmeyi destekleyen ek düzeltmeler
  • Jetpack XR Scenecore ProGuard kuralı, sıkıştırılmış istemciler için AbstractMethodError'yi önlemek üzere güncellendi. (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 taahhütleri 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 ilgili her türdeki bir 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
  • Aşağıdaki desteği sonlandırılan yöntemler kaldırıldı:
    • Session.canEmbedActivityPanel(Activity) silindi. Bunun yerine getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY)'ü kullanın.
    • Session.hasSpatialCapability(Int) silindi. getSpatialCapabilities() bir SpatialCapabilities nesnesi döndürdüğü için getSpatialCapabilities(), mekansal özelliklerin varlığını kontrol etmenin daha bölümlendirilmiş bir yolu olarak getSpatialCapabilities().hasCapability() ile 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şmek için yeni içe aktarma işlemlerini eklemesi gerekir:
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float), bir uzantı işlevine taşındı. Geliştirici dosyalarının erişmek 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şmek için yeni içe aktarma işlemlerini 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 kez taşınana kadar geçerli olmayabilir. Bu durum, paneli mevcut konumuna taşıyarak azaltılabilir.
  • ActivitySpace üzerinde BoundsChanged çağrıldığında bazı ActivityPose'ler doğru şekilde güncellenmeyebilir. Bu durum, ActivitySpace tarihinde yapılacak OnSpaceUpdated görüşmesinde güncellenecektir.

Zararlı içerikler ve davranış değişiklikleri

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

Yeni API'ler ve özellikler

  • Tam sayfa medya oluşturmak için Spherical ve Hemispherical kanvasları oluşturmanıza olanak tanıyan StereoSurface.CanvasShape özelliğini kullanıma sundu.
  • StereoSurfaceEntity.create() artık CanvasShape parametresini kabul ediyor. (Bu parametre şu anda yoksayılıyor ancak gelecekteki bir sürümde kullanılacak.)
  • StereoSurfaceEntity.create() artık Dimensions parametresi almıyor. Uygulamalar, CanvasShape
  • StereoSurfaceEntity, dinamik olarak ayarlanabilen bir CanvasShape üyesine sahiptir.
  • StereoSurfaceEntity.dimensions artık salt okunur bir mülktür; uygulamalar boyutları değiştirmek için CanvasShape değerini ayarlamalıdır.
  • StereoSurfaceEntity artık StereoMode'ın inşaattan sonra yeniden ayarlanmasına izin veriyor.

Diğer değişiklikler

  • Derleme zamanı minimum SDK sürümü 24'e düşürüldü. Tüm Jetpack XR API'leri, çalışma zamanında API 34'ü kullanmaya devam eder.
  • SceneCore'ın Oturum fabrikası (Session.create), artık SCENE_UNDERSTANDING iznini almak için intent başlatmıyor. Bunun yerine istemci uygulaması, sabitleyicileri oluşturmaya başlamadan önce kullanıcıdan açıkça izin istemelidir. Kullanıcı izin vermezse ankraj oluşturulamaz.

Hata düzeltmeleri

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

Sürüm 1.0.0-alpha01

12 Aralık 2024

androidx.xr.scenecore:scenecore-* 1.0.0-alpha01 yayınlanır.

İlk Sürümün Özellikleri Immersive sahneler ve ortamlar oluşturmak ve bunlarda değişiklik yapmak 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 birbirine ve sanal ya da gerçek dünya ortamlarınıza göre yerleştirmenize ve düzenlemenize olanak tanır.

  • SpatialEnvironment: Ortamınızın XR sahnesinin arka planı olarak bir gökyüzü kutusu resmi ve/veya 3D model geometrisi kullanarak tamamen etkileyici 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ştirebilirsiniz.
  • PanelEntity: Standart Android düzenleri ve etkinliklerini, gerçek dünya yüzeylerine sabitlenebilen veya yüzebilen uzamsal panellere yerleştirerek 3D sahnelerinize 2D içerik ekleyin.
  • GltfModelEntity: Sahnenizde 3D modeller yerleştirin, animasyonlu hale getirin ve bunlarla etkileşim kurun. SceneCore, mevcut modellerle entegrasyonu kolaylaştırmak için glTF dosya biçimini destekler.
  • Üç Boyutlu Ses: Tam anlamıyla sürükleyici, üç boyutlu ses için 3D sahnenize ortam ve nokta ses kaynakları ekleyin.
  • StereoSurfaceEntity: SceneCore, Android yüzeyinde oluşturulan içeriğin sol/sağ göze yönlendirilmesini destekler. Bu, stereoskopik içeriği yan yana veya yukarıdan aşağıya biçiminde (ör. stereo fotoğraflar, 3D video veya dinamik olarak oluşturulan diğer kullanıcı arayüzleri) oluşturmak için kullanılabilir. Uygulamalar, video kod çözme için MediaPlayer veya ExoPlayer'ı kullanmalıdır.
  • Bileşen sistemi: SceneCore, kullanıcıların modelleri ve panelleri taşıması, yeniden boyutlandırması ve bunlarla etkileşime geçmesi için 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ılara sanal içeriği gerçek ortamlarına sorunsuz bir şekilde entegre etme olanağı sunabilirsiniz.
  • Kullanıcı Pozu: İçeriğinizi kullanıcının konumuna göre yönlendirmek için kullanıcının sanal sahnedeki konumuna erişin.
  • SpatialCapabilities: Kullanılabilir olduğunda kullanıcı arayüzü içeriğinin 3D olarak konumlandırılması gibi mekansallaştırılmış özelliklerden yararlanan tamamen uyarlanabilir uygulamalar oluşturun. Ayrıca uygulamanız, çalıştırıldığı sırada özelliklerde yapılan değişiklikleri izleyebilir. Böylece, deneyimi kullanıcının Android XR cihazını kullanma şekline göre değiştirebilir.

Bilinen Sorunlar

  • Jetpack SceneCore'u kullanmak için şu anda 30'un üzerinde bir minSDK gereklidir. Çözüm olarak, 23 minSDK ile derleyip çalıştırabilmek için aşağıdaki manifest girişini <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> ekleyin.
  • Oturum, ana panelin yeniden boyutlandırılması, çevre birimlerinin bağlanması ve açık ile koyu mod arasında geçiş yapılması gibi etkinliği otomatik olarak yeniden oluşturan çeşitli durumlarda geçersiz hale gelebilir. Oturum geçersizleştirme 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/karanlık mod tema değişikliklerini devre dışı bırakma yer alır.
  • Taşınabilir ve yeniden boyutlandırılabilir bileşenler GltfEntity'de desteklenmez.
  • Entity.getSize(), GltfEntity üzerinde desteklenmez.
  • Jetpack XR uygulamalarının AndroidManifest'de android.permission.SCENE_UNDERSTANDING izni istemesi gerekir.
  • Oturum oluşturma özelliği yalnızca Android XR cihazlarda desteklenir. Şu anda bir oturum oluşturup Android XR dışında bir cihazda kullanmayı denerseniz RuntimeException alırsınız.
  • "SpatialEnvironment.setSpatialEnvironmentPreference()" aracılığıyla gökyüzü kutusunu null olarak ayarlamak, dokümanda belirtildiği gibi tamamen siyah bir gökyüzü kutusu oluşturmaz. Bu durum, sistemin varsayılan gökyüzü kutusuna neden olabilir veya mevcut gökyüzü kutusuyla ilgili herhangi bir 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. Gelecek bir sürümde scenecore, bu kitaplığı api bağımlılığı olarak içerecek. Böylece istemcilerin bunu açıkça belirtmesi gerekmeyecek.
  • SceneCore, com.google.guava:guava-31.1-android ve com.google.protobuf:protobuf-javalite'u geçişli bağımlılık olarak yanlışlıkla dahil ediyor. 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ıyorsa ve ProGuard'ı etkinleştirdiyseniz oturum oluşturduğunuzda uygulamanız kilitlenir. 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.