Jetpack SceneCore

声明依赖项

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

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

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.1.0-alpha01"

    // Use to write unit tests
    testImplementation "androidx.xr.scenecore:scenecore-testing:1.1.0-alpha01"
}

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.1.0-alpha01")

    // Use to write unit tests
    testImplementation("androidx.xr.scenecore:scenecore-testing:1.1.0-alpha01")
}

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

反馈

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

创建新问题

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

版本 1.1

版本 1.1.0-alpha01

2026 年 10 月 21 日

发布了 androidx.xr.scenecore:scenecore-*:1.1.0-alpha01。版本 1.1.0-alpha01 包含这些提交内容。

API 变更

• 添加了动态网格更新 API（MeshBuffer.createDynamic、MeshBuffer.updateVertexData、MeshBuffer.updateIndexData 和动态 CustomMesh.BuilderFromMeshData 构造函数），以支持在运行时更新顶点和索引数据。(Ia1ecb)
• 添加了 VertexLayout.getBufferIndex 辅助方法，以便轻松检索给定 VertexAttribute 或 VertexBufferLayout 的缓冲区索引。(I1a9e3)
• 将 CustomMesh.bounds 设为 var，以便在运行时动态更新边界框。(Ib0397)
• 将 glTF Animation API（GltfAnimation、GltfModelEntity.getAnimations 和 GltfModelEntity.stopAllAnimations）升级为公开/稳定版，同时将 GltfAnimation.loop setter 保留为实验性，并将 GltfAnimationStartOptions 和 start(options) 保留为实验性且已废弃。(Iacdae)
• 向 GltfModelEntity 添加了 stopAllAnimations()，使 GltfAnimation.start() 变为无参数，向 GltfAnimation 添加了 loop 和 speed 属性，并弃用了 GltfAnimationStartOptions、start(options) 和 seekTo(Duration)。(I53105)
• 更新了 GltfModelEntity API，以记录在已处置的实体上调用时会抛出 IllegalStateException（具体而言是 Entity.DisposedException）。I65a76f

bug 修复

• androidx.lifecycle:lifecycle-runtime 依赖项已更新至 2.10.0。此版本是捆绑的生命周期运行时 lint 检查在 AGP 9.5.0-alpha04 或更高版本中运行所必需的。（I99bfd、b/556807521）
• 改进了与 AudioOutputProvider 相关的 kdoc，以强调不应将其与多个 ExoPlayer 实例重复使用 (I6b18e)
• 从各种 XR 模块中移除了对 impress 的不必要依赖项。I84636c

版本 1.0

版本 1.0.0

2026 年 10 月 21 日

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

1.0.0 的主要功能：

• Jetpack XR SceneCore 现已稳定！借助 SceneCore，您可以相对于彼此和环境放置和排列由实体定义的 3D 内容。借助 SceneCore，您可以在虚拟和混合现实场景中创建、放置和操作 2D 面板和 3D 模型；指定空间环境和空间音频源；以及将虚拟内容锚定到现实世界。
• 如需了解详情，请参阅我们的概览页面和 API 参考文档。

版本 1.0.0-rc02

2026 年 10 月 7 日

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

bug 修复

• 通过移除 SessionExt 中的 perceptionRuntimeCache 并将其重构为直接从 Session 实例中检索 PerceptionRuntime，修复了潜在的内存泄漏问题。(Ie35b1)
• 通过对 OpenXR 原生句柄使用 applicationContext，修复了潜在的上下文泄露问题，以确保原生运行时不会保留对 Activity 上下文的引用。(Ie35b1)
• 通过引入适当的同步和初始化锁定，修复了 XrInstanceManager 中的竞态条件。(Ie35b1)
• 修复了 ReferenceCleaner 以支持取消注册清理操作，并确保在 dispose() 期间显式运行 Entity 清理操作，从而防止在垃圾回收时重复执行。(Ie35b1)
• 修复了 Scene 中的内存泄漏问题，方法是移除 SessionExt 中的 sceneCache，并重构 Scene 以直接从 sessionConnectors 提取实例。(Ie35b1)

版本 1.0.0-rc01

2026 年 9 月 9 日

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

API 变更

• 添加了 xr:scenecore:scenecore-openxr 库。(Ic49f2)
• 在 1.0.0 稳定版发布之前，移除了多个已废弃的 API。

bug 修复

• 解决了内存泄漏 bug，该 bug 会导致系统在 Activity 销毁后保留 Activity 引用。(I6dcd7)

行为变更

• 从 SceneCore 中移除了 logcat 输出。(I10c3c)

版本 1.0.0-beta02

2026 年 8 月 12 日

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

bug 修复

• 如果父实体已被垃圾回收，toMoveEvent() 将返回 null。(Ia7a1b)

版本 1.0.0-beta01

2026 年 7 月 15 日

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

API 变更

• GltfAnimation 和 SpatialGltfModelAnimation API 已标记为实验性。某些属性已转换为 getter。（I8d689、b/524771027）
• 移除了公开的 MovableComponent.createTrackingMovable 工厂方法。（I00912、b/477169015）
• 将 Session.create 转换为挂起函数。(I5d27f)
• ActivitySpace 和 AnchorSpace 现在扩展了一个通用 SpaceEntity 类，其中包含位置由系统控制的实体的常见行为 (I506ec, b/513619219)
• 将 AnchorEntity 更新为 AnchorSpace (Ifa95e, b/513619219)
• 提供公共测试 API SoundEffectPoolComponentTester。（I87df7、b/498104417）
• 向 SurfaceEntity.Shape.Quad 构造函数添加了可选的 cornerRadius 参数，并将 cornerRadius 属性设为公开。现在，开发者可以在创建四边形形状时指定圆角半径，以渲染具有圆角的 SurfaceEntity 画布，并查询现有四边形的半径。（Ia7809、b/474681085）
• 提供公共测试 API SpatialAudioTrackBuilderTester、SpatialAudioTrackTester 和 SceneCoreTestRule.getTester 重载。（I378c6、b/496333938）
• 为多种 ARCore 类型添加了 toString() 的专用替换。这些类型旨在为开发者提供更多信息，以便进行调试，不适合在生产环境或已发布的应用中使用。

