{ } { }

Jetpack SceneCore

tworzyć i modyfikować graf sceny Androida XR za pomocą treści 3D.
Ostatnia aktualizacja Wersja stabilna Wersja kandydująca do publikacji Wersja Beta Wersja alfa
7 maja 2025 r. - - - 1.0.0-alpha04

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

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 zagłosować na istniejący problem, 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-alpha04

7 maja 2025 r.

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

Nowe funkcje

  • Obsługa z tyły będzie teraz działać w przypadku elementów panelu bez wbudowanych działań. Aby przetwarzanie wsteczne działało, musisz określić android:enableOnBackInvokedCallback= "true" w pliku manifestu Androida.
  • StereoSurfaceEntity obsługuje teraz odtwarzanie MV-HEVC za pomocą 2 nowych wartości StereoMode: MULTIVIEW_LEFT_PRIMARY i MULTIVIEW_RIGHT_PRIMARY.
  • Funkcje PanelEntity.setSize i PanelEntity.getSize zwracają teraz rozmiary w przestrzeni nadrzędnej.
  • Funkcje Entity.setPose, Entity.getPose, Entity.setScale, Entity.getScale, Entity.setAlpha i Entity.getAlpha przyjmują teraz nowy parametr relativeTo, który umożliwia pobieranie i ustawianie wartości w różnych przestrzeniach. Obsługiwane wartości to Parent (Nadrzędny), Activity (Aktywność) i Real World (Świat rzeczywisty), a wartością domyślną tego parametru jest Parent (Nadrzędny).
  • Do SessionExt.kt dodano metody rozszerzenia wywołania zwrotnego dotyczące widoczności przestrzennej, aby monitorować, kiedy zawartość sceny przemieszcza się w polu widzenia użytkownika.
  • Do pliku SpatialAudioTrack dodano plik setPointSourceParams, co umożliwia aktualizowanie parametrów po utworzeniu ścieżki.
  • Dodaliśmy nową klasę Scene z odwołaniami do interfejsów API Scenecore. Scena będzie dostępna jako parametr rozszerzenia sesji. Funkcje w SessionExt zostały przeniesione do sceny, więc importy będą musiały zostać dostosowane, np. SessionExt.getScene(session).addSpatialCapababilitiesChangedListener kontra SessionExt.addSpatialCapabilitiesChangedListener.
  • Dodano ActivityPose.hitTestAsync, co umożliwia hitTest w przypadku treści wirtualnych.
  • Dodano nowy typ komponentu SpatialPointerComponent, który umożliwia klientom określenie ikony renderowanej dla wskaźnika lub jej wyłączenie. Ten komponent można obecnie dołączać tylko do instancji PanelEntity.
  • Przedstawiamy nową fabrykę PanelEntity, która przyjmuje wymiary paneli w metrach lub pikselach. Usunięto starszy PanelEntity factory, który przyjmował 2 parametry typu wymiaru w panelu.

Zmiany w interfejsie API

  • Usunięto ograniczenie RequiresApi(34) we wszystkich pakietach Jetpack XR. To ograniczenie było zbędne, ponieważ Jetpack XR jest obecnie dostępny tylko na urządzeniach z poziomem interfejsu API 34 lub nowszym (Iae0f8).
  • Projekty opublikowane z Kotlin 2.0 wymagają KGP 2.0.0 lub nowszej wersji (Idb6b5).
  • Zajęcia PermissionHelper zostały usunięte.
  • Środowisko wykonawcze PanelEntity.getPixelDensity zostało wycofane.
  • Usługi PanelEntity.setPixelDimensions i PanelEntity.getPixelDimension zostały usunięte i zastąpione usługami setSizeInPixels i getSizeInPixels.
  • Opcja Entity.getActivitySpaceAlpha została usunięta. Może być zastąpiony przez Entity.getAlpha(Space.Activity).
  • Opcja Entity.getWorldSpaceScale została usunięta. Może być zastąpiony przez Entity.getScale(Space.REAL\_WORLD).
  • Klasa Session w SceneCore została usunięta na rzecz klasy Session w XR Runtime.
  • Nazwa StereoSurfaceEntity została zmieniona na SurfaceEntity.
  • Metody Entity.setSize i Entity.getSize zostały usunięte, a te same metody zostały dodane do metody PanelEntity.
  • Nazwa PointSourceAttributes została zmieniona na PointSourceParams.
  • Nazwa SpatializerConstants.SOURCE\_TYPE\_BYPASS została zmieniona na SpatializerConstants.SOURCE\_TYPE\_DEFAULT.
  • Element PointSourceParams został zmodyfikowany z dostępu publicznego na dostęp wewnętrzny.
  • Funkcja AnchorEntity.create wymaga teraz skonfigurowania elementu PlaneTrackingMode w sekcji Session.configure().
  • Interfejsy API SpatialUser wymagają teraz skonfigurowania HeadTrackingMode w Session.configure().
  • Jeśli nie dołączysz parametru ResizableComponent, zostanie wyświetlony dziennik na poziomie INFO, a nie ERROR.
  • Klasa Fov jest teraz zwykłą klasą Kotlin.
  • Split Entity.kt, aby umieścić każdy konkretny typ elementu w osobnym pliku.
  • Podczas tworzenia nowego widoku PanelEntity większość widoków zostanie przeniesiona do widoku nadrzędnego FrameLayout. Ułatwia to korzystanie z funkcji LayoutInspector w ramach paneli przestrzennych.
  • Obecnie używana instancja XrExtensions jest zarejestrowana na platformie, aby ułatwić debugowanie aplikacji.

