Tworzenie, kontrolowanie i zarządzanie elementami

Odpowiednie urządzenia XR
Te wskazówki pomogą Ci tworzyć treści na te urządzenia XR.
Więcej informacji o typach urządzeń XR →
Gogle XR
Przewodowe okulary XR
Więcej informacji o typach urządzeń XR →

Pakiet Jetpack XR SDK umożliwia tworzenie, kontrolowanie i zarządzanie instancjami Entity, takimi jak modele 3D, filmy stereoskopowe i PanelEntity, za pomocą Jetpack SceneCore.

Jetpack SceneCore wykorzystuje 2 popularne wzorce architektoniczne, aby obsługiwać tworzenie treści 3D: graf sceny i system komponentów jednostek (ECS).

Tworzenie i kontrolowanie obiektów za pomocą wykresu sceny

Aby tworzyć obiekty w przestrzeni 3D i nimi sterować, możesz użyć interfejsu API Session w Jetpack SceneCore, aby uzyskać dostęp do wykresu sceny. Graf sceny jest zgodny ze światem rzeczywistym użytkownika i umożliwia organizowanie obiektów 3D, takich jak panele i modele 3D, w strukturę hierarchiczną oraz przechowywanie stanu tych obiektów.

Po uzyskaniu dostępu do grafu sceny możesz używać interfejsów API w Jetpack Compose na potrzeby XR do tworzenia przestrzennego interfejsu (np. instancji SpatialPanel i Orbiter) w grafie sceny. W przypadku treści 3D, takich jak modele 3D, możesz uzyskać dostęp do sesji bezpośrednio. Więcej informacji znajdziesz w sekcji Informacje o przestrzeni aktywności na tej stronie.

System komponentów encji

System komponentów jednostek jest zgodny z zasadą kompozycji zamiast dziedziczenia. Możesz rozszerzyć działanie elementów, dołączając komponenty definiujące działanie, co pozwala zastosować to samo działanie do różnych typów elementów. Więcej informacji znajdziesz w sekcji Dodawanie do encji wspólnych zachowań na tej stronie.

Informacje o ActivitySpace

Każdy Session ma ActivitySpace, który jest tworzony automatycznie za pomocą Session. ActivitySpace to element Entity najwyższego poziomu w grafie sceny.

Przestrzeń aktywności to przestrzeń trójwymiarowa z prawoskrętnym układem współrzędnych (oś X jest skierowana w prawo, oś Y w górę, a oś Z do tyłu względem początku układu współrzędnych) i jednostkami w metrach, które odpowiadają rzeczywistości. Pochodzenie ActivitySpace jest nieco arbitralne (użytkownicy mogą zresetować pozycję ActivitySpace w rzeczywistym świecie), dlatego zalecamy pozycjonowanie treści względem siebie, a nie względem punktu początkowego.

Praca z encjami

Elementy są kluczowe w SceneCore. Większość elementów, które użytkownik widzi i z którymi wchodzi w interakcję, to obiekty reprezentujące panele, modele 3D i inne elementy.

Ponieważ ActivitySpace jest węzłem najwyższego poziomu w grafie sceny, domyślnie wszystkie nowe elementy są umieszczane bezpośrednio w ActivitySpace. Możesz przenieść elementy w grafie sceny, ustawiając ich parent lub używając addChild().

Jednostki mają pewne domyślne zachowania w przypadku elementów, które są uniwersalne dla wszystkich jednostek, takich jak zmiana pozycji, rotacji lub widoczności. Określone Entitypodklasy, takie jak GltfModelEntity, mają dodatkowe zachowania, które obsługują podklasę.

Manipulowanie encjami

Jeśli zmienisz Entity właściwość należącą do klasy bazowej Entity, zmiana zostanie zastosowana do wszystkich jej elementów podrzędnych. Na przykład zmiana Pose elementu nadrzędnego Entity powoduje, że wszystkie elementy podrzędne mają taką samą zmianę. Zmiana w podrzędnym Entity nie ma wpływu na jego element nadrzędny.

Symbol Pose reprezentuje lokalizację i obrót jednostki w przestrzeni 3D. Lokalizacja to Vector3 składający się z wartości liczbowych x, y i z. Obrót jest oznaczony symbolem Quaternion. Położenie Entity jest zawsze względne w stosunku do podmiotu nadrzędnego. Innymi słowy, Entity, którego pozycja to (0, 0, 0), zostanie umieszczony w punkcie początkowym jednostki nadrzędnej.

// Place the entity forward 2 meters
val newPosition = Vector3(0f, 0f, -2f)
// Rotate the entity by 180 degrees on the up axis (upside-down)
val newOrientation = Quaternion.fromEulerAngles(0f, 0f, 180f)
// Update the position and rotation on the entity
entity.setPose(Pose(newPosition, newOrientation))
Entities.kt

Aby wyłączyć Entity, użyj setEnabled(). Spowoduje to, że stanie się on niewidoczny i wszelkie przetwarzanie danych w nim zawartych zostanie wstrzymane.

// Disable the entity.
entity.setEnabled(false)
Entities.kt

Aby zmienić rozmiar Entity, zachowując jego ogólny kształt, użyj setScale().

// Double the size of the entity
entity.setScale(2f)
Entities.kt

Dodawanie do encji typowych zachowań

