threejs-image-pipeline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Image Pipeline

图像管线

Build one causal image graph: one HDR scene pass with depth, selected shared signals, and one final output conversion. Add a scene traversal or attachment only when its measured alternative is worse.

Use the atomic owner for each admitted effect:

```
$threejs-ambient-contact-shading
```
for GTAO and indirect-light composition;
```
$threejs-bloom
```
for glare source selection and
```
BloomNode
```
controls;
```
$threejs-exposure-color-grading
```
for metering, adaptation, tone mapping, and LUT domains;
```
$threejs-dynamic-surface-effects
```
for feature-local screen history;
```
$threejs-visual-validation
```
for capture, timing, and lifecycle evidence.

构建一个因果图像图：一个包含深度信息的HDR场景通道、选定的共享信号，以及一次最终输出转换。仅当实测显示替代方案效果更差时，才添加场景遍历或附加项。

为每个引入的特效指定原子所有者：

```
$threejs-ambient-contact-shading
```
用于GTAO和间接光照合成；
```
$threejs-bloom
```
用于眩光源选择和
```
BloomNode
```
控制；
```
$threejs-exposure-color-grading
```
用于测光、自适应调整、色调映射和LUT域；
```
$threejs-dynamic-surface-effects
```
用于特征局部屏幕历史；
```
$threejs-visual-validation
```
用于捕获、计时和生命周期验证。

1. Fix the baseline

1. 修复基准线

Declare physical canvas pixels, target browser/GPU, frame budget, primary visual contract, and a readable no-post view. Initialize one

WebGPURenderer

, confirm

renderer.backend.isWebGPUBackend

, create one

RenderPipeline

, and make one

pass(scene, camera)

own scene-linear HDR plus its depth texture. Set

trackTimestamp

before

renderer.init()

when GPU timing is requested.

This step is complete when the baseline renders without optional post, the HDR and depth producers are named, and exactly one component owns presentation.

声明物理画布像素、目标浏览器/GPU、帧预算、主要视觉约定，以及一个可读的无后期处理视图。初始化一个

WebGPURenderer

，确认

renderer.backend.isWebGPUBackend

，创建一个

RenderPipeline

，并让一个

pass(scene, camera)

拥有场景线性HDR及其深度纹理。当需要GPU计时时，在

renderer.init()

之前设置

trackTimestamp

。

当基准线在无可选后期处理的情况下完成渲染、HDR和深度生成器已命名，且恰好有一个组件负责画面呈现时，此步骤完成。

2. Inventory signals

2. 盘点信号

For every candidate signal—HDR color, depth, normal, emissive, velocity, diffuse/base color, IDs, histories, exposure, and UI—record:

text

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

Treat depth as the pass depth texture rather than an MRT color output. Request only signals with a real reader.

This step is complete when every graph edge has one writer, all consumers agree on domain and extent, and every optional signal has a working disable path.

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

text

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

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

当每个图像图边缘都有一个写入者、所有消费者在域和范围上达成一致，且每个可选信号都有可用的禁用路径时，此步骤完成。

3. Admit attachments

3. 引入附加项

First reject any reconstruction, attachment, or narrow-rerender candidate that cannot meet the signal's declared domain, precision/error bound, spatial coverage, temporal stability, or discard semantics. Compare the remaining correct candidates on the target graph:

text

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

Keep the attachment when paired evidence shows

costMRT(a) < costAlt(a)

among the correct candidates and the peak resident budget still passes. Inspect compiled physical formats: r185 named

PassNode

attachments clone the pass output by default, so compact normal or velocity storage exists only after explicit configuration and verification.

This step is complete when every retained attachment has a named reader, verified domain and physical format, declared error/coverage contract, measured winning correct alternative, and accounted peak bytes.

When implementing

pass()

, MRT, compact formats, or depth branches, read Graph construction and signal formats.

首先拒绝任何无法满足信号声明的域、精度/误差范围、空间覆盖、时间稳定性或丢弃语义的重建、附加项或窄通道重渲染候选方案。在目标图像图上比较剩余符合要求的候选方案：

text

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. Admit temporal history

4. 引入temporal history

Enable temporal output only after all rendered motion has valid previous and current presentation state:

rigid transforms, instances, bones, and procedural deformation;
stable particle/slot identity where particles enter history;
unjittered previous/current camera transforms and one jitter owner;
depth, velocity, neighborhood, and out-of-bounds rejection;
resets for resize/DPR, cut, projection or origin change, scene load, spawn/despawn, teleport, reparent, LOD/topology change, and discontinuous deformation;
current, history, rejected-history, velocity, jitter, and reset diagnostics.

r185 velocity is

currentNDC - previousNDC

; TRAA converts it to UV with a negative Y scale. Stock

TRAANode

requires matching color/depth/velocity/input extents and MSAA off. A composite temporal input materializes another texture and fullscreen draw. Stock TRAA has no public general reset or reactive-mask input, so cuts and discontinuities require an evidenced rebuild or bypass/reseed policy.

This step is complete when horizontal and vertical motion reproject correctly, every rendered representation has a velocity policy, each discontinuity fires an executable reset, and every temporal allocation has an owner.

When temporal reconstruction is present, read Temporal admission and resets before creating velocity or history nodes.

When stock

TRAANode

is rebuilt for a supported reset, read the minimal rebuild example for its public-API replacement, output rebind, graph invalidation, and explicit old/new ownership. Retire the returned previous node only after the replacement graph has compiled/rendered successfully and the prior GPU generation has completed.

仅当所有渲染的运动都具备有效的先前和当前呈现状态时，才启用时间输出：

