Jetpack SceneCore

API Referansı
androidx.xr.scenecore
androidx.xr.scenecore.testing

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
12 Şubat 2025	-	-	-	1.0.0-alpha02

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

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-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) politikasını 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.
Artık setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) kullanılarak null bir gökyüzü kutusu tercihi iletildiğinde gökyüzü kutusu tamamen siyah olarak ayarlanacaktır. Sistemdeki 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. Dilerseniz 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ünyadaki yüzeylere 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 ekleyebilirsiniz. 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 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 uzamsallaş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. Geçici çö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.
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 oturum 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 işlem, sistemin varsayılan gökyüzü kutusuna neden olabilir veya mevcut gökyüzü kutusunda herhangi bir değişiklik yapmayabilir.
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ığı 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, 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.