Google Filament 项目构建指南：从环境配置到多平台编译

Google Filament 项目构建指南：从环境配置到多平台编译

filament Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WebGL2 项目地址: https://gitcode.com/gh_mirrors/filament/filament

前言

Google Filament 是一个功能强大的实时渲染引擎，专为移动设备和桌面平台设计。本文将全面介绍如何在不同平台上构建 Filament 项目，包括环境准备、构建选项配置以及常见问题的解决方案。

环境准备

基础工具要求

在开始构建 Filament 之前，需要确保系统已安装以下基础工具：

• CMake：3.19 或更高版本，用于项目配置和生成
• Clang：14.0 或更高版本，推荐使用 LLVM 工具链
• Ninja：1.10 或更高版本，作为构建系统

平台特定依赖

Linux 系统

在基于 Debian/Ubuntu 的系统上，需要安装以下开发包：

sudo apt install clang-14 libglu1-mesa-dev libc++-14-dev \
     libc++abi-14-dev ninja-build libxi-dev \
     libxcomposite-dev libxxf86vm-dev -y

macOS 系统

在 macOS 上需要：

1. 最新版本的 Xcode
2. 命令行工具（通过 xcode-select --install 安装）
3. 如需使用 Vulkan 后端而非默认的 Metal，需安装 LunarG SDK

Windows 系统

Windows 平台需要：

• Visual Studio 2019 或更高版本
• Windows SDK
• Python 3.7
• CMake 3.14 或更高版本

构建流程

简易构建脚本

Filament 提供了 build.sh 脚本来简化构建过程：

# 调试版本构建
./build.sh debug

# 发布版本构建
./build.sh release

# 同时构建调试和发布版本
./build.sh debug release

脚本选项说明：

• -c：强制清理构建目录
• -i：安装构建产物
• -h：显示帮助信息

手动构建流程

对于需要更多控制的开发者，可以手动使用 CMake 和 Ninja：

1. 创建构建目录并配置项目：

mkdir out/cmake-release
cd out/cmake-release
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=../release/filament ../..

2. 执行构建：

ninja

重要 CMake 选项

Filament 提供了一些特有的构建选项：

| 选项名称 | 描述 | 默认值 | |---------|------|-------| | FILAMENT_ENABLE_LTO | 启用链接时优化 | OFF | | FILAMENT_SUPPORTS_OPENGL | 包含 OpenGL 后端 | ON | | FILAMENT_SUPPORTS_METAL | 包含 Metal 后端 (macOS/iOS) | ON | | FILAMENT_SUPPORTS_VULKAN | 包含 Vulkan 后端 | ON | | FILAMENT_SKIP_SAMPLES | 跳过示例程序构建 | OFF |

可通过以下方式修改选项：

cmake . -DFILAMENT_SUPPORTS_OPENGL=OFF

多平台构建指南

Android 平台构建

环境准备

• Android Studio Flamingo 或更高版本
• Android SDK 和 NDK (25.1+)
• Java 17
• 设置 ANDROID_HOME 环境变量

构建命令

# 简易构建
./build.sh -p android release

# 手动构建 (ARM64)
mkdir out/android-build-release-aarch64
cd out/android-build-release-aarch64
cmake -G Ninja \
      -DCMAKE_TOOLCHAIN_FILE=../../build/toolchain-aarch64-linux-android.cmake \
      -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=../android-release/filament ../..
ninja install

AAR 包生成

构建完成后，可在 Android Studio 项目中生成 AAR 包：

./gradlew -Pcom.google.android.filament.dist-dir=../../out/android-release/filament assembleRelease

iOS 平台构建

使用简易构建脚本：

./build.sh -p ios debug

WebAssembly 构建

1. 安装 Emscripten SDK：

source ./emsdk_env.sh

2. 执行构建：

export EMSDK=/path/to/emsdk
./build.sh -p webgl release

3. 运行本地服务器测试：

emrun out/cmake-webgl-release/web/samples --no_browser --port 8000

示例程序运行

Filament 提供了多个示例程序，位于 samples/ 目录下。运行前需要准备资源：

1. 转换模型格式：

./tools/filamesh/filamesh ./assets/models/monkey/monkey.obj monkey.filamesh

2. 生成 IBL 环境贴图：

./tools/filamesh/cmgen -f ktx -x ./ibls/ my_ibl.exr

软件渲染方案

对于没有 GPU 硬件的环境，Filament 支持以下软件渲染方案：

SwiftShader (Vulkan)

1. 构建 SwiftShader
2. 设置 Vulkan 驱动路径：

export VK_ICD_FILENAMES=/path/to/vk_swiftshader_icd.json

Mesa LLVMPipe (GL) 和 Lavapipe (Vulkan)

1. 构建 Mesa 软件渲染器
2. 设置库路径：

# 对于 OpenGL
LD_LIBRARY_PATH=/path/to/mesa/lib ./gltf_viewer -a opengl

# 对于 Vulkan
VK_ICD_FILENAMES=/path/to/lvp_icd.json ./gltf_viewer -a vulkan

文档生成

要生成 C++ API 文档：

doxygen docs/doxygen/filament.doxygen

生成的文档位于 docs/html/index.html。

结语

本文详细介绍了 Google Filament 项目在不同平台上的构建方法。通过合理的配置选项，开发者可以根据目标平台选择最适合的渲染后端和构建参数。无论是移动设备、桌面应用还是 Web 环境，Filament 都提供了完善的构建支持。

filament Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WebGL2 项目地址: https://gitcode.com/gh_mirrors/filament/filament