Jetpack SceneCore

Crea e manipola il grafico della scena Android XR con contenuti 3D.
Ultimo aggiornamento Release stabile Candidato per la release Versione beta Alpha Release
7 maggio 2025 - - - 1.0.0-alpha04

Dichiarazione di dipendenze

Per aggiungere una dipendenza da XR SceneCore, devi aggiungere il repository Maven di Google al tuo progetto. Per saperne di più, consulta il repository Maven di Google.

Aggiungi le dipendenze per gli artefatti che ti servono nel file build.gradle per la tua app o il tuo modulo:

Alla moda

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

Per saperne di più sulle dipendenze, consulta Aggiungere dipendenze di build.

Feedback

Il tuo feedback ci aiuta a migliorare Jetpack. Facci sapere se riscontri nuovi problemi o hai idee per migliorare questa libreria. Prima di crearne uno nuovo, dai un'occhiata ai problemi esistenti in questa libreria. Puoi aggiungere il tuo voto a un problema esistente facendo clic sul pulsante a forma di stella.

Creare un nuovo problema

Per ulteriori informazioni, consulta la documentazione di Issue Tracker.

Versione 1.0

Versione 1.0.0-alpha04

7 maggio 2025

androidx.xr.scenecore:scenecore:1.0.0-alpha04 e androidx.xr.scenecore:scenecore-testing:1.0.0-alpha04 sono stati rilasciati. La versione 1.0.0-alpha04 contiene questi commit.

Nuove funzionalità

  • La gestione del backhandling ora funzionerà sulle entità del riquadro senza attività incorporate. Per il funzionamento della gestione del pulsante Indietro, devi specificare android:enableOnBackInvokedCallback= "true" nel manifest Android.
  • StereoSurfaceEntity ora supporta la riproduzione MV-HEVC tramite due nuovi valori StereoMode: MULTIVIEW_LEFT_PRIMARY e MULTIVIEW_RIGHT_PRIMARY.
  • PanelEntity.setSize e PanelEntity.getSize ora restituiscono le dimensioni nello spazio principale.
  • Entity.setPose, Entity.getPose, Entity.setScale, Entity.getScale, Entity.setAlpha e Entity.getAlpha ora accettano un nuovo parametro relativeTo, che consente di ottenere/impostare valori relativi a spazi diversi. I valori supportati sono Spazi genitore, Attività e Mondo reale e il valore predefinito per questo parametro è Genitore.
  • Metodi di estensione di callback della visibilità spaziale aggiunti a SessionExt.kt per monitorare quando i contenuti della scena si spostano all'interno o all'esterno del campo visivo dell'utente.
  • setPointSourceParams è stato aggiunto a SpatialAudioTrack, consentendo l'aggiornamento dei parametri dopo la creazione della traccia.
  • È stata aggiunta una nuova classe, Scena, con riferimenti alle API Scenecore. La scena sarà accessibile come proprietà di estensione della sessione. Le funzioni all'interno di SessionExt sono state spostate in Scena, quindi gli importazioni dovranno essere modificate. Ad esempio, SessionExt.getScene(session).addSpatialCapababilitiesChangedListener contro SessionExt.addSpatialCapabilitiesChangedListener.
  • È stato aggiunto ActivityPose.hitTestAsync, che consente di hitTest contro i contenuti virtuali.
  • È stato aggiunto il nuovo tipo di componente SpatialPointerComponent, che consente ai clienti di specificare l'icona visualizzata per il puntatore o di disattivarla. Questo componente può essere collegato attualmente solo a PanelEntity istanze.
  • Introduzione della nuova fabbrica PanelEntity, che accetta le dimensioni del pannello in metri o pixel. Rimozione della fabbrica PanelEntity precedente che accettava due parametri di tipo Dimension per il pannello.

