{ } { }

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 7 tháng 5 năm 2025 - - - 1.0.0-alpha04

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

Để 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-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 không có hoạt động được nhúng. Để tính năng xử lý lui hoạt động, bạn cần chỉ định android:enableOnBackInvokedCallback= "true" trong tệp kê khai Android.
  • StereoSurfaceEntity hiện hỗ trợ phát MV-HEVC thông qua hai 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 sử dụng một tham số mới relativeTo, cho phép lấy/đặt giá trị tương ứng với các không gian khác nhau. Các giá trị được hỗ trợ là không gian Mẹ, Hoạt động và Thế giới thực, còn giá trị mặc định cho tham số này là Mẹ.
  • Các phương thức mở rộng 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 bên trong hoặc bên 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 tạo kênh.
  • Thêm một lớp mới, Scene (Cảnh), với các tệp tham chiếu đến API Scenecore. Bạn có thể truy cập vào Cảnh dưới dạng thuộc tính mở rộng của Phiên. Các hàm bên trong SessionExt đã được chuyển sang Scene, vì vậy, bạn cần điều chỉnh các lệnh nhập; ví dụ: SessionExt.getScene(session).addSpatialCapababilitiesChangedListener so với SessionExt.addSpatialCapabilitiesChangedListener.
  • Thêm ActivityPose.hitTestAsync, 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 ứ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. Thành phần này hiện chỉ có thể được đính kèm vào các thực thể PanelEntity.
  • Giới thiệu nhà máy PanelEntity mới, lấy kích thước bảng điều khiển theo mét hoặc pixel. Xoá nhà máy PanelEntity cũ lấy hai tham số loại Phương diện cho bảng điều khiển.

Thay đổi về API

  • Xoá hạn chế RequiresApi(34) trên tất cả gói Jetpack XR. Quy định hạn chế này là thừa 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 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.
  • Xoá PanelEntity.setPixelDimensions và PanelEntity.getPixelDimension, 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 vào đó là Phiên trong XR Runtime.
  • StereoSurfaceEntity đổi tên thành SurfaceEntity
  • Xoá Entity.setSize và Entity.getSize, đồng thời thêm các phương thức tương tự vào PanelEntity.
  • PointSourceAttributes đổi tên thành PointSourceParams
  • SpatializerConstants.SOURCE\_TYPE\_BYPASS đổi tên thành SpatializerConstants.SOURCE\_TYPE\_DEFAULT
  • Thực thể PointSourceParams đã được sửa đổi 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 PlaneTrackingMode được định cấu hình trong Session.configure().
  • Các API SpatialUser hiện yêu cầu phải định cấu hình HeadTrackingMode trong Session.configure().
  • Khi không đính kèm ResizableComponent, ứng dụng 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.
  • Phân tách 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 Khung hiển thị sẽ được liên kết lại với một FrameLayout. Điều này tạo điều kiện cho việc sử dụng LayoutInspector với Bảng điều khiển không gian.
  • Phiên bản XrExtensions hiện đang được sử dụng hiện đã được đăng ký với nền tảng theo cách tốt nhất có thể để giúp gỡ lỗi ứng dụng.

Sửa lỗi

  • Thêm một bản sửa lỗi để ngăn sự cố có thể xảy ra khi di chuyển PanelEntity với MovableComponent và AnchorPlacement
  • Khắc phục lỗi 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ợ tính năng rút gọn Proguard cho Jetpack XR SceneCore (I4f47e)
  • Cập nhật quy tắc ProGuard của Jetpack XR Scenecore để ngăn AbstractMethodError cho các ứng dụng rút gọ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 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:
    • Xoá Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) và thay thế bằng ActivityPanelEntity.create(Session, Dimensions, String, Pose)
    • Xoá Session.createAnchorEntity(Anchor) và thay thế bằng AnchorEntity.create(Session, Anchor)
    • Xoá Session.createAnchorEntity(Dimensions, Int, Int, Duration) và thay thế bằng AnchorEntity.create(Session, Dimensions, Int, Int, Duration)
    • Xoá Session.createEntity(String, Pose) và thay thế bằng ContentlessEntity.create(Session, String, Pose)
    • Xoá Session.createExrImageResource(String) và thay thế bằng ExrImage.create(Session, String)
    • Xoá Session.createGltfEntity(GltfModel, Pose) và thay thế bằng GltfModelEntity.create(Session, GltfModel, Pose)
    • Xoá Session.createGltfModelResource(String) và thay thế bằng GltfModel.create(Session, String)
    • Xoá Session.createInteractableComponent(Executor, InputEventListener) và thay thế bằng InteractableComponent.create(Session, Executor, InputEventListener)
    • Xoá Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) và thay thế bằng MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
    • Xoá Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) và thay thế bằng PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose)
    • Xoá Session.createResizableComponent(Dimensions, Dimensions) và thay thế bằng ResizableComponent.create(Session, Dimensions, Dimensions)
    • Xoá Session.createStereoSurfaceEntity(Int, Dimensions, Pose) 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. Phương thức này đã được thay thế bằng cách sử dụng getSpatialCapabilities().hasCapability() như một cách phân chia rõ ràng hơn để kiểm tra xem có các chức năng không gian hay không vì getSpatialCapabilities() trả về một đối tượng SpatialCapabilities.
    • Xoá Session.requestFullSpaceMode() và thay thế bằng SpatialEnvironment.requestFullSpaceMode()
    • Xoá Session.requestHomeSpaceMode() và thay thế bằng SpatialEnvironment.requestHomeSpaceMode()
  • Session.setFullSpaceMode(Bundle) và Session.setFullSpaceModeWithEnvironmentInherited(Bundle) đã được chuyển sang các hàm mở rộng. Các tệp dành cho nhà phát triển sẽ cần thêm các lệnh 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 dành cho 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 chuyển sang các hàm mở rộng. Các tệp dành cho nhà phát triển sẽ cần thêm các lệnh 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 tiếp theo, bạn có thể giảm thiểu điều này bằng cách di chuyển bảng điều khiển về 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 chính xác. Thông tin này sẽ được cập nhật trong lệnh gọi OnSpaceUpdated sau trên 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

