{ } { }

Jetpack SceneCore

tworzyć i modyfikować graf sceny Androida XR za pomocą treści 3D.
Ostatnia aktualizacja Wersja stabilna Wersja kandydująca Wersja Beta Wersja alfa
12 lutego 2025 r. - - - 1.0.0-alpha02

Deklarowanie zależności

Aby dodać zależność od XR SceneCore, musisz dodać repozytorium Google Maven do projektu. Więcej informacji znajdziesz w repozytorium Maven firmy Google.

Dodaj zależności dla artefaktów, których potrzebujesz, w pliku build.gradle aplikacji lub modułu:

Odlotowe

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

Więcej informacji o zależnościach znajdziesz w artykule Dodawanie zależności kompilacji.

Opinia

Twoja opinia pomoże nam ulepszyć Jetpacka. Jeśli zauważysz nowe problemy lub masz pomysły na ulepszenie tej biblioteki, daj nam znać. Zanim utworzysz nowy problem, zapoznaj się z dotychczasowymi problemami w tej bibliotece. Możesz oddać głos w sprawie istniejącego problemu, klikając przycisk z gwiazdką.

Tworzenie nowego zgłoszenia

Więcej informacji znajdziesz w dokumentacji narzędzia Issue Tracker.

Wersja 1.0

Wersja 1.0.0-alpha02

12 lutego 2025 r.

androidx.xr.scenecore:scenecore:1.0.0-alpha02 i androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02 są dostępne. Wersja 1.0.0-alpha02 zawiera te komity.

Nadchodząca zmiana, która wpłynie na aplikacje utworzone przed wersją 1.0.0-alpha02

  • Metody fabryczne zostały przeniesione z klasy Session do metod towarzyszących w przypadku poszczególnych typów:
    • Tabela Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) została usunięta i zastąpiona tabelą ActivityPanelEntity.create(Session, Dimensions, String, Pose)
    • Tabela Session.createAnchorEntity(Anchor) została usunięta i zastąpiona tabelą AnchorEntity.create(Session, Anchor)
    • Tabela Session.createAnchorEntity(Dimensions, Int, Int, Duration) została usunięta i zastąpiona tabelą AnchorEntity.create(Session, Dimensions, Int, Int, Duration)
    • Tabela Session.createEntity(String, Pose) została usunięta i zastąpiona tabelą ContentlessEntity.create(Session, String, Pose)
    • Tabela Session.createExrImageResource(String) została usunięta i zastąpiona tabelą ExrImage.create(Session, String)
    • Tabela Session.createGltfEntity(GltfModel, Pose) została usunięta i zastąpiona tabelą GltfModelEntity.create(Session, GltfModel, Pose)
    • Tabela Session.createGltfModelResource(String) została usunięta i zastąpiona tabelą GltfModel.create(Session, String)
    • Tabela Session.createInteractableComponent(Executor, InputEventListener) została usunięta i zastąpiona tabelą InteractableComponent.create(Session, Executor, InputEventListener)
    • Tabela Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) została usunięta i zastąpiona tabelą MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
    • Tabela Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) została usunięta i zastąpiona tabelą PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose)
    • Tabela Session.createResizableComponent(Dimensions, Dimensions) została usunięta i zastąpiona tabelą ResizableComponent.create(Session, Dimensions, Dimensions)
    • Tabela Session.createStereoSurfaceEntity(Int, Dimensions, Pose) została usunięta i zastąpiona tabelą StereoSurface.create(Session, Int, Dimensions, Pose)
  • Usunęliśmy te wycofane metody:
    • Kontakt Session.canEmbedActivityPanel(Activity) został usunięty. Zamiast tego użyj kolumny getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY).
    • Kontakt Session.hasSpatialCapability(Int) został usunięty. Został on zastąpiony przez getSpatialCapabilities().hasCapability(), ponieważ getSpatialCapabilities() zwraca obiekt SpatialCapabilities, co pozwala na bardziej uporządkowany sposób sprawdzania obecności funkcji przestrzennych.
    • Tabela Session.requestFullSpaceMode() została usunięta i zastąpiona tabelą SpatialEnvironment.requestFullSpaceMode()
    • Tabela Session.requestHomeSpaceMode() została usunięta i zastąpiona tabelą SpatialEnvironment.requestHomeSpaceMode()
  • Funkcje Session.setFullSpaceMode(Bundle) i Session.setFullSpaceModeWithEnvironmentInherited(Bundle) zostały przeniesione do funkcji rozszerzeń. Pliki deweloperów muszą zawierać nowe instrukcje importowania:
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Funkcja Session.setPreferredAspectRatio(Activity, Float) została przeniesiona do funkcji rozszerzenia. Pliki deweloperów muszą dodać nowy import, aby uzyskać dostęp:
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Funkcje Session.getEntitiesOfType(Class<out T>) i Session.getEntityForRtEntity(RtEntity) zostały przeniesione do funkcji rozszerzeń. Pliki deweloperów muszą zawierać nowe instrukcje importowania:
    • import androidx.xr.scenecore.getEntitiesOfType
    • import androidx.xr.scenecore.getEntityForRtEntity
  • Pokój Session.unpersistAnchor(Anchor) został usunięty
  • Pokój Session.createPersistedAnchorEntity(UUID) został usunięty

