Ta strona została przetłumaczona przez Cloud Translation API.

Jetpack SceneCore

Dokumentacja API
androidx.xr.scenecore
androidx.xr.scenecore.testing

Twórz i modyfikuj wykres sceny Androida XR za pomocą treści 3D.

Najnowsza 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 Google.

Dodaj zależności dotyczące potrzebnych artefaktów 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 odkryjesz nowe problemy lub masz pomysły na ulepszenie tej biblioteki, daj nam znać. Zanim utworzysz nową kartę, zapoznaj się z dotychczasowymi problemami w tej bibliotece. Możesz dodać swój głos do istniejącego problemu, klikając przycisk gwiazdki.

Tworzenie nowego problemu

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 zostały opublikowane. Wersja 1.0.0-alpha04 zawiera te zmiany.

Nowe funkcje

Funkcja obsługi powrotu będzie teraz działać w przypadku elementów panelu bez osadzonych aktywności. Aby działało cofanie, musisz określić android:enableOnBackInvokedCallback= "true" w manifeście Androida.
StereoSurfaceEntity obsługuje teraz odtwarzanie MV-HEVC dzięki 2 nowym StereoMode wartościom: MULTIVIEW_LEFT_PRIMARY i MULTIVIEW_RIGHT_PRIMARY.
PanelEntity.setSize i PanelEntity.getSize zwracają teraz rozmiary w przestrzeni nadrzędnej.
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 względem różnych przestrzeni. Obsługiwane wartości to Parent, Activity i Real World spaces, a domyślna wartość tego parametru to Parent.
Dodano metody rozszerzenia wywołania zwrotnego widoczności przestrzennej do SessionExt.kt, aby monitorować, kiedy zawartość sceny przesuwa się wewnątrz lub na zewnątrz pola widzenia użytkownika.
Do obszaru roboczego SpatialAudioTrack dodano element setPointSourceParams, co umożliwia aktualizowanie parametrów po utworzeniu ścieżki.
Dodaliśmy nową klasę Scene z odwołaniami do interfejsów Scenecore API. Scena będzie dostępna jako właściwość rozszerzenia sesji. Funkcje w SessionExt zostały przeniesione do sceny, więc importy trzeba będzie dostosować, np. SessionExt.getScene(session).addSpatialCapababilitiesChangedListener – SessionExt.addSpatialCapabilitiesChangedListener
Dodano emotikon ActivityPose.hitTestAsync, który 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 wyłączenie ikony. Ten komponent można obecnie dołączać tylko do PanelEntity instancji.
Wprowadzamy nowy PanelEntity, który przyjmuje wymiary panelu w metrach lub pikselach. Starsza fabryka PanelEntity, która przyjmowała 2 parametry typu Dimension dla panelu, została usunięta.

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 API 34 lub wyższym. (Iae0f8)
Projekty wydane w Kotlinie 2.0 wymagają do użycia KGP w wersji 2.0.0 lub nowszej (Idb6b5).
Zajęcia PermissionHelper zostały usunięte.
Środowisko wykonawcze PanelEntity.getPixelDensity zostało wycofane.
PanelEntity.setPixelDimensions i PanelEntity.getPixelDimension zostały usunięte i zastąpione przez setSizeInPixels i getSizeInPixels.
Opcja Entity.getActivitySpaceAlpha została usunięta. Można go zastąpić elementem Entity.getAlpha(Space.Activity).
Opcja Entity.getWorldSpaceScale została usunięta. Można go zastąpić elementem Entity.getScale(Space.REAL\_WORLD).
Klasa Session w SceneCore została usunięta na rzecz klasy Session w środowisku wykonawczym XR.
Nazwa StereoSurfaceEntity została zmieniona na SurfaceEntity.
Entity.setSize i Entity.getSize zostaną usunięte, a te same metody zostaną dodane do PanelEntity.
Nazwa PointSourceAttributes została zmieniona na PointSourceParams.
Nazwa SpatializerConstants.SOURCE\_TYPE\_BYPASS została zmieniona na SpatializerConstants.SOURCE\_TYPE\_DEFAULT.
PointSourceParams został zmieniony z dostępu publicznego na wewnętrzny.
AnchorEntity.create wymaga teraz skonfigurowania PlaneTrackingMode w Session.configure().
Interfejsy API SpatialUser wymagają teraz skonfigurowania parametru HeadTrackingMode w usłudze Session.configure().
Jeśli ResizableComponent nie jest dołączony, zamiast logu na poziomie ERROR zostanie wygenerowany log na poziomie INFO.
Klasa Fov jest teraz zwykłą klasą Kotlin.
Podziel Entity.kt, aby umieścić każdy typ konkretnego elementu w osobnym pliku.
Podczas tworzenia nowego PanelEntity większość widoków zostanie przeniesiona do FrameLayout. Ułatwia to korzystanie z LayoutInspector w przypadku paneli przestrzennych.
Obecnie używana instancja XrExtensions jest teraz zarejestrowana na platformie w miarę możliwości, aby ułatwić debugowanie aplikacji.

