Jetpack SceneCore

Erstellen und bearbeiten Sie den Android XR-Szenengraphen mit 3D-Inhalten.
Letzte Aktualisierung Stabile Version Releasekandidat Beta-Ausgabe Alpharelease
7. Mai 2025 - – - 1.0.0-alpha04

Abhängigkeiten deklarieren

Wenn Sie eine Abhängigkeit von XR SceneCore hinzufügen möchten, müssen Sie Ihrem Projekt das Google Maven-Repository hinzufügen. Weitere Informationen finden Sie im Maven-Repository von Google.

Fügen Sie der Datei build.gradle für Ihre App oder Ihr Modul die Abhängigkeiten für die benötigten Artefakte hinzu:

Cool

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

Weitere Informationen zu Abhängigkeiten finden Sie unter Build-Abhängigkeiten hinzufügen.

Feedback

Ihr Feedback hilft uns, Jetpack zu verbessern. Lassen Sie es uns wissen, wenn Sie neue Probleme entdecken oder Ideen zur Verbesserung dieser Bibliothek haben. Sehen Sie sich die vorhandenen Probleme in dieser Bibliothek an, bevor Sie ein neues erstellen. Sie können für ein vorhandenes Problem abstimmen, indem Sie auf die Schaltfläche mit dem Stern klicken.

Neues Problem erstellen

Weitere Informationen finden Sie in der Dokumentation zur Problemverfolgung.

Version 1.0

Version 1.0.0-alpha04

7. Mai 2025

androidx.xr.scenecore:scenecore:1.0.0-alpha04 und androidx.xr.scenecore:scenecore-testing:1.0.0-alpha04 werden veröffentlicht. Version 1.0.0-alpha04 enthält diese Commits.

Neue Funktionen

  • Die Rückabwicklung funktioniert jetzt auch für Panel-Entitäten ohne eingebettete Aktivitäten. Damit die Rücktaste funktioniert, müssen Sie android:enableOnBackInvokedCallback= "true" im Android-Manifest angeben.
  • StereoSurfaceEntity unterstützt jetzt die MV-HEVC-Wiedergabe über zwei neue StereoMode-Werte: MULTIVIEW_LEFT_PRIMARY und MULTIVIEW_RIGHT_PRIMARY.
  • PanelEntity.setSize und PanelEntity.getSize geben jetzt Größen im übergeordneten Bereich zurück.
  • Entity.setPose, Entity.getPose, Entity.setScale, Entity.getScale, Entity.setAlpha und Entity.getAlpha verwenden jetzt den neuen Parameter relativeTo, mit dem Werte relativ zu verschiedenen Bereichen abgerufen/festgelegt werden können. Die unterstützten Werte sind „Parent“, „Activity“ und „Real World“. Der Standardwert für diesen Parameter ist „Parent“.
  • Der Klasse SessionExt.kt wurden Erweiterungsmethoden für den Spatial Visibility Callback hinzugefügt, um zu überwachen, wann sich der Inhalt der Szene innerhalb oder außerhalb des Sichtfelds des Nutzers befindet.
  • setPointSourceParams wurde SpatialAudioTrack hinzugefügt. Dadurch können die Parameter aktualisiert werden, nachdem der Track erstellt wurde.
  • Es wurde eine neue Klasse „Scene“ mit Verweisen auf Scenecore-APIs hinzugefügt. Die Szene ist als Erweiterungseigenschaft der Sitzung verfügbar. Funktionen in SessionExt wurden in „Scene“ verschoben. Daher müssen Importe angepasst werden, z. B. SessionExt.getScene(session).addSpatialCapababilitiesChangedListener im Vergleich zu SessionExt.addSpatialCapabilitiesChangedListener.
  • ActivityPose.hitTestAsync wurde hinzugefügt, wodurch eine hitTest für virtuelle Inhalte möglich ist.
  • Der neue Komponententyp SpatialPointerComponent wurde hinzugefügt. Damit können Kunden das Symbol für den Zeiger angeben oder das Symbol deaktivieren. Diese Komponente kann derzeit nur an PanelEntity-Instanzen angehängt werden.
  • Wir führen die neue PanelEntity-Factory ein, die die Abmessungen des Panels in Metern oder Pixeln akzeptiert. Die alte PanelEntity-Factory, die zwei Parameter vom Typ „Dimension“ für das Feld verwendet, wurde entfernt.