版本 1.0.0-alpha16

2026 年 6 月 17 日

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

API 变更

• 向 CustomMesh.BuilderFromMeshData 和 CustomMesh.BuilderFromMeshBuffer 添加了 addVertexData、setIndexData 和 addSubset 的重载。这些重载允许开发者直接传递原始数据和参数（例如 ByteBuffer、offset、size、topology、indexOffset、indexCount），而无需将其封装在 ByteBufferRegion 或 MeshSubset 等中间对象中。(I84d5c)
• Scene.requestFullSpaceMode() 和 Scene.requestHomeSpaceMode() 已分别重命名为 requestFullSpace() 和 requestHomeSpace()。其他提及“主共享空间模式”和“全沉浸空间模式”的方法和文档也进行了类似的更新。(I45751)
• 提供公共测试 API PanelEntityTester 和 MainPanelEntityTester (I961e4)
• 向 SoundEffectPoolComponent 添加了 pointSourceParams 属性 (I4a750)
• 提供公开测试 API MovableComponentTester (I0c972)
• 提供公共测试 API PointerCaptureComponentTester (Ic0d4f)
• 提供公共测试 API ActivityPanelEntityTester (I837c4)
• 提供公共测试 API ResizableComponentTester (I0a3a4)
• 提供公共测试 API BoundsComponentTester. (Iefd53)
• 提供公开测试 API SpatialMediaPlayerTester (Ia3e09)
• 提供公共测试 API SpatialEnvironmentTester (Icf60f)
• 提供公共测试 API GltfModelTester 和 SceneCoreTestRule.getGltfModelTester。(I33fcb)
• 提供公共测试 API InteractableComponentTester。(Ia7096)
• 提供公共测试 API SurfaceEntityTester。(Ic0740)
• 提供公共测试 API GltfModelEntityTester、TestGltfModelNode 和 TestGltfAnimation。(I72c4d)
• 提供公共测试 API SceneTester 和 SceneCoreTestRule.sceneTester。(Ib4ec5)
• 提供公共测试 API PerceptionSpaceTester 和 SceneCoreTestRule.perceptionSpaceTester。(Icf739)
• 提供公共测试 API MeshEntityTester。(I63801)
• 提供公共测试 API ImageBasedLightingAssetTester 和 SceneCoreTestRule.getTester 重载。(I57ec4)
• 提供公开测试 API TextureTester (Ia865b)
• 提供公共测试 API PositionalAudioComponentTester (Icd96e)
• 提供公开测试 API SpatialSoundPoolTester (Ia3531)
• 提供公共测试 API SoundEffectPoolTester (If349a)
• 提供公共测试 API ActivitySpaceTester 和 SceneCoreTestRule.activitySpaceTester。(I2d5c2)
• 提供公共测试 API SpatialWindowTester (I41837)
• 提供公开测试 API AnchorEntityTester (I68404)
• 提供公共测试 API 接口 SceneCoreTestRule。(Ic72d3)
• 添加了 PixelDensity 类，并通过 Scene#virtualPixelDensity 公开该类，以便提供基于硬件的每米像素比，从而在 ActivitySpace 中实现准确的物理尺寸映射。(I0e3ac)
• 添加了用于创建和渲染自定义网格的公共 API。(I7ad2f)
• VertexLayout API 已更新为使用 VertexBufferLayout 列表，其中每个 VertexBufferLayout 描述单个顶点缓冲区内的属性。这样可以更灵活地排列顶点数据，包括具有自定义步长和偏移量的交错属性。(Ic426b)
• 提供 MovableComponent.createTrackingMovable，用于将 ARCore 可跟踪对象转换为相对于 Activity 空间的姿态。(I12249)
• Entity.create 中父级的默认值已更新为 null。(Ic3145)
• Entity 已更新为类（而非接口），现在是所有 Entity 类型的基类。在此次变更中，BaseEntity已被移除。(I7fbc9)
• GltfModel、ExrImage 和 ImageBasedLightingAsset 现在实现 AutoCloseable，以便使用 Kotlin 的 use 代码块进行惯用资源管理。(I1ac79)
• 引入了 ImageBasedLightingAsset 类，用于替换 ExrImage 来定义空间环境光照。ExrImage 已被废弃，并已从公共 API 中移除。SpatialEnvironmentPreference 已更新为使用 ImageBasedLightingAsset。(I6c92a)
• 将 SpatialEnvironment 中的 skybox 参数重命名为 imageBasedLightingAsset，以更好地反映其用途，并阐明视觉天空盒纹理应包含在几何图形参数中。(I24d4a)
• 空间实体现在使用稳定的设备密度在空间 API 级别 1 和 2 上进行像素到米的计算，从而确保无论系统显示密度如何变化，尺寸都保持一致。(I37051)

版本 1.0.0-alpha15

2026 年 5 月 19 日

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

API 变更

