{ } { }

Jetpack SceneCore

Die Android XR-Szenengraphik mit 3D-Inhalten erstellen und bearbeiten
Letzte Aktualisierung Stabile Version Releasekandidat Beta-Ausgabe Alphaversion
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 erforderlichen 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. Bitte teilen Sie uns mit, wenn Sie neue Probleme feststellen 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 einem vorhandenen Problem Ihre Stimme geben, indem Sie auf die Schaltfläche mit dem Stern klicken.

Neues Problem erstellen

Weitere Informationen finden Sie in der Dokumentation zum Issue Tracker.

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 freigegeben. Version 1.0.0-alpha04 enthält diese Commits.

Neue Funktionen

  • Die Rückhandhabung funktioniert jetzt auch für Bereichsentitäten ohne eingebettete Aktivitäten. Damit die Back-Handling-Funktion funktioniert, müssen Sie android:enableOnBackInvokedCallback= "true" im Android-Manifest angeben.
  • StereoSurfaceEntity unterstützt jetzt die Wiedergabe von MV-HEVC über zwei neue StereoMode-Werte: MULTIVIEW_LEFT_PRIMARY und MULTIVIEW_RIGHT_PRIMARY.
  • PanelEntity.setSize und PanelEntity.getSize geben jetzt Größen im übergeordneten Gruppenbereich zurück.
  • Für Entity.setPose, Entity.getPose, Entity.setScale, Entity.getScale, Entity.setAlpha und Entity.getAlpha gibt es jetzt den neuen Parameter relativeTo, mit dem Werte relativ zu verschiedenen Gruppenbereichen abgerufen und festgelegt werden können. Die unterstützten Werte sind „Übergeordnet“, „Aktivität“ und „Real World“. Der Standardwert für diesen Parameter ist „Übergeordnet“.
  • SessionExt.kt wurden Erweiterungsmethoden für Rückrufe zur räumlichen Sichtbarkeit hinzugefügt, um zu überwachen, wann sich die Szeneninhalte in das Blickfeld des Nutzers bewegen oder daraus heraustreten.
  • setPointSourceParams wurde SpatialAudioTrack hinzugefügt, damit die Parameter nach dem Erstellen des Tracks aktualisiert werden können.
  • Es wurde eine neue Klasse „Scene“ mit Verweis auf Scenecore APIs hinzugefügt. Auf „Szene“ kann als Erweiterungseigenschaft von „Sitzung“ zugegriffen werden. Funktionen in SessionExt wurden in „Szene“ 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 gegen virtuelle Inhalte möglich ist.
  • Der neue Komponententyp SpatialPointerComponent wurde hinzugefügt. Damit können Kunden das Symbol angeben, das für den Cursor gerendert werden soll, oder das Symbol deaktivieren. Diese Komponente kann derzeit nur an PanelEntity-Instanzen angehängt werden.
  • Neue PanelEntity-Fabrik, die die Abmessungen von Panels in Metern oder Pixeln annimmt Ältere PanelEntity-Fabrik, die zwei Parameter vom Typ „Dimension“ für das Steuerfeld akzeptiert, wurde entfernt.

API-Änderungen

  • Die Einschränkung für RequiresApi(34) wurde für alle Jetpack XR-Pakete aufgehoben. Diese Einschränkung war redundant, da Jetpack XR derzeit nur auf Geräten mit API-Level 34 und 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 wurde eingestellt.
  • 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 Sitzungsklasse in SceneCore wurde zugunsten der Sitzung in der XR-Laufzeit 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.
  • Der Zugriff auf die Entität PointSourceParams wurde von „öffentlich“ zu „intern“ geändert.
  • Für AnchorEntity.create muss jetzt PlaneTrackingMode in Session.configure() konfiguriert werden.
  • Für SpatialUser-APIs muss HeadTrackingMode jetzt in Session.configure() konfiguriert werden.
  • Wenn ResizableComponent nicht angehängt ist, wird ein Protokoll auf INFO-Ebene statt auf ERROR-Ebene ausgegeben.
  • Die Klasse „Fov“ ist jetzt eine reguläre Kotlin-Klasse.
  • Splitten Sie Entity.kt, um jeden konkreten Entitätstyp in eine eigene Datei zu verschieben.
  • Wenn Sie eine neue PanelEntity erstellen, werden die meisten Datenansichten einem FrameLayout neu zugeordnet. So lässt sich LayoutInspector einfacher mit räumlichen Infofeldern verwenden.
  • Die derzeit verwendete XrExtensions-Instanz wird jetzt auf der Plattform registriert, um das Entwickeln von Apps zu unterstützen.