API-Änderungen

  • Die Einschränkung RequiresApi(34) wurde für alle Jetpack XR-Pakete entfernt. Diese Einschränkung war überflüssig, da Jetpack XR derzeit nur auf Geräten mit API-Level 34 oder höher verfügbar ist. (Iae0f8)
  • Für Projekte, die mit Kotlin 2.0 veröffentlicht wurden, ist KGP 2.0.0 oder höher erforderlich (Idb6b5).
  • Der Kurs „PermissionHelper“ wurde entfernt.
  • PanelEntity.getPixelDensity ist veraltet.
  • PanelEntity.setPixelDimensions und PanelEntity.getPixelDimension werden entfernt und durch setSizeInPixels und getSizeInPixels ersetzt.
  • Entity.getActivitySpaceAlpha entfernt. Kann durch Entity.getAlpha(Space.Activity) ersetzt werden.
  • Entity.getWorldSpaceScale entfernt. Kann durch Entity.getScale(Space.REAL\_WORLD) ersetzt werden.
  • Die Session-Klasse in SceneCore wurde zugunsten der Session in XR Runtime gelöscht.
  • StereoSurfaceEntity wurde in SurfaceEntity umbenannt.
  • Entity.setSize und Entity.getSize wurden entfernt und dieselben Methoden wurden PanelEntity hinzugefügt.
  • PointSourceAttributes wurde in PointSourceParams umbenannt.
  • SpatializerConstants.SOURCE\_TYPE\_BYPASS wurde in SpatializerConstants.SOURCE\_TYPE\_DEFAULT umbenannt.
  • Die PointSourceParams-Entität wurde von öffentlichem zu internem Zugriff geändert.
  • Für AnchorEntity.create muss jetzt PlaneTrackingMode in Session.configure() konfiguriert werden.
  • Für SpatialUser-APIs muss jetzt HeadTrackingMode in Session.configure() konfiguriert werden.
  • Wenn ResizableComponent nicht angehängt ist, wird ein Log auf INFO-Ebene anstelle eines Logs auf ERROR-Ebene ausgegeben.
  • Die Fov-Klasse ist jetzt eine reguläre Kotlin-Klasse.
  • Teilen Sie Entity.kt auf, um jeden konkreten Entitätstyp in einer eigenen Datei zu platzieren.
  • Wenn Sie ein neues PanelEntity erstellen, werden die meisten Ansichten einem FrameLayout untergeordnet. Dadurch wird die Verwendung von LayoutInspector mit räumlichen Bereichen erleichtert.
  • Die derzeit verwendete XrExtensions-Instanz wird jetzt nach bestem Wissen und Gewissen bei der Plattform registriert, um das Debuggen von Apps zu erleichtern.

Fehlerkorrekturen

  • Es wurde eine Korrektur hinzugefügt, um einen Absturz zu verhindern, der auftreten konnte, wenn ein PanelEntity mit MovableComponent und AnchorPlacement verschoben wurde.
  • Ein Problem wurde behoben, bei dem ResizableComponent veraltete Größen im onResizeStart-Callback bereitgestellt hat.
  • Ein Absturz wurde behoben, der auftrat, wenn JxrPlatformAdapterAxr's dispose() mehrmals aufgerufen wurde.

Version 1.0.0-alpha03

26. Februar 2025

androidx.xr.scenecore:scenecore:1.0.0-alpha03 und androidx.xr.scenecore:scenecore-testing:1.0.0-alpha03 werden veröffentlicht. Version 1.0.0-alpha03 enthält diese Commits.

Neue Funktionen

  • Proguard-Minifizierung wird jetzt für Jetpack XR-Code unterstützt

Fehlerkorrekturen

  • Zusätzliche Korrekturen zur Unterstützung der Proguard-Minifizierung für Jetpack XR SceneCore (I4f47e)
  • Die Jetpack XR-Scenecore-Regel ProGuard wurde aktualisiert, um AbstractMethodError für minimierte Clients zu verhindern. (I91a01)

Version 1.0.0-alpha02

12. Februar 2025

androidx.xr.scenecore:scenecore:1.0.0-alpha02 und androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02 werden veröffentlicht. Version 1.0.0-alpha02 enthält diese Commits.

