Tạo, kiểm soát và quản lý thực thể

SDK Jetpack XR cho phép bạn sử dụng Jetpack SceneCore để tạo, kiểm soát và quản lý các thực thể Entity, chẳng hạn như mô hình 3D, video lập thể và PanelEntity bằng Jetpack SceneCore.

Jetpack SceneCore sử dụng hai mẫu kiến trúc phổ biến để hỗ trợ phát triển 3D: biểu đồ cảnh và hệ thống thành phần thực thể (ECS).

Sử dụng biểu đồ cảnh để tạo và kiểm soát các thực thể

Để tạo và kiểm soát các đối tượng trong không gian 3D, bạn phải sử dụng API Phiên của Jetpack SceneCore để có quyền truy cập vào biểu đồ cảnh. Biểu đồ cảnh phù hợp với thế giới thực của người dùng và cho phép bạn sắp xếp các thực thể 3D như bảng điều khiển và mô hình 3D thành một cấu trúc phân cấp, đồng thời giữ trạng thái của các thực thể đó.

Sau khi có quyền truy cập vào biểu đồ cảnh, bạn có thể sử dụng các API trong Jetpack Compose cho XR để tạo giao diện người dùng không gian (ví dụ: SpatialPanel và Orbiter) trong biểu đồ cảnh. Đối với nội dung 3D như mô hình 3D, bạn có thể truy cập trực tiếp vào phiên. Để tìm hiểu thêm, hãy xem phần Giới thiệu về ActivitySpace trên trang này.

Hệ thống thành phần thực thể

Hệ thống thành phần thực thể tuân theo nguyên tắc kết hợp thay vì kế thừa. Bạn có thể mở rộng hành vi của các thực thể bằng cách đính kèm các thành phần xác định hành vi, cho phép bạn áp dụng cùng một hành vi cho nhiều loại thực thể. Để biết thêm thông tin, hãy xem phần Thêm hành vi phổ biến vào thực thể trên trang này.

Giới thiệu về ActivitySpace

Mỗi Session có một ActivitySpace được tạo tự động bằng Session. ActivitySpace là Entity cấp cao nhất trong biểu đồ cảnh.

ActivitySpace đại diện cho một không gian 3 chiều với hệ toạ độ thuận tay phải (trục x chỉ sang phải, trục y chỉ lên và trục z quay lại so với gốc) và với đơn vị mét cho các đơn vị khớp với thế giới thực. Nguồn gốc của ActivitySpace có phần tuỳ ý (vì người dùng có thể đặt lại vị trí của ActivitySpace trong thế giới thực), do đó, bạn nên đặt nội dung tương ứng với nhau thay vì tương ứng với nguồn gốc.

Làm việc với thực thể

Các thực thể là trung tâm của SceneCore. Hầu hết mọi thứ mà người dùng nhìn thấy và tương tác đều là các thực thể đại diện cho bảng điều khiển, mô hình 3D và nhiều nội dung khác.

Vì ActivitySpace là nút cấp cao nhất của biểu đồ cảnh, nên theo mặc định, tất cả thực thể mới sẽ được đặt trực tiếp vào ActivitySpace. Bạn có thể di chuyển lại các thực thể dọc theo biểu đồ cảnh bằng cách gọi setParent hoặc addChild.

Các thực thể có một số hành vi mặc định cho những hành vi phổ biến đối với tất cả các thực thể, chẳng hạn như thay đổi vị trí, xoay hoặc chế độ hiển thị. Các lớp con Entity cụ thể, chẳng hạn như GltfEntity, có các hành vi bổ sung hỗ trợ lớp con.

Thao tác với thực thể

Khi bạn thay đổi một thuộc tính Entity thuộc lớp Entity cơ sở, thay đổi đó sẽ được áp dụng cho tất cả các thành phần con. Ví dụ: việc điều chỉnh Pose của Entity mẹ sẽ khiến tất cả các thành phần con đều có cùng mức điều chỉnh. Việc thay đổi Entity con không ảnh hưởng đến Entity mẹ.

Pose đại diện cho vị trí và độ xoay của Thực thể trong không gian 3D. Vị trí là một Vector3 bao gồm các vị trí số x, y, z. Độ xoay được biểu thị bằng Quaternion. Vị trí của Entity luôn tương ứng với thực thể mẹ. Nói cách khác, Entity có vị trí là (0, 0, 0) sẽ được đặt tại gốc của thực thể mẹ.

//place the entity forward 2 meters
val modelPosition = 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))

