Jetpack SceneCore

Tạo và thao tác với biểu đồ cảnh Android XR bằng nội dung 3D.
Bản cập nhật mới nhất Bản phát hành ổn định Bản phát hành dùng thử Bản phát hành beta Bản phát hành alpha
Ngày 30 tháng 7 năm 2025 - - - 1.0.0-alpha05

Khai báo phần phụ thuộc

Để thêm một phần phụ thuộc trên XR SceneCore, bạn phải thêm kho lưu trữ Google Maven vào dự án. Đọc nội dung Kho lưu trữ Maven của Google để biết thêm thông tin.

Thêm các phần phụ thuộc cho cấu phần phần mềm bạn cần trong tệp build.gradle cho ứng dụng hoặc mô-đun:

Groovy

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha05"
    // 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-alpha05"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha05")
    // 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-alpha05")
}

Để biết thêm thông tin về các phần phụ thuộc, hãy xem bài viết Thêm phần phụ thuộc vào bản dựng.

Ý kiến phản hồi

Ý kiến phản hồi của bạn có thể giúp chúng tôi cải thiện Jetpack. Hãy cho chúng tôi biết nếu bạn phát hiện lỗi mới hoặc có ý tưởng cải thiện thư viện này. Vui lòng xem các lỗi hiện có trong thư viện này trước khi báo một lỗi mới. Bạn có thể thêm lượt bình chọn cho lỗi hiện có bằng cách nhấp vào nút dấu sao.

Báo lỗi mới

Xem tài liệu về Công cụ theo dõi lỗi để biết thêm thông tin.

Phiên bản 1.0

Phiên bản 1.0.0-alpha05

Ngày 30 tháng 7 năm 2025

Phát hành androidx.xr.scenecore:scenecore-guava:1.0.0-alpha05, androidx.xr.scenecore:scenecore-testing:1.0.0-alpha05 và androidx.xr.scenecore:scenecore:1.0.0-alpha05. Phiên bản 1.0.0-alpha05 bao gồm các thay đổi sau.

Tính năng mới

  • Đã thêm API Độ phân giải cảm nhận vào Thực thể bảng điều khiển và SurfaceEntities. (I118f6)
  • PerceivedResolution Các phương thức gọi lại được thêm vào Scene.kt để theo dõi độ phân giải cảm nhận được của bảng điều khiển chính của hoạt động trong HSM. (I58084)
  • SurfaceEntity – Đã thêm tính năng hỗ trợ cho Ứng dụng để yêu cầu lấy mẫu siêu dữ liệu tại thời điểm tạo. Điều này cho phép các ứng dụng sử dụng bộ lọc lấy mẫu siêu cao để khử răng cưa. (I06913)
  • Đã thêm thuộc tính recommendedContentBoxInFullSpace vào ActivitySpace. Thao tác này trả về một hộp đề xuất để đặt nội dung vào khi ở Chế độ Toàn không gian. (I4cd6f)
  • Cung cấp hàm khởi tạo quá tải cho đối tượng sửa đổi có thể di chuyển cho phép neo. (Ic0c70)

Thay đổi về API

