{ } { }

Jetpack SceneCore

使用 3D 内容构建和操控 Android XR 场景图。
最近更新时间 稳定版 候选版 Beta 版 Alpha 版
2025 年 5 月 7 日 - - - 1.0.0-alpha04

声明依赖项

如需添加 XR SceneCore 的依赖项,您必须将 Google Maven 制品库添加到项目中。如需了解详情,请参阅 Google 的 Maven 代码库

在应用或模块的 build.gradle 文件中添加所需工件的依赖项:

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

如需详细了解依赖项,请参阅添加 build 依赖项

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题,或对此库有任何改进建议,请告诉我们。创建新问题前,请先查看此库中的现有问题。您可以点击星标按钮,为现有问题投票。

创建新问题

如需了解详情,请参阅问题跟踪器文档

版本 1.0

版本 1.0.0-alpha04

2025 年 5 月 7 日

发布了 androidx.xr.scenecore:scenecore:1.0.0-alpha04androidx.xr.scenecore:scenecore-testing:1.0.0-alpha04。版本 1.0.0-alpha04 包含这些提交内容

新功能

  • 返回处理现在适用于未嵌入 activity 的面板实体。为了使回调正常运行,您需要在 Android 清单中指定 android:enableOnBackInvokedCallback= "true"
  • StereoSurfaceEntity 现在通过两个新的 StereoMode 值(MULTIVIEW_LEFT_PRIMARY 和 MULTIVIEW_RIGHT_PRIMARY)支持 MV-HEVC 播放。
  • PanelEntity.setSizePanelEntity.getSize 现在会返回父空间中的大小。
  • Entity.setPoseEntity.getPoseEntity.setScaleEntity.getScaleEntity.setAlphaEntity.getAlpha 现在接受新的参数 relativeTo,该参数允许获取/设置相对于不同聊天室的值。支持的值包括“父级”“activity”和“真实世界”聊天室,此参数的默认值为“父级”。
  • SessionExt.kt 添加了空间可见性回调扩展方法,用于监控场景内容何时移出或移入用户视野范围。
  • setPointSourceParams 已添加到 SpatialAudioTrack,这样便可以在轨道构建后更新参数。
  • 添加了一个新的类 Scene,其中包含对 Scenecore API 的引用。场景将作为会话的扩展属性进行访问。SessionExt 中的函数已移至 Scene,因此需要调整导入项;例如,SessionExt.getScene(session)addSpatialCapababilitiesChangedListenerSessionExt.addSpatialCapabilitiesChangedListener
  • 添加了 ActivityPose.hitTestAsync,以针对虚拟内容启用 hitTest
  • 添加了新的组件类型 SpatialPointerComponent,让客户端可以指定为指针呈现的图标,或停用该图标。此组件目前只能附加到 PanelEntity 实例。
  • 引入了新的 PanelEntity 工厂,该工厂接受以米或像素为单位的面板尺寸。移除了接受两个 Dimension 类型参数的旧版 PanelEntity 工厂。