• Entity.dispose() 现已从公共 API 中移除。应用可以不调用 Entity 实例上的 dispose()，而是通过将 parent 设置为 null 并清除对这些实例的所有强引用，使实例可清理。(I396c9)
• 已删除 SoundEffectPool 的 set/clearOnLoadCompleteListener 方法。改用 add/removeLoadCompleteListener。(Iae78d)
• Scene 的 set/clearSpatialVisibilityChangedListener 已替换为 add/removeSpatialVisibilityChangedListener。(I67dff)
• 所有 SceneCore add/removeOnFooListener 方法均已重命名为 add/removeFooListener，从名称中移除了 On。(Ibe50b)
• AnchorEntity.setOnOriginChangedListener 和 AnchorEntity.setOnStateChangedListener 方法已替换为 add/removeFooListener 方法，以支持多个同时运行的监听器。(I13749)
• AnchorEntity.State.TIMEDOUT 已重命名为 State.TIMED_OUT。(Id2b8d)
• Component API 已经过重构，以提高安全性和可扩展性。Component 现在是一个抽象类。onAttach() 和 onDetach() 方法现在为 protected，以防止直接调用。请使用 Entity.addComponent() 和 Entity.removeComponent() 管理组件生命周期。(Id04e8)
• SceneCore 的 PlaneSemanticType PlaneOrientation 常量已从 Int 迁移到自定义类型。其 ANY 常量将被移除，客户端应改为明确枚举所有所需常量，或使用新的 .ALL 不可变 Set 常量。AnchorEntity 工厂方法现在接受这些类型的 Set，而不是单个值。(Ib1033)
• 为实验性 Custom Mesh API 添加了对骨骼动画（蒙皮）的支持。现在，开发者可以在创建 MeshEntity 时指定 boneCount，并使用 MeshEntity.setBoneTransforms() 实时更新动画，从而为自定义网格添加动画效果。（Id8ba2、b/496692490）
• 引入了实验性 CustomMesh API。开发者现在可以使用 CustomMesh、MeshBuffer 和 MeshEntity 以编程方式在场景中创建和渲染 3D 几何图形。(I94617)
• 移除了 androidx.xr.scenecore.SpatializerConstants.SourceType.SOURCE_TYPE_SOUND_FIELD。已改用 SourceType.SOUND_FIELD。(Ia68b9)
• 添加了空间音频组件：PositionalAudioComponent、SoundEffectPoolComponent 和 SoundFieldAudioComponent (Ieda89)
• AnchorEntity.getAnchor 已替换为 AnchorEntity.anchor，现在当 AnchorEntity 是通过 ARCore Anchor 创建时，将返回 Anchor (I5c7c8)
• ActivityPanelEntity、GltfModelEntity、GroupEntity、PanelEntity 和 SurfaceEntity 工厂方法中 parent 参数的默认值已从 ActivitySpace 更改为 null。现在，如需将实体附加到场景图并使其可见，开发者必须在实例化期间或通过 Entity.parent = ... 明确设置其父级 (Ie7cc1)

bug 修复

• SceneCore 现在会在 Entity 实例变为虚幻可达时自动回收这些实例，从而无需开发者显式调用 dispose() 来释放资源。为确保 [Entity] 实例得到妥善回收，开发者应：
  • 通过将其 parent 设置为 null，将其从场景图中分离。
  • 在代码中放弃对该实例的所有强引用。
  • 关于特殊实体类型的说明：对于无法设置父级的实体（例如 AnchorEntity），开发者必须在实例使用期间保持强引用。如果所有引用均已释放，这些实例将变为虚引用可达，并会被自动回收。(I83fe4)
• 缩小了所有 SceneCore 库的 Proguard 保留规则。(I98447)

已知问题

• 将 PositionalAudioComponent 附加到具有非活跃 ExoPlayer 实例的 Entity 会导致崩溃。在 ExoPlayer 停止时，请勿调用 setPointSourceParams 或附加/分离空间音频组件。此问题将在下一版本中修复。

版本 1.0.0-alpha14

2026 年 5 月 6 日

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

API 变更

• TrackingState 和 VpsAvailabilityResult 已移至 androidx.xr.arcore package，androidx.xr.runtime 中的类型现已废弃。（Ic7930、b/480462213）
• Plane.Type 已重命名为 PlaneType。（I8c90c、b/482675376）
• Plane.Label 已重命名为 PlaneLabel。（Ic6b67、b/482675376）
• 已弃用 androidx.xr.runtime.FieldOfView。已改用 androidx.xr.runtime.math.FieldOfView。（Ia01a0、b/480233045）
• Matrix4.pose 已重命名为 Matrix4.toPose()。姿势属性现已弃用。（I329b4、b/493383490）
• 重命名了 HandJointType 个枚举值。（Ifbc83、b/482670596）
• 将 Component.onAttach 和 onDetach 公开为公共 API，以允许自定义 Component 实现。(I0ca1f)
• 添加了空间音频组件（I39ddd、b/489421980、b/436642086、b/436642499）
• 从 PointSourceParams 中移除实体。而是直接与 SpatialAudioTrack、SpatialSoundPool 和 SpatialMediaPlayer 搭配使用（Ib3685、b/489421980、b/436634048）
• 将 DeviceTrackingMode.LAST_KNOWN 重命名为 SPATIAL_LAST_KNOWN（具有已弃用的回退），为 3DoF 跟踪添加了 INERTIAL_LAST_KNOWN，并向 TrackingState 添加了 TRACKING_DEGRADED。（Ie661c、b/445466590）
• 已废弃 GroupEntity。如需让实体仅具有基本实体功能，请调用 Entity.create，它将返回实体接口。（I4c450、b/473867483）
• 添加了 XrLog API。将 XrLog.isEnabled 设置为 true，以在 JetpackXR 中启用日志记录，并使用 XrLog.Level 设置日志级别。（I76a1f、b/463460895、b/487378441）