Chúng tôi đã thực hiện nhiều thay đổi về API đối với SceneCore trong bản phát hành này. Một số lớp đã được đổi tên và/hoặc di chuyển sang các mô-đun khác, đồng thời hầu hết các phương thức getter/setter đều đã được thay thế bằng các thuộc tính Kotlin. Mặc dù chúng tôi dự đoán sẽ có các thay đổi về API có thể gây lỗi trong tương lai cho đến khi phát hành bản Beta đầu tiên, nhưng những thay đổi này sẽ không gây gián đoạn hoặc có số lượng lớn.

  • Đổi tên và/hoặc di chuyển các lớp và giao diện sau: androidx.xr.scenecore.PixelDimensions thành androidx.xr.runtime.math.IntSize2d; androidx.xr.scenecore.Dimensions thành androidx.xr.runtime.math.FloatSize3d; androidx.xr.scenecore.ActivityPose thành ScenePose, androidx.xr.scenecore.ContentlessEntity thành GroupEntity, androidx.xr.scenecore.PlaneType thành PlaneOrientation; androidx.xr.scenecore.PlaneSemantic thành PlaneSemanticType. (Ifd405)(I3b622) (If534d)
  • Một số phương thức thiết lập cho các thuộc tính của Scene đã được đặt ở chế độ riêng tư; các phương thức này không được phép thay đổi bởi các ứng dụng SceneCore: activitySpace, activitySpaceRoot, mainPanelEntity, perceptionSpace, spatialCapabilities, spatialEnvironment và spatialUser. (I2f506)
  • Trong Thực thể: Đã thay đổi các thuộc tính sau: get/setParent(), setContentDescription; Không dùng Entity.is/setHidden() nữa, hãy dùng Entity.is/setEnabled. (Ibc4c6)
  • Đã xoá lớp androidx.xr.scenecore.BasePanelEntity, thay vào đó, hãy dùng trực tiếp PanelEntity. Thay thế phương thức getter và setter cho PanelEntity bằng các thuộc tính. Đã thay đổi thuộc tính PanelEntity.size từ Float3dSize thành Float2dSize. Xoá phương thức không được dùng nữa androidx.xr.scenecore.PanelEntity.getPixelDimensions, thay vào đó hãy sử dụng getSizeInPixels. (Icc174)
  • Thay thế androidx.xr.scenecore.OnSpaceUpdatedListener bằng Runnable. (I19308)
  • Thay thế SpatialUser.getCameraViews() bằng một thuộc tính. (Ib0cc5) Đối với ExrImage và GltfModel:, đã thay đổi các phương thức create thành các hàm tạm ngưng; sửa đổi các tham số tạo để chấp nhận Uri hoặc Path thay vì String. (Id8883) (I0d247), (I25706)
  • Đã di chuyển SpatialEnvironment.requestFullSpaceMode và SpatialEnvironment.requestHomeSpaceMode sang Cảnh, ví dụ: sử dụng session.scene.requestFullSpaceMode() thay vì session.scene.spatialEnvironment.requestFullSpaceMode(). addOnPassthroughOpacityChangedListener và addOnSpatialEnvironmentChangedListener hiện có các phương thức ghi đè chấp nhận các Executor không bắt buộc. (I12fe0) (I6b21e)
  • Đã xoá các phương thức SpatialEnvironment không dùng nữa sau đây: togglePassthrough, setPassthrough, setPassthroughOpacity, getPassthroughMode, getPassthroughOpacity, setSkybox và setGeometry. Ngoài ra, chúng tôi cũng xoá lớp SpatialEnvironment.PassthroughMode không còn dùng nữa (I927bd) (I927bd) (I927bd)
  • Thay thế các phương thức truy xuất và thiết lập SpatialEnvironment sau đây bằng các thuộc tính Kotlin: getCurrentPassthroughOpacity(), get/setPassthroughOpacityPreference(), get/setSpatialEnvironmentPreference(), isSpatialEnvironmentPreferenceActive() (I33a7b) (Ie06e2) (Ie06e2)
  • Loại SpatialEnvironmentPreference.preferredPassthroughOpacity đã thay đổi từ Float? thành Float. Trường này không còn chấp nhận giá trị rỗng nữa. Thay vào đó, SpatialEnvironment.NO_PASSTHROUGH_OPACITY_PREFERENCE được dùng để báo hiệu rằng không có lựa chọn ưu tiên nào về độ mờ. (I40107)
  • Cập nhật tham số windowBoundsPx thành pixelDimensions và loại của tham số này từ Rect thành IntSize2d trong phương thức tạo. (I1926e)
  • Hàm khởi tạo SpatialEnvironment hiện là nội bộ (I75a51)
  • Thay thế lớp SpatialPointerIconNone và SpatialPointerIconCircle bằng các đối tượng đồng hành SpatialPointerIcon.NONE và SpatialPointerIcon.CIRCLE (I416d2)
  • SpatialPointerIcon trong SpatialPointerComponent không còn có thể rỗng nữa. Sử dụng SpatialPointerIcon.DEFAULT thay vì giá trị rỗng để cho biết rằng bạn nên sử dụng biểu tượng con trỏ mặc định của hệ thống. (I416d2)
  • Thay thế androidx.xr.scenecore.AnchorEntity.getState() bằng một thuộc tính chỉ đọc. Đã đổi tên các tham số trên phương thức AnchorEntity.create() để rõ ràng hơn. Trong các phương thức của AnchorEntity để thiết lập và thêm trình nghe, trình nghe đã được chuyển sang đối số cuối cùng để bật lambda theo sau. Thay thế androidx.xr.scenecore.OnStateChangedListener cho AnchorEntity bằng Consumer<AnchorEntity.State>. (I472e0)
  • GltfModelEntity.getAnimationState() hiện là một tài sản. (I10b29)
  • Thay thế ActivitySpace.getBounds() bằng một thuộc tính. Đổi tên ActivitySpace.addBoundsChangedListener thành ActivitySpace.addOnBoundsChangedListener. Thay thế ActivitySpace.setOnSpaceUpdatedListener bằng các phương thức thêm/xoá. (I4c956)
  • Đối với AnchorPlacement: planeTypeFilter, anchorablePlaneOrientations đã được đổi tên thành planeSemanticFilter, planeSemanticFilter đã được đổi tên thành anchorablePlaneSemanticTypes. Thêm MovableComponent vào AnchorEntity hoặc ActivitySpace sẽ trả về giá trị false, MoveListener đã được đổi tên thành EntityMoveListener shouldDisposeParentAnchor, disposeParentOnReAnchor systemMovable đã được đổi tên thành disposeParentOnReAnchor systemMovable, disposeParentOnReAnchor systemMovable đã bị xoá khỏi hàm create để chuyển sang creeateCustomMovable, createSystemMovable và createAnchorable (If11c4)
  • Xoá SurfaceEntity.featherRadiusX/Y và thêm khái niệm về lớp EdgeFeatheringParams. (Ic78fc)
  • Phương thức PanelEntity.enablePanelDepthTest() được thay thế bằng thuộc tính panelClippingConfig. Đặt Scene.panelClippingConfig = PanelClippingConfig(isDepthTestEnabled = true) để bật tính năng kiểm tra độ sâu hoặc đặt thành PanelClippingConfig(isDepthTestEnabled = false) để tắt tính năng này. (I0cbe0)
  • Scene.mainPanelEntity hiện thuộc loại MainPanelEntity thay vì PanelEntity (I7125a)
  • Đổi tên phương thức setFullSpaceMode của Cảnh thành configureBundleForFullSpaceModeLaunch và phương thức setFullSpaceModeWithEnvironmentInherited thành configureBundleForFullSpaceModeLaunchWithEnvironmentInherited. (I0cbe0) (I0cbe0)
  • Đổi tên các giá trị UNKNOWN, OUTSIDE_FOV, PARTIALLY_WITHIN_FOV và WITHIN_FOV của SpatialVisibility thành SPATIAL_VISIBILITY_UNKNOWN, SPATIAL_VISIBILITY_OUTSIDE_FIELD_OF_VIEW, SPATIAL_VISIBILITY_PARTIALLY_WITHIN_FIELD_OF_VIEW và SPATIAL_VISIBILITY_WITHIN_FIELD_OF_VIEW (tương ứng) (Ie7e8c)
  • Lớp SpatialVisibility được thay thế bằng đối tượng công khai có các giá trị Int const. setSpatialVisibilityChangedListener hiện chấp nhận Consumer<Int> thay vì Consumer<SpatialVisibility> (Ie7e8c)
  • Đổi tên và di chuyển các hằng số PointerCaptureComponent sang đối tượng PointerCaptureComponent.PointerCaptureState (I9c7ac)
  • Thay thế PointerCaptureComponents' StateListener bằng Consumer<Int>. (I9c7ac)
  • Thay thế InputEventListener bằng Consumer<InputEvent> (I9c7ac)
  • setPreferredAspectRatio được di chuyển từ lớp Cảnh sang đối tượng SpatialWindow và nhận phiên làm tham số đầu tiên. (I7b717)
  • Entity.setHidden() được thay thế bằng Entity.setEnabled() và Entity.isHidden() được thay thế bằng Entity.isEnabled(). setHidden(false) bằng setEnabled(true) và isHidden() == !isEnabled(). (Icf0de)
  • Loại Entity.contentDescription đã thay đổi từ String thành CharSequence. (Ie59be)
  • Session.create và Session.configure hiện gửi SecurityException khi chưa được cấp đủ quyền thay vì trả về SessionCreatePermissionsNotGranted hoặc SessionConfigurePermissionsNotGranted. (I7c488)
  • ResizableComponent.create hiện yêu cầu Consumer<ResizeEvent> ResizeEventListener đã được thay thế bằng Consumer<ResizeEvent> ResizableComponent.size đã được đổi tên thành ResizableComponent.affordanceSize ResizableComponent.minimumSize đã được đổi tên thành ResizableComponent.minimumEntitySize ResizableComponent.maximumSize đã được đổi tên thành ResizableComponent.maximumEntitySize, ResizableComponent.autoHideContent đã được đổi tên thành ResizableComponent.shouldAutoHideContent ResizableComponent.forceShowResizeOverlay đã được đổi tên thành ResizableComponent.shouldAlwaysShowOverlay (I97a2d)
  • Giảm minSDK xuống 24 cho androidx.xr.scenecore và androidx.xr.compose. Các gói XR vẫn yêu cầu API 34 trong thời gian chạy. (I17224)
  • Xoá hạn chế RequiresApi(34) đối với tất cả các gói Jetpack XR. Hạn chế này là không cần thiết vì Jetpack XR hiện chỉ có trên các thiết bị có API cấp 34 trở lên. (Iae0f8)
  • Cấu phần phần mềm SceneCore chính (xr:scenecore:scenecore) sẽ chỉ chứa các API không đồng bộ theo kiểu Kotlin. Nhà phát triển Java có thể dựa vào thư viện xr:scenecore:scenecore-guava để truy cập vào các API tương thích. (If221b)
  • Các dự án được phát hành bằng Kotlin 2.0 yêu cầu sử dụng KGP 2.0.0 trở lên (Idb6b5)
  • Thư viện này hiện sử dụng chú giải về giá trị rỗng JSpecify, là loại sử dụng. Nhà phát triển Kotlin nên sử dụng đối số trình biên dịch sau đây để thực thi việc sử dụng chính xác: -Xjspecify-annotations=strict (đây là đối số mặc định bắt đầu từ phiên bản 2.1.0 của trình biên dịch Kotlin) (Ia8420)
  • Tất cả các phương thức không đồng bộ trả về ListenableFuture đều đã được thay thế bằng các hàm tạm ngưng Kotlin. Giờ đây, những nhà phát triển Java muốn sử dụng các phương thức không đồng bộ dựa trên ListenableFuture thay vì các hàm tạm ngưng trong Kotlin phải sử dụng các hàm mở rộng trong :xr:scenecore-scenecore-guava. Ví dụ: GuavaExrImage chứa các hàm không đồng bộ ExrImage tương đương với Guava, GuavaScenePose chứa các hàm không đồng bộ ScenePose tương đương với Guava, GuavaGltfModel chứa các hàm không đồng bộ Guava-equivalent GltfModel, v.v. (If7283) (I0af60) (If7283) (Ia8515) (I4efdf) (I54bbf) (I3467a) (I82a33)

