{ } { }

Jetpack SceneCore

声明依赖项

要添加对 XR SceneCore 的依赖项，您必须将 Google Maven 代码库添加到您的项目。请参阅Google 的 Maven 代码库了解详情。

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

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

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

有关依赖项的更多信息，请参阅添加构建依赖项。

反馈

您的反馈有助于改进 Jetpack。如果您发现新问题或有改进此库的建议，请告诉我们。在创建新问题之前，请先查看此库中的现有问题。您可以通过点击星形按钮为您关注的现有问题投票。

创建新问题

请参阅问题跟踪器文档了解详情。

版本 1.0

版本 1.0.0-alpha04

2025 年 5 月 7 日

androidx.xr.scenecore:scenecore:1.0.0-alpha04 和 androidx.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.setSize 和 PanelEntity.getSize 现在在父空间中返回大小。
• Entity.setPose、Entity.getPose、Entity.setScale、Entity.getScale、Entity.setAlpha 和 Entity.getAlpha 现在接受一个新参数 relativeTo，该参数允许获取/设置相对于不同空间的值。支持的值包括 Parent、Activity 和 Real World 空间，此参数的默认值为 Parent。
• 已将空间可见性回调扩展方法添加到 SessionExt.kt，以监控场景内容何时移入或移出用户的视野范围。
• setPointSourceParams 已添加到 SpatialAudioTrack，允许在构建轨道后更新参数。
• 添加了一个新类 Scene，其中包含对 Scenecore API 的引用。Scene 将作为 Session 的扩展属性进行访问。SessionExt 内部的函数已移至 Scene，因此需要调整导入，例如 SessionExt.getScene(session).addSpatialCapababilitiesChangedListener 与 SessionExt.addSpatialCapabilitiesChangedListener。
• ActivityPose.hitTestAsync 已添加，可实现对虚拟内容的 hitTest 命中测试。
• 添加了新的组件类型 SpatialPointerComponent，允许客户端指定为指针渲染的图标，或禁用该图标。此组件目前只能附加到 PanelEntity 实例。
• 引入新的 PanelEntity 工厂，该工厂以米或像素为单位获取面板尺寸。旧版 PanelEntity 面板工厂（接受两个 Dimension 类型参数）已移除。

API 变更

• 已移除所有 Jetpack XR 软件包上的 RequiresApi(34) 限制。此限制是多余的，因为 Jetpack XR 目前仅适用于 API 级别 34+ 的设备。(Iae0f8)
• 随 Kotlin 2.0 发布的项目需要使用 KGP 2.0.0 或更高版本 (Idb6b5)
• PermissionHelper 类已移除。
• PanelEntity.getPixelDensity 已弃用。
• PanelEntity.setPixelDimensions 和 PanelEntity.getPixelDimension 已移除，替换为 setSizeInPixels 和 getSizeInPixels。
• Entity.getActivitySpaceAlpha 已移除。可替换为 Entity.getAlpha(Space.Activity)。
• Entity.getWorldSpaceScale 已移除。可替换为 Entity.getScale(Space.REAL\_WORLD)。
• SceneCore 中的 Session 类已删除，取而代之的是 XR Runtime 中的 Session。
• StereoSurfaceEntity 已重命名为 SurfaceEntity。
• Entity.setSize 和 Entity.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 时，大多数视图将被重新父级到 FrameLayout。这有助于将 LayoutInspector 与空间面板配合使用。
• 当前使用的 XrExtensions 实例现在已尽力注册到平台，以帮助应用调试。

Bug 修复

• 已添加修复，以防止当具有 MovableComponent 和 AnchorPlacement 的 PanelEntity 被移动时可能发生的崩溃
• 修复了 ResizableComponent 在 onResizeStart 回调中提供过期大小的问题。
• 修复了当 JxrPlatformAdapterAxr 的 dispose() 被多次调用时发生的崩溃。

版本 1.0.0-alpha03

2025 年 2 月 26 日

androidx.xr.scenecore:scenecore:1.0.0-alpha03 和 androidx.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-alpha02 和 androidx.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().hasCapability()，这是一种更模块化的方式来检查空间功能是否存在，因为 getSpatialCapabilities() 返回一个 SpatialCapabilities 对象。
  • 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 时更新。

破坏性变更与行为变更

• PanelEntity 和 ActivityPanelEntity 将具有 32dp 或更小的默认圆角半径（如果面板的宽度或高度小于 32dp）

新 API 和功能

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

其他变更

• 将编译时 minSDK 降至 24。所有 Jetpack XR API 在运行时仍要求 API 34。
• SceneCore 的 Session 工厂 (Session.create) 不再启动 intent 来获取 SCENE_UNDERSTANDING 权限。相反，客户端应用必须在尝试创建锚点之前明确地向用户请求权限。如果用户未授予权限，则锚点创建将失败。

bug 修复

• getActivitySpacePose() 已修复，通过返回缩放米中的平移值而不是始终返回未缩放米来考虑 ActivitySpace 缩放。transformPoseTo 现在在源或目标涉及 ActivitySpace 时也使用正确的单位计算坐标更改。
• 现在，每当使用 setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)) 传递空 skybox 偏好设置时，skybox 都将设置为全黑。要恢复到系统默认的 skybox 和几何体，请使用 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 视频或其他动态渲染的 UI。应用应使用 MediaPlayer 或 ExoPlayer 进行视频解码。
• 组件系统：SceneCore 提供了一个健壮灵活的组件系统，用于为您的 XR 内容添加功能，包括用户移动、调整大小以及与模型和面板交互的便利功能。
• Anchor：启用直通后，您可以将面板和模型附加到实际表面，让用户在真实世界环境中无缝集成虚拟内容。
• 用户姿态：访问用户在虚拟场景中的位置，以便根据用户的位置调整内容方向。
• SpatialCapabilities：构建完全自适应的应用，利用可用的空间化功能，例如 UI 内容的 3D 定位。不仅如此，您的应用还可以在应用执行期间监控功能变更，以便根据用户使用其 Android XR 设备的方式修改体验。

已知问题

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