Poprawki błędów

Dodaliśmy poprawkę, która zapobiega awarii, do której mogło dojść podczas przenoszenia PanelEntity z MovableComponent i AnchorPlacement.
Rozwiązaliśmy problem, który powodował, że funkcja ResizableComponent przekazywała nieaktualne rozmiary w wywołaniu zwrotnym onResizeStart.
Rozwiązano problem z awarią, która występowała, gdy funkcja JxrPlatformAdapterAxr's dispose() była wywoływana wielokrotnie.

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 zostały opublikowane. Wersja 1.0.0-alpha03 zawiera te commity.

Nowe funkcje

Minimalizacja Proguard jest teraz obsługiwana w przypadku kodu Jetpack XR

Poprawki błędów

Dodatkowe poprawki obsługi minimalizacji Proguard w przypadku Jetpack XR SceneCore (I4f47e)
Zaktualizowano regułę Jetpack XR Scenecore ProGuard, aby zapobiec AbstractMethodError w przypadku zminimalizowanych 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 zostały opublikowane. Wersja 1.0.0-alpha02 zawiera te zmiany.

Nadchodząca zmiana powodująca niezgodność wsteczną, która wpłynie na aplikacje utworzone przed wersją 1.0.0-alpha02

Metody fabrykujące zostały przeniesione z klasy Session do metody towarzyszącej w przypadku każdego 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:
- Pokój Session.canEmbedActivityPanel(Activity) został usunięty. Zamiast niej używaj zasady getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY).
- Pokój Session.hasSpatialCapability(Int) został usunięty. Została ona zastąpiona przez getSpatialCapabilities().hasCapability(), która jest bardziej odseparowanym sposobem sprawdzania obecności funkcji przestrzennych, ponieważ getSpatialCapabilities() zwraca obiekt SpatialCapabilities.
- 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()
Session.setFullSpaceMode(Bundle) i Session.setFullSpaceModeWithEnvironmentInherited(Bundle) zostały przeniesione do funkcji rozszerzeń. Aby uzyskać dostęp, deweloperzy będą musieli dodać do plików nowe instrukcje importu:
- import androidx.xr.scenecore.setFullSpaceMode
- import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
Session.setPreferredAspectRatio(Activity, Float) została przeniesiona do funkcji rozszerzenia. Do plików dewelopera trzeba będzie dodać nowy import, aby uzyskać dostęp:
- import androidx.xr.scenecore.setPreferredAspectRatio
Session.getEntitiesOfType(Class<out T>) i Session.getEntityForRtEntity(RtEntity) zostały przeniesione do funkcji rozszerzeń. Aby uzyskać dostęp, deweloperzy będą musieli dodać do plików nowe instrukcje importu:
- 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

PanelEntity.setCornerRadius() i ActivityPanelEntity.setCornerRadius() mogą zostać wprowadzone dopiero po następnym przesunięciu panelu. Można temu zapobiec, przesuwając panel do jego bieżącej pozycji.
Gdy funkcja BoundsChanged jest wywoływana na ActivitySpace, niektóre ActivityPose mogą nie zostać prawidłowo zaktualizowane. Zostanie ona zaktualizowana podczas następnej rozmowy OnSpaceUpdated, która odbędzie się ActivitySpace.

