Sceneform 概览

利用 Sceneform，您可以轻松地在 AR 和非 AR 应用中渲染逼真的 3D 场景，而无需学习 OpenGL。它包括以下内容：

一个高级场景图 API
逼真的基于物理的渲染器，由 Filament 提供
一个 Android Studio 插件，用于导入、查看和构建 3D asset

本页通过探究 Hello Sceneform 示例应用中的代码来说明关键概念。注：

此示例使用 Sceneform 和 ARCore。

要在没有 ARCore 的情况下使用 Sceneform，请按照以下步骤操作，忽略 ARCore 依赖项和摄像头权限要求。如构建场景中所述，在您的应用布局中使用 SceneView 。
此示例应用编写为一个 AR 必备应用。

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

开始使用 Sceneform 和 ARCore

要在您的项目中使用 Sceneform 和 ARCore，您需要执行以下操作：

配置您项目的 build.gradle 文件
更新您的 AndroidManifest.xml
执行运行时检查并创建场景图
创建可渲染对象
构建场景

配置您项目的 `build.gradle` 文件

确保您项目的 build.gradle 包括 Google 的 Maven 代码库：
```
allprojects {
    repositories {
        google()
        …
```

更新您应用的 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.5.0'

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

    // Alternatively, use ArSceneView without the UX dependency.
    implementation 'com.google.ar.sceneform:core:1.5.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" />

<!-- Indicates that app requires ARCore ("AR Required"). Ensures app is only
     visible 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 Google
         Play Store to download and install ARCore 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 会话管理：

检查是否安装了兼容版本的 ARCore，根据需要提示用户进行安装或更新
检查应用是否有权访问摄像头，并在其尚未获得授权时请求用户提供权限

如果您的应用需要请求其他权限，或者希望自定义如何以及何时创建 AR 会话，您可以执行以下操作：

将 ArFragment 子类化以请求其他权限。
直接使用或扩展 ArSceneView。按照太阳系示例中演示的那样，您的应用必须执行 ARCore 版本检查并调用 setupSession() 来手动创建 ARCore 会话。

检查通过后，ArFragment 会创建：

一个 ArSceneView，可通过 getArSceneView() 访问，它会：
- 将会话中的摄像头图像渲染到其表面上
- 渲染内置 Sceneform 用户体验动画，它将为用户展示如何移动他们的手机来激活 AR 体验。
- 突出显示已检测到的使用默认 PlaneRenderer 的 Planes
一个 ARCore Session，可通过 getSession() 访问

要在您的应用中使用 ArFragment，请按照 HelloSceneform 示例中的 activity_ux.xml 演示的那样，将其添加到您的 Activity 的布局中：

<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 模型，可置于场景中的任何位置，由网格、材料和纹理组成。

可根据以下内容创建可渲染对象：

标准 Android ViewRenderable，在 3D 场景中被渲染为平面的 2D 卡片，同时可以通过触摸与它们交互。
3D asset 文件（OBJ、FBX、glTF），可以使用 Android Studio 插件将其导入、转换和预览。如需了解详细信息，请参阅导入和预览 3D Asset。
基本形状和材料，可通过编程方式结合，以便在运行时创建更复杂的物体。

示例应用根据一个 3D andy.obj asset 文件创建可渲染对象。导入此 asset 后，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 运动跟踪指导）渲染场景图。您的应用可以通过侦听触摸和手势事件、执行针对节点的命中测试以及放置锚点，与场景进行交互。如需了解详细信息，请参阅构建场景并与之互动。