bug 修复

• Scene.keyEntity 现已默认为 mainPanelEntity。(I6a3ef)

版本 1.0.0-alpha13

2026 年 3 月 25 日

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

API 变更

• 从 Session.create 中移除了 unscaledGravityAlignedActivitySpace 标志。ActivitySpace 现在始终不缩放且与重力对齐。（If6f11、b/458173423）
• 从 GltfModelEntity 中移除了已弃用的 setMaterialOverride 和 clearMaterialOverride 函数，现在这些函数在各个 GltfModelNode 上调用。(I2e5d2)
• 向 PanelEntity 添加了 transformPixelCoordinatesToLocalPosition 和 transformNormalizedCoordinatesToLocalPosition，并移除了过去返回姿势而非 Vector3 位置的等效实验性方法。（Ib6960、b/460123106、b/458333591）
• 添加了 GltfAnimation API，用于控制 SceneCore 中的 glTF 动画。（I2c172、b/466065486、b/465819070、b/465818617）
• ScenePose.activitySpacePose 已重命名为 ScenePose.poseInActivitySpace（I8f175、b/427822261）
• 添加了 Scenecore 投影运行时实现 (I9c4ab, b/476440158)
• 调整主面板实体的大小时，它可能会自行重新定位到 ActivitySpace 原点。除了手动或以编程方式将面板重新定位回其原始位置之外，没有其他解决方法。此 bug 将在未来版本中修复。(b/489427007).
• 在某些情况下，MovableComponent 的功能可见性可能不会针对 SurfaceEntity 和其他非面板实体类型显示。明确设置 MovableComponent.size 会导致显示功能。此 bug 将在未来版本中修复 (b/490983469)。

版本 1.0.0-alpha12

2026 年 2 月 25 日

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

已知问题

• 锚定实体可能会在几秒钟后从锚定位置贴靠到活动空间原点。
• 应用在创建 SurfaceEntity 实例时可能会崩溃。此问题已在 androidx.xr.scenecore:scenecore-*:1.0.0-alpha13 及后续版本中得到解决。受影响的应用应更新到最新版本。

API 变更

• ActivitySpace.addOnSpaceUpdatedListener 和 ActivitySpace.removeOnSpaceUpdatedListener 已重命名为 addOnOriginChangedListener 和 removeOnOriginChangedListener。AnchorEntity.setOnSpaceUpdatedListener 已重命名为 setOnOriginChangedListener。(I5d8fb)
• 向 FakeEntity 添加了公开名称属性，并在 FakePanelEntity 上公开了视图。(Ifa1f9)

bug 修复

• 修复了较新系统映像上的像素密度计算问题 (I57d04)

版本 1.0.0-alpha11

2026 年 1 月 28 日

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

API 变更

• 将 PerceivedResolutionResult.InvalidCameraView 重命名为 PerceivedResolutionResult.InvalidRenderViewpoint，因为 getPerceivedResolution API 现在依赖于 ARCore 的 RenderViewpoint API，而不是 CameraViewScenePose。此名称能更好地反映新的实现。（I8c967、b/446989745、b/419311998）
• PanelEntity/SurfaceEntity.getPerceivedResolution 方法现在将开发者提供的 RenderViewpoint 作为参数。之前，运行时会任意选择用于感知分辨率计算的 RenderViewpoint。（I8c967、b/446989745、b/419311998）
• 移除了 SpatialUser、ScenePose.Head 和 ScenePose.CameraView。这些 API 的功能由 ARCore for Jetpack XR 中的 ArDevice 和 RenderViewpoint API 涵盖。如需获取与用户的头部或左眼/右眼对应的 ScenePose，开发者可以将 PerceptionSpace.getScenePoseFromPerceptionPose 与使用 ARCore API 获取的适当姿势搭配使用。（I2f69c、b/446989745）

版本 1.0.0-alpha10

2025 年 12 月 3 日

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

API 变更

• 向 PanelEntity 添加了 transformPixelCoordinatesToPose 和 transformNormalizedCoordinatesToPose (I462b3)
• 根据 SceneCore 中的逻辑，向 SceneCore 运行时添加了辅助类 Utils (I570b9)

bug 修复

• 修复了在会话被销毁且收到 SpatialModeChangeEvent 时可能发生的潜在崩溃问题 (If44e8)
• 修复了在离开或重新进入 Activity 时可能导致抛出 IllegalStateException 的 bug。(Ibff1c)

版本 1.0.0-alpha09

2025 年 11 月 19 日

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

新功能

• 添加了一个 API，用于检索 ScenePose，该对象表示感知空间原点姿态和相对于感知空间原点的姿态的组合。(I5b50a)
• 新增了 getGravityAlignedPose 函数。重力对齐姿势会忽略旋转的俯仰角和横滚角。(I5ae21)
• AnchorEntity.State 常量类型已从 Int 更改为 State 子类型。(Ib0c49)
• 向 Entity 接口添加了 getChildren()。更新了 MainPanelEntity 生命周期。(Ia69d6)

API 变更