Fehlerkorrekturen

  • Ein Fehler wurde behoben, der beim Verschieben einer PanelEntity mit MovableComponent und AnchorPlacement zu einem Absturz führen konnte.
  • Ein Problem wurde behoben, durch das ResizableComponent im onResizeStart-Callback veraltete Größen zurückgab.
  • Ein Absturz wurde behoben, der auftrat, wenn dispose() von JxrPlatformAdapterAxr 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 freigegeben. Version 1.0.0-alpha03 enthält diese Commits.

Neue Funktionen

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

Fehlerkorrekturen

  • Weitere Fehlerkorrekturen zur Unterstützung der Proguard-Minimierung für Jetpack XR SceneCore (I4f47e)
  • Die Jetpack XR Scenecore-ProGuard-Regel 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 freigegeben. Version 1.0.0-alpha02 enthält diese Commits.

Anstehende gravierende Änderung für vor 1.0.0-alpha02 erstellte Apps

  • Die Fabrikmethoden wurden aus der Session-Klasse in eine zugehörige 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 veralteten 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 es eine detailliertere Möglichkeit bietet, die Verfügbarkeit von geografischen 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 zu Erweiterungsfunktionen verschoben. Entwicklerdateien müssen die neuen Importe für den Zugriff hinzufügen:
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float) wurde in eine Erweiterungsfunktion verschoben. Entwicklerdateien müssen den neuen Import für den Zugriff hinzufügen:
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Session.getEntitiesOfType(Class<out T>) und Session.getEntityForRtEntity(RtEntity) wurden zu Erweiterungsfunktionen verschoben. Entwicklerdateien müssen die neuen Importe für den Zugriff hinzufügen:
    • 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 beim nächsten Verschieben des Steuerfelds wirksam. Sie können dies vermeiden, indem Sie das Steuerfeld an seine aktuelle Position verschieben.
  • Wenn BoundsChanged auf der ActivitySpace aufgerufen wird, wurden einige ActivityPoses möglicherweise nicht richtig aktualisiert. Sie wird beim nächsten OnSpaceUpdated-Anruf am ActivitySpace aktualisiert.

Nicht abwärtskompatible Änderungen und Verhaltensänderungen

  • PanelEntity und ActivityPanelEntity haben standardmäßig einen Eckradius von 32 dp oder weniger, wenn der Bereich eine Breite oder Höhe von weniger als 32 dp hat.

Neue APIs und Funktionen

  • Einführung von StereoSurface.CanvasShape, mit dem Spherical- und Hemispherical-Canvases zum Rendern von immersiven Medien erstellt werden können.
  • Für StereoSurfaceEntity.create() kann jetzt ein CanvasShape-Parameter verwendet werden. (Dieser Parameter wird derzeit ignoriert, aber in einer zukünftigen Version verwendet.)
  • Für StereoSurfaceEntity.create() ist kein Dimensions-Parameter mehr erforderlich. Die Größe des Canvas sollte in Anwendungen über die Einstellung CanvasShape gesteuert werden.
  • StereoSurfaceEntity hat ein CanvasShape-Mitglied, das dynamisch festgelegt werden kann.
  • StereoSurfaceEntity.dimensions ist jetzt eine schreibgeschützte Property. In Anwendungen sollte CanvasShape festgelegt werden, um Dimensionen zu ändern.
  • Mit StereoSurfaceEntity kann StereoMode jetzt nach dem Erstellen zurückgesetzt werden.

Sonstige Änderungen

  • Das Mindest-SDK für die Kompilierungszeit wurde auf 24 reduziert. Für alle Jetpack XR APIs ist weiterhin API 34 in der Laufzeit erforderlich.
  • Die Sitzungs-Factory von SceneCore (Session.create) startet nicht mehr den Intent zum Abrufen der Berechtigung SCENE_UNDERSTANDING. Stattdessen muss die Clientanwendung die Berechtigungen vom Nutzer explizit anfordern, bevor versucht wird, die Anker zu erstellen. Die Erstellung des Ankers schlägt fehl, wenn der Nutzer die Berechtigung nicht gewährt.

