Sceneform 概览

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

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

  • 此示例使用 Sceneform 和 ARCore。

    要在没有 ARCore 的情况下使用 Sceneform,请按照以下步骤操作,忽略 ARCore 依赖项和摄像头权限要求。 如构建场景中所述,在您的应用布局中使用 SceneView

  • 此示例应用编写为一个 AR 必备应用。

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

开始使用 Sceneform 和 ARCore

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

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

配置您项目的 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.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 会话管理:

  1. 检查是否安装了兼容版本的 ARCore,根据需要提示用户进行安装或更新

  2. 检查应用是否有权访问摄像头,并在其尚未获得授权时请求用户提供权限

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

  • ArFragment 子类化以请求其他权限。

  • 直接使用或扩展 ArSceneView。 按照太阳系示例中演示的那样,您的应用必须执行 ARCore 版本检查并调用 setupSession() 来手动创建 ARCore 会话。

检查通过后,ArFragment 会创建:

  1. 一个 ArSceneView,可通过 getArSceneView() 访问,它会:

    • 将会话中的摄像头图像渲染到其表面上

    • 渲染内置 Sceneform 用户体验动画,它将为用户展示如何移动他们的手机来激活 AR 体验。

    • 突出显示已检测到的使用默认 PlaneRendererPlanes

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

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

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