Google Filament 源码学习（六）：Material System (五) - 材质系统框架

Introduction

   本节是 Filament 材质框架阅读的部分。之前的小节由于有官方文档，因此，笔记不会存在明显的错误。但在本节之后，都是自己对Filament的理解，可能在理解和总结上有严重的错误。因此，需要经常回来调整内容。

Filament 工程简化

   从 GitHub 克隆下来的工程包含很多官方的示例。看起来比较臃肿。个人认为学习某个开源项目第一步是把该项目的核心内容分离出来。

删除 Filament 工程中非核心内容

• 注意
  • 本节包含的，包括以后对 Filament 框架的调整只适用于Window系统，其他系统处理方式大部分相同，只是某些平台相关的部分处理不同。

根目录保留

1. build
2. filament
3. libs
4. shaders
5. third_party
6. tools
7. CMakeLists.txt

build文件夹中保留

1. windows
2. licenses.inc.in

filament文件夹中保留

1. backend
2. include
3. src
4. CMakeLists.txt

libs文件夹中保留

1. bluegl/bluevk
2. filamat 
3. filameshio 
4. filabridge 
5. filaflat 
6. geometry
7. ibl 
8. imageio 
9. image 
10. math  
11. utils 

third_party文件夹中保留

1. astcenc 
2. etc2comp
3. getopt 
4. glslang
5. libpng  
6. libz
7. libassimp
8. meshoptimizer
9. robin-map
10. spirv-cross 
11. spirv-tools 
12. smol-v
13. stb 
14. tinyexr    
15. vkmemalloc

tools文件夹中保留

1. cmgen
2. filamesh 
3. glslminifier
4. matc 
5. mipgen 
6. resgen 

关于CmakeList中的修改

• Cmake 我也只是懂些基础而已，对编写构建脚本不熟，所以修改也是缝缝补补，不严谨 !

根目录下CmakeList 修改

• 删除（可搜索关键字 “IS_HOST_PLATFORM” ）

  	  add_subdirectory(${FILAMENT}/java/filamat)
        add_subdirectory(${FILAMENT}/java/filament)
        add_subdirectory(${FILAMENT}/java/gltfio)
  

• IS_HOST_PLATFORM 保留以下内容，其余都删除

  	1.  add_subdirectory(${LIBRARIES}/bluegl)
  	2.  add_subdirectory(${LIBRARIES}/imageio)
  	3.  add_subdirectory(${EXTERNAL}/astcenc/tnt)
  	4.  add_subdirectory(${EXTERNAL}/etc2comp) 
  	5.  add_subdirectory(${EXTERNAL}/libassimp/tnt)
  	6.  add_subdirectory(${EXTERNAL}/libpng/tnt)
  	7.  add_subdirectory(${EXTERNAL}/libz/tnt)
  	8.  add_subdirectory(${EXTERNAL}/tinyexr/tnt)
  	9.  add_subdirectory(${TOOLS}/cmgen)
  	10. add_subdirectory(${TOOLS}/filamesh)
  	11. add_subdirectory(${TOOLS}/glslminifier)  
  	12. add_subdirectory(${TOOLS}/matc)
  	13. add_subdirectory(${TOOLS}/mipgen)
  	14. add_subdirectory(${TOOLS}/resgen)
  

• Common to all platforms 以下内容，其余都删除

  	1.  add_subdirectory(${LIBRARIES}/filabridge)
  	2.  add_subdirectory(${LIBRARIES}/filaflat)
  	3.  add_subdirectory(${LIBRARIES}/filameshio)
  	4.  add_subdirectory(${LIBRARIES}/geometry)
  	5.  add_subdirectory(${LIBRARIES}/ibl)
  	6.  add_subdirectory(${LIBRARIES}/image)
  	7.  add_subdirectory(${LIBRARIES}/math)
  	8.  add_subdirectory(${LIBRARIES}/utils)
  	9.  add_subdirectory(${FILAMENT}/filament)
  	10. add_subdirectory(${FILAMENT}/shaders) 
  	11. add_subdirectory(${EXTERNAL}/robin-map/tnt)
  	12. add_subdirectory(${EXTERNAL}/smol-v/tnt)
  	13. add_subdirectory(${EXTERNAL}/meshoptimizer)
  	14. add_subdirectory(${EXTERNAL}/stb/tnt)
  	15. add_subdirectory(${EXTERNAL}/getopt)
  

