2022-11-22-在sceneform中使用自定义材质

写在前面的话

Sceneform源于谷歌，现已存档。之后ThomasGorisse基于sceneform1.16之后维护过一段时间。现已停止更新。
本文档中的sceneform是基于谷歌存档的。自2020年6月起，一直在持续迭代中，相关描述可能与上述版本有变化，但官方文档依然可做重要参考。

借助 Sceneform，可以轻松地在 AR 应用和非 AR 应用中渲染逼真的 3D 场景，而无需学习 OpenGL。
Sceneform基于filament，了解filament有助于使用Scenefrom。

重要参考

以下链接非常重要，因此就写在文档最前面了。

filament材质说明点我跳转，官方的材质说明文档
filament材质说明点我跳转，中文文档，jerkwin译
filament编译流程点我跳转，官方文档，包含了多平台编译filament的流程。
sceneform自定义材质参考文档点我跳转，目录结构较为直观，但部分内容已过时。

使用流程

本部分内容介绍如何快速地通过matc工具去编译一个材质，并在sceneform中使用的流程

前提条件

matc.exe是材质编译工具，它通过编译filament可得到。也可直接拷贝他人已编译好的。

生成matc的过程见后文描述

matc工具

友情提示：

配置环境变量后更方便
matc工具的版本要与scenefrom的版本一致。

通过输入CMD命令查看
matc -v
若filament版本为1.12.x，则matc的版本为12
若filament版本为1.28.x，则matc的版本为28

编写材质

新建一个后缀为.mat的文件
输入如下内容，更多材质参考 filament材质说明点我跳转

material {
    "name" : "Material",

    "parameters" : [
        {
           "type" : "float4",
           "name" : "color"
        },
        {
            "type" : "float4",
            "name" : "emissive"
        }
    ],
    "requires" : [
        "position",
        "uv0"
    ],
    "shadingModel" : "lit",
    "blending" : "opaque",
    doubleSided : true
}
fragment {
    void material(inout MaterialInputs material) {
        prepareMaterial(material);
        material.baseColor = materialParams.color;
        material.emissive = materialParams.emissive;
    }
}

编译材质

sceneform和filament中加载自定义材质是filamat格式，在使用之前需要对mat文件进行编译。

使用matc工具编译材质

输入如下命令：

matc --optimize-size --platform=mobile -o eqmat.filamat eqmat.mat

注：此处只需要移动端材质，因此platform选择mobile即可，这样编译结果体积更小。

批量生成材质

创建一个bat文件，内容如下：

for /R %%G in (*.mat) do matc --optimize-size --platform=mobile -o "%%~nG.filamat" "%%G"

执行bat文件，即可根据同级目录中所有mat文件，批量生成filamat文件

bat文件

使用材质

源码参考

sceneform中有个工厂类MaterialFactory，在源码中搜索该类。参考它的makeOpaqueWithColor(Context,Color)等方法即可。

使用builder创建

在res/目录下创建raw路径，将编译好的材质文件（*.filamat）拷贝至该路径下。

文件路径

参考如下代码创建材质，得到mat对象后，使用mat对象去做后续诸如构建mesh等内容。

private Material mat;        
Material.builder().setSource(this, R.raw.mat_unlit_opaque_colored).build()
    .thenAccept(new Consumer<Material>() {
        @Override
        public void accept(Material material) {
            mat = material;
            //...
        }
    });

生成matc工具

按照 filament编译文档，通过编译filament即可得到完整的编译产物。

在out/release/filament/bin/路径下就包含了matc、cmgen、filamesh等工具（备注：默认根据文档操作，生成的路径是这样的，仅作参考）。

仅编译桌面工具的话，可参考如下流程。

编译环境

filament编译的官方描述

官方编译文档链接

编译前，先确认环境中配置了以下内容：

CMake 3.19 (or more recent)
clang 7.0 (or more recent)
ninja 1.10 (or more recent)

编译安卓aar，需要确认有以下环境：

Android Studio Arctic Fox or more recent
Android SDK
Android NDK 25.1 or higher

我的简易环境配置流程

安装AndroidStudio，安装SDK、NDK(编译filament1.28.x，使用的版本25.x，这里需要结合filament的版本来看，不同时期的会编译不过)
安装VS，勾选C++桌面开发

配置ninja

参考网友教程

配置python环境（我使用的3.7版本）
执行python安装ninja，得到ninja.exe
配置ninja.exe的环境变量

其实吧，若安装了AndroidStudio，安装了cmake，则在cmake\bin路径下，就有一个ninja.exe，使用cmake3.18之后版本的ninja，直接配置环境变量即可。

ninja.exe

编译桌面工具

此处仅描述在Windows上编译桌面工具（matc），用于sceneform自定义材质的需求。

详细编译流程，参考安卓编译文档，实现在Windows上编译安卓产物。

使用x64 Native Tools Command Prompt for VS 2019

**踩坑记录 **

不要使用cmd和gitbash，编译不过
早时期的filament在VS 2022的该工具下，编译不过。使用VS2019的即可。
使用管理员权限打开，可避掉一些坑

command tool

mkdir out\cmake-release
cd out\cmake-release
cmake ^
    -G Ninja ^
    -DCMAKE_INSTALL_PREFIX=..\release\filament ^
    -DFILAMENT_ENABLE_JAVA=NO ^
    -DCMAKE_BUILD_TYPE=Release ^
    ..\..

编译完成后，在out\camke-release\目录下，存在一个build.ninja文件

在在out\camke-release\目录下，执行如下命令

ninja matc resgen cmgen

也可执行命令

ninja install

编译结束后，在out/release/目录下生成相应的编译产物。

building

查看matc.exe工具

编译windows

使用x64 Native Tools Command Prompt for VS 2019 ，进入filament根目录，输入如下命令，待编译结束

> mkdir out/windows
> cd out/windows
> cmake ../..