Modifiche alle API

  • Rimossa la limitazione RequiresApi(34) su tutti i pacchetti Jetpack XR. Questa limitazione era ridondante in quanto Jetpack XR è attualmente disponibile solo sui dispositivi con livello API 34 o superiore. (Iae0f8)
  • I progetti rilasciati con Kotlin 2.0 richiedono l'utilizzo di KGP 2.0.0 o versioni successive (Idb6b5)
  • Il corso PermissionHelper è stato rimosso.
  • PanelEntity.getPixelDensity è deprecato.
  • PanelEntity.setPixelDimensions e PanelEntity.getPixelDimension vengono rimossi e sostituiti da setSizeInPixels e getSizeInPixels.
  • Lingua Entity.getActivitySpaceAlpha rimossa. Può essere sostituito con Entity.getAlpha(Space.Activity).
  • Lingua Entity.getWorldSpaceScale rimossa. Può essere sostituito con Entity.getScale(Space.REAL\_WORLD).
  • La classe Session in SceneCore è stata eliminata a favore di Session in XR Runtime.
  • StereoSurfaceEntity è stato rinominato in SurfaceEntity.
  • Entity.setSize e Entity.getSize vengono rimossi e gli stessi metodi sono stati aggiunti a PanelEntity.
  • PointSourceAttributes è stato rinominato in PointSourceParams.
  • SpatializerConstants.SOURCE\_TYPE\_BYPASS è stato rinominato in SpatializerConstants.SOURCE\_TYPE\_DEFAULT.
  • L'entità PointSourceParams è stata modificata da accesso pubblico ad accesso interno.
  • Ora AnchorEntity.create richiede la configurazione di PlaneTrackingMode in Session.configure().
  • Le API SpatialUser ora richiedono la configurazione di HeadTrackingMode in Session.configure().
  • Quando ResizableComponent non è allegato, viene fornito un log a livello INFO anziché a livello ERROR.
  • La classe Fov è ora una normale classe Kotlin.
  • Dividi Entity.kt per inserire ogni tipo di entità concreta nel proprio file.
  • Quando crei un nuovo PanelEntity, la maggior parte delle visualizzazioni viene riassegnata a un FrameLayout. Ciò facilita l'utilizzo di LayoutInspector con i riquadri spaziali.
  • L'istanza XrExtensions attualmente in uso è ora registrata sulla piattaforma, nel miglior modo possibile, per facilitare il debug dell'app.

Correzioni di bug

  • È stata aggiunta una correzione per evitare un arresto anomalo che poteva verificarsi quando veniva spostato un PanelEntity con MovableComponent e AnchorPlacement
  • È stato risolto un problema per cui ResizableComponent forniva dimensioni obsolete nel callback onResizeStart.
  • È stato risolto il problema di arresto anomalo quando dispose() di JxrPlatformAdapterAxr veniva chiamato più volte.

Versione 1.0.0-alpha03

26 febbraio 2025

androidx.xr.scenecore:scenecore:1.0.0-alpha03 e androidx.xr.scenecore:scenecore-testing:1.0.0-alpha03 sono stati rilasciati. La versione 1.0.0-alpha03 contiene questi commit.

Nuove funzionalità

  • La riduzione Proguard è ora supportata per il codice Jetpack XR

Correzioni di bug

  • Correzioni aggiuntive per supportare la minimizzazione Proguard per Jetpack XR SceneCore (I4f47e)
  • Aggiornamento della regola ProGuard di Jetpack XR Scenecore per impedire AbstractMethodError per i client ridotti. (I91a01)

Versione 1.0.0-alpha02

12 febbraio 2025

androidx.xr.scenecore:scenecore:1.0.0-alpha02 e androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02 sono stati rilasciati. La versione 1.0.0-alpha02 contiene questi commit.

Modifica che causa interruzioni imminenti che interessano le app create prima della versione 1.0.0-alpha02

  • I metodi di fabbrica sono stati spostati dalla classe Session a un metodo complementare su ogni tipo rispettivamente:
    • Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) è stato eliminato e sostituito con ActivityPanelEntity.create(Session, Dimensions, String, Pose)
    • Session.createAnchorEntity(Anchor) è stato eliminato e sostituito con AnchorEntity.create(Session, Anchor)
    • Session.createAnchorEntity(Dimensions, Int, Int, Duration) è stato eliminato e sostituito con AnchorEntity.create(Session, Dimensions, Int, Int, Duration)
    • Session.createEntity(String, Pose) è stato eliminato e sostituito con ContentlessEntity.create(Session, String, Pose)
    • Session.createExrImageResource(String) è stato eliminato e sostituito con ExrImage.create(Session, String)
    • Session.createGltfEntity(GltfModel, Pose) è stato eliminato e sostituito con GltfModelEntity.create(Session, GltfModel, Pose)
    • Session.createGltfModelResource(String) è stato eliminato e sostituito con GltfModel.create(Session, String)
    • Session.createInteractableComponent(Executor, InputEventListener) è stato eliminato e sostituito con InteractableComponent.create(Session, Executor, InputEventListener)
    • Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) è stato eliminato e sostituito con MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
    • Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) è stato eliminato e sostituito con PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose)
    • Session.createResizableComponent(Dimensions, Dimensions) è stato eliminato e sostituito con ResizableComponent.create(Session, Dimensions, Dimensions)
    • Session.createStereoSurfaceEntity(Int, Dimensions, Pose) è stato eliminato e sostituito con StereoSurface.create(Session, Int, Dimensions, Pose)
  • Sono stati rimossi i seguenti metodi deprecati:
    • Session.canEmbedActivityPanel(Activity) è stato eliminato. Utilizza invece getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY).
    • Session.hasSpatialCapability(Int) è stato eliminato. È stato sostituito a favore dell'utilizzo di getSpatialCapabilities().hasCapability() come modo più compartimentato per verificare la presenza di funzionalità spaziali, poiché getSpatialCapabilities() restituisce un oggetto SpatialCapabilities.
    • Session.requestFullSpaceMode() è stato eliminato e sostituito con SpatialEnvironment.requestFullSpaceMode()
    • Session.requestHomeSpaceMode() è stato eliminato e sostituito con SpatialEnvironment.requestHomeSpaceMode()
  • Session.setFullSpaceMode(Bundle) e Session.setFullSpaceModeWithEnvironmentInherited(Bundle) sono state spostate nelle funzioni di estensione. I file dello sviluppatore dovranno aggiungere i nuovi import per l'accesso:
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float) è stato spostato in una funzione di estensione. I file dello sviluppatore dovranno aggiungere il nuovo import per l'accesso:
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Session.getEntitiesOfType(Class<out T>) e Session.getEntityForRtEntity(RtEntity) sono state spostate nelle funzioni di estensione. I file dello sviluppatore dovranno aggiungere i nuovi import per l'accesso:
    • import androidx.xr.scenecore.getEntitiesOfType
    • import androidx.xr.scenecore.getEntityForRtEntity
  • Session.unpersistAnchor(Anchor) è stato eliminato
  • Session.createPersistedAnchorEntity(UUID) è stato eliminato