Fehlerkorrekturen

  • getActivitySpacePose() wurde korrigiert, um die ActivitySpace-Skala zu berücksichtigen. Es werden jetzt Übersetzungswerte in skalierten Metern zurückgegeben, anstatt immer nicht skalierte Meter. transformPoseTo verwendet jetzt auch die richtigen Einheiten, um Koordinatenänderungen zu berechnen, wenn die ActivitySpace in der Quelle oder dem Ziel enthalten ist.
  • Die Skybox wird jetzt auf eine komplett schwarze Skybox gesetzt, wenn über setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) eine Einstellung für eine leere Skybox übergeben wird. Wenn Sie zum Standard-Skybox und zur Standardgeometrie 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: Mit einem Skybox-Bild und/oder einer 3D‑Modellgeometrie als Kulisse für Ihre XR-Szene Ihrer Umgebung können Sie ein vollständig immersives Erlebnis schaffen. Sie können auch die Funktion „Passthrough“ aktivieren, damit Ihre virtuelle Szene in die reale Umgebung des Nutzers eingebunden werden kann.
  • PanelEntity: Fügen Sie Ihren 3D-Szenen 2D-Inhalte hinzu, indem Sie standardmäßige Android-Layouts und ‑Aktivitäten in räumliche Bereiche einbetten, die schweben oder an realen Oberflächen verankert werden können.
  • GltfModelEntity: Hiermit können Sie 3D-Modelle in Ihrer Szene platzieren, animieren und mit ihnen interagieren. SceneCore unterstützt das glTF-Dateiformat, um die Einbindung in vorhandene Modelle zu vereinfachen.
  • SpatialAudio: Fügen Sie Ihrer 3D-Szene Umgebungs- und Punktaudioquellen hinzu, um einen räumlichen, immersiven Klang zu erzielen.
  • StereoSurfaceEntity: SceneCore unterstützt das Routing von Inhalten, die auf einer Android-Oberfläche gerendert werden, an das linke oder rechte Auge. So können Sie stereoskopische Inhalte im Side-by-Side- oder im Top-Bottom-Format rendern, z. B. Stereofotos, 3D-Videos oder andere dynamisch gerenderte Benutzeroberflächen. Für die Videodecodierung sollten Anwendungen MediaPlayer oder ExoPlayer verwenden.
  • Komponentensystem: SceneCore bietet ein robustes und flexibles Komponentensystem, mit dem Sie Ihren XR-Inhalten Funktionen hinzufügen können. Dazu gehören Funktionen, mit denen Nutzer Modelle und Steuerfelder verschieben, ihre Größe ändern und mit ihnen interagieren können.
  • Ankern: Wenn die Funktion „Durchlässiges AR“ aktiviert ist, können Sie Panels und Modelle an tatsächlichen Oberflächen anbringen. So können Nutzer virtuelle Inhalte nahtlos in ihre reale Umgebung einbinden.
  • Nutzerpose: Sie können auf die Position des Nutzers in der virtuellen Szene zugreifen, um Ihre Inhalte an seiner Position auszurichten.
  • SpatialCapabilities: Erstellen Sie vollständig adaptive Apps, die standortbezogene Funktionen nutzen, sofern verfügbar, z. B. die 3D-Positionierung von UI-Inhalten. Außerdem kann Ihre App während der Ausführung auf Änderungen an den Funktionen achten, um die Nutzung entsprechend der Art und Weise anzupassen, wie der Nutzer sein Android XR-Gerät verwendet.

Bekannte Probleme

  • Derzeit ist ein minSDK von 30 erforderlich, um Jetpack SceneCore zu verwenden. Als Problemumgehung fügen Sie den folgenden Manifesteintrag <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> hinzu, damit die App mit einer Mindest-SDK-Version von 23 erstellt und ausgeführt werden kann.
  • Die Sitzung kann in verschiedenen Situationen ungültig werden, in denen die Aktivität automatisch neu erstellt wird, z. B. wenn Sie die Größe eines Hauptbereichs ändern, Peripheriegeräte anschließen oder zwischen dem hellen und dem dunklen Modus wechseln. Wenn Probleme mit der Sitzungsstornierung auftreten, können Sie als Problemumgehung das Hauptsteuerfeld größenfixieren, ein dynamisches Steuerfeld verwenden, die Wiederherstellung von Aktivitäten für bestimmte Konfigurationsänderungen deaktivieren oder die Änderungen des Themas für den hellen/dunklen Modus deaktivieren.
  • Bewegliche und veränderbare Komponenten werden von GltfEntity nicht unterstützt.
  • Entity.getSize() wird von 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 einem Android XR-Gerät unterstützt. Wenn Sie derzeit eine Sitzung erstellen und versuchen, sie auf einem Gerät zu verwenden, das kein Android XR-Gerät ist, wird eine RuntimeException ausgegeben.
  • Wenn Sie den Skybox über „SpatialEnvironment.setSpatialEnvironmentPreference()“ auf „null“ setzen, wird nicht wie beschrieben ein durchgehend schwarzer Skybox angezeigt. Dies kann dazu führen, dass der Standard-Skybox des Systems verwendet wird oder dass der aktuelle Skybox nicht geändert wird.
  • SceneCore-Kunden 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 von Scenecore als api-Abhängigkeit enthalten, 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 doppelten Klassenfehlern in Ihrem Build führt, können diese beiden Abhängigkeiten sicher ausgeschlossen werden.
  • Wenn Ihre App SceneCore verwendet und ProGuard aktiviert ist, stürzt sie beim Erstellen einer Sitzung ab. Deaktivieren Sie als Behelfslösung ProGuard. Weitere Informationen zum Aktivieren von ProGuard finden Sie in diesem Leitfaden.