• PointerCaptureComponent.PointerCaptureState 常量类型已从 Int 更改为 PointerCaptureState 子类型。(Ic888a)
• Scene.spatialCapabilities 现在是 Set<SpatialCapability> 类型，而不是 Int 字段。SpatialCapability 常量已重命名。(I9c109)
• SurfaceEntity 常量类型已重命名，并从 Int 更改为 SurfaceEntity 子类型。(I419ed)
• SpatializerConstant 常量类型已重命名，并从 Int 更改为 SpatializerConstant 子类型。(Ia0e18)
• TextureSampler 常量类型已重命名，并从 Int 更改为 TextureSampler 子类型。(I44078)
• SpatialVisibility 常量类型已从 Int 更改为 SpatialVisibility 子类型。(I70739)
• ResizeEvent.ResizeState 常量类型已重命名，并从 Int 更改为 ResizeState 子类型。(I384d5)
• InputEvent 常量类型已重命名，并从 Int 更改为继承自其各自的封闭类型。(I82817)
• GltfModelEntity.AnimationState 常量类型已从 Int 更改为 AnimationState 子类型。(I24f4e)
• AlphaMode 常量类型已重命名，并从 Int 更改为 AlphaMode 子类型。(I27b56)
• Space 常量类型已从 Int 更改为 Space 子类型。(I9255b)
• 如果未找到交集，ScenePose.hitTest 和相关方法现在会返回 null，而不是返回 hitPosition 为 null 的 HitTestResult。HitTestResult.hitPosition 不再可为 null。(I1400a)
• 将 ActivityPose 的引用更改为 ScenePose。(I7fe43)

版本 1.0.0-alpha08

October 22, 2025

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

API 变更

• ActivityPanelEntity.moveActivity 已重命名为 transferActivity（I273c5、b/430332856）

bug 修复

• :xr:scenecore:scenecore-spatial-rendering 和 :xr:scenecore:scenecore-spatial-core 已添加为 :xr:scenecore:scenecore 的实现依赖项 (I6ab65, b/447000520)
• 如果在会话销毁后访问 session.scene，系统会抛出异常。(I77e6f)

版本 1.0.0-alpha07

2025 年 9 月 24 日

发布了 androidx.xr.scenecore:scenecore:1.0.0-alpha07、androidx.xr.scenecore:scenecore-guava:1.0.0-alpha07 和 androidx.xr.scenecore:scenecore-testing:1.0.0-alpha07。版本 1.0.0-alpha07 包含这些提交内容。

API 变更

• 将 fixedAspectRatio 重命名为 isFixedAspectRatioEnabled，并将其设为布尔值属性 (I5c4e8, b/440588971)
• Scenecore 伪造现在位于 xr:scenecore:scenecore-testing 模块中。(Idd951)
• 将 shouldAutoHideContent 重命名为 isAutoHideContentWhileResizingEnabled，将 shouldAlwaysShowOverlay 重命名为 isAlwaysShowOverlayEnabled (I97c36, b/432335421)
• 更新了 SceneCore TextureSampler 常量以提高可读性，例如 TextureSampler.MinFilter.LINEAR 现在为 TextureSampler.MIN_FILTER_LINEAR (Ib159c)
• 场景的 setKeyEntity setter 已合并到 keyEntity 变量中。将 keyEntity 设置为不可移动的实体（例如 AnchorEntity）会抛出 IllegalArgumentException，而不是返回布尔值 false。（I62080、b/428721695、b/422215745）
• Scene 的 SpatialModeChangeListener 变量已替换为 setSpatialModeChangedListener。它接受 Consumer<SpatialModeChangeEvent> 而不是 SpatialModeChangedListener。setSpatialModeChangedListener 现在可以选择性地接受 Executor。（I62080、b/428721695、b/422215745）
• 从 ActivityPanelEntity.startActivity 中移除了 bundle 参数 (I64344, b/430332856, b/430333040)
• SpatializerConstants.SOURCE_TYPE_BYPASS 已重命名为 SpatializerConstants.SOURCE_TYPE_DEFAULT。（Ifc7fe、b/422215565）
• 添加了 SpatialSoundPool.PLAY_FAILED 常量。（Ifc7fe、b/422215565）
• 向 SpatialSoundPool.play 方法添加了默认参数。（Ifc7fe、b/422215565）
• 移除了 SpatialAudioTrackBuilder 中 setter 的返回值。（Ifc7fe、b/422215565）
• SurfaceEntity 变更
  • SurfaceEntity.CanvasShape已重命名为Shape
  • SurfaceEntity.CanvasShape.Vr180Hemisphere已重命名为Hemisphere
  • SurfaceEntity.CanvasShape.Vr360Sphere已重命名为Sphere
  • SurfaceEntity.EdgeFeatheringParams.SmoothFeather已重命名为RectangleFeather
  • SurfaceEntity.EdgeFeathingParams.SolidEdge重命名了NoFeathering
  • SurfaceEntity.ContentSecurityLevel已重命名为SurfaceProtection
  • SurfaceEntity.ContentSecurityLevel.{values}添加了SURFACE_PROTECTION_前缀。
  • SurfaceEntity.SuperSampling.{$values}添加了 SUPER_SAMPLING_ 前缀
  • SurfaceEntity.StereoMode.{values}添加了 STEREO_MODE_ 前缀
  • SurfaceEntity.ContentColorMetadata.maxCLL 已重命名为 maxContentLightLevel（I7eb5f、b/422216050、b/427529950）
