3d-sky-rays

3D 天光射线

让光线看起来像是穿过场景中的缝隙。随着摄像机移动，屋顶边缘和枝叶应塑造出光束的形状。

适配现有渲染器

检查渲染器版本、渲染目标、alpha 用法、深度路径、色调映射和后期处理顺序。保留现有的 WebGL 或 WebGPU 后端。下面的着色器方案描述的是 WebGL 屏幕空间效果；使用 WebGPU 时，请在项目的节点／渲染管线中实现等效效果。

天空、射线光源和方向光照应使用同一个归一化世界空间方向，且方向指向太阳。如果美术方向刻意让可见太阳与光照太阳的位置有所偏移，请在一处记录并控制该偏移。

构建考虑遮挡的射线渲染通道

1. 在线性 HDR 中渲染场景颜色。获取用于识别天空开放区域的蒙版：天空为白色，不透明遮挡物为黑色。在蒙版渲染通道中匹配枝叶的 alpha 遮罩和顶点运动，避免叶片变成实心矩形。
2. 专用天空蒙版是通用性更好的默认方案。仅当所有前置渲染通道都保留场景 alpha 的含义时，才将复用场景 alpha 作为优化方案：天空 alpha 为 0，不透明几何体 alpha 为 1。透明玻璃、粒子、画布合成和 AO 都可能破坏这一约定；请直接检查蒙版。
3. 沿太阳方向从摄像机投影一个点。使用投影坐标前，先排除位于摄像机后方的光源。将 NDC 转换为 UV：uv = ndc.xy * 0.5 + 0.5；并考虑管线中的纹理方向。
4. 对每个射线缓冲区像素，朝太阳 UV 方向步进。采样天空可见度，并乘以高于 HDR 阈值的天空亮度。累积衰减后的采样值，并除以权重总和，使采样数量变化时曝光保持不变。
5. 排除超出蒙版纹理范围的 UV。太阳远离屏幕时，逐渐淡出效果；将采样坐标钳制到边缘会产生亮带。太阳刚好位于画面外时，留出少量过扫描边距会有帮助。
6. 在最终色调映射／输出变换之前，将射线颜色以加法方式合成到线性场景颜色中。如果后续渲染通道需要输入 alpha，请予以保留。

核心累积过程的伪代码：

step = (pixelUV - sunUV) * density / sampleCount
sampleUV = pixelUV - step * jitter
sum = 0; weightSum = 0; weight = 1
repeat sampleCount times:
    sampleUV -= step
    if sampleUV is inside the texture:
        energy = max(luminance(scene(sampleUV)) - threshold, 0)
        sum += min(energy, energyCap) * skyMask(sampleUV) * weight
    weightSum += weight
    weight *= decay
rays = sum / max(weightSum, epsilon)

使用考虑宽高比的源点距离计算径向衰减。任何角度变化都应宽泛而微妙；场景遮挡应提供大部分结构。在不透明的前景表面上，强烈衰减屏幕空间叠加效果，以保留木材和石材的对比度。这是一种美术近似，不能替代基于深度积分的体积散射。

优先调整效果，再优化成本

从较低的太阳高度、偏暖的中性色调、清晰可见的缝隙和克制的强度开始调试。从屋脊后方和树冠间观察。画面泛白通常意味着强度过高或蒙版有误，而不是泛光不足。

可先尝试约 24–48 个采样点和半分辨率射线缓冲区；只有在可见条带确实需要改善时才增加采样点。Seijaku 的参考实现使用 72 个采样点，这只是一个参考选择，并非最低画质要求。平滑的噪声抖动可以减少条带，但动画抖动可能导致闪烁；对于静止画面或减少动态效果的视图，请使用稳定噪声，除非支持时间累积。

效果贡献为零时跳过该渲染通道。随绘制缓冲区调整其缓冲区大小，并释放已替换的目标；测量启用和禁用射线时额外增加的 GPU／帧耗时。避免在渲染循环中同步读取 GPU 数据。

验证

• 屋顶和叶片轮廓能明显打断光束；枝叶周围没有矩形光晕。
• 背对太阳时效果消失，且不会出现反向光源或闪光。
• 进入室内时仍能保留表面对比度；无关的自发光物体不会变成太阳。
• 摄像机环绕、竖屏尺寸调整、黄昏场景和静止的减少动态效果帧都保持稳定。
• 桌面端和移动端检查包括着色器错误、帧耗时和实际射线缓冲区大小。

参考资料

有关源代码和渲染器的文档，请阅读 REFERENCES.md。在 Seijaku 中，检查 GodRayShader、makePost 和投影源更新逻辑。其 alpha 蒙版约定依赖完整的渲染管线；不要单独照搬这一假设。