刚体变换、实例化、骨骼和程序变形；
粒子进入历史记录时具备稳定的粒子/插槽标识；
无抖动的先前/当前相机变换，且有一个抖动所有者；
深度、速度、邻域和越界拒绝；
针对窗口大小调整/DPR变化、镜头切换、投影或原点更改、场景加载、生成/销毁、传送、重父化、LOD/拓扑变化以及不连续变形的重置机制；
当前、历史、被拒绝的历史、速度、抖动和重置诊断。

r185版本中的速度为

currentNDC - previousNDC

；TRAA会将其转换为带有负Y轴缩放的UV。原生

TRAANode

要求颜色/深度/速度/输入范围匹配，且MSAA关闭。复合时间输入会生成另一个纹理和全屏绘制。原生TRAA没有公开的通用重置或反应遮罩输入，因此镜头切换和不连续变化需要经过验证的重建或绕过/重新种子策略。

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

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

当为支持重置而重建原生

TRAANode

时，请阅读最小重建示例，了解其公开API替代方案、输出重新绑定、图失效以及显式的新旧所有权。仅当替代图像图成功编译/渲染，且先前的GPU世代完成后，才可以停用返回的旧节点。

5. Compose once

5. 一次性合成

Use this default order:

text

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

Keep history in stable pre-exposure scene radiance by default. Add bloom RGB while preserving scene alpha. If

renderOutput()

owns presentation, set

renderPipeline.outputColorTransform = false

; after any output-node change, set

renderPipeline.needsUpdate = true

This step is complete when every present meter, bloom, exposure, tone map, LUT, alpha operation, and output conversion has one owner, and every transparent/refractive layer has an explicit position.

When choosing a LUT/output ending or handling transparent alpha, read Color, alpha, and legal endings.

使用以下默认顺序：

text

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

默认将历史记录保存在稳定的曝光前场景辐射中。在保留场景alpha的同时添加bloom RGB。如果

renderOutput()

负责画面呈现，请设置

renderPipeline.outputColorTransform = false

；在任何输出节点更改后，设置

renderPipeline.needsUpdate = true

。

当每个当前的测光、bloom、曝光、色调映射、LUT、alpha操作和输出转换都有一个所有者，且每个透明/折射层都有明确的位置时，此步骤完成。

在选择LUT/输出结尾或处理透明alpha时，请阅读颜色、alpha与合法结尾。

6. Own toggles, size, and lifetime

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

Count persistent private targets owned by built-in

BloomNode

GTAONode

TRAANode

, and

PassNode

. Rebuild the pass to reclaim an attachment previously requested with

getTextureNode()

; a logical MRT toggle does not reclaim it. On resize or DPR change, update every explicit extent and reseed all affected histories. Dispose removed nodes, passes, targets, materials, and storage after their final GPU use.

Add adaptive DPR only after the fixed-DPR graph has sustained timings. Use asymmetric dwell and cooldown, distinguish fixed from pixel-scaled work, and remeasure every quality tier after a size change.

This step is complete when repeated cycles for every supported toggle, size, tier, and admitted resource stabilize resource counts, and every graph mutation marks the pipeline dirty.

When estimating traffic, private target residency, marginal cost, or adaptive DPR, read Memory, timing, and adaptive resolution.

统计由内置

BloomNode

、

GTAONode

、

TRAANode

和

PassNode

拥有的持久私有目标。重建通道以回收之前通过

getTextureNode()

请求的附加项；逻辑MRT开关不会回收该附加项。在窗口大小调整或DPR变化时，更新所有显式范围并重新种子所有受影响的历史记录。在最终GPU使用后，释放已移除的节点、通道、目标、材质和存储。

仅当固定DPR的图像图持续稳定运行后，才添加自适应DPR。使用非对称停留和冷却机制，区分固定工作与像素缩放工作，并在尺寸变化后重新测量每个质量层级。

当每个支持的开关、尺寸、层级和引入资源的重复循环使资源计数稳定，且每个图像图变更都标记管线为脏状态时，此步骤完成。

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

7. Prove the graph

7. 验证图像图

Capture the no-post baseline, each admitted signal, the diagnostics for each admitted temporal/meter/bloom/color branch, final output, and physical target inventory. Measure the complete warmed graph and paired marginal variants only for admitted alternatives at identical scene state. Exercise the applicable negative controls: disable each supported optional effect, force each reset class owned by an admitted history, resize admitted size-dependent resources, and destroy/recreate the graph.

When a capture, timing scope, reset, output-isolation, or lifecycle control fails, read Diagnostics and failure signatures.

The pipeline is complete when every supported shipping tier preserves the visual contract, the full graph and resident targets meet declared budgets, output isolation shows one output conversion and—when admitted—one tone map, diagnostics pass for every admitted temporal branch and axis, and lifecycle counts plateau after disposal.

捕获无后期处理的基准线、每个引入的信号、每个引入的时间/测光/bloom/颜色分支的诊断信息、最终输出以及物理目标清单。仅针对相同场景状态下的引入替代方案，测量完整预热后的图像图和配对的边际变体。执行适用的阴性控制：禁用每个支持的可选特效、强制每个由引入历史记录拥有的重置类别、调整引入的尺寸相关资源大小，以及销毁/重建图像图。

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

当每个支持的发布层级都保留视觉约定、完整图像图和驻留目标符合声明的预算、输出隔离显示一次输出转换以及（若引入）一次色调映射、每个引入的时间分支和轴的诊断通过，且生命周期计数在释放后趋于稳定时，管线即完成。