Jetpack SceneCore

Jetpack SceneCore

用户指南  代码示例

API 参考文档
androidx.xr.scenecore
androidx.xr.scenecore.testing

使用 3D 内容构建和操纵 Android XR 场景图。

最近更新时间	稳定版	候选版	Beta 版	Alpha 版
2025 年 10 月 22 日	-	-	-	1.0.0-alpha08

声明依赖项

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

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

Groovy

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha08"

    // Optional dependencies for asynchronous conversions
    implementation "androidx.xr.scenecore:scenecore-guava:1.0.0-alpha08"

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

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha08")

    // Optional dependencies for asynchronous conversions
    implementation("androidx.xr.scenecore:scenecore-guava:1.0.0-alpha08")

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

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

反馈

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

创建新问题

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

1.0 版

版本 1.0.0-alpha08

2025 年 10 月 22 日

发布了 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）
• 场景的 SpatialModeChangeListener 变量已替换为 setSpatialModeChangedListener。它接受 Consumer<SpatialModeChangeEvent> 而不是 SpatialModeChangedListener。setSpatialModeChangedListener 现在可以选择性地接受执行器。（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 类型，而不是实体。(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 属性。它会返回一个建议的框，用于在 Full Space 模式下放置内容。(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)
• 在实体中：将以下内容更改为属性：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 方法更改为挂起函数；修改了创建参数以接受 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)
• 在创建方法中，将 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，EntityMoveListener shouldDisposeParentAnchor 已重命名为 disposeParentOnReAnchor systemMovable，disposeParentOnReAnchor systemMovable 已从 create 函数中移除，取而代之的是 creeateCustomMovable、createSystemMovable 和 createAnchorable (If11c4)
• 移除了 SurfaceEntity.featherRadiusX/Y 并添加了 EdgeFeatheringParams 类概念。(Ic78fc)
• PanelEntity.enablePanelDepthTest() 方法已替换为 panelClippingConfig 属性。将 Scene.panelClippingConfig = PanelClippingConfig(isDepthTestEnabled = true) 设置为 1 可启用深度测试，设置为 0 可停用深度测试。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 类已替换为具有常量整数值的公共对象。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)
• 将 minSDK 减少到 24（适用于 androidx.xr.scenecore 和 androidx.xr.compose）。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：如果 InputEvent 的 HitInfo 上的 hitPosition 可能导致崩溃，则从系统返回的 hitPosition 为 null 时可能会发生崩溃 (I7a695)InteractableComponent
• 配置 *Mode 值已重命名，以反映其行为。(I6d247)
• 修复了 SceneCore TestApp 中 FOV 和 HitTest 存在的问题。(I2c51e)
• 修复了 SpatialCapabilities.hasCapability() 中的 bug，该 bug 会在通过按位或传递的任何功能为 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 中包含这些提交内容。

注意： 您需要使用 Android 模拟器 35.6.7 版或更高版本才能使用此版本的库。

新功能

• 现在，返回处理功能将适用于没有嵌入 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 的引用。场景将作为会话的扩展属性进行访问。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 中的会话类已被删除，取而代之的是 XR 运行时的会话。
• 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通话中更新

破坏性变更和行为变更

• 如果面板的宽度或高度小于 32dp，PanelEntity 和 ActivityPanelEntity 的默认圆角半径将为 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 嵌入到可浮动或锚定到现实世界表面的空间化面板中，将 2D 内容添加到 3D 场景中。
• 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"/>，以便能够使用 23 的 minSDK 进行构建和运行。
• 在各种会自动重新创建 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-android 和 com.google.protobuf:protobuf-javalite 作为传递依赖项包含在内。如果这导致 build 中出现重复的类错误，则可以放心地排除这两个依赖项。
• 如果您的应用使用 SceneCore 并启用 ProGuard，则在创建会话时会发生崩溃。如需解决此问题，请停用 ProGuard。如需详细了解如何启用 ProGuard，请参阅本指南。