Zmiany w zachowaniu i nawyki

PanelEntity i ActivityPanelEntity będą miały domyślny promień zaokrąglenia wynoszący 32 dp lub mniej, jeśli panel ma szerokość lub wysokość mniejszą niż 32 dp.

Nowe interfejsy API i możliwości

Wprowadza StereoSurface.CanvasShape, które umożliwia tworzenie obszarów Spherical i Hemispherical do renderowania multimediów immersyjnych.
StereoSurfaceEntity.create() akceptuje teraz parametr CanvasShape. (Ten parametr jest obecnie ignorowany, ale będzie używany w przyszłej wersji)
StereoSurfaceEntity.create() nie przyjmuje już parametru Dimensions. Aplikacje powinny kontrolować rozmiar obszaru roboczego, ustawiając wartość CanvasShape
StereoSurfaceEntity ma CanvasShape element, który można ustawić dynamicznie.
StereoSurfaceEntity.dimensions jest teraz właściwością tylko do odczytu. Aby zmienić wymiary, aplikacje powinny ustawić CanvasShape.
StereoSurfaceEntity umożliwia teraz ponowne ustawienie StereoMode po zakończeniu budowy.

Inne zmiany

Zmniejszono minimalną wersję SDK w czasie kompilacji do 24. Wszystkie interfejsy Jetpack XR API nadal wymagają interfejsu API w wersji 34 w czasie działania.
Fabryka sesji SceneCore (Session.create) nie uruchamia już intencji uzyskania uprawnień SCENE_UNDERSTANDING. Zamiast tego aplikacja kliencka musi wyraźnie poprosić użytkownika o przyznanie uprawnień przed podjęciem próby utworzenia kotwic. Jeśli użytkownik nie przyzna tego uprawnienia, utworzenie kotwicy się nie powiedzie.

Poprawki błędów

getActivitySpacePose() został poprawiony, aby uwzględniać skalę ActivitySpace, zwracając wartości translacji w skalowanych metrach, a nie zawsze w metrach nieskalowanych. transformPoseTo używa teraz też odpowiednich jednostek do obliczania zmian współrzędnych, gdy ActivitySpace jest uwzględniony w źródle lub miejscu docelowym.
Gdy za pomocą setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) zostanie przekazane ustawienie pustego skyboxa, będzie on ustawiany na całkowicie czarny. Aby przywrócić domyślne ustawienia systemu dotyczące skyboxa i geometrii, użyj setSpatialEnvironmentPreference(null).

Wersja 1.0.0-alpha01

12 grudnia 2024 r.

Zostanie wycofaneandroidx.xr.scenecore:scenecore-* 1.0.0-alpha01

Funkcje pierwszej wersji Pierwsza wersja deweloperska Jetpack SceneCore, biblioteki grafu scen 3D do tworzenia i manipulowania wciągającymi scenami i środowiskami. Ta biblioteka umożliwia umieszczanie i aranżowanie modeli 3D oraz paneli treści względem siebie i w środowiskach wirtualnych lub rzeczywistych.