API 变更

  • 移除了对所有 Jetpack XR 软件包的 RequiresApi(34) 限制。由于 Jetpack XR 目前仅适用于 API 级别 34 及更高级别的设备,因此此限制是多余的。Iae0f8
  • 使用 Kotlin 2.0 发布的项目需要使用 KGP 2.0.0 或更高版本 (Idb6b5)
  • 已移除 PermissionHelper 类。
  • 弃用了 PanelEntity.getPixelDensity
  • 移除了 PanelEntity.setPixelDimensionsPanelEntity.getPixelDimension,取而代之的是 setSizeInPixelsgetSizeInPixels
  • 已移除Entity.getActivitySpaceAlpha。可以替换为 Entity.getAlpha(Space.Activity)
  • 已移除Entity.getWorldSpaceScale。可以替换为 Entity.getScale(Space.REAL\_WORLD)
  • SceneCore 中的 Session 类已被删除,取而代之的是 XR 运行时中的 Session。
  • StereoSurfaceEntity 已重命名为 SurfaceEntity
  • 移除了 Entity.setSizeEntity.getSize,并将相同的方法添加到了 PanelEntity
  • PointSourceAttributes 已重命名为 PointSourceParams
  • SpatializerConstants.SOURCE\_TYPE\_BYPASS 已重命名为 SpatializerConstants.SOURCE\_TYPE\_DEFAULT
  • PointSourceParams 实体已从公开访问权限修改为内部访问权限。
  • AnchorEntity.create 现在要求在 Session.configure() 中配置 PlaneTrackingMode
  • SpatialUser API 现在要求在 Session.configure() 中配置 HeadTrackingMode
  • 如果未附加 ResizableComponent,则会生成 INFO 级别日志,而不是 ERROR 级别日志。
  • Fov 类现在是常规的 Kotlin 类。
  • 拆分 Entity.kt,将每个具体实体类型放入自己的文件中。
  • 创建新的 PanelEntity 时,大多数 View 都会重新父级化为 FrameLayout。这有助于将 LayoutInspector 与空间面板搭配使用。
  • 系统现在会尽量向平台注册当前使用的 XrExtensions 实例,以便帮助调试应用。

bug 修复

  • 添加了一个修复程序,以防止在移动包含 MovableComponentAnchorPlacementPanelEntity 时发生崩溃
  • 修复了 ResizableComponentonResizeStart 回调中提供过时尺寸的问题。
  • 修复了多次调用 JxrPlatformAdapterAxrdispose() 时发生崩溃的问题。

版本 1.0.0-alpha03

2025 年 2 月 26 日

发布了 androidx.xr.scenecore:scenecore:1.0.0-alpha03androidx.xr.scenecore:scenecore-testing:1.0.0-alpha03。版本 1.0.0-alpha03 包含这些提交内容

新功能

  • Jetpack XR 代码现已支持 Proguard 缩减

bug 修复

  • 进行了其他修复,以支持对 Jetpack XR SceneCore 进行 Proguard 缩减 (I4f47e)
  • 更新了 Jetpack XR Scenecore ProGuard 规则,以防止为缩减后的客户端提供 AbstractMethodError。(I91a01)

版本 1.0.0-alpha02

2025 年 2 月 12 日

发布了 androidx.xr.scenecore:scenecore:1.0.0-alpha02androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02。版本 1.0.0-alpha02 包含这些提交内容