• FILAMENT_BUILD_FILAMAT 删除 the material debugger

删除所有保留库的test文件

• 经过上述处理之后，保留下来的代码中还是有很多测试用到的代码，需要删除。内容有

  1. CmakeList中标识test的代码
  2. filament CmakeList 中 add_subdirectory(test) 和 add_subdirectory(benchmark) 保留backend
  3. libs/math 中 benchmarks 包括CmakeList中信息
  4. libs/utils中 benchmarks 包括CmakeList中信息
  5. third_party 暂时不清理
  

小结

   经过上述处理，再重新编译工程即可。如果编译过程中遇到错误，根据提示修改即可。（反正我自己已经验证过N次了，应该没问题#109）

材质框架分离

   可能是跟自己的性格相关。拿到一个不熟悉的项目代码，第一件事就是拆！

Compiling materials

   首先要了解材质编译的方式（先学会用再拆分）

• 资料来源于官方文档：https://github.com/google/filament/tree/main/docs/Materials.html

Compiling

• 材质包 (Material packages) 是根据我们定义的 *.mat 文件和 Filament 根目录中 shaders/src 文件夹里 GLSL 相关文本使用 matc.exe 组装成的。材质包是后缀为.filamat的文件
• 使用命令行生成材质包示例如下
  • $ matc -o ./materials/bin/car_paint.filamat ./materials/src/car_paint.mat

Shader validation

• matc 在编译材质包的时候会对 shaders 的验证。编译错误会在命令行中进行提示。

Flags

• -o, --output
  • Value
    • [path]
  • Usage
    • 输出文件的路径
• -p,–platform
  • Value
    • desktop/mobile/all
  • Usage
    • 指定输出 platform
• -a,–api
  • Value
    • opengl/vulkan/all
  • Usage
    • 指定目标图形API
• -S, --optimize-size
  • Value
    • N/A
  • Usage
    • 在优化性能的同时，优化编译材质的大小
• -r, --reflect
  • Value
    • parameters
  • Usage
    • 将指定的元数据以JSON格式输出
• -v, --variant-filter
  • Value
    • [variant]
  • Usage
    • 筛选出指定的逗号分分隔的 variant
• matc 提供了一些与应用程序开发人员无关且仅供内部使用的其他 flags

Filament 材质包的编译

matc

• 材质包是在我们编译工程时，利用Cmake进行编译的。脚本在根目录下的filament文件夹中 CMakeLists.txt 文件中。
  • 250行开始为编译材质包的代码，如下

    //MATERIAL_SRCS为mat的相对路径 (src/materials/fsr/fsr_easu.mat)
    //MATERIAL_DIR为输出的路径
    //MATC_BASE_FLAGS为ROOT/CMakeLists.txt中的内容, 搜索Material compilation flags
    //命令实例（windows opengl） -a opengl -p desktop -gd
    foreach (mat_src ${MATERIAL_SRCS})
    	//获取文件名
        get_filename_component(localname "${mat_src}" NAME_WE)
        //获取文件的绝对路径
        get_filename_component(fullname "${mat_src}" ABSOLUTE)
        set(output_path "${MATERIAL_DIR}/${localname}.filamat")
    	//执行mat->filamat打包
        add_custom_command(
                OUTPUT ${output_path}
                COMMAND matc ${MATC_BASE_FLAGS} -o ${output_path} ${fullname}
                MAIN_DEPENDENCY ${fullname}
                DEPENDS matc
                COMMENT "Compiling material ${mat_src} to ${output_path}"
        )
        list(APPEND MATERIAL_BINS ${output_path})
    endforeach()
    mmhard
    

• 测试
  • 可以尝试使用命令行编译材质包
  • matc.exe路径
    • E:\FDMPlayer_Test\clear_filament\soar_vk\tools\matc\Release
  • mat文件路径
    • E:\FDMPlayer_Test\clear_filament\filament\src\materials
  • 命令
    • matc.exe -a opengl -p desktop -gd -o test.filamat F:\vsmMipmap.mat