Sửa lỗi

  • Cập nhật quy tắc Jetpack XR Scenecore ProGuard để ngăn AbstractMethodError cho các ứng dụng tối giản. (I91a01)
  • Các bản sửa lỗi bổ sung để hỗ trợ việc giảm thiểu Proguard cho Jetpack XR SceneCore (I4f47e)
  • Khắc phục một lỗi trong đó InteractableComponent có thể gây ra sự cố nếu hitPosition trên HitInfo của InputEvent có thể gặp sự cố nếu hitPosition do hệ thống trả về là giá trị rỗng (I7a695)
  • Các giá trị *Mode trong cấu hình đã được đổi tên để phản ánh hành vi của các giá trị đó. (I6d247)
  • Khắc phục các vấn đề về FOV và HitTest trong SceneCore TestApp. (I2c51e)
  • Đã khắc phục lỗi trong SpatialCapabilities.hasCapability(), trong đó hàm này sẽ trả về giá trị true nếu bất kỳ chức năng nào được truyền vào bằng một phép OR theo bit là true thay vì chỉ trả về giá trị true nếu tất cả các chức năng đều là true. (I2cd40)
  • SurfaceEntity.StereoMode.TOP_BOTTOM được cập nhật để có bản đồ trên cùng cho mắt trái và bản đồ dưới cùng cho mắt phải. (I4ae68)