即将影响 1.0.0-alpha02 之前构建的应用的重大变更

  • 工厂方法已从 Session 类移至各个相应类型的伴生方法:
    • Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) 已被删除,取而代之的是 ActivityPanelEntity.create(Session, Dimensions, String, Pose)
    • Session.createAnchorEntity(Anchor) 已被删除,取而代之的是 AnchorEntity.create(Session, Anchor)
    • Session.createAnchorEntity(Dimensions, Int, Int, Duration) 已被删除,取而代之的是 AnchorEntity.create(Session, Dimensions, Int, Int, Duration)
    • Session.createEntity(String, Pose) 已被删除,取而代之的是 ContentlessEntity.create(Session, String, Pose)
    • Session.createExrImageResource(String) 已被删除,取而代之的是 ExrImage.create(Session, String)
    • Session.createGltfEntity(GltfModel, Pose) 已被删除,取而代之的是 GltfModelEntity.create(Session, GltfModel, Pose)
    • Session.createGltfModelResource(String) 已被删除,取而代之的是 GltfModel.create(Session, String)
    • Session.createInteractableComponent(Executor, InputEventListener) 已被删除,取而代之的是 InteractableComponent.create(Session, Executor, InputEventListener)
    • Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) 已被删除,取而代之的是 MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
    • Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) 已被删除,取而代之的是 PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose)
    • Session.createResizableComponent(Dimensions, Dimensions) 已被删除,取而代之的是 ResizableComponent.create(Session, Dimensions, Dimensions)
    • Session.createStereoSurfaceEntity(Int, Dimensions, Pose) 已被删除,取而代之的是 StereoSurface.create(Session, Int, Dimensions, Pose)
  • 移除了以下已废弃的方法:
    • Session.canEmbedActivityPanel(Activity) 已被删除。请改用 getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY)
    • Session.hasSpatialCapability(Int) 已被删除。由于 getSpatialCapabilities() 会返回 SpatialCapabilities 对象,因此已被替换为使用 getSpatialCapabilities().hasCapability() 作为更细分的方式来检查是否存在空间功能。
    • Session.requestFullSpaceMode() 已被删除,取而代之的是 SpatialEnvironment.requestFullSpaceMode()
    • Session.requestHomeSpaceMode() 已被删除,取而代之的是 SpatialEnvironment.requestHomeSpaceMode()
  • Session.setFullSpaceMode(Bundle)Session.setFullSpaceModeWithEnvironmentInherited(Bundle) 已移至扩展函数。开发者文件需要添加新的导入项才能访问:
    • import androidx.xr.scenecore.setFullSpaceMode
    • import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
  • Session.setPreferredAspectRatio(Activity, Float) 已移至扩展函数。开发者文件需要添加新的导入项才能访问:
    • import androidx.xr.scenecore.setPreferredAspectRatio
  • Session.getEntitiesOfType(Class<out T>)Session.getEntityForRtEntity(RtEntity) 已移至扩展函数。开发者文件需要添加新的导入项才能访问:
    • import androidx.xr.scenecore.getEntitiesOfType
    • import androidx.xr.scenecore.getEntityForRtEntity
  • Session.unpersistAnchor(Anchor)”已被删除
  • Session.createPersistedAnchorEntity(UUID)”已被删除

已知问题

  • PanelEntity.setCornerRadius()ActivityPanelEntity.setCornerRadius() 可能要等到下次移动面板后才会生效,您可以通过将面板移动到其当前位置来缓解此问题
  • ActivitySpace 调用 BoundsChanged 时,部分 ActivityPose 可能未正确更新。它将在 ActivitySpace 上的下一次 OnSpaceUpdated 调用时更新

破坏性变更和行为变更

  • 如果面板的宽度或高度小于 32dp,PanelEntityActivityPanelEntity 的默认角半径将为 32dp 或更小

新 API 和功能

  • 引入了 StereoSurface.CanvasShape,可用于创建 SphericalHemispherical 画布,以呈现沉浸式媒体。
  • StereoSurfaceEntity.create() 现在接受 CanvasShape 参数。(此参数目前会被忽略,但将在未来版本中使用)
  • StereoSurfaceEntity.create() 不再接受 Dimensions 参数。应用应通过设置 CanvasShape 来控制画布的大小
  • StereoSurfaceEntity 有一个可动态设置的 CanvasShape 成员。
  • StereoSurfaceEntity.dimensions 现在是只读属性;应用应设置 CanvasShape 以更改尺寸。
  • StereoSurfaceEntity 现在允许在构建后重新设置 StereoMode

其他变化

  • 将编译时 minSDK 降低到了 24。所有 Jetpack XR API 在运行时仍需要 API 34。
  • SceneCore 的会话工厂 (Session.create) 不再启动 intent 来获取 SCENE_UNDERSTANDING 权限。相反,客户端应用必须先向用户明确请求权限,然后才能尝试创建锚点。如果用户未授予此权限,则锚点创建将失败。

bug 修复

  • getActivitySpacePose() 已修正,以通过返回经过放大米制的平移值(而不是始终返回未放大米制值)来考虑 ActivitySpace 比例。现在,当源或目标涉及 ActivitySpace 时,transformPoseTo 还会使用正确的单位来计算坐标变化。
  • 现在,每当使用 setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) 传递 null 天空盒偏好设置时,天空盒都会设为全黑天空盒。如需还原为系统默认的天空盒和几何图形,请使用 setSpatialEnvironmentPreference(null).

版本 1.0.0-alpha01

2024 年 12 月 12 日