resgen

• 生成 Filament 使用的 .h 和 .c 文件是使用 resgen.exe。这部分教程没有详细说明，这里简单总结一下
• resgen.exe 路径
  • E:\FDMPlayer_Test\clear_filament\soar_vk\tools\resgen\Release
  • 参数在根目录下CMakeLists.txt文件内 # Common Functions 中
• 使用命令
  • resgen.exe -qcx -p test F:\test.filamat
• resgen 的作用是将材质包转化成十六进制的字符数组，程序可以直接读取这些字符来编译shader。

Matc 工程分离

• 分离成 “Matc 代码 + lib” 形式
• 工程结构
  • include : Filament 内部库头文件文件夹
  • lib：Filament 内部库lib文件夹
  • matc: matc 源代码文件夹
  • main.h：主函数
  • 3rd： Filament使用的第三方库文件夹
    • include：第三方库有文件
    • lib： 第三方库lib
• 首先编译好简化后的Filament工程生成相关库的lib文件
• 工程配置 （IDE VS2022）（Release 版本）
  • 第三方库引入
    • getopt
      • 头文件
        • G:\clear_filament\third_party\getopt\include
          • getopt文件夹复制到
          • 3rd/include 中
      • lib
        • G:\clear_filament\soar\third_party\getopt\Release
          • getopt.lib复制到
          • 3rd/lib 中
    • glslang
      • 头文件
        • G:\clear_filament\third_party\
          • glslang文件夹复制到
          • 3rd/include/中
      • lib
        • G:\clear_filament\soar\third_party\glslang\tnt\glslang\Release
          • glslang.lib复制到
          • 3rd/lib 中
        • G:\clear_filament\soar\third_party\glslang\tnt\glslang\OSDependent\Windows\Release
          • OSDependent.lib复制到
          • 3rd/lib 中
        • G:\clear_filament\soar\third_party\glslang\tnt\OGLCompilersDLL\Release
          • OGLCompiler.lib复制到
          • 3rd/lib 中
        • G:\clear_filament\soar\third_party\glslang\tnt\SPIRV\Release
          • SPIRV.lib 和 SPVRemapper.lib复制到
          • 3rd/lib 中
    • robin-map
      • 头文件
        • G:\clear_filament\third_party\robin-map
          • robin-map文件夹复制到
          • 3rd/include 中
    • smol-v
      • 头文件
        • G:\clear_filament\third_party\smol-v\source
          • smolv.h 复制到
          • 3rd/include 中
      • lib
        • G:\clear_filament\soar\third_party\smol-v\tnt\Release
          • smol-v.lib 复制到
          • 3rd/lib 中
    • spirv-cross
      • 头文件
        • G:\clear_filament\third_party\spirv-cross\include
          • spirv_cross文件夹复制到
          • 3rd/include 中
      • lib
        • G:\clear_filament\soar\third_party\spirv-cross\tnt\Release
          • spirv-cross-core.lib、spirv-cross-glsl.lib、spirv-cross-msl.lib复制到
          • 3rd/lib 中
    • spirv-tools
      • 头文件
        • G:\clear_filament\third_party\spirv-tools\include
          • spirv-tools文件夹复制到
          • 3rd/include 中
      • lib
        • G:\clear_filament\soar\third_party\spirv-tools\source\Release
          • SPIRV-Tools.lib 复制到
          • 3rd/lib 中
        • E:\filament\soar_vk\third_party\spirv-tools\source\opt\Release
          • SPIRV-Tools-opt.lib 复制到
          • 3rd/lib 中
  • 内部库引用

    • filamat

      • 头文件
        • G:\clear_filament\libs\filamat\include
          • filamat文件夹复制到
          • include 中
      • lib
        • G:\clear_filament\soar\libs\filamat\Release
          • filamat.lib 复制到
          • lib 中

    • utils

      • 头文件
        • G:\clear_filament\libs\utils\include
          • utils文件夹复制到
          • include 中
      • lib
        • G:\clear_filament\soar\libs\utils\Release
          • utils.lib 复制到
          • lib 中

    • filabridge

      • 头文件
        • G:\clear_filament\libs\filabridge\include
          • filament 和 private 文件夹复制到
          • include 中
      • lib
        • G:\clear_filament\soar\libs\filabridge\Release
          • filabridge.lib 复制到
          • lib 中

    • shaders

      • 头文件
        • G:\clear_filament\soar\shaders\generated
          • shaders.h复制到
          • include 中
      • lib
        • G:\clear_filament\soar\shaders\Release
          • shaders.lib 复制到
          • lib 中

    • filament

      • 头文件
        • G:\clear_filament\filament\backend\include
          • backend 和 private 文件夹复制到
          • include 中

    • math

      • 头文件
        • G:\clear_filament\libs\math\include
          • math 文件夹复制到
          • include 中

    • sca

      • 头文件
        • E:\filament\libs\filamat\src\sca
          • builtinResource.h 复制到
          • include/sca 中

    • licenses

      • 头文件
        • E:\filament\soar_vk\tools\matc\generated\licenses
          • licenses.inc 复制到
          • include/licenses 中
  • Matc 代码引入
    • G:\clear_filament\tools\matc\src
    • matc 和 main.h复制到工程根目录
  • VS配置

    • lib

      filamat.lib
      getopt.lib
      utils.lib
      filabridge.lib
      smol-v.lib
      SPIRV.lib
      glslang.lib
      shaders.lib
      OSDependent.lib
      Shlwapi.lib
      spirv-cross-core.lib
      spirv-cross-glsl.lib
      spirv-cross-msl.lib
      SPIRV-Tools-opt.lib
      SPVRemapper.lib
      OGLCompiler.lib
      SPIRV-Tools.lib 
      

    • 附加包含目录

      • E:\matc_project\demo\include
      • E:\matc_project\demo\3rd\include
      • E:\matc_project\demo\3rd\include\glslang
      • E:\matc_project\demo\3rd\include\glslang\glslang\Include
      • E:\matc_project\demo\3rd\include\glslang\SPIRV
      • E:\matc_project\demo\3rd\include\glslang\glslang\Public
      • E:\matc_project\demo\3rd\include\glslang\glslang\MachineIndependent
      • E:\matc_project\demo\3rd\include\robin-map

    • VS C++语言标准：预览 - 最新 C++ 工作草案中的功能 (/std:c++latest)

    • SDL检查：否

    • 宏：WIN32

    • 运行库：多线程 (/MT)