Anstehende schwerwiegende Änderung für Apps, die vor Version 1.0.0-alpha02 erstellt wurden

  • Factory-Methoden wurden aus der Klasse Session in eine Companion-Methode für jeden jeweiligen Typ verschoben:
    • Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) wurde gelöscht und durch ActivityPanelEntity.create(Session, Dimensions, String, Pose) ersetzt
    • Session.createAnchorEntity(Anchor) wurde gelöscht und durch AnchorEntity.create(Session, Anchor) ersetzt
    • Session.createAnchorEntity(Dimensions, Int, Int, Duration) wurde gelöscht und durch AnchorEntity.create(Session, Dimensions, Int, Int, Duration) ersetzt
    • Session.createEntity(String, Pose) wurde gelöscht und durch ContentlessEntity.create(Session, String, Pose) ersetzt
    • Session.createExrImageResource(String) wurde gelöscht und durch ExrImage.create(Session, String) ersetzt
    • Session.createGltfEntity(GltfModel, Pose) wurde gelöscht und durch GltfModelEntity.create(Session, GltfModel, Pose) ersetzt
    • Session.createGltfModelResource(String) wurde gelöscht und durch GltfModel.create(Session, String) ersetzt
    • Session.createInteractableComponent(Executor, InputEventListener) wurde gelöscht und durch InteractableComponent.create(Session, Executor, InputEventListener) ersetzt
    • Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) wurde gelöscht und durch MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean) ersetzt
    • Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) wurde gelöscht und durch PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose) ersetzt
    • Session.createResizableComponent(Dimensions, Dimensions) wurde gelöscht und durch ResizableComponent.create(Session, Dimensions, Dimensions) ersetzt
    • Session.createStereoSurfaceEntity(Int, Dimensions, Pose) wurde gelöscht und durch StereoSurface.create(Session, Int, Dimensions, Pose) ersetzt
  • Die folgenden nicht mehr unterstützten Methoden wurden entfernt:
    • Session.canEmbedActivityPanel(Activity) wurde gelöscht. Verwenden Sie stattdessen getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY).
    • Session.hasSpatialCapability(Int) wurde gelöscht. Es wurde durch getSpatialCapabilities().hasCapability() ersetzt, da dies eine besser abgegrenzte Möglichkeit ist, das Vorhandensein von räumlichen Funktionen zu prüfen, da getSpatialCapabilities() ein SpatialCapabilities-Objekt zurückgibt.
    • Session.requestFullSpaceMode() wurde gelöscht und durch SpatialEnvironment.requestFullSpaceMode() ersetzt
    • Session.requestHomeSpaceMode() wurde gelöscht und durch SpatialEnvironment.requestHomeSpaceMode() ersetzt
  • Session.setFullSpaceMode(Bundle) und Session.setFullSpaceModeWithEnvironmentInherited(Bundle) wurden in Erweiterungsfunktionen verschoben. In Entwicklerdateien müssen die neuen Importe für den Zugriff hinzugefügt werden:
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float) wurde in eine Erweiterungsfunktion verschoben. In Entwicklerdateien muss der neue Import für den Zugriff hinzugefügt werden:
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Session.getEntitiesOfType(Class<out T>) und Session.getEntityForRtEntity(RtEntity) wurden in Erweiterungsfunktionen verschoben. In Entwicklerdateien müssen die neuen Importe für den Zugriff hinzugefügt werden:
    • import androidx.xr.scenecore.getEntitiesOfType
    • import androidx.xr.scenecore.getEntityForRtEntity
  • Session.unpersistAnchor(Anchor) wurde gelöscht
  • Session.createPersistedAnchorEntity(UUID) wurde gelöscht

Bekannte Probleme

  • PanelEntity.setCornerRadius() und ActivityPanelEntity.setCornerRadius() werden möglicherweise erst wirksam, wenn das Panel das nächste Mal bewegt wird. Das lässt sich vermeiden, indem Sie das Panel an seine aktuelle Position bewegen.
  • Wenn BoundsChanged für die ActivitySpace aufgerufen wird, wurden einige ActivityPoses möglicherweise nicht richtig aktualisiert. Sie wird beim nächsten OnSpaceUpdated-Aufruf am ActivitySpace aktualisiert.

Nicht abwärtskompatible Änderungen und Verhaltensänderungen

  • PanelEntity und ActivityPanelEntity haben einen Standard-Eckenradius von 32 dp oder weniger, wenn der Bereich eine Breite oder Höhe von weniger als 32 dp hat.

