前言 有光的地方就有影子。但如果你写过渲染引擎，就会知道——光照模型（比如 Blinn-Phong）默认是不会产生阴影的。它只告诉你"这个点被光照了多亮"，但不会告诉你"这个点有没有被别的东西挡住"。 KisekiEngine 之前已经实现了 Blinn-Phong 点光源光照，场景里有立方体、有地面、有光照明暗，但就是没有阴影。一个物体浮在地面上，下面却没有影子，看起来就像悬浮在空中一样不真实。 要加阴影，最经典的方案就是 Shadow Mapping（阴影贴图）。它的核心思想只需要一句话： 站在光源的位置看一眼，记下每个方向上最近的深度；然后在正常渲染时，把每个片元投影回光源视角，比较一下深度——如果片元比记录的深度更远，说明它被什么东西挡住了，那它就在阴影里。 接下来，我们一步一步把这个想法变成 Metal 代码。 整体架构：双 Pass 渲染 整个实现的核心是在同一个 Command Buffer 里做两个 Render Pass： ┌─────────────────────────────────────────────────┐ │ Command Buffer │ │ │ │ ┌─────────────────────┐ ┌──────────────────┐ │ │ │ Shadow Pass │ │ Main Pass │ │ │ │ │ │ │ │ │ │ 光源视角渲染深度 │──▶│ 正常渲染 + │ │ │ │ → Shadow Map │ │ 采样 Shadow Map │ │ │ │ (1024×1024) │ │ → 阴影判定 │ │ │ └─────────────────────┘ └──────────────────┘ │ └─────────────────────────────────────────────────┘ Pass 1（Shadow Pass）：把光源当成一台摄像机，用透视投影渲染整个场景，但只写深度，不输出颜色。结果存到一张 1024×1024 的深度纹理里，这就是 shadow map。 Pass 2（Main Pass）：用正常的摄像机渲染场景。在片段着色器里，把每个片元的世界坐标投影到光源空间，去 shadow map 里查一下深度，判断它是不是在阴影里。 下面按实现顺序逐步讲解。

开源项目地址：https://github.com/sznswjr/kiseki_engine KisekiEngine 渲染 Bug 排查实录：从“立方体全亮、地面纹理消失”到 7/7 自动化测试全通过 背景 KisekiEngine 是一个基于 Metal 的 3D 图形引擎，实现了 Blinn-Phong 点光源光照、纹理贴图、OBJ 模型加载和多物体场景渲染。在完成所有功能后，用户报告了两个渲染问题： 立方体全亮：没有明暗面，整个立方体看起来亮度均匀 地面纹理消失：设置了 ground.png 纹理但地面显示为纯色 第一轮尝试：盲修（失败） 假设 1：uniform 布局不对齐 怀疑 C++ 端 simd_float3（16 字节）和 Metal shader 端 float3（12 字节）的对齐差异导致数据错位。 操作：将所有 simd_float3 + padding 改为 simd_float4 打包。 结果：编译通过但问题未解决。事后验证发现结构体偏移量实际上是一致的（offset 80 处 hasTexture），这个修改虽然没直接修到 bug，但让布局更安全了。 假设 2：无纹理物体残留纹理 怀疑光源球体（无纹理）渲染后残留了之前的纹理绑定。 操作：对无纹理物体显式调用 [encoder setFragmentTexture:nil atIndex:0]。 结果：问题仍未解决。 教训 盲修效率极低。每次修改都是猜测，无法验证是否真正触及根因。 转折点：先做验证工具，而不是继续猜 真正改变排查策略的一句要求是： 先不要解决问题，先设计一套测试工具验证修复到底正不正确。 这一步很关键。对于图形渲染问题，仅凭肉眼看窗口往往不够，必须建立一套可以重复执行的观测和验证机制。 第二轮：构建诊断系统 1）Debug Mode Shader 利用 Metal function constants 实现了多种 shader 可视化模式，用来分别观察不同信号：