{ } { }

Jetpack SceneCore

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

Dichiarazione delle dipendenze

Per aggiungere una dipendenza da XR SceneCore, devi aggiungere il repository Maven di Google al tuo progetto. Per ulteriori informazioni, consulta il repository Maven di Google.

Aggiungi le dipendenze per gli elementi necessari 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 ulteriori informazioni sulle dipendenze, consulta Aggiungere dipendenze di compilazione.

Feedback

Il tuo feedback ci aiuta a migliorare Jetpack. Facci sapere se riscontri nuovi problemi o hai idee per migliorare questa raccolta. Prima di crearne uno nuovo, dai un'occhiata ai problemi esistenti in questa raccolta. 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 del Tracker dei problemi.

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 vengono rilasciati. La versione 1.0.0-alpha04 contiene questi commit.

Nuove funzionalità

  • La gestione a ritroso ora funzionerà sulle entità del riquadro senza attività incorporate. Affinché il backhandling funzioni, devi specificare android:enableOnBackInvokedCallback= "true" nel file manifest Android.
  • StereoSurfaceEntity ora supporta la riproduzione di 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 Parent, Activity e Real World spaces e il valore predefinito per questo parametro è Parent.
  • Metodi di estensione di callback di 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 del canale.
  • È stata aggiunta una nuova classe, Scene, con riferimenti alle API Scenecore. La scena sarà accessibile come proprietà di estensione di Session. Le funzioni all'interno di SessionExt sono state spostate in Scene, pertanto le importazioni dovranno essere regolate, ad esempio SessionExt.getScene(session).addSpatialCapababilitiesChangedListener contro SessionExt.addSpatialCapabilitiesChangedListener.
  • È stato aggiunto ActivityPose.hitTestAsync, che consente di segnalare i contenuti virtuali.hitTest
  • È stato aggiunto il nuovo tipo di componente SpatialPointerComponent, che consente ai client di specificare l'icona visualizzata per il cursore o di disattivarla. Al momento questo componente può essere collegato solo a istanze PanelEntity.
  • È stata introdotta la nuova funzione di impostazione PanelEntity, che prende le dimensioni del pannello in metri o pixel. È stata rimossa la vecchia factory PanelEntity che accettava due parametri di tipo di dimensione per il riquadro.

Modifiche all'API

  • È stata rimossa la limitazione RequiresApi(34) su tutti i pacchetti Jetpack XR. Questa limitazione era ridondante perché Jetpack XR è attualmente disponibile solo sui dispositivi con livello API 34 e versioni successive. (Iae0f8)
  • I progetti rilasciati con Kotlin 2.0 richiedono KGP 2.0.0 o versioni successive per essere utilizzati (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 della Session in XR Runtime.
  • StereoSurfaceEntity è stato rinominato in SurfaceEntity.
  • Entity.setSize e Entity.getSize vengono rimossi e gli stessi metodi vengono 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().
  • Se ResizableComponent non è allegato, verrà generato 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 in un file separato.
  • Quando crei un nuovo PanelEntity, la maggior parte delle visualizzazioni verrà associata a un FrameLayout. Ciò facilita l'utilizzo di LayoutInspector con i riquadri spaziali.
  • L'istanza XrExtensions attualmente in uso è ora registrata sulla piattaforma, secondo il criterio del "best effort", per facilitare il debug dell'app.

Correzioni di bug

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

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 vengono rilasciati. La versione 1.0.0-alpha03 contiene questi commit.

Nuove funzionalità

  • La minimizzazione di Proguard è ora supportata per il codice Jetpack XR

Correzioni di bug

  • Correzioni aggiuntive per supportare la minimizzazione di Proguard per Jetpack XR SceneCore (I4f47e)
  • Aggiornamento della regola ProGuard di Jetpack XR Scenecore per impedire AbstractMethodError per i client minimizzati. (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 vengono rilasciati. La versione 1.0.0-alpha02 contiene questi commit.

Modifica in violazione imminente che interessa le app create prima della versione 1.0.0-alpha02

  • I metodi di fabbrica sono stati spostati dalla classe Session a un metodo complementare per ogni rispettivo tipo:
    • 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)
  • I seguenti metodi deprecati sono stati rimossi:
    • Session.canEmbedActivityPanel(Activity) è stato eliminato. Utilizza invece getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY).
    • Session.hasSpatialCapability(Int) è stato eliminato. È stato sostituito dall'utilizzo di getSpatialCapabilities().hasCapability() come metodo 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 stati spostati nelle funzioni di estensione. I file dello sviluppatore dovranno aggiungere le nuove importazioni 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 la nuova importazione per l'accesso:
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Session.getEntitiesOfType(Class<out T>) e Session.getEntityForRtEntity(RtEntity) sono stati spostati nelle funzioni di estensione. I file dello sviluppatore dovranno aggiungere le nuove importazioni 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 essere applicati fino al successivo spostamento del riquadro. Questo problema può essere risolto spostando il riquadro nella posizione corrente
  • Quando BoundsChanged viene chiamato in ActivitySpace, alcuni ActivityPose potrebbero non essere stati aggiornati correttamente. Verrà aggiornato nella chiamata OnSpaceUpdated successiva del giorno ActivitySpace

Modifiche che comportano interruzioni e modifiche del comportamento

  • PanelEntity e ActivityPanelEntity avranno un raggio di curvatura degli angoli predefinito pari o inferiore a 32 dp se il pannello ha una larghezza o un'altezza inferiore a 32 dp