Neue APIs und Funktionen

  • Mit StereoSurface.CanvasShape können Spherical- und Hemispherical-Arbeitsbereiche zum Rendern immersiver Medien erstellt werden.
  • StereoSurfaceEntity.create() akzeptiert jetzt einen CanvasShape-Parameter. Dieser Parameter wird derzeit ignoriert, wird aber in einer zukünftigen Version verwendet.
  • StereoSurfaceEntity.create() akzeptiert keinen Dimensions-Parameter mehr. Anwendungen sollten die Größe des Canvas durch Festlegen von CanvasShape steuern.
  • StereoSurfaceEntity hat ein CanvasShape-Element, das dynamisch festgelegt werden kann.
  • StereoSurfaceEntity.dimensions ist jetzt eine schreibgeschützte Eigenschaft. Anwendungen sollten CanvasShape festlegen, um die Abmessungen zu ändern.
  • Mit StereoSurfaceEntity kann StereoMode jetzt nach der Konstruktion neu festgelegt werden.

Sonstige Änderungen

  • Die minSDK-Version für die Kompilierung wurde auf 24 reduziert. Für alle Jetpack XR-APIs ist weiterhin API 34 zur Laufzeit erforderlich.
  • Die Sitzungsfactory (Session.create) von SceneCore startet keinen Intent mehr, um die Berechtigung SCENE_UNDERSTANDING zu erhalten. Stattdessen muss die Clientanwendung die Berechtigungen explizit vom Nutzer anfordern, bevor sie versucht, die Anker zu erstellen. Die Ankererstellung schlägt fehl, wenn der Nutzer die Berechtigung nicht erteilt.

Fehlerkorrekturen

  • getActivitySpacePose() wurde korrigiert, um die ActivitySpace-Skalierung zu berücksichtigen. Es werden jetzt Übersetzungs-Werte in skalierten Metern zurückgegeben, anstatt immer nicht skalierte Meter. transformPoseTo verwendet jetzt auch die richtigen Einheiten, um Koordinatenänderungen zu berechnen, wenn ActivitySpace in der Quelle oder im Ziel enthalten ist.
  • Die Skybox wird jetzt auf eine komplett schwarze Skybox festgelegt, wenn mit setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) eine Null-Skybox-Einstellung übergeben wird. Wenn Sie zur Standard-Skybox und ‑Geometrie des Systems zurückkehren möchten, verwenden Sie setSpatialEnvironmentPreference(null)..

Version 1.0.0-alpha01

12. Dezember 2024

androidx.xr.scenecore:scenecore-* 1.0.0-alpha01 wird veröffentlicht.

Funktionen der ersten Version Erste Entwicklerversion von Jetpack SceneCore, einer 3D-Szenengraph-Bibliothek zum Erstellen und Bearbeiten von immersiven Szenen und Umgebungen. Mit dieser Bibliothek können Sie 3D-Modelle und Inhaltsbereiche relativ zueinander und zu Ihren virtuellen oder realen Umgebungen platzieren und anordnen.

  • SpatialEnvironment: Erstellen Sie vollständig immersive Erlebnisse mit einem Skybox-Bild und/oder einer 3D-Modellgeometrie als Kulisse für Ihre XR-Szene Ihrer Umgebung. Oder Sie aktivieren den Passthrough-Modus, damit sich die virtuelle Szene in die reale Umgebung des Nutzers einfügen kann.
  • PanelEntity: Sie können 2D-Inhalte in Ihre 3D-Szenen einfügen, indem Sie Standard-Android-Layouts und -Aktivitäten in räumlich angeordnete Bereiche einbetten, die frei schweben oder an realen Oberflächen verankert werden können.
  • GltfModelEntity: Mit dieser Funktion können Sie 3D-Modelle in Ihrer Szene platzieren, animieren und mit ihnen interagieren. SceneCore unterstützt das glTF-Dateiformat, um die Integration mit vorhandenen Modellen zu vereinfachen.
  • SpatialAudio: Fügen Sie Ihrer 3D-Szene Umgebungs- und Punkt-Audioquellen hinzu, um einen vollständig immersiven, räumlichen Sound zu erzeugen.
  • StereoSurfaceEntity: SceneCore unterstützt das Routing von Inhalten, die auf einer Android-Oberfläche gerendert werden, zum linken und rechten Auge. Damit können stereoskopische Inhalte im Side-by-Side- oder Top-Bottom-Format gerendert werden, z. B. Stereofotos, 3D-Videos oder andere dynamisch gerenderte Benutzeroberflächen. Anwendungen sollten MediaPlayer oder ExoPlayer für die Videodecodierung verwenden.
  • Komponentensystem: SceneCore bietet ein robustes und flexibles Komponentensystem zum Hinzufügen von Funktionen zu Ihren XR-Inhalten, einschließlich Affordanzen für Nutzer, um Modelle und Bereiche zu verschieben, ihre Größe zu ändern und mit ihnen zu interagieren.
  • Anker: Wenn Passthrough aktiviert ist, können Sie Panels und Modelle an realen Oberflächen anbringen. So können Nutzer virtuelle Inhalte nahtlos in ihre reale Umgebung einfügen.
  • Nutzer-Pose: Ermöglicht den Zugriff auf den Standort des Nutzers in der virtuellen Szene, um Inhalte an der Position des Nutzers auszurichten.
  • SpatialCapabilities: Entwickeln Sie vollständig adaptive Apps, die räumliche Funktionen nutzen, wenn sie verfügbar sind, z. B. die 3D-Positionierung von UI-Inhalten. Außerdem kann Ihre App während der Ausführung auf Änderungen an Funktionen achten, um die Nutzererfahrung basierend darauf zu ändern, wie der Nutzer sein Android XR-Gerät verwendet.

