灯丝

灯丝

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

下载

下载 Filament 版本以访问稳定版本。灯丝发布档案包含生成资产所需的主机端工具。

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

如果您想自己构建 Filament，请参阅我们的构建手册。

安卓

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

存储库 { // ...
    mavenCentral()
}依赖项{
    实现 'com.google.android.filament:filament-android:1.56.0'}

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

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

iOS系统

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

 pod '灯丝', '~> 1.56.0'

文档

• Filament，深入解释基于物理的实时渲染、Filament 的图形功能和实现。本文档解释了我们大多数决策背后的数学和推理。本文档是对图形程序员的 PBR 很好的介绍。

• 材料，我们材料系统的完整参考文档。本文档解释了我们不同的材质模型、如何使用材质编译器matc以及如何编写自定义材质。

• 材料属性，标准材料模型的参考表。

示例

特征

蜜蜂

• 适用于 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

• 朗伯漫反射 BRDF

• 自定义照明/表面着色

• HDR/线性照明

• 金属工作流程

• 透明涂层

• 各向异性照明

• 近似半透明（次表面）材质

• 布料/织物/光泽着色

• 法线贴图和环境光遮挡贴图

• 基于图像的照明

• 基于物理的相机（快门速度、灵敏度和光圈）

• 物理光单位

• 点光源、聚光灯和定向光

• 镜面反锯齿

• 点、聚光和定向光阴影

• 层叠阴影

• EVSM、PCSS、DPCF 或 PCF 阴影

• 透明阴影

• 接触阴影

• 屏幕空间环境光遮挡

• 屏幕空间反射

• 屏幕空间折射

• 全球雾

• 动态分辨率（支持 AMD FidelityFX FSR）

后处理

• HDR 绽放

• 景深散景

• 多种色调映射器：通用（可定制）、ACES、电影等。

• 颜色和色调管理：亮度缩放、色域映射

• 色彩分级：曝光、夜间适应、白平衡、通道混合器、阴影/中间色调/高光、ASC CDL、对比度、饱和度等。

• TAA、FXAA、MSAA

• 屏幕空间镜头光晕

GLTF 2.0

• 编码

• 嵌入式

• 二进制

• 原始类型

• 积分

• 线路

• 线路循环

• 线带

• 三角形

• 三角带

• 三角扇

• 动画片

• 稀疏访问器

• 变换动画

• 线性插补

• 变形动画

• 皮肤动画

• 联合动画

• 扩展

• KHR_draco_mesh_压缩

• KHR_lights_punctual

• KHR_材料_透明涂层

• KHR_materials_emissive_strength

• KHR_材料_ior

• KHR_materials_pbr镜面光泽度

• KHR_材料_光泽

• KHR_材料_传输

• KHR_materials_unlit

• KHR_materials_variants

• KHR_材料_体积

• KHR_材质_镜面反射

• KHR_mesh_量化

• KHR_texture_basisu

• KHR_纹理_变换

• EXT_meshopt_压缩

使用灯丝渲染

本机 Linux、macOS 和 Windows

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

引擎*引擎=引擎::create();
SwapChain* swapChain = 引擎->createSwapChain(nativeWindow);
渲染器*渲染器=引擎->createRenderer();

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

相机* 相机 = 引擎->createCamera(EntityManager::get().create());
View* view = engine->createView();
场景*场景=引擎->createScene();

视图->setCamera(相机);
视图->setScene(场景);

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

 Entity renderable = EntityManager::get().create();//构建一个quadRenderableManager::Builder(1)
        .boundingBox({{ -1, -1, -1 }, { 1, 1, 1 }})
        .material(0, 材质实例)
        .geometry(0, RenderableManager::PrimitiveType::TRIANGLES, vertexBuffer, indexBuffer, 0, 6)
        .剔除（假）
        .build(*引擎，可渲染);
场景->addEntity(可渲染);

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

材质*材质=材质::Builder()
        .package((void*) BAKED_MATERIAL_PACKAGE, sizeof(BAKED_MATERIAL_PACKAGE))
        .build(*引擎);
MaterialInstance*materialInstance = 材质->createInstance();

要了解有关材料和matc更多信息，请参阅材料文档。

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

 // 如果我们需要跳过一帧，则 beginFrame() 返回 false if (renderer->beginFrame(swapChain)) { // 对于每个 View
    渲染器->渲染（视图）；
    渲染器->endFrame();
}

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

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

安卓

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

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

在 Android 上使用 Filament 进行渲染与从本机代码进行渲染类似（跨语言的 API 基本相同）。您可以通过将Surface传递给createSwapChain方法来渲染到Surface中。这允许您渲染到SurfaceTexture 、 TextureView或SurfaceView 。为了让事情变得更容易，我们在com.google.android.filament.android包中提供了一个名为UiHelper的 Android 特定 API。您需要做的就是在助手上设置渲染回调并将SurfaceView或TextureView附加到它。您仍然负责在onNativeWindowChanged()回调中创建交换链。

iOS系统

iOS 11.0 及更高版本支持 Filament。有关在 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 的灯丝材料生成库（AAR）

• filament-android ：适用于 Android 的灯丝库 (AAR)

• filament-utils-android ：额外的实用程序（KTX 加载器、数学类型等）

• gltfio-android ：适用于 Android 的灯丝 glTF 加载库（AAR）

• samples ：Android 特定的 Filament 示例

• art ：各种艺术品的来源（徽标、PDF 手册等）

• assets ：与示例应用程序一起使用的 3D 资源

• build : CMake 构建脚本

• docs ：文档

• math ：用于探索 BRDF、方程等的 Mathematica 笔记本。

• 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 ：用于在运行时检查着色器的调试服务器（仅调试版本）

• math ：数学库

• mathio ：输出流的数学类型支持

• utils ：实用程序库（线程、内存、数据结构等）

• viewer ：glTF 查看器库（需要 gltfio）

• samples ：示例桌面应用程序

• shaders : filamat和matc使用的着色器

• third_party ：外部库和资产

• environments ：CC0 许可下的环境图，可与cmgen一起使用

• models : 许可许可下的模型

• textures ：CC0 许可下的纹理

• tools ：主机工具

• cmgen ：基于图像的照明资产生成器

• filamesh : 网格转换器

• glslminifier ：缩小 GLSL 源代码

• matc ：材质编译器

• matinfo显示有关使用matc编译的材料的信息

• mipgen从源图像生成一系列 miplevel

• normal-blending ：混合法线贴图的工具

• resgen将二进制 blob 聚合为可嵌入资源

• roughness-prefilter ：从法线贴图中预过滤粗糙度贴图以减少锯齿

• specular-color ：根据光谱数据计算导体的镜面颜色

• web ：JavaScript 绑定、文档和示例

执照

请参阅许可证。

免责声明

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