{ } { }

Jetpack SceneCore

Die Android XR-Szenengraphik mit 3D-Inhalten erstellen und bearbeiten
Letzte Aktualisierung Stabile Version Release-Kandidat Beta-Ausgabe Alphaversion
12. Februar 2025 - – - 1.0.0-alpha02

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

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-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 Klasse Session 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 in 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 in 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 statt immer in nicht skalierten Metern zurückgegeben. 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. 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 Probleme mit der Sitzungsstornierung auftreten, können Sie als Problemumgehung das Hauptsteuerfeld größenfixieren, ein dynamisches Steuerfeld verwenden, die Aktivitätswiederherstellung für bestimmte Konfigurationsänderungen deaktivieren oder die Themenänderungen 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 die Standard-Skybox des Systems verwendet wird oder dass sich die aktuelle Skybox nicht ändert.
  • 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.