228 lines
7.7 KiB
Markdown
228 lines
7.7 KiB
Markdown
# MainLight 方向光阴影修复计划
|
||
|
||
日期: `2026-04-13`
|
||
|
||
## 1. 文档定位
|
||
|
||
这份文档是基于当前仓库代码状态重新整理的版本，用来承接 MainLight 单张方向光阴影的后续修复工作。
|
||
|
||
需要明确：
|
||
|
||
- 这不是对之前已删除计划文件的逐字恢复。
|
||
- 这是一份按当前实现状态、最近两次提交和现有阴影链路重新整理的执行计划。
|
||
- 当前目标不是上级联阴影，而是先把单张 MainLight 阴影做到可用。
|
||
|
||
## 2. 当前问题定义
|
||
|
||
当前 MainLight 阴影已经具备从规划、投射到接收采样的完整闭环，但实际效果仍然不可用，核心问题有两个：
|
||
|
||
1. 自阴影过重，表面出现明显 acne。
|
||
2. 阴影边缘呈现大块锯齿，采样质量不足。
|
||
|
||
当前阶段暂不解决：
|
||
|
||
- 级联阴影
|
||
- 点光 / 聚光阴影
|
||
- 阴影时域稳定与降噪的完整方案
|
||
- 多光源阴影编排
|
||
|
||
## 3. 当前阴影链路梳理
|
||
|
||
当前单张 MainLight 阴影主链如下：
|
||
|
||
`SceneRenderRequestPlanner`
|
||
-> `DirectionalShadowRenderPlan`
|
||
-> `CameraRenderer`
|
||
-> `ShadowCaster Pass`
|
||
-> `RenderSceneData::lighting.mainDirectionalShadow`
|
||
-> `BuiltinForwardPipeline`
|
||
-> `forward-lit.shader / Toon.shader`
|
||
|
||
关键代码位置：
|
||
|
||
- 规划层
|
||
- `engine/include/XCEngine/Rendering/Planning/SceneRenderRequestPlanner.h`
|
||
- `engine/src/Rendering/Planning/Internal/DirectionalShadowPlanning.cpp`
|
||
- 请求与运行时数据
|
||
- `engine/include/XCEngine/Rendering/Planning/CameraRenderRequest.h`
|
||
- `engine/include/XCEngine/Rendering/FrameData/RenderSceneData.h`
|
||
- `engine/src/Rendering/Execution/CameraRenderer.cpp`
|
||
- ShadowCaster 消费 bias
|
||
- `engine/include/XCEngine/Rendering/Passes/BuiltinDepthStylePassBase.h`
|
||
- `engine/src/Rendering/Passes/BuiltinDepthStylePassBaseResources.cpp`
|
||
- `engine/assets/builtin/shaders/shadow-caster.shader`
|
||
- 接收端采样
|
||
- `engine/src/Rendering/Pipelines/BuiltinForwardPipeline.cpp`
|
||
- `engine/assets/builtin/shaders/forward-lit.shader`
|
||
- `project/Assets/Shaders/Toon.shader`
|
||
|
||
## 4. 已完成阶段
|
||
|
||
### Phase 0：阴影参数契约正式化
|
||
|
||
已完成，目标是先把原来散落在不同位置的 shadow 参数收成正式数据契约。
|
||
|
||
对应提交：
|
||
|
||
- `2ee74e7` `rendering: formalize main light shadow params`
|
||
|
||
完成结果：
|
||
|
||
- MainLight shadow 的 map metrics / sampling 数据有了明确结构。
|
||
- 规划层到运行时数据链路不再依赖匿名 float 参数拼装。
|
||
|
||
### Phase 1：bias 设置正式化并接入 ShadowCaster
|
||
|
||
已完成，目标是把 caster bias 和 receiver bias 的职责拆清楚，并让 ShadowCaster 真正消费运行时设置。
|
||
|
||
对应提交：
|
||
|
||
- `1d6f2e2` `rendering: formalize main light shadow bias settings`
|
||
|
||
完成结果：
|
||
|
||
- 新增 `DirectionalShadowSamplingSettings`
|
||
- 新增 `DirectionalShadowCasterBiasSettings`
|
||
- planner 能输出 sampling / caster bias 默认值
|
||
- `ShadowCaster` pass 不再依赖 shader 内部写死的 `Offset`
|
||
- forward / toon 接收端继续消费统一的 shadow sampling contract
|
||
|
||
## 5. 根因判断
|
||
|
||
### 5.1 自阴影严重的根因
|
||
|
||
当前 acne 的根因不是单一问题，而是以下几项叠加：
|
||
|
||
1. caster bias 与 receiver bias 原先没有清晰契约，调参入口混乱。
|
||
2. receiver 端 normal bias 和 depth bias 默认值没有经过系统标定。
|
||
3. caster 端深度偏移之前由 shader 写死，无法和场景尺度、shadow map texel 尺度统一调整。
|
||
|
||
### 5.2 阴影锯齿严重的根因
|
||
|
||
当前接收端虽然已经做了一个固定 3x3 手写采样，但效果仍然偏糙，原因主要是：
|
||
|
||
1. 当前仍然是单张 shadow map，分辨率预算有限。
|
||
2. 阴影采样核是最基础的固定 3x3 box，没有更平滑的权重设计。
|
||
3. `BuiltinForwardPipeline` 里的 shadow sampler 目前仍是 point sampler。
|
||
4. 当前还没有专门面向“单张 MainLight 阴影可用性”的 filter 参数设计。
|
||
|
||
### 5.3 当前不应优先处理的方向
|
||
|
||
以下方向现在都不是第一优先级：
|
||
|
||
- 直接上级联阴影
|
||
- 直接引入更复杂的多光源阴影系统
|
||
- 先大改 planner 架构
|
||
|
||
原因很简单：如果当前单张阴影的 bias 和 filter 基线都没有站稳，上级方案只会把问题放大。
|
||
|
||
## 6. 下一阶段执行顺序
|
||
|
||
## Phase 2：建立可用的 bias 基线
|
||
|
||
这是下一步最高优先级。
|
||
|
||
目标：
|
||
|
||
- 明显压住自阴影 acne
|
||
- 不引入明显 peter-panning
|
||
- 让不同材质和几何体至少达到“能看”的单张阴影结果
|
||
|
||
本阶段只调这四个核心参数：
|
||
|
||
- `DirectionalShadowCasterBiasSettings.depthBiasFactor`
|
||
- `DirectionalShadowCasterBiasSettings.depthBiasUnits`
|
||
- `DirectionalShadowSamplingSettings.receiverDepthBias`
|
||
- `DirectionalShadowSamplingSettings.normalBiasScale`
|
||
|
||
执行要点：
|
||
|
||
1. 先以默认值为基线做小步调参，不再混用 shader 内固定 offset。
|
||
2. 先看 caster bias 是否足以压掉大面积 acne，再看 receiver bias 是否还需要补偿。
|
||
3. `normalBiasScale` 只用于削减掠射角表面 acne，不能把它当成主修复手段。
|
||
4. 调参顺序优先保证“角色和常见静态模型表面不脏”，再控制阴影悬浮。
|
||
|
||
验收标准：
|
||
|
||
- 球、立方体、角色模型等常见几何体上没有大片自阴影脏斑。
|
||
- 接触阴影没有整体漂浮一截。
|
||
- forward-lit 与 toon 两条接收路径结果一致性不回退。
|
||
|
||
## Phase 3：升级单张阴影采样质量
|
||
|
||
这个阶段才开始处理“大块锯齿”。
|
||
|
||
目标：
|
||
|
||
- 让当前单张 MainLight shadow 的边缘从“块状锯齿”变成“有限预算下可接受的软化边缘”
|
||
|
||
优先处理项：
|
||
|
||
1. 升级当前固定 3x3 box 采样，不再停留在最基础平均核。
|
||
2. 明确是否继续走跨后端一致的手写 PCF，还是为 comparison sampler 单独补后端支持。
|
||
3. 如果继续保持跨后端一致性优先，则先做更好的手写 PCF 核，再评估 comparison sampler。
|
||
|
||
本阶段建议的最小落地方案：
|
||
|
||
- 先保留单张 shadow map
|
||
- 先保留当前主链结构
|
||
- 把 receiver 端阴影采样从固定 3x3 平均核升级为更稳定的 PCF 核
|
||
- 如有必要，再补 `filterRadiusInTexels` 一类的正式参数
|
||
|
||
验收标准：
|
||
|
||
- 阴影边缘不再呈现明显的 1-bit 台阶块状感。
|
||
- 角色和场景静态物体阴影边缘的可读性明显提升。
|
||
- 不因为滤波升级导致阴影整体发灰或漏光严重。
|
||
|
||
## Phase 4：单张方向光阴影稳定性收口
|
||
|
||
在 bias 和 filter 达到可用以后，再收口稳定性问题。
|
||
|
||
目标：
|
||
|
||
- 降低相机轻微移动时的 shadow crawl / shimmering
|
||
|
||
重点项：
|
||
|
||
1. 审查当前 shadow camera 拟合结果是否需要 texel snapping。
|
||
2. 审查 ortho bounds 与 focus point 的稳定性。
|
||
3. 重新评估 `boundsPadding` / `minDepthPadding` / `minDepthRange` 的默认值是否过保守或过激进。
|
||
|
||
说明：
|
||
|
||
这一阶段仍然是“单张 MainLight 阴影修好”，不是进入级联阴影。
|
||
|
||
## Phase 5：为后续级联阴影预留演进点
|
||
|
||
只有前面几个阶段都稳定后，才进入这一阶段。
|
||
|
||
目标：
|
||
|
||
- 让当前单张 MainLight 阴影实现不阻塞未来 CSM 演进
|
||
|
||
需要预留但暂不展开的点：
|
||
|
||
- split 数据结构
|
||
- 每级 shadow map / sampler / matrix contract
|
||
- 接收端 cascade 选择逻辑
|
||
- 级联间过渡和稳定化
|
||
|
||
## 7. 推荐的提交切分
|
||
|
||
后续建议按下面的提交粒度推进：
|
||
|
||
1. `rendering: tune main light shadow bias defaults`
|
||
2. `rendering: improve main light shadow receiver filtering`
|
||
3. `rendering: stabilize single-map directional shadow fitting`
|
||
|
||
## 8. 当前结论
|
||
|
||
当前正确的下一步不是“直接做级联阴影”，而是：
|
||
|
||
1. 先把 bias 默认值标定到可用区间。
|
||
2. 再把当前接收端采样升级成真正可用的单张 shadow filter。
|
||
3. 最后再处理单张阴影稳定性。
|
||
|
||
只有这三步完成，当前 MainLight 阴影才算真正脱离“占位实现”。
|