Problemi noti

  • PanelEntity.setCornerRadius() e ActivityPanelEntity.setCornerRadius() potrebbero non avere effetto fino al successivo spostamento del pannello. Questo problema può essere risolto spostando il pannello nella sua posizione attuale.
  • Quando viene chiamato BoundsChanged su ActivitySpace, alcuni ActivityPose potrebbero non essere stati aggiornati correttamente. Verrà aggiornato nella seguente chiamata OnSpaceUpdated il giorno ActivitySpace

Modifiche che provocano errori e modifiche comportamentali

  • PanelEntity e ActivityPanelEntity avranno un raggio d'angolo predefinito di 32 dp o inferiore se il pannello ha una larghezza o un'altezza inferiore a 32 dp

Nuove API e funzionalità

  • Introduce StereoSurface.CanvasShape, che consente la creazione di canvas Spherical e Hemispherical per il rendering di contenuti multimediali immersivi.
  • StereoSurfaceEntity.create() ora accetta un parametro CanvasShape. (Questo parametro viene attualmente ignorato, ma verrà utilizzato in una versione futura)
  • StereoSurfaceEntity.create() non accetta più un parametro Dimensions. Le applicazioni devono controllare le dimensioni del canvas impostando CanvasShape
  • StereoSurfaceEntity ha un membro CanvasShape che può essere impostato in modo dinamico.
  • StereoSurfaceEntity.dimensions è ora una proprietà di sola lettura; le applicazioni devono impostare CanvasShape per modificare le dimensioni.
  • StereoSurfaceEntity ora consente di ripristinare StereoMode dopo la costruzione.

Altre modifiche

  • Riduzione della minSDK in fase di compilazione a 24. Tutte le API Jetpack XR continuano a richiedere l'API 34 in fase di runtime.
  • La Session factory di SceneCore (Session.create) non avvia più un intent per acquisire l'autorizzazione SCENE_UNDERSTANDING. L'applicazione client deve invece richiedere esplicitamente le autorizzazioni all'utente prima di tentare di creare gli ancoraggi. La creazione di ancore non riuscirà se l'autorizzazione non viene concessa dall'utente.

Correzioni di bug

  • getActivitySpacePose() è stato corretto per tenere conto della scala ActivitySpace restituendo i valori di conversione in metri scalati anziché restituire sempre metri non scalati. transformPoseTo ora utilizza anche le unità corrette per calcolare le modifiche alle coordinate quando ActivitySpace è coinvolto nell'origine o nella destinazione.
  • La skybox verrà ora impostata su una skybox completamente nera ogni volta che viene trasmessa una preferenza di skybox nulla utilizzando setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). Per ripristinare la skybox e la geometria predefinite del sistema, utilizza setSpatialEnvironmentPreference(null).

Versione 1.0.0-alpha01

12 dicembre 2024

androidx.xr.scenecore:scenecore-* 1.0.0-alpha01 viene ritirata.

