filament

Filament

Filament 是一款适用于 Android、iOS、Linux、macOS、Windows 和 WASM 的实时物理渲染引擎。它的设计目标是尽可能小巧，并在 Android 上尽可能高效。

下载

下载 Filament 发行版以获取稳定版本。 Filament 发行版压缩包包含生成资源所需的主机端工具。

请务必使用与运行时库版本相同的工具。这一点对于 matc（材质编译器）尤其重要。

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

Android

Android 项目只需将 Filament 库声明为 Maven 依赖项：

repositories {
    // ...
    mavenCentral()
}

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

以下是 com.google.android.filament 组中提供的所有库：

构件	说明
	Filament 渲染引擎本身。
	filament-android 的调试版本。
	Filament 的 glTF 2.0 加载器，依赖于 filament-android。
	KTX 加载、Kotlin 数学和相机工具，依赖于 gltfio-android。
	运行时材质构建器／编译器。此库体积较大，但包含完整的着色器编译器／验证器／优化器，并同时支持 OpenGL 和 Vulkan。

iOS

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

pod 'Filament', '~> 1.79.0'

文档

• Filament，深入讲解实时基于物理的渲染，以及 Filament 的图形功能和实现方式。 本文档阐述了我们大多数决策背后的数学原理和考量，是图形程序员了解 PBR 的良好入门资料。
• Materials，材质系统的完整参考文档。本文档介绍了不同的材质模型、如何使用材质编译器 matc，以及如何编写自定义材质。
• Material Properties，标准材质模型的参考资料。

示例

功能

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
• 适用于 Android、Linux、macOS 和 Windows 的 WebGPU
• 适用于所有支持它的浏览器的 WebGL 2.0

渲染

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

后期处理

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

glTF 2.0

• 编码

  • 嵌入式
  • 二进制

• 图元类型

  • 点
  • 线
  • 闭合线环
  • 线带
  • 三角形
  • 三角形带
  • 三角形扇

• 动画

  • 变换动画
  • 线性插值
  • 变形动画
    • 稀疏访问器
  • 蒙皮动画
  • 关节动画

• 扩展

  • KHR_draco_mesh_compression
  • KHR_lights_punctual
  • KHR_materials_clearcoat
  • KHR_materials_dispersion
  • KHR_materials_emissive_strength
  • KHR_materials_ior
  • KHR_materials_pbrSpecularGlossiness
  • KHR_materials_sheen
  • KHR_materials_specular
  • KHR_materials_transmission
  • KHR_materials_unlit
  • KHR_materials_variants
  • KHR_materials_volume
  • 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();
// build a quad
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 生成的二进制数据块加载的：

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

如需进一步了解材质和 matc，请参阅材质文档。

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

// beginFrame() returns false if we need to skip a frame
if (renderer->beginFrame(swapChain)) {
    // for each View
    renderer->render(view);
    renderer->endFrame();
}

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

如需详细了解如何为基于图像的照明准备环境贴图，请参阅 BUILDING.md。

Android

请参阅 android/samples，了解如何在 Android 上使用 Filament 的示例。

必须始终先调用 Filament.init() 初始化 Filament。

在 Android 上使用 Filament 进行渲染，与使用原生代码渲染类似（各语言的 API 大体相同）。向 createSwapChain 方法传递一个 Surface，即可渲染到该 Surface。这样便可以渲染到 SurfaceTexture、TextureView 或 SurfaceView。为简化操作，我们在 com.google.android.filament.android 包中提供了 Android 专用 API UiHelper。你只需在该辅助工具上设置渲染回调，并将 SurfaceView 或 TextureView 附加到它。仍需负责在 onNativeWindowChanged() 回调中创建交换链。

iOS

Filament 支持 iOS 11.0 及更高版本。请参阅 ios/samples，了解在 iOS 上使用 Filament 的示例。

Filament 在 iOS 上的使用方式与使用 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：采用 CC0 许可、可与 cmgen 搭配使用的环境贴图
  • models：采用宽松许可的模型
  • textures：采用 CC0 许可的纹理
• tools：主机工具
  • cmgen：基于图像的光照资源生成器
  • filamesh：网格转换器
  • glslminifier：压缩 GLSL 源代码
  • matc：材质编译器
  • matedit：已编译材质的材质编辑器
  • matinfo：显示使用 matc 编译的材质信息
  • mipgen：从源图像生成一系列 mip 级别
  • normal-blending：用于混合法线贴图的工具
  • resgen：将二进制数据块汇总为可嵌入的资源
  • roughness-prefilter：根据法线贴图预滤粗糙度贴图，以减少混叠
  • specular-color：根据光谱数据计算导体的镜面颜色
• web：JavaScript 绑定、文档和示例

许可证

请参阅 LICENSE。

免责声明

这不是 Google 官方支持的产品。