利用 Sceneform,您可以轻松地在 AR 和非 AR 应用中渲染逼真的 3D 场景,而无需学习 OpenGL。 它包括以下内容:
一个高级场景图 API
一个 Android Studio 插件,用于导入、查看和构建 3D asset
本页通过探究 Hello Sceneform 示例应用中的代码来说明关键概念。 注:
此示例使用 Sceneform 和 ARCore。
要在没有 ARCore 的情况下使用 Sceneform,请按照以下步骤操作,忽略 ARCore 依赖项和摄像头权限要求。 如构建场景中所述,在您的应用布局中使用
SceneView
。此示例应用编写为一个 AR 必备应用。
要详细了解 AR 可选与 AR 必备应用,请参阅启用 ARCore。
开始使用 Sceneform 和 ARCore
要在您的项目中使用 Sceneform 和 ARCore,您需要执行以下操作:
配置您项目的 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 运动跟踪指导)渲染场景图。 您的应用可以通过侦听触摸和手势事件、执行针对节点的命中测试以及放置锚点,与场景进行交互。 如需了解详细信息,请参阅构建场景并与之互动。