Funzionalità della versione iniziale Versione iniziale per sviluppatori di Jetpack SceneCore, una libreria di grafici di scene 3D per creare e manipolare scene e ambienti immersivi. Questa libreria ti consente di posizionare e disporre modelli 3D e pannelli di contenuti l'uno rispetto all'altro e ai tuoi ambienti virtuali o reali.

  • SpatialEnvironment: crea esperienze completamente immersive con un'immagine skybox e/o una geometria del modello 3D come sfondo per la scena XR del tuo ambiente. In alternativa, attiva il passthrough, in modo che la scena virtuale possa integrarsi con l'ambiente reale dell'utente.
  • PanelEntity: aggiungi contenuti 2D alle tue scene 3D incorporando layout e attività Android standard in pannelli spazializzati che possono fluttuare o essere ancorati a superfici del mondo reale.
  • GltfModelEntity: posiziona, anima e interagisci con i modelli 3D nella tua scena. SceneCore supporta il formato di file glTF per facilitare l'integrazione con i modelli esistenti.
  • Audio spaziale: aggiungi sorgenti audio ambientali e puntiformi alla tua scena 3D per un suono spazializzato e completamente immersivo.
  • StereoSurfaceEntity: SceneCore supporta il routing dei contenuti renderizzati su una superficie Android per l'occhio sinistro/destro. Può essere utilizzato per il rendering di contenuti stereoscopici in formato side-by-side o top-bottom, come foto stereoscopiche, video 3D o altre UI sottoposte a rendering dinamico. Le applicazioni devono utilizzare MediaPlayer o ExoPlayer per la decodifica video.
  • Sistema di componenti: SceneCore offre un sistema di componenti solido e flessibile per aggiungere funzionalità ai tuoi contenuti XR, tra cui la possibilità per gli utenti di spostare, ridimensionare e interagire con modelli e pannelli.
  • Ancoraggio: con il passthrough attivato, puoi collegare pannelli e modelli a superfici reali, consentendo agli utenti di integrare perfettamente i contenuti virtuali nel loro ambiente reale.
  • Posizione dell'utente: accedi alla posizione dell'utente nella scena virtuale per orientare i contenuti in base alla sua posizione.
  • SpatialCapabilities: crea app completamente adattive che sfruttano le funzionalità spazializzate quando disponibili, ad esempio il posizionamento 3D dei contenuti dell'interfaccia utente. Inoltre, la tua app può monitorare le modifiche alle funzionalità durante l'esecuzione, per modificare l'esperienza in base a come l'utente utilizza il proprio dispositivo Android XR.

Problemi noti

  • Al momento è necessario un minSDK di 30 per utilizzare Jetpack SceneCore. Come soluzione alternativa, aggiungi la seguente voce del manifest <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> per poter eseguire la build ed eseguire l'app con un minSDK di 23.
  • La sessione può diventare non valida in varie situazioni che ricreano automaticamente l'attività, tra cui il ridimensionamento di un pannello principale, il collegamento di periferiche e il passaggio dalla modalità Chiaro alla modalità Buio. Se riscontri problemi di invalidazione della sessione, le soluzioni alternative includono la non ridimensionabilità del pannello principale, l'utilizzo di un'entità pannello dinamico, la disattivazione della ricreazione dell'attività per modifiche specifiche alla configurazione o la disattivazione delle modifiche al tema della modalità Chiaro/Scuro.
  • I componenti Movable e Resizable non sono supportati in GltfEntity.
  • Entity.getSize() non è supportato su GltfEntity.
  • Le app Jetpack XR devono richiedere l'autorizzazione android.permission.SCENE_UNDERSTANDING in AndroidManifest.
  • La creazione di una sessione è supportata solo su un dispositivo Android XR. Al momento, se crei una sessione e provi a utilizzarla su un dispositivo XR non Android, riceverai un'eccezione RuntimeException.
  • L'impostazione della skybox su null tramite `SpatialEnvironment.setSpatialEnvironmentPreference()` non comporta una skybox nera solida come documentato. Potrebbe essere visualizzata la skybox predefinita del sistema o non essere apportata alcuna modifica alla skybox attuale.
  • I client SceneCore devono aggiungere implementation(“com.google.guava:listenablefuture-1.0”) alla configurazione Gradle per le dipendenze dell'app. In una release futura, scenecore includerà questa libreria come dipendenza api, quindi i client non dovranno dichiararla esplicitamente.
  • SceneCore include erroneamente com.google.guava:guava-31.1-android e com.google.protobuf:protobuf-javalite come dipendenze transitive. Se ciò comporta errori di classe duplicati nella build, queste due dipendenze possono essere escluse in modo sicuro.
  • Se la tua app utilizza SceneCore e attiva ProGuard, si arresterà in modo anomalo quando crei una sessione. Come soluzione alternativa, disattiva ProGuard. Per ulteriori informazioni su come attivare ProGuard, consulta questa guida.