Filament

Filament 是一个为 Android、iOS、Linux、macOS、Windows 和 WebGL 设计的实时基于物理的渲染引擎。它旨在尽可能小巧，并在 Android 上尽可能高效。

下载

下载 Filament 发布版以获取稳定构建。Filament 发布归档包含生成资产所需的主机端工具。

请确保始终使用与运行时库相同版本的工具。这对于 matc（材质编译器）尤其重要。

如果您更愿意自行构建 Filament，请参阅我们的构建手册。

Android

Android 项目可以简单地将 Filament 库声明为 Maven 依赖项：

repositories {
    // ...
    mavenCentral()
}

dependencies {
    implementation 'com.google.android.filament:filament-android:1.53.5'
}

以下是 com.google.android.filament 组中可用的所有库：

构件	描述
	Filament 渲染引擎本身。
	`filament-android` 的调试版本。
	Filament 的 glTF 2.0 加载器，依赖于 `filament-android`。
	KTX 加载、Kotlin 数学和相机实用工具，依赖于 `gltfio-android`。
	运行时材质构建器/编译器。这个库体积较大，但包含完整的着色器编译器/验证器/优化器，并支持 OpenGL 和 Vulkan。
	`filamat-android` 的一个更小的替代品，只能生成 OpenGL 着色器。它不提供验证或优化功能。

iOS

iOS 项目可以使用 CocoaPods 安装最新版本：

pod 'Filament', '~> 1.53.5'

快照版本

如果您喜欢尝鲜，可以按照以下步骤下载持续构建版本：

找到您感兴趣的提交。
点击提交信息下方的绿色对勾。
点击您感兴趣的平台的"详情"链接。
在左上角点击"摘要"，然后在"构件"部分选择所需的构件。

文档

Filament，深入解释了实时基于物理的渲染、Filament 的图形功能和实现。这份文档解释了我们大多数决策背后的数学原理和推理。对于图形程序员来说，这是一个很好的 PBR 入门文档。
材质，我们材质系统的完整参考文档。这份文档解释了我们不同的材质模型、如何使用材质编译器 matc 以及如何编写自定义材质。
材质属性，标准材质模型的参考表。

示例

屏幕空间折射

特性

API

适用于 Android、iOS、Linux、macOS 和 Windows 的原生 C++ API
适用于 Android 的 Java/JNI API
JavaScript API

后端

适用于 Linux、macOS 和 Windows 的 OpenGL 4.1+
适用于 Android 和 iOS 的 OpenGL ES 3.0+
适用于 macOS 和 iOS 的 Metal
适用于 Android、Linux、macOS 和 Windows 的 Vulkan 1.0
适用于所有平台的 WebGL 2.0

渲染

聚类前向渲染器
Cook-Torrance 微表面镜面 BRDF
Lambertian 漫反射 BRDF
自定义光照/表面着色
HDR/线性光照
金属工作流程
清漆涂层
各向异性光照
近似半透明（次表面）材质
布料/织物/光泽着色
法线贴图和环境遮蔽贴图
基于图像的光照
基于物理的相机（快门速度、感光度和光圈）
物理光照单位
点光源、聚光灯和方向光
镜面抗锯齿
点光源、聚光灯和方向光阴影
级联阴影
EVSM、PCSS、DPCF 或 PCF 阴影
透明阴影
接触阴影
屏幕空间环境遮蔽
屏幕空间反射
屏幕空间折射
全局雾效
动态分辨率（支持 AMD FidelityFX FSR）

后处理

HDR 泛光
景深散景
多种色调映射器：通用（可自定义）、ACES、电影等
色彩和色调管理：亮度缩放、色域映射
色彩分级：曝光、夜间适应、白平衡、通道混合器、阴影/中间调/高光、ASC CDL、对比度、饱和度等
TAA、FXAA、MSAA
屏幕空间镜头光晕

glTF 2.0

编码
- 嵌入式
- 二进制
图元类型
- 点
- 线
- 线环
- 线带
- 三角形
- 三角形带
- 三角形扇
动画
- 变换动画
- 线性插值
- 形态动画
  - 稀疏访问器
- 蒙皮动画
- 关节动画
扩展
- KHR_draco_mesh_compression
- KHR_lights_punctual
- KHR_materials_clearcoat
- KHR_materials_emissive_strength
- KHR_materials_ior
- KHR_materials_pbrSpecularGlossiness
- KHR_materials_sheen
- KHR_materials_transmission
- KHR_materials_unlit
- KHR_materials_variants
- KHR_materials_volume
- KHR_materials_specular
- KHR_mesh_quantization
- KHR_texture_basisu
- KHR_texture_transform
- EXT_meshopt_compression

使用 Filament 进行渲染

原生 Linux、macOS 和 Windows

您必须创建一个 Engine、一个 Renderer 和一个 SwapChain。SwapChain 是从本机窗口指针创建的（例如，在 macOS 上是 NSView，在 Windows 上是 HWND）：

Engine* engine = Engine::create();
SwapChain* swapChain = engine->createSwapChain(nativeWindow);
Renderer* renderer = engine->createRenderer();

要渲染一帧，您还必须创建一个 View、一个 Scene 和一个 Camera：

Camera* camera = engine->createCamera(EntityManager::get().create());
View* view = engine->createView();
Scene* scene = engine->createScene();

view->setCamera(camera);
view->setScene(scene);

可渲染对象被添加到场景中：

