{ } { }

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

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

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 Monitoraggio problemi.

Versione 1.0

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 sua 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 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 integrarsi con l'ambiente reale dell'utente.
  • PanelEntity: aggiungi contenuti 2D alle tue scene 3D incorporando layout e attività Android standard in riquadri 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.