Phiên bản 1.0.0-alpha04

Ngày 7 tháng 5 năm 2025

Phát hành androidx.xr.scenecore:scenecore:1.0.0-alpha04 và androidx.xr.scenecore:scenecore-testing:1.0.0-alpha04. Phiên bản 1.0.0-alpha04 bao gồm các thay đổi sau.

Tính năng mới

  • Giờ đây, tính năng xử lý thao tác quay lại sẽ hoạt động trên các thực thể bảng điều khiển mà không có hoạt động được nhúng. Để tính năng xử lý thao tác quay lại hoạt động, bạn cần chỉ định android:enableOnBackInvokedCallback= "true" trong tệp kê khai Android.
  • StereoSurfaceEntity hiện hỗ trợ chế độ phát MV-HEVC thông qua 2 giá trị StereoMode mới: MULTIVIEW_LEFT_PRIMARY và MULTIVIEW_RIGHT_PRIMARY.
  • PanelEntity.setSize và PanelEntity.getSize hiện trả về kích thước trong không gian mẹ.
  • Entity.setPose, Entity.getPose, Entity.setScale, Entity.getScale, Entity.setAlpha và Entity.getAlpha hiện lấy một tham số mới relativeTo, cho phép nhận/đặt các giá trị tương ứng với các khoảng trắng khác nhau. Các giá trị được hỗ trợ là Parent, Activity và Real World spaces, đồng thời giá trị mặc định cho tham số này là Parent.
  • Các phương thức mở rộng Spatial Visibility Callback (Lệnh gọi lại khả năng hiển thị không gian) được thêm vào SessionExt.kt để theo dõi thời điểm nội dung cảnh di chuyển vào trong hoặc ra ngoài trường nhìn của người dùng.
  • setPointSourceParams đã được thêm vào SpatialAudioTrack, cho phép cập nhật các tham số sau khi bản nhạc được tạo.
  • Thêm một lớp mới (Scene) có các tham chiếu đến API Scenecore. Cảnh sẽ có thể truy cập được dưới dạng một thuộc tính mở rộng của Phiên. Các hàm bên trong SessionExt đã được chuyển sang Scene nên bạn sẽ cần điều chỉnh các lệnh nhập; ví dụ: SessionExt.getScene(session).addSpatialCapababilitiesChangedListener đấu với SessionExt.addSpatialCapabilitiesChangedListener.
  • ActivityPose.hitTestAsync đã được thêm, cho phép hitTest chống lại nội dung ảo.
  • Thêm loại Thành phần mới SpatialPointerComponent, cho phép các ứng dụng chỉ định biểu tượng được kết xuất cho con trỏ hoặc tắt biểu tượng. Hiện tại, bạn chỉ có thể đính kèm Thành phần này vào các thực thể PanelEntity.
  • Ra mắt nhà máy PanelEntity mới, có kích thước bảng điều khiển bằng mét hoặc pixel. Đã xoá nhà máy PanelEntity cũ lấy 2 tham số loại Dimension cho bảng điều khiển.