Các API và tính 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 sử dụng trong bản phát hành sau này)
  • StereoSurfaceEntity.create() không còn nhận tham số Dimensions. Các ứng dụng phải kiểm soát kích thước của canvas thông qua việc thiết lập CanvasShape
  • StereoSurfaceEntity có một thành phần CanvasShape có thể được đặt một cách linh động.
  • StereoSurfaceEntity.dimensions hiện là 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 tạo.

Các thay đổi khác

  • Giảm minSDK tại thời điểm biên dịch xuống còn 24. Tất cả API Jetpack XR vẫn yêu cầu API 34 trong thời gian chạy.
  • Nhà máy phiên (Session.create) của SceneCore 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 neo. Việc tạo 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 trong mét theo tỷ lệ thay vì luôn trả về mét không theo 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 liên quan đến nguồn hoặc đích.
  • Giờ đây, hộp bầu trời sẽ được đặt thành hộp bầu trời toàn màu đen bất cứ khi nào bạn truyền tuỳ chọn hộp bầu trời rỗng bằng setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). Để quay lại hộp bầu trời và 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 dành 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 và bảng nội dung tương ứng với nhau cũng như môi trường ảo hoặc thực tế của bạn.

  • SpatialEnvironment: Tạo trải nghiệm sống động bằng hình ảnh hộp bầu trời và/hoặc hình học mô hình 3D làm phông nền cho cảnh XR của môi trường. Hoặc bật tính năng truyền để cảnh ảo của bạn có thể tích hợp với môi trường thực 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 không gian có thể nổi hoặc được neo vào các bề mặt thực tế.
  • 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 nguồn âm thanh xung quanh và âm thanh điểm vào cảnh 3D để có âm thanh không gian sống động, chân thực.
  • StereoSurfaceEntity: SceneCore hỗ trợ định tuyến mắt trái/phải của nội dung được kết xuất lên một Surface Android. Bạn có thể dùng tính năng này để kết xuất nội dung âm thanh nổi ở định dạng cạnh nhau hoặc trên dưới, chẳng hạn như ảnh âm thanh nổi, video 3D hoặc các giao diện người dùng được kết xuất động khác. 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 tính năng vào nội dung XR, bao gồm cả các tính năng hỗ trợ người dùng di chuyển, đổi kích thước và tương tác với các mô hình và bảng điều khiển.
  • Mối liên kết: Khi bật tính năng truyền tải, bạn có thể đính kèm bảng điều khiển 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ế của 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 của bạn xung quanh vị trí của người dùng.
  • SpatialCapabilities: Tạo các ứng dụng thích ứng hoàn toàn tận dụng các chức năng không gian khi có, chẳng hạn như định vị nội dung giao diện người dùng theo 3D. Không chỉ vậy, ứng dụng của bạn còn có thể theo dõi các thay đổi đối với 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.

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à thay đổ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, bạn có thể khắc phục bằng cách không thay đổi kích thước bảng điều khiển chính, sử dụng thực thể bảng điều khiển động, tắt tính năng tạo lại hoạt động đối với 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.
  • Các thành phần có thể di chuyển và thay đổi kích thước không được hỗ trợ trên GltfEntity.
  • Entity.getSize() không được hỗ trợ trên GltfEntity.
  • Các ứng dụng Jetpack XR bắt buộc phải yêu cầu quyền android.permission.SCENE_UNDERSTANDING trong AndroidManifest.
  • Tính năng tạo phiên chỉ được hỗ trợ trên thiết bị Android XR. 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ẽ nhận được một RuntimeException.
  • Việc đặt hộp bầu trời thành rỗng thông qua `SpatialEnvironment.setSpatialEnvironmentPreference() không dẫn đến hộp bầu trời màu đen đồng nhất như đã ghi nhận. Điều này có thể dẫn đến hộp bầu trời mặc định của hệ thống hoặc không thay đổi hộp bầu trời hiện tại.
  • Ứng dụng SceneCore phải 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 bản phát hành trong tương lai, scenecore sẽ đưa thư viện này vào dưới dạng phần phụ thuộc api để ứng dụng không cần phải khai báo rõ ràng.
  • SceneCore bao gồm com.google.guava:guava-31.1-android và com.google.protobuf:protobuf-javalite dưới dạng phần phụ thuộc bắc cầu một cách không chính xác. Nếu điều này dẫn đến lỗi lớp trùng lặp trong bản dựng, bạn có thể loại trừ an toàn 2 phần phụ thuộc này.
  • 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 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.