Bekannte Probleme

  • Derzeit ist ein minSDK von 30 erforderlich, um Jetpack SceneCore zu verwenden. Fügen Sie als Workaround den folgenden Manifesteintrag <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> hinzu, damit Sie mit einem minSDK von 23 erstellen und ausführen können.
  • Sitzungen können in verschiedenen Situationen ungültig werden, in denen die Aktivität automatisch neu erstellt wird. Dazu gehören das Ändern der Größe eines Hauptbereichs, das Anschließen von Peripheriegeräten und das Wechseln zwischen dem hellen und dem dunklen Modus. Wenn Sie Probleme mit der Ungültigmachung von Sitzungen haben, können Sie unter anderem Folgendes tun: Das Hauptfeld nicht in der Größe veränderbar machen, eine dynamische Feld-Entität verwenden, die Neuerstellung von Aktivitäten deaktivieren oder Änderungen am hellen/dunklen Design deaktivieren.
  • Verschiebbare und in der Größe anpassbare Komponenten werden in GltfEntity nicht unterstützt.
  • Entity.getSize() wird für GltfEntity nicht unterstützt.
  • Jetpack XR-Apps müssen die Berechtigung android.permission.SCENE_UNDERSTANDING in AndroidManifest anfordern.
  • Das Erstellen einer Sitzung wird nur auf Android XR-Geräten unterstützt. Wenn Sie derzeit eine Sitzung erstellen und versuchen, sie auf einem XR-Gerät zu verwenden, das nicht auf Android basiert, erhalten Sie eine RuntimeException.
  • Wenn die Skybox über `SpatialEnvironment.setSpatialEnvironmentPreference()` auf „null“ gesetzt wird, wird nicht wie dokumentiert eine einfarbig schwarze Skybox angezeigt. Möglicherweise wird die Standard-Skybox des Systems verwendet oder die aktuelle Skybox bleibt unverändert.
  • SceneCore-Clients sollten implementation(“com.google.guava:listenablefuture-1.0”) in ihrer Gradle-Konfiguration für die Abhängigkeiten ihrer App hinzufügen. In einer zukünftigen Version wird diese Bibliothek als api-Abhängigkeit in „scenecore“ enthalten sein, sodass Clients sie nicht explizit deklarieren müssen.
  • SceneCore enthält fälschlicherweise com.google.guava:guava-31.1-android und com.google.protobuf:protobuf-javalite als transitive Abhängigkeiten. Wenn dies zu Fehlern aufgrund doppelter Klassen in Ihrem Build führt, können diese beiden Abhängigkeiten problemlos ausgeschlossen werden.
  • Wenn Ihre App SceneCore verwendet und ProGuard aktiviert ist, stürzt sie beim Erstellen einer Sitzung ab. Deaktivieren Sie ProGuard als Behelfslösung. Weitere Informationen zum Aktivieren von ProGuard finden Sie in diesem Leitfaden.