Thay đổi về API

  • Xoá hạn chế RequiresApi(34) đối với tất cả các gói Jetpack XR. Hạn chế này là không cần thiết vì Jetpack XR hiện chỉ có trên các thiết bị có API cấp 34 trở lên. (Iae0f8)
  • Các dự án được phát hành bằng Kotlin 2.0 yêu cầu sử dụng KGP 2.0.0 trở lên (Idb6b5)
  • Xoá lớp PermissionHelper.
  • Ngừng sử dụng PanelEntity.getPixelDensity.
  • PanelEntity.setPixelDimensions và PanelEntity.getPixelDimension bị xoá, thay thế bằng setSizeInPixels và getSizeInPixels.
  • Xoá Entity.getActivitySpaceAlpha. Có thể thay thế bằng Entity.getAlpha(Space.Activity).
  • Xoá Entity.getWorldSpaceScale. Có thể thay thế bằng Entity.getScale(Space.REAL\_WORLD).
  • Lớp Phiên trong SceneCore đã bị xoá để thay thế bằng Phiên trong XR Runtime.
  • StereoSurfaceEntity đổi tên thành SurfaceEntity
  • Entity.setSize và Entity.getSize bị xoá và các phương thức tương tự đã được thêm vào PanelEntity.
  • PointSourceAttributes đổi tên thành PointSourceParams
  • SpatializerConstants.SOURCE\_TYPE\_BYPASS đổi tên thành SpatializerConstants.SOURCE\_TYPE\_DEFAULT
  • Đã sửa đổi thực thể PointSourceParams từ quyền truy cập công khai thành quyền truy cập nội bộ.
  • AnchorEntity.create hiện yêu cầu bạn phải định cấu hình PlaneTrackingMode trong Session.configure().
  • Các API SpatialUser hiện yêu cầu bạn định cấu hình HeadTrackingMode trong Session.configure().
  • Khi ResizableComponent không được đính kèm, nó sẽ cung cấp nhật ký cấp INFO thay vì nhật ký cấp ERROR.
  • Lớp Fov hiện là một lớp Kotlin thông thường.
  • Chia Entity.kt để đặt từng loại thực thể cụ thể vào tệp riêng.
  • Khi tạo một PanelEntity mới, hầu hết các Chế độ xem sẽ được liên kết lại với một FrameLayout. Điều này giúp bạn dễ dàng sử dụng LayoutInspector với Bảng điều khiển không gian.
  • Giờ đây, phiên bản XrExtensions đang dùng đã được đăng ký với nền tảng theo cách hiệu quả nhất có thể để hỗ trợ gỡ lỗi ứng dụng.

Sửa lỗi

  • Chúng tôi đã thêm một bản sửa lỗi để ngăn sự cố có thể xảy ra khi PanelEntity có MovableComponent và AnchorPlacement được di chuyển
  • Khắc phục vấn đề ResizableComponent cung cấp kích thước cũ trong lệnh gọi lại onResizeStart.
  • Khắc phục sự cố khi dispose() của JxrPlatformAdapterAxr được gọi nhiều lần.

Phiên bản 1.0.0-alpha03

Ngày 26 tháng 2 năm 2025

