threejs-scalable-real-time-shadows

可扩展实时阴影

方向光阴影是一个拟合问题：拟合能够覆盖所需遮挡物到接收面的光线的最小光空间表示，然后将工作量投入接收面实际使用的投影、滤波和更新。

$threejs-choose-skills 是可选的多系统协调器。使用 $threejs-visual-validation 获取捕获／回读证据。

1. 选择一种拓扑

对比使用相同种子工作负载、投影、滤波和接收面策略的方案：

Gate	首个 r185 WebGPU 分支	成本拓扑
有界接收面／遮挡物体积通过世界空间纹素和深度精度门槛	一个 DirectionalLight 阴影	一个视图、一张深度纹理、一次滤波计算
相机深度覆盖范围持续变化	CSMShadowNode	L 个阴影视图／贴图；通常启用一个滤波器，淡入淡出时启用两个
一个固定正交覆盖范围在空间上进行分区	TileShadowNode	一个深度数组、N 次后端层渲染通道、N 次包含性测试，以及一个联合渲染列表，其中每个遮挡物都可能在每一层绘制
超大覆盖范围持续存在，且实测复用在失效后仍有收益	自定义缓存式裁剪贴图	L 个持久层级；选择性更新；L 个可移植滤波器，或一个／两个经目标平台验证的数组／图集滤波器
遮挡物每帧都会大范围变形或变化	一个拟合阴影、CSM，或同一光源下静态／动态拆分	缓存失效接近完整重绘。

核心阴影和 Tile 阴影目标会在深度附件旁保留带颜色的附件；VSM 会增加分布／模糊资源和渲染通道。TileShadowNode 会一同更新所有层，并非持久化的分块缓存。

将重要数值归类为：根据边界／方程得出的 Derived、表达意图的 Authored、限制条件 Gated，或目标平台的 Measured 证据。

**完成标准：**根据实测的绘制／光栅化／接收面／绑定／复用压力选定一种拓扑，每个被否决的方案都有未通过的门槛，且选择不受照搬的贴图尺寸、层级数、偏差值或毫秒级承诺驱动。

2. 拟合投影、纹素、滤波和偏差

• 将 XY 拟合到所需的偏置接收面坐标，并加上滤波、对齐和覆盖范围保护。将 Z 独立拟合到接收面及其光线上的每个遮挡物；XY 纹素宽度不能确定有效的 Z 量化单位。
• 使用稳定的方向光基向量和全局／光源锚点。将每个已提交的中心以单一确定性量化器对齐到固定的 dx/dy 网格。基向量／符号／锚点发生变化时，开启新的内容纪元。
• 根据实际的 Basic／PCF／PCFSoft／VSM 实现和后端推导滤波支持范围。在包含性范围内预留该支持范围，并确保混合时世界空间覆盖范围一致。
• 将 normalBias 视为世界空间法线偏移，将 bias／biasNode 视为归一化比较深度偏移。分别推导和验证。

处理抖动、接缝、阴影痤疮或阴影悬浮时，请参阅投影、滤波和偏差机制。

**完成标准：**缓慢的亚纹素运动保持稳定；所有 XY／Z 边界始终有覆盖；滤波支持范围不会越出其作用域；并且在所选深度约定下，正面、掠射、薄接触和跨层级测试场景均通过。

3. 针对确切的 r185 实现进行门控

检查功能之前先初始化 WebGPU：

await renderer.init();
if ( renderer.backend.isWebGPUBackend !== true ) {
  throw new Error( 'Directional shadows require WebGPU.' );
}

在受影响的材质/光照图构建之前，通过 light.shadow.shadowNode 挂接自定义节点。运行时更改要求重新构建所有受影响的图和管线，并通过处置/重建检查。

使用 core、CSM、Tile、反向深度或自定义阴影钩子时，请阅读 r185 源码门控，了解克隆遗漏、深度比较、层行为、变换约定和生命周期注意事项。

完成条件： 修订版本/导入、后端/深度策略、相机所有权、阴影目标类型、层行为、材质绑定布局，以及每项已选内置功能的注意事项，都有固定场景诊断或被拒绝的配置。

4. 仅在选用时构建显式自定义缓存

每个层级都拥有独立状态：

