threejs-image-pipeline

图像流水线

构建一个因果图像图：一个包含深度的 HDR 场景通道、选定的共享信号，以及一次最终输出转换。只有在测得的替代方案表现更差时，才添加场景遍历或附件。

为每个纳入的效果指定原子负责人：

• $threejs-ambient-contact-shading 负责 GTAO 和间接光合成；
• $threejs-bloom 负责眩光源选择和 BloomNode 控件；
• $threejs-exposure-color-grading 负责测光、自适应、色调映射和 LUT 域；
• $threejs-dynamic-surface-effects 负责功能局部的屏幕历史；
• $threejs-visual-validation 负责捕获、计时和生命周期证据。

1. 确定基线

声明物理画布像素尺寸、目标浏览器/GPU、帧预算、主要视觉约定，以及清晰可读的无后期处理视图。初始化一个 WebGPURenderer，确认 renderer.backend.isWebGPUBackend，创建一个 RenderPipeline，并让一个 pass(scene, camera) 负责场景线性 HDR 和深度纹理。请求 GPU 计时前，先设置 trackTimestamp，然后再调用 renderer.init()。

当基线无需可选后期处理即可渲染、HDR 和深度的生成器均已命名，且恰好只有一个组件负责呈现时，此步骤即完成。

2. 清点信号

对每个候选信号——HDR 颜色、深度、法线、自发光、速度、漫反射/基础颜色、ID、历史记录、曝光和 UI——记录：

writer | readers | mathematical/color domain | physical format and extent
first write -> last read | history/reset owner | disable path

将深度视为通道深度纹理，而非 MRT 颜色输出。仅请求有实际读取方的信号。

当图中每条边都只有一个写入方、所有使用方对域和范围达成一致，且每个可选信号都有可用的禁用路径时，此步骤即完成。

3. 纳入附件

首先排除任何无法满足信号所声明的域、精度/误差界限、空间覆盖范围、时间稳定性或丢弃语义的重建、附件或窄范围重渲染候选方案。然后，在目标图上比较剩余的正确方案：

costMRT(a) = export + store/resolve + all later reads
costAlt(a) = reconstruction or narrow rerender + its traffic

当配对证据表明，在正确候选方案中 costMRT(a) < costAlt(a)，且峰值驻留预算仍达标时，保留该附件。检查编译后的物理格式：r185 中，具名 PassNode 附件默认会克隆通道输出，因此只有经过显式配置和验证后，才能使用紧凑法线或速度存储。

当每个保留的附件都有具名读取方、经过验证的域和物理格式、声明的误差/覆盖约定、测量后胜出的正确替代方案，以及已核算的峰值字节数时，此步骤即完成。

实现 pass()、MRT、紧凑格式或深度分支时，请阅读图构建与信号格式。

4. 纳入时间历史

只有在所有渲染的运动都具备有效的前一帧和当前帧呈现状态后，才启用时间输出：

• 刚体变换、实例、骨骼和程序化变形；
• 粒子进入历史记录时具有稳定的粒子／槽位身份；
• 未抖动的前一帧／当前帧相机变换，以及唯一的抖动所有者；
• 深度、速度、邻域和越界拒绝；
• 针对调整大小／DPR、切镜、投影或原点变更、场景加载、生成／销毁、传送、重新挂接、LOD／拓扑变更和不连续变形进行重置；
• 当前帧、历史、被拒绝的历史、速度、抖动和重置诊断信息。

r185 速度为 currentNDC - previousNDC；TRAA 会通过负 Y 缩放将其转换为 UV。Stock TRAANode 要求颜色／深度／速度／输入的尺寸一致，并关闭 MSAA。它的普通分支无法保留现有的相机视图偏移，也无法保留任意指定的纹理所有者。应明确处理首帧和边界行为，不要假设调整大小逻辑能证明两者都已处理。合成时间输入会生成另一张纹理并执行一次全屏绘制。Stock TRAA 没有公开的通用重置接口或响应式蒙版输入，因此切镜和不连续情况需要有依据的重建或旁路／重新播种策略。