Phát hành androidx.xr.scenecore:scenecore:1.0.0-alpha03 và androidx.xr.scenecore:scenecore-testing:1.0.0-alpha03. Phiên bản 1.0.0-alpha03 bao gồm các thay đổi sau.

Tính năng mới

  • Tính năng rút gọn Proguard hiện được hỗ trợ cho mã Jetpack XR

Sửa lỗi

  • Các bản sửa lỗi bổ sung để hỗ trợ việc giảm thiểu Proguard cho Jetpack XR SceneCore (I4f47e)
  • Cập nhật quy tắc Jetpack XR Scenecore ProGuard để ngăn AbstractMethodError cho các ứng dụng tối giản. (I91a01)

Phiên bản 1.0.0-alpha02

Ngày 12 tháng 2 năm 2025

Phát hành androidx.xr.scenecore:scenecore:1.0.0-alpha02 và androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02. Phiên bản 1.0.0-alpha02 bao gồm các thay đổi sau.

Thay đổi có thể gây lỗi sắp tới ảnh hưởng đến các ứng dụng được tạo trước phiên bản 1.0.0-alpha02

  • Các phương thức của nhà máy đã được chuyển từ lớp Session sang một phương thức đồng hành trên từng loại tương ứng:
    • Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) đã bị xoá và thay thế bằng ActivityPanelEntity.create(Session, Dimensions, String, Pose)
    • Session.createAnchorEntity(Anchor) đã bị xoá và thay thế bằng AnchorEntity.create(Session, Anchor)
    • Session.createAnchorEntity(Dimensions, Int, Int, Duration) đã bị xoá và thay thế bằng AnchorEntity.create(Session, Dimensions, Int, Int, Duration)
    • Session.createEntity(String, Pose) đã bị xoá và thay thế bằng ContentlessEntity.create(Session, String, Pose)
    • Session.createExrImageResource(String) đã bị xoá và thay thế bằng ExrImage.create(Session, String)
    • Session.createGltfEntity(GltfModel, Pose) đã bị xoá và thay thế bằng GltfModelEntity.create(Session, GltfModel, Pose)
    • Session.createGltfModelResource(String) đã bị xoá và thay thế bằng GltfModel.create(Session, String)
    • Session.createInteractableComponent(Executor, InputEventListener) đã bị xoá và thay thế bằng InteractableComponent.create(Session, Executor, InputEventListener)
    • Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) đã bị xoá và thay thế bằng MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
    • Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) đã bị xoá và thay thế bằng PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose)
    • Session.createResizableComponent(Dimensions, Dimensions) đã bị xoá và thay thế bằng ResizableComponent.create(Session, Dimensions, Dimensions)
    • Session.createStereoSurfaceEntity(Int, Dimensions, Pose) đã bị xoá và thay thế bằng StereoSurface.create(Session, Int, Dimensions, Pose)
  • Các phương thức không dùng nữa sau đây đã bị xoá:
    • Session.canEmbedActivityPanel(Activity) đã bị xóa. Thay vào đó, hãy sử dụng getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY).
    • Session.hasSpatialCapability(Int) đã bị xóa. Hàm này đã được thay thế để sử dụng getSpatialCapabilities().hasCapability() như một cách phân vùng rõ ràng hơn để kiểm tra sự hiện diện của các chức năng không gian vì getSpatialCapabilities() trả về một đối tượng SpatialCapabilities.
    • Session.requestFullSpaceMode() đã bị xoá và thay thế bằng SpatialEnvironment.requestFullSpaceMode()
    • Session.requestHomeSpaceMode() đã bị xoá và thay thế bằng SpatialEnvironment.requestHomeSpaceMode()
  • Session.setFullSpaceMode(Bundle) và Session.setFullSpaceModeWithEnvironmentInherited(Bundle) đã được di chuyển sang các hàm mở rộng. Các tệp của nhà phát triển sẽ cần thêm nội dung nhập mới để truy cập:
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float) đã được chuyển sang một hàm mở rộng. Các tệp nhà phát triển sẽ cần thêm nội dung nhập mới để truy cập:
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Session.getEntitiesOfType(Class<out T>) và Session.getEntityForRtEntity(RtEntity) đã được di chuyển sang các hàm mở rộng. Các tệp của nhà phát triển sẽ cần thêm nội dung nhập mới để truy cập:
    • import androidx.xr.scenecore.getEntitiesOfType
    • import androidx.xr.scenecore.getEntityForRtEntity
  • Đã xóa Session.unpersistAnchor(Anchor)
  • Đã xóa Session.createPersistedAnchorEntity(UUID)