Resgen 工程分离

• 分离成 “Resgen 代码 + lib” 形式
  • resgen 比较简单，只依赖于第三方库 getopt 和 内部库 utils
• 工程结构
  • include : Filament 内部库头文件文件夹
  • lib：Filament 内部库lib文件夹
  • resgen: resgen 源代码文件夹
  • 3rd： Filament使用的第三方库文件夹
    • include：第三方库有文件
    • lib： 第三方库lib
• 工程配置 （IDE VS2022）（Release 版本）
  • 第三方库引入
    • getopt
      • 头文件
        • G:\clear_filament\third_party\getopt\include
          • getopt文件夹复制到
          • 3rd/include 中
      • lib
        • G:\clear_filament\soar\third_party\getopt\Release
          • getopt.lib复制到
          • 3rd/lib 中
  • 内部库引用
    • utils
      • 头文件
        • G:\clear_filament\libs\utils\include
          • utils文件夹复制到
          • include 中
      • lib
        • G:\clear_filament\soar\libs\utils\Release
          • utils.lib 复制到
          • lib 中
  • resgen 代码引入
    • G:\clear_filament\tools\resgen\src
    • main.h复制到工程根目录
  • VS配置
    • lib

      	getopt.lib
      	utils.lib
      	shlwapi.lib
      

    • 附加包含目录
      • E:\matc_project\demo\include
      • E:\matc_project\demo\3rd\include
    • 运行库：多线程 (/MT)

总结

   Material System 这部分先总结到这里。应该说已经把 Filament 如何使用材质和管理 shader 代码片元部分都做了总结。如何使用由材质包生成的shader代码在之后总结Filament框架时再研究。