当水平和垂直运动都能正确重投影、每种渲染表示都有速度策略、每种不连续情况都会触发可执行的重置，并且每个时间分配都有所有者时，此步骤即告完成。

存在时间重建时，在创建速度或历史节点之前，请阅读时间准入与重置。

为支持的重置重建 Stock TRAANode 时，请阅读最小重建示例，了解其经公开 API 验证的替换方案、公开设置保留、输出重新绑定、防护式回滚、图失效，以及明确的新旧所有权。 只有在替换图成功编译／渲染且前一 GPU 代次已完成后，才退役返回的前一节点。

5. 只合成一次

使用以下默认顺序：

HDR scene pass + depth + admitted MRT
  -> effect-local lighting histories
  -> lighting/AO/atmosphere with valid temporal inputs
  -> temporal scene-radiance resolve, when admitted
  -> excluded transparent or refractive layers
  -> meter tap from resolved pre-bloom HDR, when admitted
  -> bloom and other scene-linear optical effects, when admitted
  -> fixed or adapted exposure, when admitted
  -> tone map, when admitted
  -> LUT in its declared domain, when admitted
  -> one output conversion
  -> display-domain AA, dither, diagnostics, and UI

默认在稳定的预曝光场景辐射度中保留历史。应用 Bloom 所有者的不透明、覆盖裁剪或保留光晕的 Alpha 分支；未更改的源 Alpha 无法保留表面之外的光晕。如果由 renderOutput() 负责呈现，请设置 renderPipeline.outputColorTransform = false；更改任何输出节点后，请设置 renderPipeline.needsUpdate = true。

当每个已使用的测光、Bloom、曝光、色调映射、LUT、Alpha 操作和输出转换都只有一个所有者，并且每个透明／折射图层都有明确的位置时，此步骤即告完成。

选择 LUT／输出收尾方式或处理透明 Alpha 时，请阅读颜色、Alpha 与合规的收尾方式。

6. 管理开关、尺寸和生命周期

统计内置 BloomNode、GTAONode、TRAANode 和 PassNode 所拥有的持久私有目标。重新构建通道，以回收先前通过 getTextureNode() 请求的附件；逻辑 MRT 开关不会回收它。调整大小或更改 DPR 时，更新每个显式范围，并为所有受影响的历史记录重新设种。节点／管线的释放不会递归清理图；保留明确拥有的句柄，并在操作失败时通过 try/finally 恢复借用的状态。在 GPU 最后一次使用后，释放已移除的节点、通道、目标、材质和存储。

只有在固定 DPR 的图持续获得稳定计时后，才添加自适应 DPR。采用不对称驻留时间和冷却时间，区分固定工作与按像素缩放的工作，并在尺寸变化后重新测量每个质量档位。

当每个受支持的开关、尺寸、档位和准入资源都经过反复循环后，资源计数趋于稳定，且每次图变更都会将管线标记为脏，此步骤即告完成。

估算流量、私有目标驻留、边际成本或自适应 DPR 时，请阅读 内存、计时和自适应分辨率。

7. 验证图

捕获无后期处理基线、每个准入信号、每个准入时序／测光／泛光／色彩分支的诊断结果、最终输出，以及物理目标清单。测量完整预热后的图；对于准入的备选方案，仅在场景状态相同的情况下测量成对边际变体。执行适用的负向控制：禁用每个受支持的可选效果，强制触发每个准入历史记录所拥有的重置类别，调整准入尺寸相关资源的大小，并销毁／重新创建图。

当捕获、计时范围、重置、输出隔离或生命周期控制失败时，请阅读诊断与故障特征。

当每个受支持的发布档位都保留视觉契约、完整图和常驻目标均满足声明的预算、输出隔离确认仅进行一次输出转换且在准入时仅进行一次色调映射、每个准入时序分支和轴的诊断均通过，并且释放后的生命周期计数趋于稳定时，管线即告完成。