Vấn đề đã biết

  • PanelEntity.setCornerRadius() và ActivityPanelEntity.setCornerRadius() có thể không có hiệu lực cho đến khi bảng điều khiển được di chuyển vào lần tiếp theo. Bạn có thể giảm thiểu vấn đề này bằng cách di chuyển bảng điều khiển đến vị trí hiện tại
  • Khi BoundsChanged được gọi trên ActivitySpace, một số ActivityPose có thể chưa được cập nhật đúng cách. Thông tin này sẽ được cập nhật trong cuộc gọi OnSpaceUpdated tiếp theo vào ngày ActivitySpace

Thay đổi có thể gây lỗi và thay đổi về hành vi

  • PanelEntity và ActivityPanelEntity sẽ có bán kính góc mặc định là 32 dp trở xuống nếu bảng điều khiển có chiều rộng hoặc chiều cao nhỏ hơn 32 dp

API và chức năng mới

  • Giới thiệu StereoSurface.CanvasShape, cho phép tạo các canvas Spherical và Hemispherical để kết xuất nội dung nghe nhìn sống động.
  • StereoSurfaceEntity.create() hiện chấp nhận tham số CanvasShape. (Tham số này hiện bị bỏ qua, nhưng sẽ được dùng trong một bản phát hành sau này)
  • StereoSurfaceEntity.create() không còn lấy tham số Dimensions nữa. Các ứng dụng phải kiểm soát kích thước của canvas bằng cách đặt CanvasShape
  • StereoSurfaceEntity có một thành phần CanvasShape mà bạn có thể đặt một cách linh động.
  • StereoSurfaceEntity.dimensions hiện là một thuộc tính chỉ có thể đọc; các ứng dụng nên đặt CanvasShape để thay đổi kích thước.
  • StereoSurfaceEntity hiện cho phép đặt lại StereoMode sau khi khởi tạo.

Các thay đổi khác

  • Giảm minSDK thời gian biên dịch xuống còn 24. Tất cả các API Jetpack XR đều tiếp tục yêu cầu API 34 trong thời gian chạy.
  • Nhà máy phiên của SceneCore (Session.create) không còn khởi chạy ý định để có được quyền SCENE_UNDERSTANDING nữa. Thay vào đó, ứng dụng khách phải yêu cầu người dùng cấp quyền một cách rõ ràng trước khi cố gắng tạo các neo. Việc tạo điểm neo sẽ không thành công nếu người dùng không cấp quyền.

Sửa lỗi

  • getActivitySpacePose() đã được sửa để tính đến tỷ lệ ActivitySpace bằng cách trả về các giá trị dịch theo mét được chia tỷ lệ thay vì luôn trả về các mét không được chia tỷ lệ. transformPoseTo hiện cũng sử dụng các đơn vị phù hợp để tính toán các thay đổi về toạ độ khi ActivitySpace có trong nguồn hoặc đích đến.
  • Giờ đây, skybox sẽ được đặt thành skybox toàn màu đen bất cứ khi nào một lựa chọn ưu tiên skybox rỗng được truyền bằng setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). Để quay lại skybox và thành phần hình học mặc định của hệ thống, hãy sử dụng setSpatialEnvironmentPreference(null).

Phiên bản 1.0.0-alpha01

Ngày 12 tháng 12 năm 2024

Phát hành androidx.xr.scenecore:scenecore-* 1.0.0-alpha01.