Entity renderable = EntityManager::get().create();
// 构建一个四边形
RenderableManager::Builder(1)
        .boundingBox({{ -1, -1, -1 }, { 1, 1, 1 }})
        .material(0, materialInstance)
        .geometry(0, RenderableManager::PrimitiveType::TRIANGLES, vertexBuffer, indexBuffer, 0, 6)
        .culling(false)
        .build(*engine, renderable);
scene->addEntity(renderable);

材质实例是从材质获得的，材质本身是从 matc 生成的二进制 blob 加载的：

Material* material = Material::Builder()
        .package((void*) BAKED_MATERIAL_PACKAGE, sizeof(BAKED_MATERIAL_PACKAGE))
        .build(*engine);
MaterialInstance* materialInstance = material->createInstance();

要了解更多关于材质和 matc 的信息，请参阅材质文档。

要渲染，只需将 View 传递给 Renderer：

// beginFrame() 在需要跳过一帧时返回 false
if (renderer->beginFrame(swapChain)) {
    // 对每个 View
    renderer->render(view);
    renderer->endFrame();
}

要查看 Linux、macOS 和 Windows 完整的 Filament 应用示例，请查看 samples/ 目录中的源文件。这些示例都基于 libs/filamentapp/，其中包含使用 SDL2 创建原生窗口并初始化 Filament 引擎、渲染器和视图的代码。

有关如何为基于图像的照明准备环境贴图的更多信息，请参阅 BUILDING.md。

Android

有关如何在 Android 上使用 Filament 的示例，请参见 android/samples。

你必须始终先通过调用 Filament.init() 来初始化 Filament。

在 Android 上使用 Filament 进行渲染与原生代码渲染类似（各语言的 API 大致相同）。你可以通过将 Surface 传递给 createSwapChain 方法来渲染到 Surface。这允许你渲染到 SurfaceTexture、TextureView 或 SurfaceView。为了简化操作，我们在 com.google.android.filament.android 包中提供了一个特定于 Android 的 API，称为 UiHelper。你只需要在助手上设置渲染回调，并将 SurfaceView 或 TextureView 附加到它上面。你仍然需要负责在 onNativeWindowChanged() 回调中创建交换链。

iOS

Filament 支持 iOS 11.0 及以上版本。有关在 iOS 上使用 Filament 的示例，请参见 ios/samples。

iOS 上的 Filament 与使用 C++ 的原生渲染大致相同。将 CAEAGLLayer 或 CAMetalLayer 传递给 createSwapChain 方法。iOS 版 Filament 同时支持 Metal（首选）和 OpenGL ES。

资源

入门时，你可以使用 third_party/textures 和 third_party/environments 中的纹理和环境贴图。这些资源使用 CC0 许可。请参阅各自的 URL.txt 文件以了解原作者的更多信息。

环境贴图必须使用 cmgen 或 libiblprefilter 库进行预处理。

如何贡献

请阅读并遵循 CONTRIBUTING.md 中的步骤。确保你熟悉代码风格。

目录结构

这个仓库不仅包含 Filament 核心引擎，还包含其支持库和工具。

android: Android 库和项目
- filamat-android: Android 版 Filament 材质生成库（AAR）
- filament-android: Android 版 Filament 库（AAR）
- filament-utils-android: 额外工具（KTX 加载器、数学类型等）
- gltfio-android: Android 版 Filament glTF 加载库（AAR）
- samples: 特定于 Android 的 Filament 示例
art: 各种艺术作品的源文件（徽标、PDF 手册等）
assets: 用于示例应用的 3D 资源
build: CMake 构建脚本
docs: 文档
- math: 用于探索 BRDF、方程等的 Mathematica 笔记本
filament: Filament 渲染引擎（最小依赖）
- backend: 渲染后端/驱动（Vulkan、Metal、OpenGL/ES）
ide: IDE 配置文件（CLion 等）
ios: iOS 示例项目
libs: 库
- bluegl: macOS、Linux 和 Windows 的 OpenGL 绑定
- bluevk: macOS、Linux、Windows 和 Android 的 Vulkan 绑定
- camutils: 相机操作工具
- filabridge: Filament 引擎和主机工具共享的库
- filaflat: 用于材质的序列化/反序列化库
- filagui: Dear ImGui 的辅助库
- filamat: 材质生成库
- filamentapp: 用于构建示例应用的 SDL2 框架
- filameshio: 小型 filamesh 解析库（另见 tools/filamesh）
- geometry: 网格相关工具
- gltfio: glTF 2.0 加载器
- ibl: IBL 生成工具
- image: 图像滤波和简单变换
- imageio: 图像文件读/写，仅供内部使用
- matdbg: 用于在运行时检查着色器的 DebugServer（仅调试版本）
- math: 数学库
- mathio: 输出流的数学类型支持
- utils: 实用工具库（线程、内存、数据结构等）
- viewer: glTF 查看器库（需要 gltfio）
samples: 桌面示例应用
shaders: filamat 和 matc 使用的着色器
third_party: 外部库和资源
- environments: 可与 cmgen 一起使用的 CC0 许可环境贴图
- models: 宽松许可下的模型
- textures: CC0 许可下的纹理
tools: 主机工具
- cmgen: 基于图像的照明资源生成器
- filamesh: 网格转换器
- glslminifier: GLSL 源代码压缩工具
- matc: 材质编译器
- matinfo 显示用 matc 编译的材质信息
- mipgen 从源图像生成一系列 mip 级别
- normal-blending: 法线贴图混合工具
- resgen 将二进制 blob 聚合成可嵌入的资源
- roughness-prefilter: 从法线贴图预过滤粗糙度贴图以减少锯齿
- specular-color: 基于光谱数据计算导体的镜面颜色
web: JavaScript 绑定、文档和示例