Znane problemy

  • Ustawienia PanelEntity.setCornerRadius() i ActivityPanelEntity.setCornerRadius() mogą nie zadziałać, dopóki panel nie zostanie przeniesiony. Można to obejść, przenosząc panel do jego bieżącej pozycji.
  • Gdy wywoływana jest funkcja BoundsChanged w obiekcie ActivitySpace, niektóre ActivityPose mogą nie zostać prawidłowo zaktualizowane. Zostanie on zaktualizowany podczas następnego połączenia OnSpaceUpdated na ActivitySpace

Zmiany w zakresie zmian w funkcjonalności i zachowaniu

  • PanelEntity i ActivityPanelEntity będą mieć domyślny promień narożnika wynoszący 32 dp lub mniej, jeśli panel ma szerokość lub wysokość mniejszą niż 32 dp.

Nowe interfejsy API i funkcje

  • Wprowadza StereoSurface.CanvasShape, który umożliwia tworzenie Spherical i Hemispherical do renderowania treści wrażeń przestrzennych.
  • StereoSurfaceEntity.create() obsługuje teraz parametr CanvasShape. (Ten parametr jest obecnie ignorowany, ale będzie używany w przyszłej wersji)
  • Funkcja StereoSurfaceEntity.create() nie przyjmuje już parametru Dimensions. Aplikacje powinny kontrolować rozmiar płótna za pomocą ustawienia CanvasShape
  • StereoSurfaceEntity ma element CanvasShape, który może być ustawiany dynamicznie.
  • Właściwość StereoSurfaceEntity.dimensions jest teraz tylko do odczytu. Aplikacje powinny ustawiać wartość CanvasShape, aby zmieniać wymiary.
  • StereoSurfaceEntity umożliwia teraz ponowne ustawienie StereoMode po utworzeniu.

Inne zmiany

  • Zmniejszono minimalną wersję Androida na etapie kompilacji do 24. Wszystkie interfejsy Jetpack XR nadal wymagają interfejsu API 34 w czasie wykonywania.
  • Fabryka sesji (Session.create) usługi SceneCore nie uruchamia już intencji służącej do uzyskania uprawnień SCENE_UNDERSTANDING. Zamiast tego aplikacja klienta musi wyraźnie poprosić użytkownika o przyznanie uprawnień, zanim spróbuje utworzyć kotwicy. Jeśli użytkownik nie przyzna uprawnień, utworzenie kotwicy się nie powiedzie.

Poprawki błędów

  • Funkcja getActivitySpacePose() została naprawiona, aby uwzględnić skalę ActivitySpace, zwracając wartości przekształcania w skali metrycznej, a nie zawsze w metrycznej. Funkcja transformPoseTo używa teraz odpowiednich jednostek do obliczania zmian współrzędnych, gdy ActivitySpace jest używana w źródle lub docelowym.
  • Skybox będzie teraz ustawiany jako czarny, gdy zostanie przekazane puste ustawienie skyboxa za pomocą setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). Aby przywrócić domyślną geometrię i niebo systemu, użyj setSpatialEnvironmentPreference(null).

Wersja 1.0.0-alpha01

12 grudnia 2024 r.

androidx.xr.scenecore:scenecore-* 1.0.0-alpha01 został zwolniony.

