docs: archive old plans

docs/plan/MainLight方向光阴影修复计划_2026-04-13.md

@@ -1,227 +0,0 @@
-# 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 阴影才算真正脱离“占位实现”。

docs/used/MainLight方向光阴影修复计划_2026-04-13.md

@@ -0,0 +1,356 @@
+# MainLight 方向光阴影修复计划（归档）
+
+日期: `2026-04-13`
+
+状态: `已归档到 docs/plan/used`
+
+## 1. 文档定位
+
+这份文档记录本轮 `MainLight` 单张方向光阴影修复工作的执行结果、参数含义和后续边界。
+
+需要明确：
+
+- 本轮目标是先把单张 `MainLight` 阴影从“占位实现”修到“基本可用”。
+- 本轮明确不做 `CSM`、点光阴影、聚光阴影和多光源阴影编排。
+- 本轮完成后，后续如果继续推进大范围覆盖质量问题，应单开 `CSM` 专项计划。
+
+## 2. 修复前的问题定义
+
+修复前的核心问题有两个：
+
+1. 自阴影过重，表面出现明显 `acne`。
+2. 阴影边缘呈现大块锯齿，单张阴影图完全不可用。
+
+这些问题在修复前同时叠加在：
+
+- `caster` 端深度偏移没有正式参数契约。
+- `receiver` 端 bias 没有稳定基线。
+- 单张阴影图覆盖范围过大，近处 `texel density` 太低。
+- 接收端采样只有基础方案，阴影边缘完全是硬台阶。
+
+## 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` 偏移
+  - `engine/src/Rendering/Passes/BuiltinDepthStylePassBaseResources.cpp`
+  - `engine/include/XCEngine/Rendering/Materials/RenderMaterialStateUtils.h`
+  - `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`
+- 面板与参数归属
+  - `engine/include/XCEngine/Components/LightComponent.h`
+  - `engine/src/Components/LightComponent.cpp`
+  - `editor/src/ComponentEditors/LightComponentEditor.h`
+
+## 4. 本轮已落地结果
+
+### Phase 0：阴影参数契约正式化
+
+已完成。
+
+对应提交：
+
+- `2ee74e7` `rendering: formalize main light shadow params`
+
+完成结果：
+
+- `MainLight shadow` 的 `map metrics / sampling` 数据有了正式结构。
+- 规划层到运行时数据链路不再依赖匿名 `float` 参数拼装。
+
+### Phase 1：bias 设置正式化并接入 ShadowCaster
+
+已完成。
+
+对应提交：
+
+- `1d6f2e2` `rendering: formalize main light shadow bias settings`
+- `00875e0` `rendering: tune main light shadow bias defaults`
+
+完成结果：
+
+- 新增 `DirectionalShadowSamplingSettings`
+- 新增 `DirectionalShadowCasterBiasSettings`
+- `ShadowCaster` pass 正式消费运行时 `caster bias`
+- `forward-lit / toon` 接收端继续消费统一的 `sampling contract`
+- 默认值基线已经收敛到当前可用区间
+
+当前默认基线：
+
+- `receiverDepthBias = 0.0010f`
+- `normalBiasScale = 2.0f`
+- `shadowStrength = 0.85f`
+- `depthBiasFactor = 2.5f`
+- `depthBiasUnits = 4`
+
+### Phase 2：单张阴影图覆盖范围收紧
+
+已完成到“单图可用化”阶段。
+
+对应提交：
+
+- `95edf04` `rendering: stabilize single-map directional shadow fitting`
+
+完成结果：
+
+- `receive-only` 物体不再参与方向光阴影拟合包围。
+- 单张阴影图默认分辨率从 `1024` 提升到 `2048`。
+- `maxFocusDistance` 从 `64.0f` 收紧到 `32.0f`。
+- `boundsPadding` 进一步从 `1.0f` 收紧到 `0.5f`。
+
+当前 planner 侧有效默认值：
+
+- `mapDimension = 2048`
+- `minFocusDistance = 5.0`
+- `maxFocusDistance = 32.0`
+- `minDepthRange = 20.0`
+- `boundsPadding = 0.5`
+- `minDepthPadding = 2.0`
+
+说明：
+
+- 这一步本质上是在提升单张阴影图的有效 `texel density`。
+- 它不能替代 `CSM`，但在不做 `CSM` 的前提下，这是当前最值当的单图修复手段。
+
+### Phase 3：receiver 端滤波升级
+
+已完成当前阶段的最小落地。
+
+对应提交：
+
+- `adb6fe4` `rendering: improve main light shadow receiver filtering`
+
+完成结果：
+
+- `forward-lit.shader` 与 `Toon.shader` 已统一切到更稳定的手写 `PCF`。
+- 当前滤波的作用是软化既有阴影台阶，不再让边缘完全是 `1-bit` 硬切。
+
+说明：
+
+- `PCF` 有作用，但它只能软化边缘，不能凭空增加几何细节。
+- 单张阴影图的覆盖范围和 `texel density` 仍然是大块感的主因。
+
+### Phase 4：MainLight 面板调参入口接通
+
+已完成，当前工作区已接通。
+
+完成结果：
+
+- `Directional Light` 在开启 `Cast Shadows` 后，会出现 `Override Shadow Params` 开关。
+- 打开后，可以在灯光面板直接调整当前最关键的 5 个阴影参数。
+- 参数已挂到 `LightComponent`，并接通序列化 / 反序列化。
+- `SceneRenderRequestPlanner` 会在主方向光开启覆盖时优先读取该灯光上的阴影参数。
+
+重要限制：
+
+- 这些覆盖参数当前只作用在被选为 `MainLight` 的方向光上。
+- 它们不是“所有灯统一生效”的全局参数。
+- `mapDimension / focusDistance / boundsPadding / minDepthPadding` 这类拟合参数仍然属于 planner 侧全局参数，没有塞进 `LightComponent`。
+
+## 5. 面板参数完整说明
+
+当前在 `Directional Light + Cast Shadows + Override Shadow Params` 条件下，会暴露以下 5 个参数。
+
+### 5.1 Receiver Depth Bias
+
+作用位置：
+
+- `receiver` 端 shader。
+- 本质上是在阴影比较前，把当前像素的 `receiverDepth` 略微往“更靠前”方向偏移。
+
+作用目的：
+
+- 抑制自阴影 `acne`。
+
+调大后的结果：
+
+- 更不容易长 `acne`
+- 但接触阴影更容易发飘、漏光
+
+调小后的结果：
+
+- 阴影更贴物体
+- 但更容易重新出现 `acne`
+
+适用场景：
+
+- 主要用于小幅微调，不应作为主修复手段。
+
+### 5.2 Normal Bias Scale
+
+作用位置：
+
+- `receiver` 端 shader。
+- 采样位置沿法线方向推开，且偏移量与 `shadow texel world size` 挂钩。
+
+作用目的：
+
+- 重点压制掠射角表面的 `acne`。
+
+调大后的结果：
+
+- 角色曲面、斜面更不容易脏
+- 但阴影边缘更容易从物体表面脱开
+
+调小后的结果：
+
+- 阴影更贴
+- 但掠射角面更容易重新长脏斑
+
+适用场景：
+
+- 用于补掠射角问题，不应替代 `caster bias`。
+
+### 5.3 Shadow Strength
+
+作用位置：
+
+- `receiver` 端最终混合阶段。
+
+作用目的：
+
+- 纯视觉强度控制，不参与几何修正。
+
+调大后的结果：
+
+- 阴影更黑、更实
+
+调小后的结果：
+
+- 阴影更淡、更灰
+
+说明：
+
+- 它不会解决 `acne`，也不会解决锯齿，只改观感。
+
+### 5.4 Depth Bias Factor
+
+作用位置：
+
+- `ShadowCaster` pass 的 `slope-scaled depth bias`。
+
+作用目的：
+
+- 对有斜率的表面提供更强的投射端深度偏移。
+
+调大后的结果：
+
+- 更能压住 `caster` 端 `acne`
+- 但更容易出现 `peter-panning`
+
+调小后的结果：
+
+- 阴影更贴
+- 但斜面 `acne` 更容易回来
+
+适用场景：
+
+- 是 `caster bias` 的主调参项之一。
+
+### 5.5 Depth Bias Units
+
+作用位置：
+
+- `ShadowCaster` pass 的常量 `depth bias`。
+
+作用目的：
+
+- 作为基础兜底偏移，对低斜率面和平面也生效。
+
+调大后的结果：
+
+- 平面更不容易脏
+- 但阴影也更容易整体悬浮
+
+调小后的结果：
+
+- 阴影更贴地
+- 但基础 `acne` 更容易冒出来
+
+适用场景：
+
+- 适合作为 `Depth Bias Factor` 的辅助项。
+
+## 6. 推荐调参顺序
+
+建议按下面顺序调：
+
+1. 先调 `Depth Bias Factor`
+2. 再调 `Depth Bias Units`
+3. 再用 `Normal Bias Scale` 补掠射角表面问题
+4. `Receiver Depth Bias` 只做小幅微调
+5. 最后再调 `Shadow Strength`
+
+这样做的原因是：
+
+- 先把 `caster` 端基线压稳，能更系统地治 `acne`
+- 再用 `receiver` 端去补细节，而不是反过来拿大量 `receiver bias` 去硬顶
+
+## 7. 常见症状与对应调法
+
+如果出现下面这些问题，优先这样处理：
+
+### 症状 1：表面一片脏斑，自阴影很重
+
+优先操作：
+
+- 小幅增加 `Depth Bias Factor`
+- 必要时小幅增加 `Depth Bias Units`
+
+### 症状 2：角色曲面、斜面还是脏
+
+优先操作：
+
+- 小幅增加 `Normal Bias Scale`
+
+### 症状 3：阴影离脚、接触处发飘
+
+优先操作：
+
+- 先降低 `Depth Bias Factor / Depth Bias Units`
+- 再降低 `Normal Bias Scale / Receiver Depth Bias`
+
+### 症状 4：只是觉得阴影太浅或太黑
+
+优先操作：
+
+- 直接调 `Shadow Strength`
+
+## 8. 本轮结论
+
+本轮单张 `MainLight` 阴影修复已经完成“从占位实现到可用基线”的目标，当前结果可以概括为：
+
+1. 自阴影 `acne` 已经被压到可接受范围。
+2. 单张阴影图的覆盖范围已经显著收紧，近处密度明显提升。
+3. `PCF` 已经接入，阴影边缘不再完全是硬切台阶。
+4. 最关键的 5 个参数已经暴露到方向光面板，后续可直接做小步视觉标定。
+
+仍需明确：
+
+- 单张阴影图的大范围覆盖问题不会被彻底解决。
+- 这一类问题的正式解法仍然是 `CSM`。
+- 但 `CSM` 不应建立在一套不稳定的单图 `bias / filter / fit` 基线上。
+
+因此，本轮工作的正确归档结论是：
+
+- 单张 `MainLight` 阴影修复已完成本阶段目标。
+- 后续如继续推进，应以 `CSM` 为新阶段目标重新立项，而不是继续在这份单图修复计划上扩写。