Các tính năng của bản phát hành ban đầu Bản phát hành ban đầu cho nhà phát triển của Jetpack SceneCore, một thư viện biểu đồ cảnh 3D để tạo và thao tác với các cảnh và môi trường sống động. Thư viện này cho phép bạn đặt và sắp xếp các mô hình 3D cũng như bảng nội dung tương ứng với nhau và với môi trường ảo hoặc thực tế.

  • SpatialEnvironment: Tạo trải nghiệm hoàn toàn sống động bằng hình ảnh skybox và/hoặc hình học mô hình 3D làm bối cảnh cho cảnh XR của môi trường. Hoặc bật chế độ nhìn xuyên qua để cảnh ảo của bạn có thể tích hợp với môi trường thực tế của người dùng.
  • PanelEntity: Thêm nội dung 2D vào cảnh 3D bằng cách nhúng các bố cục và Hoạt động Android tiêu chuẩn vào các bảng điều khiển được không gian hoá có thể nổi hoặc được cố định vào các bề mặt trong thế giới thực.
  • GltfModelEntity: Đặt, tạo ảnh động và tương tác với các mô hình 3D trong cảnh. SceneCore hỗ trợ định dạng tệp glTF để dễ dàng tích hợp với các mô hình hiện có.
  • SpatialAudio: Thêm các nguồn âm thanh xung quanh và âm thanh tại một điểm vào cảnh 3D để có âm thanh không gian sống động và chân thực.
  • StereoSurfaceEntity: SceneCore hỗ trợ định tuyến nội dung cho mắt trái/phải được kết xuất trên một Surface của Android. Bạn có thể dùng thành phần này để kết xuất nội dung lập thể ở định dạng song song hoặc trên dưới, chẳng hạn như ảnh lập thể, video 3D hoặc các giao diện người dùng khác được kết xuất động. Các ứng dụng nên sử dụng MediaPlayer hoặc ExoPlayer để giải mã video.
  • Hệ thống thành phần: SceneCore cung cấp một hệ thống thành phần mạnh mẽ và linh hoạt để thêm các chức năng vào nội dung XR của bạn, bao gồm cả các chức năng cho phép người dùng di chuyển, thay đổi kích thước và tương tác với các mô hình và bảng điều khiển.
  • Điểm neo: Khi bật chế độ nhìn xuyên qua, bạn có thể gắn các bảng và mô hình vào các bề mặt thực tế, giúp người dùng tích hợp liền mạch nội dung ảo vào môi trường thực tế của họ.
  • Tư thế người dùng: Truy cập vào vị trí của người dùng trong cảnh ảo để định hướng nội dung xung quanh vị trí của người dùng.
  • SpatialCapabilities: Tạo các ứng dụng hoàn toàn thích ứng, tận dụng các chức năng không gian khi có sẵn, chẳng hạn như định vị nội dung giao diện người dùng ở chế độ 3D. Không chỉ vậy, ứng dụng của bạn còn có thể theo dõi các thay đổi về chức năng trong khi ứng dụng đang thực thi, để sửa đổi trải nghiệm dựa trên cách người dùng đang sử dụng thiết bị Android XR của họ.

Lỗi đã biết

  • Hiện tại, bạn cần có minSDK là 30 để sử dụng Jetpack SceneCore. Để khắc phục, hãy thêm mục nhập tệp kê khai <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> sau đây để có thể tạo và chạy với minSDK là 23.
  • Phiên có thể trở nên không hợp lệ trong nhiều trường hợp tự động tạo lại Hoạt động, bao gồm cả việc đổi kích thước bảng điều khiển chính, kết nối thiết bị ngoại vi và chuyển đổi giữa chế độ sáng và tối. Nếu bạn gặp phải vấn đề về việc vô hiệu hoá phiên, thì các giải pháp tạm thời bao gồm việc làm cho bảng điều khiển chính không thể thay đổi kích thước, sử dụng một thực thể bảng điều khiển động, tắt tính năng tạo lại hoạt động cho các thay đổi cụ thể về cấu hình hoặc tắt các thay đổi về giao diện ở chế độ sáng/tối.
  • GltfEntity không hỗ trợ các thành phần có thể di chuyển và đổi kích thước.
  • Entity.getSize() không được hỗ trợ trên GltfEntity.
  • Các ứng dụng Jetpack XR phải yêu cầu quyền android.permission.SCENE_UNDERSTANDING trong AndroidManifest.
  • Chỉ thiết bị Android XR mới hỗ trợ việc tạo phiên. Tại thời điểm này, nếu tạo một Phiên và cố gắng sử dụng Phiên đó trên một thiết bị không phải Android XR, bạn sẽ gặp phải một RuntimeException.
  • Việc đặt skybox thành giá trị rỗng thông qua `SpatialEnvironment.setSpatialEnvironmentPreference()` không dẫn đến skybox màu đen như được ghi lại. Điều này có thể dẫn đến việc sử dụng skybox mặc định của hệ thống hoặc không có thay đổi nào đối với skybox hiện tại.
  • Các ứng dụng SceneCore nên thêm implementation(“com.google.guava:listenablefuture-1.0”) vào cấu hình Gradle cho các phần phụ thuộc của ứng dụng. Trong một bản phát hành trong tương lai, scenecore sẽ bao gồm thư viện này dưới dạng một phần phụ thuộc api để các ứng dụng không cần khai báo rõ ràng.
  • SceneCore nhầm lẫn khi đưa com.google.guava:guava-31.1-android và com.google.protobuf:protobuf-javalite vào làm các phần phụ thuộc bắc cầu. Nếu điều này dẫn đến lỗi trùng lặp lớp trong bản dựng, bạn có thể loại trừ hai phần phụ thuộc này một cách an toàn.
  • Nếu ứng dụng của bạn sử dụng SceneCore và bật ProGuard, thì ứng dụng sẽ gặp sự cố khi bạn tạo một Phiên. Để khắc phục, hãy tắt ProGuard. Hãy xem hướng dẫn này để biết thêm thông tin về cách bật ProGuard.