标签为“自动化测试”的页面如下
2026-04-08
KisekiEngine 渲染 Bug 排查实录:从“立方体全亮、地面纹理消失”到 7/7 自动化测试全通过
开源项目地址: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 可视化模式,用来分别观察不同信号:
继续阅读