Sceneform 使用入门

本页通过探索 Hello Sceneform 示例应用中的代码来解释关键概念。注意：

  • 此示例使用 Sceneform 和 ARCore。

    如需在不使用 ARCore 的情况下使用 Sceneform，请按以下步骤操作，同时忽略 ARCore 依赖项和摄像头权限要求。按照构建场景中的说明，在应用的布局中使用 SceneView。

  • 此示例应用采用 AR 必备应用编写。

    如需详细了解 AR 可选应用与 AR 必备应用，请参阅启用 ARCore。

如需开始在项目中使用 Sceneform，您需要：

  1. 导入 Sceneform 插件
  2. 配置项目的 build.gradle 文件
  3. 更新 AndroidManifest.xml
  4. 执行运行时检查并创建场景视图
  5. 创建可渲染对象
  6. 构建场景

将 Sceneform 插件导入项目中

安装 Sceneform 插件后，您可以使用 Sceneform SDK 在 Android Studio 中为 AR 应用导入、查看和构建 3D 资源。它需要 Android Studio 3.1 及更高版本。

要安装该插件，请运行以下命令：

  1. 在 Android Studio 中，打开 Plugins 设置：

    • Windows：文件 &gt；设置 &gt；插件 &gt；浏览代码库

    • macOS：Android Studio > Preferences > Plugins

  2. 点击浏览代码库，然后安装 Google Sceneform Tools (Beta)。

配置项目的 build.gradle 文件

  1. 确保您的项目 build.gradle 包含 Google 的 Maven 代码库：

    allprojects {
    repositories {
        google()
        …

  2. 更新应用的 build.gradle 以添加最新的 ARCore 和 Sceneform 用户体验依赖项，并确保您的项目设置与这两个库兼容。

    android {
    …
    defaultConfig {
        // Sceneform requires minSdkVersion >= 24.
        minSdkVersion 24
        …
    }
    // Sceneform libraries use language constructs from Java 8.
    // Add these compile options if targeting minSdkVersion < 26.
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    …
    // Provides ARCore Session and related resources.
    implementation 'com.google.ar:core:1.15.0'

    // Provides ArFragment, and other UX resources.
    implementation 'com.google.ar.sceneform.ux:sceneform-ux:1.15.0'

    // Alternatively, use ArSceneView without the UX dependency.
    implementation 'com.google.ar.sceneform:core:1.15.0'
}

更新您的AndroidManifest.xml

修改 AndroidManifest.xml 以表明您的应用使用（AR 可选）或需要（AR 必备）ARCore 和摄像头访问权限：

<!-- Both "AR Optional" and "AR Required" apps require CAMERA permission. -->
<uses-permission android:name="android.permission.CAMERA" />

<!-- Sceneform requires OpenGL ES 3.0 or later. -->
<uses-feature android:glEsVersion="0x00030000" android:required="true" />

<!-- Indicates that app requires ARCore ("AR Required"). Ensures the app is
     visible only in the Google Play Store on devices that support ARCore.
     For "AR Optional" apps remove this line. -->
<uses-feature android:name="android.hardware.camera.ar" />

<application>
    …
    <!-- Indicates that app requires ARCore ("AR Required"). Causes the Google
         Play Store to download and install Google Play Services for AR along
         with the app. For an "AR Optional" app, specify "optional" instead of
         "required".
    -->
    <meta-data android:name="com.google.ar.core" android:value="required" />
</application>

执行运行时检查并创建场景视图

如需开始使用 Sceneform 和创建场景视图，最简单的方法是使用 ArFragment，它会在执行必要的 ARCore 运行时检查后自动处理 ARCore 会话管理：

  1. 检查是否安装了兼容版本的 Google Play Services for AR，必要时提示用户安装或更新

  2. 检查应用是否有权访问相机，并在应用尚未获得授权时请求用户权限

如果您的应用需要请求其他权限，或者想要自定义创建 AR 会话的方式和时间，您可以改为执行以下操作：

  • 创建 ArFragment 的子类以请求其他权限。

  • 直接使用或扩展 ArSceneView。您的应用必须执行 ARCore 版本检查并调用 setupSession() 来手动创建 ARCore 现场录像，如太阳系统示例所示。

检查通过后，ArFragment 会创建：

  1. 可通过 getArSceneView() 访问的 ArSceneView：

    • 将会话中的相机图像渲染到其表面上

    • 呈现内置 Sceneform 用户体验动画，向用户展示应如何移动手机以激活 AR 体验。

    • 使用默认的 PlaneRenderer Planes 检测到突出显示内容

  2. ARCore Session，可通过 getSession() 访问

如需在应用中使用 ArFragment，请将其添加到 Activity 的布局中，如 Hello Sceneform 示例中的 activity_ux.xml 所示：

<fragment android:name="com.google.ar.sceneform.ux.ArFragment"
    android:id="@+id/ux_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

创建可渲染对象

Renderable 是一种 3D 模型，可放置在场景中的任何位置，由网格、材料和纹理组成。

可渲染对象可以通过以下代码创建：

示例应用会根据 3D andy.obj 资源文件创建可渲染对象。导入此素材资源后，Sceneform 插件会更新应用 build.gradle 以应用该插件，并为导入的模型添加 sceneform.asset() 条目：

apply plugin: 'com.google.ar.sceneform.plugin'

sceneform.asset('sampledata/models/andy.obj', // 'Source Asset Path' specified during import.
                'default',                    // 'Material Path' specified during import.
                'sampledata/models/andy.sfa', // '.sfa Output Path' specified during import.
                'src/main/res/raw/andy')      // '.sfb Output Path' specified during import.

res/raw/andy 资源用于创建 ModelRenderable：

private ModelRenderable andyRenderable;

@Override
protected void onCreate(Bundle savedInstanceState) {
    …

    ModelRenderable.builder()
        .setSource(this, R.raw.andy)
        .build()
        .thenAccept(renderable -> andyRenderable = renderable)
        .exceptionally(
            throwable -> {
            Log.e(TAG, "Unable to load Renderable.", throwable);
            return null;
        });
}

打造场景

ARSceneView 已附加 Scene。场景是一种树状数据结构，其中包含要呈现的虚拟对象的 Node。

这里，andy 可渲染对象直接附加到根场景节点：

Node node = new Node();
node.setParent(arFragment.getArSceneView().getScene());
node.setRenderable(andyRenderable);

每个节点都包含 Sceneform 对其进行渲染（包括其位置、屏幕方向和可渲染对象）以及与其进行交互所需的所有信息（包括其冲突形状和事件监听器）。

可以将节点添加到其他节点，以形成父子关系。如果某个节点是另一个节点的子级，则该节点会随着其父级而移动、旋转和缩放，就像在身体移动时手臂会如何移动。一个节点可以有多个子级，但只能有一个父级，从而形成一种树状结构。这种结构称为场景图。

每一帧，Sceneform 都会从相机的视角（由 ARCore 运动跟踪指导）渲染场景图。您的应用可以通过监听触摸和手势事件、针对节点执行命中测试以及放置锚点来与场景互动。如需了解详情，请参阅构建场景并与之互动。