Funkcje wersji początkowej Pierwsza wersja dla deweloperów Jetpack SceneCore, czyli biblioteki grafu sceny 3D do tworzenia i modyfikowania realistycznych scen oraz środowisk. Ta biblioteka umożliwia umieszczanie i ustawianie modeli 3D oraz paneli z treściami względem siebie i otoczenia wirtualnego lub rzeczywistego.

  • SpatialEnvironment: twórz wciągające wrażenia za pomocą obrazu nieba lub geometrii modelu 3D jako tła sceny XR środowiska. Możesz też włączyć przepuszczanie, aby Twoja wirtualna scena mogła zostać zintegrowana ze środowiskiem rzeczywistym użytkownika.
  • PanelEntity: dodawanie treści 2D do scen 3D przez umieszczanie standardowych układów i czynności Androida w panelach przestrzennych, które mogą unosić się w powietrzu lub być zakotwiczone na prawdziwych powierzchniach.
  • GltfModelEntity: umieszczanie, animowanie i interakcja z modelami 3D w scenie. SceneCore obsługuje format pliku glTF, aby ułatwić integrację z dotychczasowymi modelami.
  • SpatialAudio: dodaj źródła dźwięku otoczenia i punktowe do sceny 3D, aby uzyskać w pełni przestrzenny dźwięk.
  • StereoSurfaceEntity: SceneCore obsługuje kierowanie treści renderowanych na urządzeniu z Androidem na lewe lub prawe oko. Można go wykorzystać do renderowania treści stereoskopowych w formacie side-by-side (obok siebie) lub top-bottom (u góry i u dołu), takich jak zdjęcia stereoskopowe, filmy 3D czy inne interfejsy renderowane dynamicznie. Aplikacje powinny używać MediaPlayer lub ExoPlayer do dekodowania wideo.
  • System komponentów: SceneCore oferuje niezawodny i elastyczny system komponentów, który umożliwia dodawanie funkcji do treści XR, w tym możliwości przenoszenia, zmiany rozmiaru i interakcji z modelami i panelami.
  • Przypinanie: gdy masz włączone przepuszczanie, możesz dołączać panele i modele do rzeczywistych powierzchni, co umożliwia użytkownikom płynne łączenie wirtualnych treści z ich rzeczywistym otoczeniem.
  • Pozycja użytkownika: dostęp do lokalizacji użytkownika w wirtualnej scenie, aby ustawić treści w pobliżu jego pozycji.
  • SpatialCapabilities: tworzenie w pełni dostosowanych aplikacji, które wykorzystują możliwości przestrzenne, takie jak pozycjonowanie 3D elementów interfejsu. Aplikacja może też monitorować zmiany w możliwościach podczas wykonywania, aby modyfikować działanie w zależności od tego, jak użytkownik korzysta z urządzenia z Androidem XR.

Znane problemy

  • Obecnie do korzystania z Jetpack SceneCore wymagana jest minimalna wersja pakietu SDK 30. Aby skompilować i uruchomić aplikację z wartością minSDK 23, jako obejście dodaj do pliku manifestu ten wpis <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>.
  • Sesja może stać się nieważna w różnych sytuacjach, które powodują automatyczne odtwarzanie aktywności, w tym zmianę rozmiaru panelu głównego, podłączenie urządzeń peryferyjnych i przełączanie się między trybem jasnym a ciemnym. Jeśli napotkasz problemy z unieważnianiem sesji, możesz je obejść, np. przez ustawienie panelu głównego jako nierozszerzalnego, użycie elementu panelu dynamicznego, wyłączenie odtwarzania aktywności w przypadku określonych zmian konfiguracji lub wyłączenie zmian motywu jasnego/ciemnego.
  • Elementy ruchome i zmiennej wielkości nie są obsługiwane w przypadku obiektu GltfEntity.
  • Metoda Entity.getSize() nie jest obsługiwana w przypadku obiektu GltfEntity.
  • Aplikacje Jetpack XR muszą poprosić o uprawnienie android.permission.SCENE_UNDERSTANDING w pliku AndroidManifest.
  • Tworzenie sesji jest obsługiwane tylko na urządzeniu z Androidem XR. Jeśli w tej chwili utworzysz sesję i spróbujesz jej użyć na urządzeniu, które nie jest zgodne z Androidem XR, pojawi się wyjątek RuntimeException.
  • Ustawienie niestandardowej kuli ziemskiej za pomocą funkcji SpatialEnvironment.setSpatialEnvironmentPreference() nie powoduje, jak to zostało udokumentowane, że sfera niebieska jest czarna. Może to spowodować użycie domyślnej sceny nieba lub brak zmian w obecnej scenie nieba.
  • Klienci korzystający z SceneCore powinni dodać implementation(“com.google.guava:listenablefuture-1.0”) do konfiguracji Gradle dla zależności aplikacji. W przyszłej wersji biblioteka scenecore będzie zawierać tę bibliotekę jako api, więc klienci nie będą musieli jej deklarować.
  • SceneCore błędnie zawiera com.google.guava:guava-31.1-android i com.google.protobuf:protobuf-javalite jako zależności pośrednie. Jeśli powoduje to w Twojej kompilacji zduplikowane błędy klasy, możesz bezpiecznie wykluczyć te 2 zależności.
  • Jeśli aplikacja korzysta z SceneCore i ma włączony ProGuard, ulegnie awarii podczas tworzenia sesji. Aby rozwiązać ten problem, wyłącz ProGuard. Więcej informacji o włączaniu funkcji ProGuard znajdziesz w tym przewodniku.