Poprawki błędów

  • Dodaliśmy poprawkę, która zapobiega awarii, która może wystąpić podczas przenoszenia PanelEntity z MovableComponent i AnchorPlacement.
  • Rozwiązaliśmy problem, który powodował, że ResizableComponent zwracał nieaktualne rozmiary w wywołaniu zwrotnym onResizeStart.
  • Rozwiązano problem z zawieszaniem się aplikacji, który występował, gdy funkcja JxrPlatformAdapterAxr była wywoływana wielokrotnie.dispose()

Wersja 1.0.0-alpha03

26 lutego 2025 r.

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

Nowe funkcje

  • Obsługa kompresji Proguard dla kodu Jetpack XR

Poprawki błędów

  • Dodatkowe poprawki umożliwiające obsługę kompresji Proguarda w przypadku Jetpacka XR SceneCore (I4f47e)
  • Zaktualizowano regułę ProGuard Jetpack XR Scenecore, aby zapobiec AbstractMethodError w przypadku zminiaturyzowanych klientów. (I91a01)

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 powodująca przerwanie działania aplikacji utworzonych przed wersją 1.0.0-alpha02

  • Metody fabryczne zostały przeniesione z klasy Session do metod towarzyszących w przypadku każdego odpowiedniego typu:
    • Usługa Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) została usunięta i zastąpiona usługą ActivityPanelEntity.create(Session, Dimensions, String, Pose)
    • Usługa Session.createAnchorEntity(Anchor) została usunięta i zastąpiona usługą AnchorEntity.create(Session, Anchor)
    • Usługa Session.createAnchorEntity(Dimensions, Int, Int, Duration) została usunięta i zastąpiona usługą AnchorEntity.create(Session, Dimensions, Int, Int, Duration)
    • Usługa Session.createEntity(String, Pose) została usunięta i zastąpiona usługą ContentlessEntity.create(Session, String, Pose)
    • Usługa Session.createExrImageResource(String) została usunięta i zastąpiona usługą ExrImage.create(Session, String)
    • Usługa Session.createGltfEntity(GltfModel, Pose) została usunięta i zastąpiona usługą GltfModelEntity.create(Session, GltfModel, Pose)
    • Usługa Session.createGltfModelResource(String) została usunięta i zastąpiona usługą GltfModel.create(Session, String)
    • Usługa Session.createInteractableComponent(Executor, InputEventListener) została usunięta i zastąpiona usługą InteractableComponent.create(Session, Executor, InputEventListener)
    • Usługa Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) została usunięta i zastąpiona usługą MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
    • Usługa Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) została usunięta i zastąpiona usługą PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose)
    • Usługa Session.createResizableComponent(Dimensions, Dimensions) została usunięta i zastąpiona usługą ResizableComponent.create(Session, Dimensions, Dimensions)
    • Usługa Session.createStereoSurfaceEntity(Int, Dimensions, Pose) została usunięta i zastąpiona usługą StereoSurface.create(Session, Int, Dimensions, Pose)
  • Usunęliśmy te wycofane metody:
    • Kontakt Session.canEmbedActivityPanel(Activity) został usunięty. Zamiast tego użyj 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 umożliwia bardziej uporządkowane sprawdzanie obecności funkcji przestrzennych.
    • Usługa Session.requestFullSpaceMode() została usunięta i zastąpiona usługą SpatialEnvironment.requestFullSpaceMode()
    • Usługa Session.requestHomeSpaceMode() została usunięta i zastąpiona usługą 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ą zawierać 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ń zaokrąglenia narożnika równy 32 dp lub mniejszy, 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 kanw do renderowania immersyjnych multimediów.
  • 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 zakończeniu tworzenia.

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 metryce nieskalibrowanej. transformPoseTo używa teraz odpowiednich jednostek do obliczania zmian współrzędnych, gdy ActivitySpace jest używany w źródle lub docelowym.
  • Skybox będzie teraz ustawiany jako czarny skybox, gdy zostanie przekazane puste ustawienie skybox 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.

Element 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 użytkownika.
  • PanelEntity: dodawanie treści 2D do scen 3D przez umieszczanie standardowych układów i działań Androida w panelach przestrzennych, które mogą unosić się w powietrzu lub być przytwierdzone do rzeczywistych powierzchni.
  • 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 swojej 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: po włączeniu funkcji przesyłania danych 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 automatycznie odtwarzają Aktywność, 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 zmiany 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 uprawnienia 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 urządzeniem XR z Androidem, 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 zależność api, więc klienci nie będą musieli jej deklarować w sposób jawny.
  • 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 obejść ten problem, wyłącz ProGuard. Więcej informacji o włączaniu funkcji ProGuard znajdziesz w tym przewodniku.