• launchActivity 已重命名为 startActivity (I7db90, b/430332856)
• 移除了 Scene.activitySpaceRoot。已改用 Scene.activitySpace。（I05ee8、b/378706624、b/422215745）
• configureBundleForFullSpaceModeLaunch 和 configureBundleForFullSpaceModeLaunchWithEnvironmentInherited 分别重命名为 createBundleForFullSpaceModeLaunch 和 createBundleForFullSpaceModeLaunchWithEnvironmentInherited，并作为顶级方法移至 LaunchUtils.kt 文件，且将 Session 作为第一个参数 (I64a2c, b/437186050)
• GroupEntity 工厂现在返回 GroupEntity 类型，而不是 Entity。(I66042)

bug 修复

• 在实体实例被处置后使用时，抛出 IllegalStateException。（I90990、b/427314036、b/432063442）

版本 1.0.0-alpha06

2025 年 8 月 13 日

发布了 androidx.xr.scenecore:scenecore:1.0.0-alpha06、androidx.xr.scenecore:scenecore-guava:1.0.0-alpha06 和 androidx.xr.scenecore:scenecore-testing:1.0.0-alpha06。版本 1.0.0-alpha06 包含这些提交内容。

API 变更

• 取消对 SceneCore 的 BaseEntity 和 BaseScenePose API 的限制 (88c0ff6)

版本 1.0.0-alpha05

2025 年 7 月 30 日

发布了 androidx.xr.scenecore:scenecore-guava:1.0.0-alpha05、androidx.xr.scenecore:scenecore-testing:1.0.0-alpha05 和 androidx.xr.scenecore:scenecore:1.0.0-alpha05。版本 1.0.0-alpha05 包含这些提交内容。

新功能

• 向面板实体和 SurfaceEntities 添加了感知分辨率 API。(I118f6)
• PerceivedResolution 已将回调方法添加到 Scene.kt，以监控 HSM 中 activity 主面板的感知分辨率。(I58084)
• SurfaceEntity - 添加了对应用在创建时请求超采样的支持。这样，应用就可以使用超级采样过滤器进行抗锯齿处理。(I06913)
• ActivitySpace 中新增了 recommendedContentBoxInFullSpace 属性。它会返回一个建议的框，用于在全沉浸空间模式下放置内容。(I4cd6f)
• 为可移动修饰符提供了重载构造函数，该修饰符允许锚定。(Ic0c70)

API 变更

此版本对 SceneCore 进行了大量 API 更改。多个类已重命名和/或移至其他模块，并且大多数 getter/setter 方法已替换为 Kotlin 属性。虽然我们预计在发布首个 Beta 版之前，API 仍会发生重大变更，但这些变更不会造成太大影响，数量也不会太多。