Nuove API e funzionalità

  • Viene introdotto StereoSurface.CanvasShape, che consente di creare canvas Spherical e Hemispherical per il rendering di contenuti multimediali immersivi.
  • StereoSurfaceEntity.create() ora accetta un parametro CanvasShape. (questo parametro è 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 reimpostare StereoMode dopo la compilazione.

Altre modifiche

  • Il valore minSDK in fase di compilazione è stato ridotto a 24. Tutte le API Jetpack XR continuano a richiedere l'API 34 in fase di runtime.
  • La factory di sessione (Session.create) di SceneCore 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 le ancore. La creazione dell'ancora non andrà a buon fine se l'autorizzazione non viene concessa dall'utente.

Correzioni di bug

  • getActivitySpacePose() è stato corretto per tenere conto della scala ActivitySpace restituendo i valori di traduzione in metri scalati anziché sempre in metri non scalati. transformPoseTo ora utilizza anche le unità corrette per calcolare le variazioni delle coordinate quando ActivitySpace è coinvolto nell'origine o nella destinazione.
  • Ora la sfera celeste verrà impostata su un'esfera celeste completamente nera ogni volta che viene passata una preferenza di sfera celeste nulla utilizzando setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). Per ripristinare la geometria e lo skybox predefiniti di sistema, utilizza setSpatialEnvironmentPreference(null).

Versione 1.0.0-alpha01

12 dicembre 2024

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

Funzionalità della release iniziale Release iniziale per sviluppatori di Jetpack SceneCore, una libreria di grafici di scene 3D per la creazione e la manipolazione di ambienti e scene immersive. Questa libreria ti consente di posizionare e disporre modelli 3D e riquadri di contenuti rispetto a un altro e ai tuoi ambienti virtuali o reali.

  • SpatialEnvironment: crea esperienze completamente immersive con un'immagine skybox e/o la geometria di un modello 3D come sfondo per la scena XR del tuo ambiente. In alternativa, attiva il passthrough in modo che la scena virtuale possa essere integrata 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 galleggiare o essere ancorati a superfici reali.
  • GltfModelEntity: posiziona, anima e interagisci con i modelli 3D nella scena. SceneCore supporta il formato file glTF per facilitare l'integrazione con i modelli esistenti.
  • SpatialAudio: aggiungi sorgenti audio ambientali e puntuali alla scena 3D per un audio spazializzato e completamente immersivo.
  • StereoSurfaceEntity: SceneCore supporta il routing dell'occhio sinistro/destro dei contenuti visualizzati su una piattaforma Android. Questo può essere utilizzato per eseguire il rendering di contenuti stereoscopici in un formato affiancato o dall'alto verso il basso, ad esempio foto stereo, video 3D o altre UI con rendering dinamico. Le applicazioni devono utilizzare MediaPlayer o ExoPlayer per la decodifica video.
  • Sistema di componenti: SceneCore offre un sistema di componenti robusto e flessibile per aggiungere funzionalità ai contenuti XR, tra cui funzionalità che consentono agli utenti di spostare, ridimensionare e interagire con modelli e pannelli.
  • Ancora: con il passthrough abilitato, puoi attaccare pannelli e modelli a superfici reali, offrendo agli utenti un'integrazione perfetta dei contenuti virtuali nel loro ambiente reale.
  • Postura dell'utente: accedi alla posizione dell'utente nella scena virtuale per orientare i contenuti in base alla sua posizione.
  • SpatialCapabilities: crea app completamente adattabili che sfruttano le funzionalità spazializzate, se disponibili, come il posizionamento 3D dei contenuti dell'interfaccia utente. Non solo, ma la tua app può monitorare le modifiche alle funzionalità durante l'esecuzione per modificare l'esperienza in base al modo in cui l'utente utilizza il proprio dispositivo Android XR.

Problemi noti

  • Al momento è richiesta una versione minima dell'SDK pari a 30 per utilizzare Jetpack SceneCore. Come soluzione alternativa, aggiungi la seguente voce manifest <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> per poter eseguire la compilazione e l'esecuzione con un minSDK di 23.
  • La sessione può diventare non valida in varie situazioni che ricreano automaticamente l'attività, ad esempio il ridimensionamento di un riquadro principale, il collegamento di periferiche e il passaggio dalla modalità Luce a quella Buio e viceversa. Se riscontri problemi di convalida della sessione, le soluzioni alternative includono l'impostazione del riquadro principale come non ridimensionabile, l'utilizzo di un'entità riquadro dinamico, la disattivazione della ricreazione delle attività per modifiche di configurazione specifiche o la disattivazione delle modifiche del tema della modalità chiara/scura.
  • 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, viene generata un'eccezione RuntimeException.
  • L'impostazione di una skybox su null tramite "SpatialEnvironment.setSpatialEnvironmentPreference()" non genera una skybox nera come descritto nella documentazione. Potrebbe essere visualizzato lo skybox predefinito del sistema o non essere apportata alcuna modifica allo skybox corrente.
  • I clienti SceneCore devono aggiungere implementation(“com.google.guava:listenablefuture-1.0”) alla configurazione di Gradle per le dipendenze della loro 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 tutta sicurezza.
  • Se la tua app utilizza SceneCore e attiva ProGuard, avrà un arresto anomalo quando crei una sessione. Come soluzione alternativa, disattiva ProGuard. Per ulteriori informazioni su come attivare ProGuard, consulta questa guida.