SpatialEnvironment: twórz w pełni immersyjne środowiska z obrazem skybox lub geometrią modelu 3D jako tłem dla sceny XR Twojego środowiska. Możesz też włączyć tryb passthrough, aby wirtualna scena mogła być zintegrowana z otoczeniem użytkownika w świecie rzeczywistym.
PanelEntity: dodawaj treści 2D do scen 3D, osadzając standardowe układy i aktywności Androida w przestrzennych panelach, które mogą unosić się w powietrzu lub być przymocowane do powierzchni w rzeczywistym świecie.
GltfModelEntity: umieszczaj, animuj i wykorzystuj w interakcjach modele 3D w scenie. SceneCore obsługuje format pliku glTF, co ułatwia integrację z istniejącymi modelami.
SpatialAudio: dodaj do sceny 3D źródła dźwięku otoczenia i punktowe, aby uzyskać w pełni przestrzenny dźwięk.
StereoSurfaceEntity: SceneCore obsługuje kierowanie treści renderowanych na Android Surface do lewego i prawego oka. Można go używać do renderowania treści stereoskopowych w formacie obok siebie lub góra-dół, takich jak zdjęcia stereo, filmy 3D lub inne dynamicznie renderowane interfejsy. Aplikacje powinny używać odtwarzacza MediaPlayer lub ExoPlayer do dekodowania wideo.
System komponentów: SceneCore oferuje solidny i elastyczny system komponentów do dodawania funkcji do treści XR, w tym możliwości przesuwania, zmiany rozmiaru i interakcji z modelami i panelami.
Zakotwiczenie: po włączeniu trybu passthrough możesz przyłączać panele i modele do rzeczywistych powierzchni, zapewniając użytkownikom płynną integrację treści wirtualnych z ich otoczeniem.
Pozycja użytkownika: dostęp do lokalizacji użytkownika w scenie wirtualnej, aby dostosować treści do jego pozycji.
SpatialCapabilities: twórz w pełni adaptacyjne aplikacje, które wykorzystują funkcje przestrzenne, takie jak pozycjonowanie 3D treści interfejsu, gdy są dostępne. Aplikacja może też monitorować zmiany w zakresie możliwości podczas działania, aby modyfikować sposób korzystania z niej w zależności od tego, jak użytkownik używa urządzenia z Androidem XR.

Znane problemy

Obecnie do korzystania z Jetpack SceneCore wymagany jest pakiet SDK w wersji co najmniej 30. Aby obejść ten problem, dodaj ten wpis do pliku manifestu <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>, aby móc tworzyć i uruchamiać aplikację z wersją minSDK 23.
Sesja może stać się nieważna w różnych sytuacjach, które automatycznie odtwarzają aktywność, np. podczas zmiany rozmiaru panelu głównego, podłączania urządzeń peryferyjnych czy przełączania się między trybem jasnym a ciemnym. Jeśli napotkasz problemy z unieważnianiem sesji, możesz zastosować obejścia, takie jak uniemożliwienie zmiany rozmiaru panelu głównego, użycie dynamicznego panelu, wyłączenie ponownego tworzenia aktywności w przypadku określonych zmian konfiguracji lub wyłączenie zmian motywu w trybie jasnym/ciemnym.
Komponenty Movable i Resizable nie są obsługiwane w przypadku komponentu GltfEntity.
Metoda Entity.getSize() nie jest obsługiwana w przypadku elementu GltfEntity.
Aplikacje Jetpack XR muszą prosić o uprawnienie android.permission.SCENE_UNDERSTANDING w pliku AndroidManifest.
Tworzenie sesji jest obsługiwane tylko na urządzeniach z Androidem XR. Obecnie, jeśli utworzysz sesję i spróbujesz użyć jej na urządzeniu XR z systemem innym niż Android, otrzymasz wyjątek RuntimeException.
Ustawienie skyboxa na wartość null za pomocą funkcji `SpatialEnvironment.setSpatialEnvironmentPreference()` nie powoduje, że skybox jest całkowicie czarny, jak podano w dokumentacji. Może to spowodować przywrócenie domyślnego skyboxa lub brak zmian w obecnym skyboxie.
Klienci SceneCore powinni dodać implementation(“com.google.guava:listenablefuture-1.0”) do konfiguracji Gradle w przypadku zależności aplikacji. W przyszłej wersji scenecore będzie zawierać tę bibliotekę jako api zależność, więc klienci nie będą musieli jej jawnie deklarować.
Biblioteka SceneCore błędnie uwzględnia com.google.guava:guava-31.1-android i com.google.protobuf:protobuf-javalite jako zależności przechodnie. Jeśli spowoduje to błędy duplikatów klas w kompilacji, te 2 zależności można bezpiecznie wykluczyć.
Jeśli Twoja 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 ProGuarda znajdziesz w tym przewodniku.