desired  = next coverage request
rendered = center/range/content encoded into an inactive target
committed = exact valid target and parameters sampled by receivers
dirty    = desired coverage differs, while committed content may remain valid
invalid  = committed depth no longer represents required content

接收器只采样已提交状态。无效层级的权重为零；下一个有效的较粗层级继承剩余权重，未解析的外部覆盖区域则保持受光。正确性失效的优先级高于按时效/质量进行的刷新。

冻结期望中心、深度区间、基准系纪元和内容纪元；执行渲染；恢复渲染器状态；然后仅在重新检查内容、基准系和资源版本未被取代后，原子提交中心、区间、目标/层、矩阵和已渲染纪元。保留较新的失效状态。滤波、法线偏移和渐隐更改也必须在复用前重新验证受保护的覆盖范围及依赖资源。在当前呈现封存后编码的工作使用非活动资源代次，并提交到下一次呈现；先前已提交的代次保持不可变，直到其使用者完成。

选用自定义缓存时，请先阅读 缓存状态、调度和采样约定，再开始实现。

完成条件： 已渲染元数据与其非活动目标一致；已提交元数据与接收器采样的资源一致；仅当已提交覆盖仍有效时，期望状态才与之不同；首次使用时状态无效；更新失败时仅保留仍正确的已提交状态；较晚的更新无法修改已采样的代次；且每个无效层级在修复前都不参与采样。

5. 使扫掠影响失效并保持投射体一致性

跟踪光照基准系；投射体的上一帧/当前帧变换；几何体/LOD；可见性、层和投射标志；Alpha/遮罩/覆盖范围；变形包络；资产/区块代次；以及资源标识。合并或扫掠投射体上一帧/当前帧的保守轮廓，使已离开和新占据的阴影深度都失效。

中心变化可能与每个嵌套完整映射相交。如果重绘开销过高，则使用不重叠的归属区域、分页驻留、代理或同一光照/阴影节点内的动态叠加层。第二个定向光会造成光照重复。

可见通道和阴影通道共享局部空间变形以及 Alpha/覆盖范围。positionNode 和 castShadowPositionNode 是局部空间钩子；receivedShadowPositionNode 是世界空间接收器查找钩子，需单独验证。

关于失效事件表、接收器影响扫掠和一致性约定，请阅读扫掠失效与投射体一致性。

当其他系统提供光照/投射体运动、重基准或呈现节奏时，使用前需绑定单位、坐标系、当前/上一帧采样时间、权威来源、版本、资源代次、有效性、陈旧性和重置条件。阴影缓存仍是其期望、脏、无效、已渲染和已提交状态的唯一写入方。

完成条件： 每项内容依赖都映射到重绘、仅采样更新或无操作；每个移动/变形的投射体都会使其扫掠的旧/新影响失效；并且可见轮廓/投射体轮廓一致性通过变形、蒙皮、实例化、批处理、面朝向、层和 Alpha 覆盖范围的检查。

6. 验证持续运行行为和生命周期

记录已提交的覆盖范围/权重、光照深度、过滤支持、偏差、无效回退、投射物一致性、绑定布局、目标清单和固定最终视图。测试摄像机缓慢移动；所有 XY/Z 边界；跨层级淡入淡出；局部和大范围失效；光照基变化；调整大小/DPR；多摄像机使用；更新尖峰/积压；以及释放/重新创建。

测量预热且热状态稳定时的 CPU/GPU 帧分位数、阴影视图绘制次数和三角形数量、顶点/光栅/Alpha 开销、接收器过滤评估次数、遍历、分配、绑定、无效覆盖范围和更新尖峰。针对测得的瓶颈进行优化，而非拓扑代理指标。

有关绑定/资源清单、工作负载公式和验收门槛，请阅读绑定、工作负载和验证。

**完成条件：**渲染输出与所选基线及诊断原因相符；绝不采样已失效的过期内容；适配器和产品余量门槛通过；持续帧数和尖峰门槛通过；并且分离节点、目标/纹理、克隆的阴影/灯光、存储、监听器和调试资源后，各项计数器恢复至基线。

所有权

此技能负责方向阴影投影、过滤/偏差、投射物一致性、缓存状态/失效、接收器采样和阴影诊断。场景所有者提供投射物/灯光输入；管线所有者负责共享输出，以及因阴影内容改变而导致的时域辐射拒绝。