threejs-image-pipeline

name	threejs-image-pipeline
description	Coordinate Three.js WebGPU/TSL final-image graphs. Use when effects share scene-pass signals or output ownership, when choosing MRT versus reconstruction or narrow passes, when admitting temporal history, or when whole-graph budgets and lifetimes decide the design.

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.

1. Fix the baseline

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.

2. Inventory signals

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

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.

3. Admit attachments

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:

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.

4. Admit 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.

5. Compose once

Use this default order:

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.

6. Own toggles, size, and lifetime

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.

7. Prove the graph

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.