• 重命名和/或移动了以下类和接口：androidx.xr.scenecore.PixelDimensions 更改为 androidx.xr.runtime.math.IntSize2d；androidx.xr.scenecore.Dimensions 更改为 androidx.xr.runtime.math.FloatSize3d；androidx.xr.scenecore.ActivityPose 更改为 ScenePose；androidx.xr.scenecore.ContentlessEntity 更改为 GroupEntity；androidx.xr.scenecore.PlaneType 更改为 PlaneOrientation；androidx.xr.scenecore.PlaneSemantic 更改为 PlaneSemanticType。(Ifd405)(I3b622) (If534d)
• Scene 属性的许多 setter 已设为私有；它们不应由 SceneCore 客户端进行更改：activitySpace、activitySpaceRoot、mainPanelEntity、perceptionSpace、spatialCapabilities、spatialEnvironment 和 spatialUser。(I2f506)
• 在 Entity 中：将以下内容更改为属性：get/setParent()、setContentDescription；已废弃 Entity.is/setHidden()，请改用 Entity.is/setEnabled。(Ibc4c6)
• 移除了 androidx.xr.scenecore.BasePanelEntity 类，请直接改用 PanelEntity。将 PanelEntity 的 getter 和 setter 替换为属性。将 PanelEntity.size 属性从 Float3dSize 更改为了 Float2dSize。移除了已废弃的方法 androidx.xr.scenecore.PanelEntity.getPixelDimensions，请改用 getSizeInPixels。(Icc174)
• 已将 androidx.xr.scenecore.OnSpaceUpdatedListener 替换为 Runnable。(I19308)
• 已将 SpatialUser.getCameraViews() 替换为属性。(Ib0cc5) 对于 ExrImage 和 GltfModel:，将 create 方法更改为挂起函数；修改了 create 参数，以接受 Uri 或 Path，而不是 String。(Id8883) (I0d247), (I25706)
• 将 SpatialEnvironment.requestFullSpaceMode 和 SpatialEnvironment.requestHomeSpaceMode 移到了 Scene，例如，使用 session.scene.requestFullSpaceMode() 而不是 session.scene.spatialEnvironment.requestFullSpaceMode()。addOnPassthroughOpacityChangedListener 和 addOnSpatialEnvironmentChangedListener 现在具有接受可选执行器的替换项。(I12fe0) (I6b21e)
• 移除了以下已废弃的 SpatialEnvironment 方法：togglePassthrough、setPassthrough、setPassthroughOpacity、getPassthroughMode、getPassthroughOpacity、setSkybox 和 setGeometry。还移除了已废弃的类 SpatialEnvironment.PassthroughMode (I927bd) (I927bd) (I927bd)
• 将以下 SpatialEnvironment getter 和 setter 替换为 Kotlin 属性：getCurrentPassthroughOpacity()、get/setPassthroughOpacityPreference()、get/setSpatialEnvironmentPreference()、isSpatialEnvironmentPreferenceActive() (I33a7b) (Ie06e2) (Ie06e2)
• SpatialEnvironmentPreference.preferredPassthroughOpacity 类型从 Float? 更改为 Float。它不再接受 null 值。而是使用 SpatialEnvironment.NO_PASSTHROUGH_OPACITY_PREFERENCE 来表示没有不透明度偏好。(I40107)
• 在 create 方法中，将 windowBoundsPx 参数更新为 pixelDimensions，并将其类型从 Rect 更改为 IntSize2d。(I1926e)
• SpatialEnvironment 构造函数现已变为内部函数 (I75a51)
• 将 SpatialPointerIconNone 类和 SpatialPointerIconCircle 类替换为伴生对象 SpatialPointerIcon.NONE 和 SpatialPointerIcon.CIRCLE (I416d2)
• SpatialPointerComponent 中的 SpatialPointerIcon 不再可为 null。使用 SpatialPointerIcon.DEFAULT 而不是 null 来表示应使用系统默认指针图标。(I416d2)
• 将 androidx.xr.scenecore.AnchorEntity.getState() 替换为只读属性。重命名了 AnchorEntity.create() 方法的参数，以提高清晰度。在 AnchorEntity 用于设置和添加监听器的方法中，监听器已移至最终参数，以启用尾随 lambda。已将AnchorEntity的androidx.xr.scenecore.OnStateChangedListener替换为Consumer<AnchorEntity.State>。(I472e0)
• GltfModelEntity.getAnimationState() 现在是一项媒体资源。(I10b29)
• 已将 ActivitySpace.getBounds() 替换为属性。ActivitySpace.addBoundsChangedListener 已重命名为 ActivitySpace.addOnBoundsChangedListener。已将 ActivitySpace.setOnSpaceUpdatedListener 替换为添加/移除方法。(I4c956)
• 对于 AnchorPlacement: planeTypeFilter，已重命名为 anchorablePlaneOrientations，planeSemanticFilter 已重命名为 anchorablePlaneSemanticTypes。向 AnchorEntity 或 ActivitySpace 添加 MovableComponent 将返回 false，MoveListener 已重命名为 EntityMoveListener shouldDisposeParentAnchor，disposeParentOnReAnchor systemMovable 已从 create 函数中移除，取而代之的是 creeateCustomMovable、createSystemMovable 和 createAnchorable (If11c4)
• 移除了 SurfaceEntity.featherRadiusX/Y 并添加了 EdgeFeatheringParams 类概念。(Ic78fc)
• PanelEntity.enablePanelDepthTest() 方法已替换为 panelClippingConfig 属性。将 Scene.panelClippingConfig = PanelClippingConfig(isDepthTestEnabled = true) 设置为启用深度测试，或将其设置为 PanelClippingConfig(isDepthTestEnabled = false) 以停用深度测试。(I0cbe0)
• Scene.mainPanelEntity 的类型现在是 MainPanelEntity，而不是 PanelEntity (I7125a)
• 将 Scene 的 setFullSpaceMode 方法重命名为 configureBundleForFullSpaceModeLaunch，将 setFullSpaceModeWithEnvironmentInherited 方法重命名为 configureBundleForFullSpaceModeLaunchWithEnvironmentInherited。(I0cbe0) (I0cbe0)
• 将 SpatialVisibility 的 UNKNOWN、OUTSIDE_FOV、PARTIALLY_WITHIN_FOV 和 WITHIN_FOV 值分别重命名为 SPATIAL_VISIBILITY_UNKNOWN、SPATIAL_VISIBILITY_OUTSIDE_FIELD_OF_VIEW、SPATIAL_VISIBILITY_PARTIALLY_WITHIN_FIELD_OF_VIEW 和 SPATIAL_VISIBILITY_WITHIN_FIELD_OF_VIEW (Ie7e8c)
• SpatialVisibility 类已替换为具有 const Int 值的公共对象。setSpatialVisibilityChangedListener 现在接受 Consumer<Int>，而不是 Consumer<SpatialVisibility> (Ie7e8c)
• PointerCaptureComponent 常量已重命名并移至 PointerCaptureComponent.PointerCaptureState 对象 (I9c7ac)
• 已将 PointerCaptureComponents' StateListener 替换为 Consumer<Int>。(I9c7ac)
• 已将 InputEventListener 替换为 Consumer<InputEvent> (I9c7ac)
• setPreferredAspectRatio 已从 Scene 类移至 SpatialWindow 对象，并接受 Session 作为第一个参数。(I7b717)
• Entity.setHidden() 已替换为 Entity.setEnabled()，Entity.isHidden() 已替换为 Entity.isEnabled()。setHidden(false) 等于 setEnabled(true) 和 isHidden() == !isEnabled()。(Icf0de)
• Entity.contentDescription 类型从 String 更改为 CharSequence。(Ie59be)
• 现在，如果未授予足够的权限，Session.create 和 Session.configure 会抛出 SecurityException，而不是返回 SessionCreatePermissionsNotGranted 或 SessionConfigurePermissionsNotGranted。(I7c488)
• ResizableComponent.create 现在需要 Consumer<ResizeEvent> ResizeEventListener，已替换为 Consumer<ResizeEvent> ResizableComponent.size，已重命名为 ResizableComponent.affordanceSize ResizableComponent.minimumSize，已重命名为 ResizableComponent.minimumEntitySize ResizableComponent.maximumSize，已重命名为 ResizableComponent.maximumEntitySize，ResizableComponent.autoHideContent 已重命名为 ResizableComponent.shouldAutoHideContent，ResizableComponent.forceShowResizeOverlay 已重命名为 ResizableComponent.shouldAlwaysShowOverlay (I97a2d)
• 将 androidx.xr.scenecore 和 androidx.xr.compose 的 minSDK 减少到 24。XR 软件包在运行时仍需要 API 34。(I17224)
• 移除了对所有 Jetpack XR 软件包的 RequiresApi(34) 限制。此限制是多余的，因为 Jetpack XR 目前仅适用于 API 级别 34+ 的设备。(Iae0f8)
• 主 SceneCore 工件 (xr:scenecore:scenecore) 将仅包含 Kotlin 样式的异步 API。Java 开发者可以依赖 xr:scenecore:scenecore-guava 库来访问兼容的 API。(If221b)
• 使用 Kotlin 2.0 发布的项目需要 KGP 2.0.0 或更高版本才能使用 (Idb6b5)
• 此库现在使用 JSpecify nullness 注解，这些注解属于 type-use 类型。Kotlin 开发者应使用以下编译器实参来强制执行正确用法：-Xjspecify-annotations=strict（这是 Kotlin 编译器从 2.1.0 版开始的默认实参）(Ia8420)
• 所有返回 ListenableFuture 的异步方法均已替换为 Kotlin 挂起函数。希望使用基于 ListenableFuture 的异步方法（而非 Kotlin 挂起函数）的 Java 开发者现在必须使用 :xr:scenecore-scenecore-guava 中的扩展函数。例如，GuavaExrImage 包含与 Guava 等效的 ExrImage 异步函数，GuavaScenePose 包含与 Guava 等效的 ScenePose 异步函数，GuavaGltfModel 包含 Guava-equivalent GltfModel 异步函数，等等。(If7283) (I0af60) (If7283) (Ia8515) (I4efdf) (I54bbf) (I3467a) (I82a33)