Aby dodać do obiektów typowe zachowania, możesz użyć tych komponentów:

  • MovableComponent: umożliwia użytkownikowi przenoszenie elementów.
  • ResizableComponent: umożliwia użytkownikowi zmianę rozmiaru elementów za pomocą spójnych wzorców interfejsu.
  • InteractableComponent: umożliwia rejestrowanie zdarzeń wejściowych w przypadku niestandardowych interakcji.

Tworzenie instancji komponentów musi odbywać się za pomocą odpowiedniej metody tworzenia w klasie Session. Na przykład aby utworzyć ResizableComponent, wywołaj ResizableComponent.create().

Aby dodać do elementu Entity konkretne działanie komponentu, użyj metody addComponent().

Używanie funkcji MovableComponent, aby umożliwić użytkownikowi przesuwanie obiektu

MovableComponent umożliwia użytkownikowi przesuwanie Entity.

Zdarzenia ruchu są wysyłane do komponentu, gdy użytkownik wchodzi w interakcję z dekoracjami. Domyślne zachowanie systemu, utworzone za pomocą MovableComponent.createSystemMovable(), przesuwa Entity, gdy dekoracje są przeciągane:

val movableComponent = MovableComponent.createSystemMovable(session)
entity.addComponent(movableComponent)
MovableComponent.kt

Opcjonalny parametr scaleInZ (domyślnie ustawiony na true) powoduje, że element Entity automatycznie dostosowuje swój rozmiar, gdy jest oddalany od użytkownika, podobnie jak panele są skalowane przez system w przestrzeni domowej. Ze względu na „kaskadowy” charakter systemu komponentów encji skala elementu nadrzędnego będzie miała wpływ na wszystkie jego elementy podrzędne.

Możesz też określić, czy element może być przytwierdzony do typu powierzchni, np. poziomej lub pionowej, albo do konkretnych powierzchni semantycznych, takich jak stół, ściana lub sufit. Aby określić opcje kotwicy, podczas tworzenia MovableComponent podaj zestaw AnchorPlacement. W tym przykładzie element, który można przesuwać i zakotwiczać na dowolnej podłodze lub poziomej powierzchni stołu:

val anchorPlacement = AnchorPlacement.createForPlanes(
    anchorablePlaneOrientations = setOf(PlaneOrientation.VERTICAL),
    anchorablePlaneSemanticTypes = setOf(PlaneSemanticType.FLOOR, PlaneSemanticType.TABLE)
)

val movableComponent = MovableComponent.createAnchorable(
    session = session,
    anchorPlacement = setOf(anchorPlacement)
)
entity.addComponent(movableComponent)
MovableComponent.kt

Użyj kodu ResizableComponent, aby umożliwić zmianę rozmiaru jednostki

ResizableComponent umożliwia użytkownikom zmianę rozmiaru Entity. ResizableComponent zawiera wizualne wskazówki dotyczące interakcji, które zachęcają użytkownika do zmiany rozmiaru Entity. Podczas tworzenia ResizableComponent możesz określić minimalny lub maksymalny rozmiar (w metrach). Podczas zmiany rozmiaru możesz też określić stały współczynnik proporcji, aby szerokość i wysokość zmieniały się proporcjonalnie względem siebie.

Podczas tworzenia ResizableComponent określ resizeEventListener, który obsługuje zdarzenia aktualizacji. Możesz reagować na różne ResizeState zdarzenia, takie jak RESIZE_STATE_ONGOING czy RESIZE_STATE_END.

Oto przykład użycia właściwości ResizableComponent ze stałymi proporcjami na urządzeniu SurfaceEntity:

val resizableComponent = ResizableComponent.create(session) { event ->
    if (event.resizeState == ResizeEvent.ResizeState.END) {
        // update the Entity to reflect the new size
        surfaceEntity.shape = SurfaceEntity.Shape.Quad(FloatSize2d(event.newSize.width, event.newSize.height))
    }
}
resizableComponent.minimumEntitySize = FloatSize3d(177f, 100f, 1f)
resizableComponent.isFixedAspectRatioEnabled = true // Maintain a fixed aspect ratio when resizing

surfaceEntity.addComponent(resizableComponent)
ResizableComponent.kt

Używaj InteractableComponent do rejestrowania zdarzeń związanych z działaniami użytkownika

InteractableComponent umożliwia rejestrowanie zdarzeń wejściowych od użytkownika, takich jak interakcja z Entity lub najechanie na nią kursorem. Podczas tworzenia elementu InteractableComponent określ detektor, który będzie odbierać zdarzenia wejściowe. Gdy użytkownik wykona dowolne działanie związane z wprowadzaniem danych, wywoływana jest funkcja nasłuchująca z informacjami o wprowadzonych danych podanymi w parametrze InputEvent.

Pełną listę wszystkich stałych InputEvent znajdziesz w dokumentacji.

Poniższy fragment kodu pokazuje przykład użycia InteractableComponent do powiększania obiektu prawą ręką i zmniejszania go lewą ręką.

val executor = Executors.newSingleThreadExecutor()
val interactableComponent = InteractableComponent.create(session, executor) {
    // when the user disengages with the entity with their hands
    if (it.source == InputEvent.Source.HANDS && it.action == InputEvent.Action.UP) {
        // increase size with right hand and decrease with left
        if (it.pointerType == InputEvent.Pointer.RIGHT) {
            entity.setScale(1.5f)
        } else if (it.pointerType == InputEvent.Pointer.LEFT) {
            entity.setScale(0.5f)
        }
    }
}
entity.addComponent(interactableComponent)
InteractableComponent.kt