{ } { }

Jetpack SceneCore

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

声明依赖项

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

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

Groovy

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha01"
    // 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-alpha01"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha01")
    // 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-alpha01")
}

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

反馈

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

创建新问题

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

版本 1.0

版本 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-android 和 com.google.protobuf:protobuf-javalite 包含为传递依赖项。如果这导致 build 中出现重复的类错误，则可以放心地排除这两个依赖项。
  • 如果您的应用使用 SceneCore 并启用 ProGuard，则会在您创建会话时崩溃。如需解决此问题，请停用 ProGuard。如需详细了解如何启用 ProGuard，请参阅此指南。