简介：这份资源围绕「Filament绘制立方体」展开，面向具备一定Android与图形学基础、希望入门实时3D渲染的开发者。Filament是Google开源维护的跨平台实时渲染引擎，资源以绘制一个基础立方体为主线，串联起渲染器、场景、相机与光照等核心组件，并涉及几何体顶点数组、材质实例与Material Blueprint、透视相机配置及点光源、聚光灯、环境光等知识点，同时覆盖gradlew构建脚本与依赖管理流程。压缩包共655个文件，以xml布局与配置、flat与filamat材质、json数据、so动态库、jar与aar依赖、dex与class字节码、java源码及gradle构建脚本为主，整体约100.05MB，结构完整可直接导入Android工程。已有175人学习下载，适合作为理解3D图形编程与实时渲染原理的实践参考，帮助读者掌握从几何体创建、材质光照设置到渲染循环呈现的完整链路。
1. Filament 绘制立方体：从零到一，为什么你的第一个 3D 物体总是“翻车”
很多刚接触 Filament 的开发者，第一次尝试绘制立方体时，都会遇到一个反直觉的现象：代码明明编译通过了，屏幕却一片漆黑，或者只有一个诡异的三角形在闪烁。这其实不是你的代码写错了，而是 Filament 作为基于物理渲染（PBR）的引擎，对坐标系、材质和光照的要求比传统 OpenGL 严格得多。Filament 绘制立方体这件事，本质上是在验证你是否理解了它的渲染管线——从顶点数据到材质系统，再到光照环境，缺一环都不行。这篇文章就是写给那些想用 Filament 做 3D 可视化、但又不想被官方文档里那些晦涩术语劝退的一线开发者。我会带你从最基础的顶点缓冲区开始，一步步把立方体画出来，再把那些年我踩过的坑一个个填平。不管你是刚入行的新手，还是从 Unity 转过来的老手，只要跟着走，就能在本地跑通一个带光照、能旋转的立方体。
2. Filament 渲染立方体的底层逻辑与最小工程搭建
2.1 为什么 Filament 不能像 OpenGL 那样直接画三角形
Filament 的核心设计目标是移动端的高效 PBR 渲染，这意味着它把很多传统图形 API 的细节封装了起来。在 OpenGL 里，你写个glDrawArrays就能把顶点数据扔给 GPU，但在 Filament 里，你必须先构建一个VertexBuffer和IndexBuffer，再通过RenderableManager把几何体注册到实体上。这听起来麻烦，但好处是 Filament 会自动处理视锥剔除、材质排序和实例化渲染。如果你跳过这些步骤直接调底层 API，Filament 的渲染循环根本不会理你。常见做法是：先用VertexBuffer::Builder定义顶点属性（位置、法线、UV），再用IndexBuffer::Builder定义三角形索引，最后通过RenderableManager::Builder把两者绑到一个Entity上。这个过程就像给 Filament 交一份“简历”，它审核通过了才会把你的立方体放进渲染队列。
2.2 用 VertexBuffer 和 IndexBuffer 构建一个立方体
立方体有 8 个顶点，但每个面需要独立法线，所以实际要写 24 个顶点（每个面 4 个）。下面是我常用的顶点数据结构，位置和法线交错存储，UV 暂时用不上可以留空。
struct Vertex { filament::math::float3 position; filament::math::float3 normal; }; // 24 个顶点，每个面 4 个，法线朝外 static const Vertex CUBE_VERTICES[] = { // 前面 (+Z) {{-1, -1, 1}, { 0, 0, 1}}, {{ 1, -1, 1}, { 0, 0, 1}}, {{ 1, 1, 1}, { 0, 0, 1}}, {{-1, 1, 1}, { 0, 0, 1}}, // 后面 (-Z) {{ 1, -1, -1}, { 0, 0, -1}}, {{-1, -1, -1}, { 0, 0, -1}}, {{-1, 1, -1}, { 0, 0, -1}}, {{ 1, 1, -1}, { 0, 0, -1}}, // 上面 (+Y) {{-1, 1, 1}, { 0, 1, 0}}, {{ 1, 1, 1}, { 0, 1, 0}}, {{ 1, 1, -1}, { 0, 1, 0}}, {{-1, 1, -1}, { 0, 1, 0}}, // 下面 (-Y) {{-1, -1, -1}, { 0, -1, 0}}, {{ 1, -1, -1}, { 0, -1, 0}}, {{ 1, -1, 1}, { 0, -1, 0}}, {{-1, -1, 1}, { 0, -1, 0}}, // 右面 (+X) {{ 1, -1, 1}, { 1, 0, 0}}, {{ 1, -1, -1}, { 1, 0, 0}}, {{ 1, 1, -1}, { 1, 0, 0}}, {{ 1, 1, 1}, { 1, 0, 0}}, // 左面 (-X) {{-1, -1, -1}, {-1, 0, 0}}, {{-1, -1, 1}, {-1, 0, 0}}, {{-1, 1, 1}, {-1, 0, 0}}, {{-1, 1, -1}, {-1, 0, 0}}, }; // 36 个索引，每面两个三角形 static const uint16_t CUBE_INDICES[] = { 0, 1, 2, 0, 2, 3, // 前 4, 5, 6, 4, 6, 7, // 后 8, 9, 10, 8, 10, 11, // 上 12, 13, 14, 12, 14, 15, // 下 16, 17, 18, 16, 18, 19, // 右 20, 21, 22, 20, 22, 23 // 左 };这段代码里，顶点顺序和索引顺序必须严格对应，否则会出现面片撕裂。参数说明：position用float3表示，范围是 -1 到 1，这样立方体边长为 2；normal必须归一化，否则光照计算会出错。索引用uint16_t就够了，因为顶点数远小于 65535。构建VertexBuffer时，需要指定AttributeType::POSITION和AttributeType::NORMAL，并设置attributeCount为 2。
2.3 把几何体挂到 Entity 上并配置渲染管线
有了顶点和索引，下一步是创建VertexBuffer和IndexBuffer对象，然后通过RenderableManager绑定到实体。
// 创建 VertexBuffer filament::VertexBuffer* vb = filament::VertexBuffer::Builder() .vertexCount(24) .bufferCount(1) .attribute(filament::VertexAttribute::POSITION, 0, filament::VertexBuffer::AttributeType::FLOAT3, offsetof(Vertex, position), sizeof(Vertex)) .attribute(filament::VertexAttribute::NORMAL, 0, filament::VertexBuffer::AttributeType::FLOAT3, offsetof(Vertex, normal), sizeof(Vertex)) .build(engine); vb->setBufferAt(engine, 0, filament::VertexBuffer::BufferDescriptor( CUBE_VERTICES, sizeof(CUBE_VERTICES), nullptr)); // 创建 IndexBuffer filament::IndexBuffer* ib = filament::IndexBuffer::Builder() .indexCount(36) .bufferType(filament::IndexBuffer::IndexType::USHORT) .build(engine); ib->setBuffer(engine, filament::IndexBuffer::BufferDescriptor( CUBE_INDICES, sizeof(CUBE_INDICES), nullptr)); // 创建 Entity 并绑定 Renderable filament::Entity cube = entities::create(engine); filament::RenderableManager::Builder(1) .boundingBox({{-1, -1, -1}, {1, 1, 1}}) .material(0, material->getDefaultInstance()) .geometry(0, filament::RenderableManager::PrimitiveType::TRIANGLES, vb, ib) .culling(false) .receiveShadows(true) .castShadows(true) .build(engine, cube);这里的关键参数：boundingBox必须准确，否则视锥剔除会把立方体裁掉；material需要提前加载好，可以用 Filament 自带的defaultMaterial；culling(false)在调试阶段建议关掉，避免因为绕序问题看不到面。receiveShadows和castShadows按需开启，如果场景里没有光源，开了也没用。
3. 材质、光照与相机：让立方体真正“看得见”
3.1 用 .mat 文件定义 PBR 材质并编译成 .filamat
Filament 的材质系统是它的灵魂，也是最容易让人懵的地方。你不能直接在 C++ 里写 shader，而是要先写.mat文件，然后用matc工具编译成.filamat二进制。下面是一个最简的材质定义，只包含基础颜色和光照响应。
material { name : cubeMaterial, shadingModel : lit, parameters : [ { type : float4, name : baseColor } ] } fragment { void material(inout MaterialInputs material) { prepareMaterial(material); material.baseColor = materialParams.baseColor; } }shadingModel : lit表示这个材质会参与 PBR 光照计算；baseColor是外部传入的参数，可以在运行时修改。编译命令是matc -o cube.filamat cube.mat，注意matc的路径通常在 Filament 的bin目录下。编译成功后，用Material::Builder加载.filamat文件，再通过getDefaultInstance()获取实例。如果编译报错，多半是语法问题，比如漏了分号或者参数类型写错。
3.2 添加平行光、点光源和间接光
没有光源，立方体就是一团黑。Filament 支持多种光源，最常用的是平行光（模拟太阳）和点光源。下面代码创建一个平行光和一个点光源。
// 平行光 filament::Entity sun = entities::create(engine); filament::LightManager::Builder(filament::LightManager::Type::DIRECTIONAL) .color({1.0, 0.98, 0.95}) .intensity(100000.0f) .direction({-0.5, -1.0, -0.3}) .castShadows(true) .build(engine, sun); // 点光源 filament::Entity pointLight = entities::create(engine); filament::LightManager::Builder(filament::LightManager::Type::POINT) .color({0.2, 0.5, 1.0}) .intensity(50000.0f) .position({2.0, 2.0, 2.0}) .falloff(10.0f) .build(engine, pointLight);参数说明：intensity单位是 lux（平行光）或 lumen（点光源），数值给太小会看不见，给太大直接过曝。我一般先用 100000 试平行光，点光源用 50000 左右。direction需要归一化，falloff控制点光源的衰减半径。另外，别忘了设置IndirectLight，否则背光面会死黑。可以用 Filament 自带的defaultIbl或者自己生成一张环境贴图。
3.3 相机设置与视图投影矩阵
相机决定了你从哪个角度看立方体。Filament 的相机需要设置曝光、投影方式和位置。
filament::Camera* camera = engine->createCamera(filament::Entity()); camera->setExposure(16.0f, 1.0f / 125.0f, 100.0f); camera->setProjection(filament::Camera::Projection::PERSPECTIVE, 45.0f, 16.0f / 9.0f, 0.1f, 100.0f); camera->lookAt({3.0, 3.0, 3.0}, {0.0, 0.0, 0.0}, {0.0, 1.0, 0.0});setExposure的三个参数分别是光圈、快门速度和 ISO，这里用 16、1/125、100 是室外晴天的典型值。lookAt的 eye 位置设在 (3,3,3)，中心在原点，这样立方体刚好在视野中央。如果画面太暗，先调曝光；如果立方体变形，检查宽高比是否和视口一致。
4. 避坑指南：Filament 画立方体时最容易翻车的五个地方
4.1 现象：屏幕全黑，日志无报错
原因：最常见的是没有设置View的setViewport和setCamera，或者Renderer没有调用render。另一个可能是材质没有正确加载，Material::Builder返回了空指针。解决：检查View::Builder是否绑定了相机和场景，确认renderer->render(view)在每一帧都被调用。用material->getDefaultInstance()前先判断material是否为空。
4.2 现象：立方体只有一半，或者面片闪烁
原因：索引缓冲区里的三角形绕序（winding order）反了，导致背面剔除把正面剔掉了。Filament 默认逆时针为正面。解决：检查CUBE_INDICES里的顶点顺序，确保每个三角形从外面看是逆时针。临时方案是关掉culling，但正式项目必须修正绕序。
4.3 现象：光照计算异常，面与面之间亮度突变
原因：法线没有归一化，或者顶点法线方向反了。比如左面的法线写成了{1,0,0}。解决：在顶点数据里逐面检查法线方向，确保指向立方体外部。可以用normalize()在 shader 里再处理一次，但最好在 CPU 端就保证正确。
4.4 现象：立方体边缘有锯齿，或者纹理拉伸
原因：没有开启抗锯齿（MSAA），或者 UV 坐标缺失导致默认采样出错。解决：在Engine::Builder里设置msaaSampleCount(4)。如果不需要纹理，可以在材质里忽略 UV，但顶点属性里最好保留，避免驱动兼容性问题。
4.5 现象：旋转立方体时，背面突然消失
原因：boundingBox设置得太小，视锥剔除误判。或者相机的near和far平面范围不合理。解决：把boundingBox稍微放大一点，比如{{-1.1,-1.1,-1.1},{1.1,1.1,1.1}}。同时检查相机的near不要小于 0.01，far不要超过 1000。
5. 进阶技巧：用 TransformManager 做旋转动画与性能验证
5.1 用 TransformManager 驱动立方体自转
静态立方体画出来只是第一步，让它转起来才能验证渲染循环是否正常。Filament 的TransformManager可以给实体添加变换组件，然后在每帧更新旋转矩阵。
filament::TransformManager& tcm = engine->getTransformManager(); tcm.create(cube); filament::math::mat4f transform = filament::math::mat4f::rotation( filament::math::radians(angle), filament::math::float3{0, 1, 0}); tcm.setTransform(tcm.getInstance(cube), transform);angle每帧递增，比如angle += 0.5f。注意setTransform会覆盖之前的变换，所以如果你还想平移，需要先乘平移矩阵。这个技巧我常用在调试阶段，转起来就能一眼看出法线对不对、光照有没有跟着动。
5.2 用 FrameGraph 和 GPU 计时器验证渲染开销
Filament 的FrameGraph是个黑匣子，但你可以通过Renderer::getFrameInfo拿到一些统计信息。更直接的办法是用Engine::getTimerQuery或者平台原生的 GPU 计时器。下面是一个简单的帧时间打印。
filament::Renderer::FrameInfo info = renderer->getFrameInfo(); utils::slog.i << "Frame time: " << info.frameTime << " ms" << utils::io::endl;如果帧时间超过 16ms，说明有性能问题。常见原因是材质太复杂、光源太多或者分辨率太高。对于单个立方体，正常应该在 1ms 以内。如果发现异常，先检查是不是开了 MSAA 8x 或者阴影贴图分辨率过大。
5.3 一个我坚持了三年的调试习惯
每次新建一个 Filament 项目，我都会先画一个立方体，然后依次检查五件事：顶点法线是否朝外、索引绕序是否逆时针、材质是否编译成功、相机曝光是否合理、TransformManager 是否更新。这五步走完，基本能排除 90% 的“黑屏”问题。希望帮到你。
本文还有配套的精品资源，点击获取