发布了 androidx.xr.scenecore:scenecore-* 1.0.0-alpha01

初始版本的功能 Jetpack SceneCore 的初始开发者版本,这是一个 3D 场景图库,用于创建和操控沉浸式场景和环境。借助此库,您可以相对于彼此以及虚拟或现实环境放置和排列 3D 模型和内容面板。

  • SpatialEnvironment:使用天空盒图片和/或 3D 模型几何图形作为环境 XR 场景的背景,打造完全沉浸式体验。或者,启用透视功能,以便您的虚拟场景可与用户的真实环境集成。
  • PanelEntity:通过将标准 Android 布局和 activity 嵌入到可浮动或锚定到真实表面的空间化面板中,将 2D 内容添加到 3D 场景。
  • GltfModelEntity:在场景中放置、为 3D 模型添加动画并与其互动。SceneCore 支持 glTF 文件格式,以便轻松与现有模型集成。
  • SpatialAudio:将环境音和点音频源添加到 3D 场景中,打造身临其境的空间化音效。
  • StereoSurfaceEntity:SceneCore 支持将内容渲染到 Android Surface 的左右眼路由。这可用于以并排或上下格式渲染立体内容,例如立体照片、3D 视频或其他动态渲染的界面。应用应使用 MediaPlayer 或 ExoPlayer 进行视频解码。
  • 组件系统:SceneCore 提供了一个强大且灵活的组件系统,可为您的 XR 内容添加功能,包括让用户移动、调整大小和与模型和面板互动的功能。
  • 锚点:启用透视功能后,您可以将面板和模型附加到实际表面,让用户能够将虚拟内容无缝集成到其真实环境中。
  • 用户姿势:访问用户在虚拟场景中的位置,以便根据用户的位置调整内容的方向。
  • SpatialCapabilities:构建完全自适应应用,以便在可用时利用空间化功能,例如界面内容的 3D 定位。不仅如此,您的应用还可以在应用执行期间监控功能的变化,以便根据用户使用 Android XR 设备的方式修改体验。

已知问题

  • 目前,使用 Jetpack SceneCore 需要满足最低 SDK 版本为 30 的要求。作为一种权宜解决方法,请添加以下清单条目 <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/>,以便能够使用 minSDK 23 进行构建和运行。
  • 在自动重新创建 activity 的各种情况下,会话可能会失效,包括调整主面板大小、连接外围设备以及在浅色模式和深色模式之间切换。如果您遇到会话失效问题,可采用的权宜解决方法包括使主面板不可调整大小、使用动态面板实体、针对特定配置更改停用 activity 重新创建,或停用浅色/深色模式主题更改。
  • GltfEntity 不支持可移动和可调整大小的组件。
  • GltfEntity 不支持 Entity.getSize()。
  • Jetpack XR 应用需要在 AndroidManifest 中请求 android.permission.SCENE_UNDERSTANDING 权限。
  • 仅 Android XR 设备支持创建会话。目前,如果您创建会话并尝试在非 Android XR 设备上使用它,则会收到 RuntimeException。
  • 通过 `SpatialEnvironment.setSpatialEnvironmentPreference() 将天空盒设置为 null 不会导致纯黑天空盒,如文档所述。这可能会导致系统使用默认天空盒,或者当前天空盒不会发生任何变化。
  • SceneCore 客户端应将 implementation(“com.google.guava:listenablefuture-1.0”) 添加到其应用依赖项的 Gradle 配置中。在未来的版本中,scenecore 将将此库作为 api 依赖项包含在内,因此客户端无需明确声明它。
  • SceneCore 错误地将 com.google.guava:guava-31.1-androidcom.google.protobuf:protobuf-javalite 包含为传递依赖项。如果这导致 build 中出现重复类错误,则可以放心地排除这两个依赖项。
  • 如果您的应用使用 SceneCore 并启用 ProGuard,则在您创建会话时会崩溃。如需解决此问题,请停用 ProGuard。如需详细了解如何启用 ProGuard,请参阅此指南