Để thay đổi chế độ hiển thị của Entity, hãy sử dụng setHidden.

//hide the entity
entity.setHidden(true)

Để đổi kích thước Entity trong khi vẫn giữ nguyên hình dạng tổng thể, hãy sử dụng setScale.

//double the size of the entity
entity.setScale(2f)

Thêm hành vi phổ biến vào các thực thể

Bạn có thể sử dụng các thành phần sau để thêm hành vi phổ biến vào các thực thể:

  • MovableComponent: Cho phép người dùng di chuyển các thực thể
  • ResizableComponent: Cho phép người dùng đổi kích thước các thực thể bằng các mẫu giao diện người dùng nhất quán
  • InteractableComponent: Cho phép bạn ghi lại các sự kiện đầu vào cho các hoạt động tương tác tuỳ chỉnh

Bạn phải tạo bản sao các thành phần thông qua phương thức tạo thích hợp trong lớp Session. Ví dụ: để tạo ResizableComponent, hãy gọi session.createResizableComponent().

Để thêm hành vi thành phần cụ thể vào Entity, hãy sử dụng phương thức addComponent().

Sử dụng MovableComponent để tạo một thực thể mà người dùng có thể di chuyển

MovableComponent cho phép người dùng di chuyển Entity. Bạn cũng có thể chỉ định xem thực thể có thể được liên kết với một loại bề mặt như bề mặt ngang hoặc dọc hay các bề mặt ngữ nghĩa cụ thể như bàn, tường hoặc trần nhà hay không. Để chỉ định các tuỳ chọn liên kết, hãy chỉ định một nhóm AnchorPlacement khi tạo MovableComponent.

Dưới đây là ví dụ về một thực thể có thể di chuyển và neo vào bất kỳ bề mặt dọc nào và chỉ sàn và trần bề mặt ngang.

val anchorPlacement = AnchorPlacement.createForPlanes(
    planeTypeFilter = setOf(PlaneSemantic.FLOOR, PlaneSemantic.TABLE),
    planeSemanticFilter = setOf(PlaneType.VERTICAL))

val movableComponent = xrSession.createMovableComponent(
    systemMovable = false,
    scaleInZ = false,
    anchorPlacement = setOf(anchorPlacement)
)
entity.addComponent(movableComponent)

Sử dụng ResizableComponent để tạo một thực thể mà người dùng có thể đổi kích thước

ResizableComponent cho phép người dùng đổi kích thước Entity. ResizableComponent bao gồm các tín hiệu tương tác trực quan mời người dùng đổi kích thước Entity. Khi tạo ResizeableComponent, bạn có thể chỉ định kích thước tối thiểu hoặc tối đa (tính bằng mét). Bạn cũng có thể chỉ định tỷ lệ khung hình cố định khi đổi kích thước để chiều rộng và chiều cao đổi kích thước theo tỷ lệ với nhau.

Sau đây là ví dụ về cách sử dụng ResizableComponent với tỷ lệ khung hình cố định:

val resizableComponent = xrSession.createResizableComponent()
resizableComponent.minimumSize = Dimensions(177f, 100f, 1f )
resizableComponent.fixedAspectRatio = 16f / 9f //Specify a 16:9 aspect ratio
entity.addComponent(resizableComponent)

Sử dụng InteractableComponent để ghi lại các sự kiện đầu vào của người dùng

InteractableComponent cho phép bạn ghi lại các sự kiện đầu vào từ người dùng, chẳng hạn như khi người dùng tương tác hoặc di chuột qua Entity. Khi tạo InteractableComponent, bạn phải chỉ định một InputEventListener để nhận các sự kiện đầu vào. Khi người dùng thực hiện bất kỳ thao tác nhập nào, phương thức onInputEvent sẽ được gọi với thông tin đầu vào cụ thể được cung cấp trong tham số InputEvent.

Để biết danh sách đầy đủ tất cả hằng số InputEvent, hãy xem tài liệu tham khảo.

Đoạn mã sau đây cho thấy ví dụ về cách sử dụng InteractableComponent để tăng kích thước của một thực thể bằng tay phải và giảm kích thước bằng tay trái.

private val executor by lazy { Executors.newSingleThreadExecutor() }
val interactableComponent = xrSession.createInteractableComponent(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_TYPE_RIGHT){
            entity.setScale(1.5f)
        } else if (it.pointerType == InputEvent.POINTER_TYPE_LEFT){
            entity.setScale(0.5f)
        }
    }
}
entity.addComponent(interactableComponent)