bug 修复

• 更新了 Jetpack XR Scenecore ProGuard 规则，以防止缩减大小的客户端出现 AbstractMethodError。(I91a01)
• 进行了其他修复，以支持 Jetpack XR SceneCore 的 Proguard 缩减大小 (I4f47e)
• 修复了以下 bug：如果从系统返回的 hitPosition 为 null，InputEvent 的 HitInfo 上的 hitPosition 可能会崩溃，InteractableComponent 可能会导致崩溃 (I7a695)
• Config *Mode 值已重命名，以反映其行为。(I6d247)
• 修复了 SceneCore TestApp 中 FOV 和 HitTest 的问题。(I2c51e)
• 修复了 SpatialCapabilities.hasCapability() 中的 bug：如果使用按位 OR 传入的任何功能为 true，则该方法会返回 true，而不是仅在所有功能都为 true 时才返回 true。(I2cd40)
• SurfaceEntity.StereoMode.TOP_BOTTOM 已更新，现在顶部地图对应左眼，底部地图对应右眼。(I4ae68)

版本 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 工厂，该工厂接受以米或像素为单位的面板尺寸。移除了接受两个 Dimension 类型参数的旧 PanelEntity 工厂。

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 运行时中的 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 时，大多数 View 都会重新父级化为 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.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 嵌入到可悬浮或锚定到现实世界表面的空间化面板中，向 3D 场景添加 2D 内容。
• GltfModelEntity：在场景中放置 3D 模型、为其添加动画效果并与之互动。SceneCore 支持 glTF 文件格式，以便轻松与现有模型集成。
• SpatialAudio：将环境和点音频源添加到 3D 场景中，以实现完全沉浸式的空间化声音。
• StereoSurfaceEntity：SceneCore 支持将渲染到 Android Surface 上的内容路由到左眼/右眼。这可用于以左右或上下格式渲染立体内容，例如立体照片、3D 视频或其他动态渲染的界面。应用应使用 MediaPlayer 或 ExoPlayer 进行视频解码。
• 组件系统：SceneCore 提供了一个强大且灵活的组件系统，可为您的 XR 内容添加各种功能，包括让用户能够移动模型和面板、调整其大小以及与之互动。
• 锚定：启用透视功能后，您可以将面板和模型附加到实际表面，让用户在现实环境中无缝集成虚拟内容。
• 用户姿势：访问用户在虚拟场景中的位置，以便根据用户的位置调整内容的方向。
• SpatialCapabilities：构建完全自适应的应用，在可用时充分利用空间化功能，例如界面内容的 3D 定位。不仅如此，您的应用还可以在执行期间监控功能的变化，以便根据用户使用 Android XR 设备的方式修改体验。

已知问题

• 目前，使用 Jetpack SceneCore 需要 minSDK 为 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 设备支持创建会话。目前，如果您创建了 Session 并尝试在非 Android XR 设备上使用它，则会收到 RuntimeException。
• 通过 `SpatialEnvironment.setSpatialEnvironmentPreference()` 将天空盒设置为 null 不会像文档中所述那样产生纯黑色天空盒。这可能会导致系统默认天空盒或当前天空盒没有变化。
• SceneCore 客户端应将 implementation(“com.google.guava:listenablefuture-1.0”) 添加到其应用的 Gradle 配置中。在未来的版本中，scenecore 会将此库作为 api 依赖项包含在内，因此客户端无需明确声明它。
• SceneCore 错误地将 com.google.guava:guava-31.1-android 和 com.google.protobuf:protobuf-javalite 作为传递依赖项包含在内。如果这导致 build 中出现重复类错误，则可以安全地排除这两个依赖项。
• 如果您的应用使用 SceneCore 并启用了 ProGuard，则在您创建 Session 时，应用会崩溃。如需解决此问题，请停用 ProGuard。如需详细了解如何启用 ProGuard，请参阅此指南。