three-rs 0.3.0

A port of three.js core and its WebGPURenderer to Rust on wgpu, graded against three.js's own end-to-end pixel comparison.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
# Post-processing (rung 9)

Ports of `three.js/src/renderers/common/RenderPipeline.js`,
`src/renderers/common/QuadMesh.js` and `src/nodes/display/PassNode.js`, as the
`webgpu_postprocessing_masking` example exercises them.

## The shape

```rust
let base  = PassNode::new();
let mask1 = PassNode::new();
let mask2 = PassNode::new();

let mut compose = base.node();
compose = mask1.a().mix(compose, texture(&texture1));
compose = mask2.a().mix(compose, texture(&texture2));

let mut render_pipeline = RenderPipeline::new();
render_pipeline.output_node = Some(compose);

// each frame
base.render(&mut renderer, &mut base_scene, &mut camera);
mask1.render(&mut renderer, &mut mask_scene1, &mut camera);
mask2.render(&mut renderer, &mut mask_scene2, &mut camera);
render_pipeline.render(&mut renderer);
```

## `PassNode`

`pass( scene, camera )` owns a `RenderTarget` of `HalfFloatType` (so
`rgba16float`) plus its **own** `DepthTexture` named `depth` — three targets
means three depth textures, not one shared one. `updateBefore()` sizes the
target to the drawing buffer, sets `renderTarget.samples = renderer.samples`,
and does `setRenderTarget( rt ); render( scene, camera ); setRenderTarget( prev )`.

Two structural facts, both visible in the dumped WGSL:

* `PassNode` is a `TempNode` whose `setup()` returns a `PassTextureNode`, which
  is a `TempNode` too. So a pass emits **two** vars —
  `nodeVar0 = textureSample( … ); nodeVar1 = nodeVar0;` — and `.a` is taken on
  the outer one (`nodeVar4.w` in the dump). The port models this as
  `to_var( None, texture_uv( rt.texture(), uv() ) )`.

  **Two vars, but only when the graph holds the pass itself.** A `TempNode`
  earns a var at usage two, and `PassTextureNode.setup()` builds its `passNode`
  — that is the second usage. `pass( scene, camera )` composed directly (radial
  blur, ssaa, and `bloom( … )`, which is a pass-like `TempNode` of its own) is
  that case. `passNode.getTextureNode( name )` is not: the graph holds the
  `PassTextureNode`, the `PassNode` is built only from its `setup()`, and the
  sample lands in **one** var. `PassNode::node()` is the first;
  `PassNode::texture_node( name )` is the second. `m03` and `m12` of
  `webgpu_postprocessing_bloom_selective`'s dump show both in one example.
* `PassTextureNode` calls `setUpdateMatrix( false )`, so a pass samples the raw
  `uv()` varying. `texture( map )` does not, so each JPEG contributes a
  `mat3x3<f32>` to the object uniform block. That asymmetry is what produces the
  dump's binding interleave `0,1 / 2,3 / 4 = object buffer / 5,6 / 7,8 / 9,10`.

### Divergence: who fires `updateBefore`

three.js collects the graph's `updateBefore` nodes while the quad's material is
built and fires them from *inside* the quad's own render, which is why the
canvas `beginRenderPass` is the first thing in the API trace even though the
nested passes execute first. The nested renders use their own command encoders
and are submitted before the canvas pass's encoder.

The port did this by hand until #162: the application called
`PassNode::render` before `RenderPipeline::render`. Now the pass holds its
scene and camera (`pass( scene, camera )`, as `Rc<RefCell<…>>`), and the
renderer fires it from the quad's draw behind the `FRAME` guard, as three
does (`docs/nodes.md` §57). The explicit `render` was a deprecated forward
for one release and is removed in 0.2.0 (`docs/api.md` decision 10).

## `RenderPipeline`

`RenderPipeline` is a `QuadMesh` whose material is named `RenderPipeline` and
whose `fragmentNode` is `renderOutput( outputNode, toneMapping,
outputColorSpace )` when `outputColorTransform` is true (the default).

`render()` saves the renderer's tone mapping and output colour space, sets them
to `NoToneMapping` / the working colour space, draws the quad, and restores.
With both neutral, `Renderer.needsFrameBufferTarget` is **false**, so the quad
draws straight into the `rgba8unorm` canvas and there is no second output pass:
the unpremultiply → sRGB OETF → premultiply sandwich lives in the quad's own
shader. In the port that is `Renderer::with_neutral_output`, which flips the
`neutral_output` flag `needs_frame_buffer_target()` reads.

The quad is a full-screen **triangle**: positions come from the material's
`vertexNode` (`array<f32,3>( -1, -1, 3 )[ vertexIndex ]` etc.), so the only
vertex buffer is the `uv` attribute at stride 8 — and the draw is a non-indexed
`draw( 3, 1, 0, 0 )`. Its canvas pass still carries a `depth24plus` attachment
and the pipeline still declares `less-equal` / `depthWriteEnabled: true`, which
is what three.js does.

## Clear colour and alpha

`WebGPURenderer`'s `alpha` parameter defaults to `true`, so
`Renderer._clearColor` is `(0, 0, 0, 0)` — **not** opaque black. `Background.update()`
then either leaves it alone (`scene.background === null`) or, for a `Color`
background, copies the colour and forces alpha to 1 and a clear.

At rung 9 that zero alpha is the entire masking effect: the two mask scenes have
no background, so their `rgba16float` targets clear to `(0, 0, 0, 0)` and only
the box and torus texels have `a == 1`. The base scene's
`new Color( 0xe0e0e0 )` is converted sRGB → linear on the CPU by
`Color.setHex`, giving the clear value `0.7454042095350284` that the target,
being linear `rgba16float`, wants.

Fixing this (the port previously used an opaque-black clear) moved
`webgpu_instance_mesh` from 45 to 60 differing pixels — which is exactly what
three.js itself scores against that reference JPEG, so the port now agrees with
three.js rather than with the old accident.

## Materials

`new Mesh( geometry )` with no material gets `new MeshBasicMaterial()`, which
under `WebGPURenderer` is a `MeshBasicNodeMaterial`: white, opaque, front side,
depth test and write on. The renderer supplies it rather than panicking.

## Single-pass effect nodes (`webgpu_postprocessing_radial_blur`)

An effect from `three.js/examples/jsm/tsl/display/` is a node graph, not a
renderer feature: `radialBlur( textureNode, options )` is one `Fn()` that reads
the pass texture several times and returns a colour. The port keeps those in
`src/nodes/display/` **inside the main crate**, not in `addons/`, for that
reason — they need nothing but the node system.

`radial_blur( map, options )` mirrors the JS line for line: a `sampleUv` var, a
`base` const, a `blur` var, an `offset` const, a weight var `w`, the
interleaved-gradient-noise jitter, a node-bounded `Loop` and the final
`mix( blur, base.mul( 2 ), 0.5 )`. Three facts it pins down:

* **`Loop( { end: int( count ) } )` needs no new node kind.** `Node::Loop`'s
  count was already a `NodeRef`, so a uniform bound emits
  `for ( var i : i32 = 0; i < i32( object.nodeUniformN ); i ++ )`.
* **`uniform( int( 32 ) )` is an `f32` uniform.** `UniformNode` takes its type
  from the JavaScript value it is handed, which here is a *node*, so three.js
  falls back to float and the dump carries four `f32` object uniforms. The
  `i32` appears only at the loop bound.
* **The whole effect is wrapped in one `to_var()`.** `Node::Block` is not a
  kind the builder caches or promotes, so without the wrapper the statements
  would be emitted once per read of the result. `docs/nodes.md` §8.

### Tone mapping comes from the renderer, not from the quad

`RenderPipeline` captures `renderer.toneMapping` in its constructor and
re-checks it in `_update()`, *before* `render()` neutralises it for the draw.
So `renderer.toneMapping = NeutralToneMapping` set by the page ends up baked
into the quad's own `renderOutput( outputNode, toneMapping, outputColorSpace )`
— the tone mapper runs inside the post-processing shader, and the canvas still
needs no second output pass. `RenderPipeline::built_for` carries the tone
mapping alongside the output node's identity, so a steady frame is still a
cache hit and a change to `renderer.tone_mapping` rebuilds the quad's program
once.

## Effect nodes that own render targets (`webgpu_postprocessing_ssaa`)

`radialBlur` is a shader; `SSAAPassNode` is a *schedule*. It extends `PassNode`,
keeps a second render target of its own, and renders the scene eight times with
a sub-pixel jitter on the camera, accumulating the results additively into the
pass target that the `RenderPipeline` quad then samples. The port is
`src/renderer/ssaa_pass.rs`.

```rust
let mut ssaa_pass = SsaaPassNode::new();
render_pipeline.output_node = Some(ssaa_pass.node());
ssaa_pass.sample_level = 3;                       // 2^3 = 8 samples

// each frame
ssaa_pass.render(&mut renderer, &mut scene, &mut camera);
render_pipeline.render(&mut renderer);
```

`SsaaPassNode` *composes* a `PassNode` rather than extending one — Rust has no
inheritance, and `node()` / `texture()` forward to it — and, like `PassNode`, it
is fired by the application instead of from inside the quad's render, for the
ownership reason above.

### The schedule

Per sample `i` of `n`:

1. `camera.setViewOffset( w, h, ox + jitter.x * 0.0625, oy + jitter.y * 0.0625,
   w, h )` — the jitter is added to the offset the page already set, which is
   why the restore is a `setViewOffset` and not a `clearViewOffset`.
2. the weight uniform is set (below), the sample target is bound,
   `clear( true, true )`, then `render( scene, camera )`;
3. the accumulation target is bound; on `i == 0` only, it is cleared to
   `(0, 0, 0, 0)`; then the quad is drawn with additive blending.

That is 8 scene renders + 8 accumulation quads + 1 canvas quad = 17 draws
across 26 passes (9 of them clear-only), 2119689 triangles, 3 programs.

`_JitterVectors` is six tables of 1, 2, 4, 8, 16 and 32 offsets, all in
sixteenths of a pixel; `sampleLevel` indexes them and levels above 5 clamp to
the last. The weight of sample `i` is `1/n`, or, with `unbiased` (the default),

```
1/n + (1/32) * ( -0.5 + (i + 0.5)/n )
```

a spread around `1/n` that still sums to exactly 1 and hides the `rgba16float`
rounding of a flat `1/n`. The scout plan's table of the eight values is
arithmetically wrong (it steps by 3/512 and sums to 1.0547); the formula steps
by 1/256, and `the_eight_unbiased_sample_weights` in `ssaa_pass.rs` pins the
real values.

### `autoClear` and `clear()`

This is the first rung to need either. `Renderer.autoClear` decides whether a
render clears its target before drawing; `SSAAPassNode` turns it off for the
whole schedule, so all 17 draws carry `loadOp: "load"` and the only clears are
the explicit `renderer.clear( true, true )` calls — which are, in the port as in
three.js, a `beginRenderPass` with `loadOp: "clear"` and no draws at all.
`setClearColor` and `clear( color, depth )` are the three.js API, minus its
third `stencil` argument, which has no buffer behind it here. Every clear this
rung makes has a render target bound, so it is the bare pass; a `clear()` on the
canvas goes through the internal framebuffer target and ends in the output blit,
as `Renderer.clear()` does.

A scene with a `Color` background still clears, `autoClear` or not: three.js's
`Background.update()` forces the clear itself. The eight scene renders here have
no background, so `autoClear = false` is what keeps them from clearing.

**The accumulator's clear is alpha 0, not alpha 1.** The dumped pass descriptor
says `clearValue: (0, 0, 0, 1)`, but that is a serialization artifact of the
`renderContext` object three.js reuses across passes — the JS is
`setClearColor( 0x000000, 0.0 )`. The blend algebra decides it: the weights sum
to 1 and the blend is `one/one/add` on alpha too, so with the eight samples each
contributing `w * 1.0` the accumulator ends at alpha 1; starting from alpha 1
would end at 2, and the `unpremultiplyAlpha` in the quad would halve the colour.
The 0-pixel grade confirms it. (The scout plan says to reproduce the dumped
descriptor rather than the JS reading. On this line the plan is wrong.)

### `premultipliedAlpha` on the accumulation quad

The quad's material is `transparent`, `blending: AdditiveBlending`,
`premultipliedAlpha: true`, depth test and write off. `premultipliedAlpha`
changes two things: the blend factors become `one/one/add` on **both** colour
and alpha (rather than `srcAlpha/one`), and `NodeMaterial.setupOutput()` wraps
the output in `premultiplyAlpha()`. Since the fragment node is already
`unpremultiplyAlpha( texture( sample ) * weight )`, the pair cancels and the
sum is over straight colour — which is what makes the weights linear.

### The by-use cache clock counts frames, not renders

The by-use caches (`node_builder_states`, `buffers`) evict what has not been
used for `CACHE_GRACE_FRAMES` ticks. Ticking that clock once per *render* was
fine while a frame was one render; with nine renders per frame it evicted a
frame's own state mid-frame and rebuilt it, which
`steady_frame_builds_nothing` catches. The clock now advances only on a render
whose destination is the screen (`Renderer::begin_frame`) — nested target
renders belong to the frame they precede. Every render still sweeps: a geometry
the scene dropped should go on the render that notices. The grace window is
unchanged at 4, and so are the numbers in
`churning_geometry_and_materials_does_not_grow_the_caches`.

### Left out: the depth copy

three.js ends `updateBefore()` with
`renderer.copyTextureToTexture( this._sampleRenderTarget.depthTexture,
this.renderTarget.depthTexture )`, so that a later effect reading the pass's
`getTextureNode( 'depth' )` gets the last sample's depth rather than an
uninitialised texture. Nothing in this example reads it, the port has no
`copyTextureToTexture`, and the pass target's depth texture is simply never
written. An effect that chains depth off an SSAA pass needs that copy first.

## MRT: several colour attachments from one draw (`webgpu_postprocessing_bloom_selective`, part A)

`mrt( { output, bloomIntensity: float( 0 ) } )` names the values a draw
writes to a render target's several colour attachments. Three levels
are involved and all three are ported:

```rust
let pass = PassNode::new();
pass.set_mrt(mrt(vec![
    ("output", output_property()),
    ("bloomIntensity", float(0.0)),
]));
// asking for the node is what creates the attachment
let bloom_intensity = pass.texture_node("bloomIntensity");

// per material
material.mrt_node = Some(mrt(vec![("bloomIntensity", uniform_value(Type::F32, vec![1.0]))]));
```

* **The pass** holds the default. `PassNode::set_mrt` is
  `passNode.setMRT()`; the pass's `updateBefore()` hands it to the renderer
  for the duration of its own render and restores the previous one, as
  `PassNode.updateBefore()` does. `Renderer::set_mrt` / `mrt()` are
  `Renderer.setMRT()` / `getMRT()`.
* **The material** overrides it. `NodeMaterial.setup()` merges the two with
  the material's entries winning, which is how fifty spheres sharing one
  pipeline each get their own `bloomIntensity`.
* **The render target** decides the layout. `MRTNode.setup()` resolves each
  output *name* against `renderTarget.textures` and fills the members by
  attachment **index**, so the order the attachments were created in is the
  order of the `@location`s, and the dictionary's own order decides nothing.
  An output with no attachment of that name is dropped.

`PassNode::texture_node( name )` is `getTextureNode( name )`: it creates
the attachment on first ask and memoises the node. Naming an output in the
MRT does *not* create its attachment — three.js is the same, which is why
a page that sets an MRT and never samples the extra output renders
single-attachment.

### What the fragment stage emits

With an MRT in play the generated fragment stage takes three.js's other
output shape, `OutputStructNode`'s:

```wgsl
struct OutputType {
	@location( 0 ) m0 : vec4<f32>,
	@location( 1 ) m1 : vec4<f32>,
	
};
var<private> output : OutputType;
…
	Output = max( vec4<f32>( DiffuseColor.xyz, DiffuseColor.w ), vec4<f32>( 0.0 ) );
	output.m0 = Output;
	output.m1 = vec4<f32>( object.nodeUniform2 );

	// result

	return output;
```

The struct's *name* changes too (`OutputStruct` → `OutputType`), and the
member names are `m0`, `m1`, … — that is three's own branch, not an
accident, and `examples/dump_wgsl.rs`'s `bloom_selective_scene` section is
byte-identical to `m01_fragment_fragment.wgsl` of the scout's dump.

Two details are load-bearing:

* **The assignments are in the flow, not in the result section.**
  `OutputStructNode.generate()` pushes one `output.mN = …` line per member
  and returns the struct's name, so the entry point ends at a bare `return
  output;`.
* **`Output` is analysed once, not twice.** Without an MRT the basic output
  is reached both by the `Output` property and by `output.color`, which is
  what gives it a var of its own. Here the MRT's `output` member reads the
  *property* back, so the output node is reached only by the property
  assignment and stays inlined into it — which is exactly what the dump
  shows. It is the same rule a custom `material.output_node` already had.

Everything else on the ladder is untouched: with no MRT set the fragment
stage is the old `struct OutputStruct { @location( 0 ) color }` and one
`output.color = …`. All 184 pre-existing `dump_wgsl` sections are
byte-identical across this change.

### The pass and the pipeline

A pass gets one colour attachment per `renderTarget.textures` entry, all
sharing the pass's clear op, and a pipeline one `ColorTargetState` per
attachment. The attachment *count* is part of `RenderState`, so a program
drawn into a one-attachment pass and into an MRT pass gets two pipelines
rather than a validation error.

`MRTNode.blendModes` and `MRTNode.clearColors` — three's per-output blend
mode and clear colour — are not ported. Every MRT material here is opaque,
where three's `MaterialBlending` and `NoBlending` both come out as no
blend state at all, and nothing on this ladder sets a per-output clear.
MSAA and MRT never meet either: a `PassNode` with an MRT is `samples: 0`,
so only attachment 0 can have a resolve target.

## `BloomNode`: eleven render targets and twelve quads (`webgpu_postprocessing_bloom_selective`, part B)

`bloom( input )` is the UnrealBloomPass as a node
(`examples/jsm/tsl/display/BloomNode.js`): a luminosity high pass, five
mip levels each blurred horizontally and then vertically with a separable
Gaussian, and a composite that adds the five mips back together. It is the
third and largest of the effect-node shapes in this document — an effect
that owns render targets *and* several materials of its own.

```rust
let mut bloom_pass = bloom(output_pass.mul(bloom_intensity_pass));
// once per frame, before the output quad
bloom_pass.render(&mut renderer);
render_pipeline.output_node = Some(render_output(
    scene_pass.texture_node("output").add(bloom_pass.node()),
    ToneMapping::Neutral,
));
```

### The twelve passes

`BloomNode.updateBefore()`, which the renderer runs (§57 of `docs/nodes.md`), is `resetRendererState` (no MRT, an
opaque black clear colour, `autoClear` on), then the high pass into
`bright`, then for each of the five mips a horizontal pass into `h[i]` and
a vertical one into `v[i]`, then the composite back into `h0` — which is
the texture `node()` samples. Every one of the twelve is a single
attachment with no depth, because all eleven targets are
`depth_buffer: false`, and every one clears: the quad covers the target
anyway, but `autoClear` is what three.js leaves on here.

### Sizes are floored, not rounded

`setSize()` is `Math.floor( width * resolutionScale )` and then
`Math.floor( res / 2 )` per mip. At 800×500 and the default half scale
that is 400×250, 200×125, 100×**62**, 50×**31**, 25×15 — `floor( 125 / 2 )`
is 62 where rounding would give 63, and the chain diverges from there
down. `src/nodes/display/bloom.rs`'s `the_mip_chain_is_floor_halved` is
the gate; the scout plan's "rounding, not integer division" reading of the
dumped sizes is wrong about the rule and right about the numbers.

### Ten separable materials, five programs' worth of WGSL

three.js swaps `separableBlurMaterial.colorTexture.value` between the
horizontal and the vertical pass of a mip, so one material serves both. A
`Texture` is an identity in this port and a material's graph names it, so
`BloomNode` builds **two** blur materials per mip, one per direction. Their
generated WGSL is the same text — that is what the five
`bloom_separable_N` sections of `dump_wgsl` diff against `m05..m09` — so
the divergence is ten pipelines where three.js has five, not a different
shader.

### The high pass is replaceable

`BloomNode::with_high_pass` takes the function three.js keeps in
`bloomNode.highPassFn`. It is a constructor argument rather than a field
because the port has no `setup()` stage to rebuild the quad materials in:
the materials are built once, in `new`. `webgpu_postprocessing_bloom` and
`_anamorphic` are the callers that will pass their own.

### `uniformArray`

The composite's five bloom tint colours are one `uniformArray`, not five
uniforms: `uniform_array_vec3()` gives a handle whose `element( i )` all
read the same binding, emitted as

```wgsl
struct NodeBuffer_0Struct { value : array< vec4<f32>, 5 > };
```

with each `Vector3` padded to a `vec4` exactly as
`UniformArrayNode.js` does. The five bloom *factors* beside them are a
`array_var()` — a `var<private> nodeVar0 : array< f32, 5 >` written once
and indexed five times, which is what three's `array( [ … ] )` const
becomes when it is read more than once.

## The previous frame (`webgpu_postprocessing_difference`)

`passNode.getPreviousTextureNode( name )` is the frame *before* this one on
that output. Three keeps two textures per name and swaps them in
`toggleTexture( name )`, which `updateBefore()` runs for every such name
**before** it renders — so the very first frame draws into one of the pair and
the "previous" node points at the other, which nothing has ever rendered into.
The zero-initialised texture is what the graded frame of
`webgpu_postprocessing_difference` actually sees: its `| previous − current |`
is `| 0 − current |`, i.e. the whole image saturated. Rendering the previous
buffer, or toggling after the render rather than before, gives a different
picture that still looks plausible.

### Divergence: the swap is on the texture, not on the node

three.js swaps the two `Texture` objects inside the render target and rebuilds
whatever was keyed on them. A `NodeRef` here is immutable and
`texture_uv( texture, uv() )` holds its handle for good, so the port swaps the
**GPU textures behind the two handles** (`Texture::swap_gpu`) and leaves both
identities — and every bind group, pipeline and cache key on them — alone.
`bind_groups()` and `texture_view()` build a fresh view per draw per frame, so
no cached view can go stale, and the rung's second and third frames build
nothing. The previous texture is registered on the render target
(`RenderTarget::add_previous_texture`) so that `prepare_render_target`
allocates and resizes it with the attachments, but it is never itself a colour
attachment.

`getTextureNode( name )` is also *not* `pass( … )` used as a value: it is the
inner `PassTextureNode` on its own, so it emits one var and no
`nodeVarN = nodeVarM;` copy. `webgpu_postprocessing_masking` takes the first
form and this rung the second; both dumps show the difference.

## No pass at all (`webgpu_postprocessing_direct`)

Everything above puts the output transform on a quad of its own: render the
scene into a target, then draw one triangle that reads the target, applies
`renderOutput()` and writes the canvas. `DirectRenderPipeline` is the other
arrangement — **no target, no quad**. The transform is compiled into the end
of every material's fragment shader, and the frame is just the scene's draws
straight to the canvas.

```rust
let mut pipeline = DirectRenderPipeline::new();
pipeline.output_node = Some(vec4_join(vec![
    saturation(output_property().rgb(), saturation_factor),
    output_property().a(),
]));
pipeline.render(&mut renderer, &mut scene, &mut camera);
```

The mechanism is a hook on the material setup rather than a node in a graph.
`DirectRenderPipeline::render()` builds `render_output( output_node,
tone_mapping )` once, hands it to the renderer as an
[`OutputContext`](crate::materials::OutputContext), renders with tone mapping
and output colour space neutralised — so the renderer itself adds no output
pass — and takes the hook back off. `NodeMaterial::setup()` does what three's
`getOutput` closure does: assign the material's result to the `Output`
property, then build the hook's node *in its place*, which reads `Output` back
and assigns it again. Hence the doubled `Output = nodeVarN;` at the top of the
tail, which is in three's dump too.

Because it is a field of `SetupContext`, the hook is part of the program cache
key by construction: the same material drawn with and without it compiles two
programs, and neither can be served from the other's slot. The node itself is
memoised on the pipeline, so a steady frame builds nothing.

### What gets the hook

three.js decides inside the closure (`if ( renderer.isOutputTarget === false
&& renderer.getRenderTarget() !== null ) return materialOutputNode`). The port
decides on the renderer, before any material is set up: the hook is applied
only when the render is going to the canvas (`self.render_target.is_none()`),
and shadow passes pass `output: None` explicitly. Same set of materials, one
place to read it.

### The background stops being a clear colour

A solid `scene.background` is normally the clear value. Under a direct
pipeline it would be the one thing in the frame that skipped the transform
every material now applies — a visibly wrong backdrop. `_getBackgroundNode()`
substitutes `uniform( color )` for the duration of the render, which promotes
the background to a real quad draw whose fragment shader carries the same
tail. The port swaps `scene.background` for `Background::Node` and restores it
afterwards, memoising one uniform node per colour so the quad's program stays
a cache hit.

### Why it is not the default

It saves a full-screen colour target and a full-screen draw, and pays for them
by changing what blending means: every material now writes display-referred,
tone-mapped colour, so anything blending against the framebuffer blends in the
wrong space and a transmissive material sampling the framebuffer reads the
wrong values. `outputColorTransform = false` (hand tone mapping down instead
of baking it), the XR direct target and the `onBeforePipeline` /
`onAfterPipeline` callbacks are not ported; nothing on the ladder uses them.
## `rtt()`: a node that is its own render target (`webgpu_postprocessing_anamorphic`, `webgpu_postprocessing_ca`)

`src/nodes/display/rtt.rs` is `src/nodes/utils/RTTNode.js`. `rtt( node )`
hands back a texture node whose texture is a render target it owns: the node
becomes a full-screen quad's `fragmentNode`, the quad is drawn into the target
once a frame, and everything downstream samples the result rather than
re-evaluating the graph.

`webgpu_postprocessing_anamorphic` is the rung that needs it and shows why.
Its high pass reads the bright pass **eighty times** along x. Without the
`rtt()` those eighty taps would each inline the whole
`mix( vec4( 0 ), scenePass, smoothstep( … ) )`, including eighty samples of
the scene texture; with it they are eighty samples of one 800x500 half-float
texture, and the bright pass is computed once.

`webgpu_postprocessing_ca` reaches the same node by the other door.
`chromaticAberration( node, … )` does not sample its argument: it calls
`convertToTexture( node )` first, which is `rtt( node )` whenever the node is
not already a texture. The effect reads its input at four different uvs, so a
graph passed straight in would be evaluated four times per pixel instead of
once. The page also sets `renderPipeline.outputColorTransform = false`, because
the `renderOutput()` is *inside* the RTT pass; leaving it on applies the output
transform twice, which is a plausible-looking image and a failing one.

Three things about the target are not `BloomNode`'s:

* **It keeps a depth buffer.** `new RenderTarget( w, h, { type: HalfFloatType,
  ...options } )` — an `rtt()` caller passes no `depthBuffer`, so it defaults
  to `true`. Three's dump has the matching `depth24plus` beside the
  `rgba16float`, and the port allocates it for the same reason: to match, not
  because the quad reads it.
* **It carries its own sampler wrapping.** `rtt( node, null, null, { wrapS,
  wrapT } )`, and the anamorphic page passes `MirroredRepeatWrapping` on both
  axes. See `docs/webgpu_postprocessing_anamorphic-progress.md` for why the
  dump makes that look untrue and why it is.
* **It is a `TextureNode`, not a pass.** `super( renderTarget.texture, uv() )`
  gives the base class a non-null uv node, so `setUpdateMatrix( uvNode === null )`
  leaves the uv matrix off. An `rtt()` tap therefore carries no `mat3x3`
  uniform, which is why `RttNode::sample` is built on `texture_uv` rather than
  `texture_sample`.

### Who fires it

Since #162 the renderer fires `RTTNode.updateBefore()` from inside the render
that samples the texture, as three does (`docs/nodes.md` §57). The anamorphic
example's `animate()` is `renderPipeline.render()` alone. The output quad's
draw pulls the anamorphic chain: `bright_pass` pulls `scene_pass` in turn.
That submits `scene_pass`, `bright_pass`, the bloom, and the output quad, in
three's submit order. `webgpu_postprocessing_ca` is the same: the scene pass,
the RTT pass, the pipeline. `RttNode::render`, the explicit forward this
relied on before #162, was removed in 0.2.0 (`docs/api.md` decision 10).

### `fullscreenPass` and `currentSamples`

`webgpu_postprocessing_anamorphic` is the first example on the ladder that
asks for `antialias: true` *and* draws a quad straight to the canvas. Three's
`Renderer.currentSamples` returns 0 when `renderContext.fullscreenPass` is
set, so the final `RenderPipeline` quad is never multisampled even though the
scene pass behind it is; the port now has the same branch
(`Renderer::fullscreen_pass`, set around `render_quad`). Without it the canvas
would get an MSAA resolve texture three's dump does not have.

## MSAA and the output quad (`webgpu_postprocessing_bloom`)

`Renderer.currentSamples` has three branches, not two:

```js
let samples = this._samples;
if ( this._renderTarget !== null ) samples = this._renderTarget.samples;
else if ( this.needsFrameBufferTarget ||
          this._currentRenderContext?.fullscreenPass === true ) samples = 0;
```

The port had the first two. The third is set by `_renderScene()` from
`scene.isQuadMesh === true`, so **any** full-screen quad drawn to the canvas is
single-sample, whatever `antialias` asked for. It has to be: the texture the
quad samples was resolved when its own pass ended, so multisampling the quad
would cost four shader invocations a pixel to average four identical samples,
and the canvas colour attachment would need a resolve target it has no other
use for.

Until this rung the branch was unreachable. Every graded example's last draw is
either three's own output blit or a `RenderPipeline` quad under tone mapping,
and both of those go through the internal framebuffer target — so
`needsFrameBufferTarget` had already returned 0 and no canvas pass had ever run
multisampled. `webgpu_postprocessing_bloom` is the first page to combine
`new WebGPURenderer( { antialias: true } )` with a `RenderPipeline`:
`RenderPipeline::render` neutralises the tone mapping (the transform moves into
the quad's own `fragmentNode`), `needsFrameBufferTarget` goes false, and the
quad lands on the canvas with the renderer's `samples` still 4. On this adapter
a 4x canvas attachment with a resolve target renders black, and the graded
frame is black with it.

`Renderer` carries `fullscreen_pass`, set and restored around `render_quad()`
and around `render_output()`'s quad. The `PassNode`'s own scene render is
unaffected: it binds a render target, so it takes the first branch and keeps
`renderTarget.samples`, which the pass's `sync_before_build` and its own
`updateBefore()` both keep at `renderer.samples()` (`docs/nodes.md` §57.5).
That is where this page's antialiasing actually happens — the scene is drawn
4x into the pass target and resolved before bloom ever samples it.

## Velocity and motion blur (`webgpu_postprocessing_motion_blur`)

`velocity` is one more MRT member, which is where three puts it too:

```rust
scene_pass.set_mrt(mrt(vec![
    ("output", output_property()),
    ("velocity", velocity()),
]));
let vel = scene_pass.texture_node("velocity").mul(blur_amount);
let m_blur = motion_blur(&scene_pass.texture(), vel, 16);
```

Nothing about the attachment is new. `PassNode` creates it by name, as it
creates `bloomIntensity` (above), and the renderer gives it the pass target's
`rgba16float`. Two things are new:

- **The previous frame.** `velocity` needs last frame's model, view and
  projection matrices, and a skinned mesh needs last frame's bones. The
  renderer keeps them, and `docs/nodes.md` §62 describes how. The pass's MRT
  is what turns on the skinned path. `PassNode`'s render sets the renderer's
  MRT before it draws the scene, so `needsPreviousData()` sees `velocity`
  while the pass is drawing. The output quad has no velocity and pays
  nothing.
- **`motion_blur( input, velocity, numSamples )`** is `MotionBlur.js`. It
  takes a centre tap, then `numSamples` taps from `uv - velocity / 2` to
  `uv + velocity / 2`, and divides by `numSamples`. As in three, the centre
  tap is not in the count. A still pixel therefore comes out 17/16 as bright
  at 16 samples. The port keeps that for parity.

The rung's graded frame is the page's first, so its velocity is zero. The
rung shows that this composes. `tests/velocity_frames.rs` shows the motion.

## Temporal anti-aliasing (`webgpu_postprocessing_traa`)

TRAA reads the scene pass's colour, depth and `velocity`, and it needs the
pipeline as well as the pass:

```rust
let scene_pass = pass(scene.clone(), camera.clone());
scene_pass.set_mrt(mrt(vec![
    ("output", output_property()),
    ("velocity", velocity()),
]));
let _ = scene_pass.texture_node("velocity"); // adds and links the attachment

let traa_node = traa(
    &scene_pass.texture(),
    &scene_pass.depth_texture(),
    &scene_pass.texture_named("velocity"),
    camera.clone(),
);
traa_node.attach(&mut render_pipeline);
render_pipeline.output_node = Some(traa_node.node());
```

`attach` is the one step three does not have. Three's `TRAANode.setup()`
installs the jitter on the pipeline itself, through `OnBeforeRenderPipeline`.
The port's nodes have no handle on the pipeline while they build, so the
caller hands it over. Without `attach` the camera never moves, the history
never gains new samples, and the output is the scene with a one-frame delay
through the resolve. `docs/api.md` §8 has the reasoning, and
`docs/nodes.md` §63 the frame order and where the history lives.

The camera has to be the pass's camera, and a `PerspectiveCamera`. Each
frame, TRAA renders its resolve quad and makes two GPU copies, one of colour
and one of depth, into the history. It allocates nothing per frame.

**There is no rung.** three lists `webgpu_postprocessing_traa` in its own e2e
exception list (`test/e2e/puppeteer.js`, under "Black screen"), so its page
is not graded upstream. The port is gated on the resolve shader against
three's dump, and on `tests/traa_frames.rs`, which checks over sixteen frames
that the silhouette blends while the inside and the background hold. The
example is in the native viewer (`viewer traa`).

## Screen-space shadows (`webgpu_postprocessing_sss`)

SSS marches from each pixel towards one light through a depth pre-pass, for
the contact shadows a shadow map is too coarse to resolve. The scene pass
multiplies the result into that light's colour:

```rust
let mut pre_pass = pass(scene.clone(), camera.clone());
pre_pass.set_transparent(false);
pre_pass.set_mrt(mrt(vec![("output", velocity())]));
let _ = pre_pass.texture_node("depth");

let scene_pass = pass(scene.clone(), camera.clone());

let sss_node = sss(&pre_pass.depth_texture(), camera.clone(), &dir_light);
sss_node.max_distance.set(vec![0.2]);
sss_node.set_use_temporal_filtering(true);

// `scenePass.contextNode = builtinShadowContext( sss.r, dirLight )`.
scene_pass.set_context_shadow(sss_node.sample(screen_uv()).x(), &dir_light);
```

The page then resolves the scene pass with TRAA, reading the pre-pass's
depth and velocity. The SSS node renders the pre-pass itself before its own
quad. The context reaches only the draws where `dir_light`'s shadow map
applies: the light casts shadows, the object receives them, and
`renderer.shadow_map_enabled` is on. Anywhere else the SSS has nothing to
multiply into, as in three. `clear_context_shadow()` is the page's "Scene
with Shadow Maps" mode. The target is `rgba8unorm`, not three's
`RedFormat`, so the sample is read with `.x()`. `docs/nodes.md` §71 has the
rest.

**There is no rung.** three lists `webgpu_postprocessing_sss` in its e2e
exception list ("Black screen"). The port is gated on the SSS quad and the
ground's shadow context against three's dump, and on
`tests/sss_frames.rs`, which renders a box on a floor with the light
behind it. The example is in the native viewer (`viewer postprocessing_sss`).
## Screen space global illumination (`webgpu_postprocessing_ssgi`)

`ssgi()` reads the scene pass's colour, depth and packed normals. It writes
two textures, an AO and a one-bounce GI, and the page composites them before
TRAA:

```rust
let scene_pass = pass(scene.clone(), camera.clone());
let mut scene_mrt = mrt(vec![
    ("output", output_property()),
    ("diffuseColor", diffuse_color()),
]);
scene_mrt.set_deferred("normal", || pack_normal_to_rgb(normal_view()));
scene_mrt.set("velocity", velocity());
scene_pass.set_mrt(scene_mrt);
let color = scene_pass.texture_node("output");
let diffuse = scene_pass.texture_node("diffuseColor");
let _ = scene_pass.texture_node("normal");
let _ = scene_pass.texture_node("velocity");

let gi_pass = ssgi(
    &scene_pass.texture(),
    &scene_pass.depth_texture(),
    &scene_pass.texture_named("normal"), // packed; ssgi() unpacks it
    camera.clone(),
);
gi_pass.slice_count.set(vec![2.0]);
gi_pass.step_count.set(vec![8.0]);

let composite = convert_to_texture(vec4_join(vec![
    color.xyz().mul(gi_pass.ao_node()).add(diffuse.xyz().mul(gi_pass.gi_node())),
    color.w(),
]));
let traa_node = traa(
    &composite.texture(),
    &scene_pass.depth_texture(),
    &scene_pass.texture_named("velocity"),
    camera.clone(),
);
traa_node.attach(&mut render_pipeline);
render_pipeline.output_node = Some(traa_node.node());
```

Every option of three's node is a public `SettableValue` on `SsgiNode`, so
the GUI's sliders are uniform writes. `set_use_temporal_filtering( false )`
holds the slice rotation and step offset still. The rotating slices are
meant to be resolved by TRAA, so when the page's checkbox turns temporal
filtering off, the page also drops TRAA and outputs the composite directly.

Each frame the node draws one quad into one two-attachment target. The AO
attachment is `R8Unorm`. The GI attachment is `Rg11b10Ufloat`. On an
adapter that cannot render it the node logs three's error and the effect
fails, as three's does: wgpu rejects the attachment. It allocates
nothing per frame. `docs/nodes.md` §69 has the divergences, and §66 the
`output_struct()` node it writes its two attachments with.

**There is no rung.** three lists `webgpu_postprocessing_ssgi` in its own e2e
exception list (`test/e2e/puppeteer.js`, under "Black screen"). The port is
gated on its SSGI, composite and TRAA resolve shaders against three's dump of
the page, and on `tests/ssgi_frames.rs`. That test checks the AO darkening
and the colour bleeding at a wall's foot, the temporal rotation, and that the
options are live. The example is in the native viewer (`viewer ssgi`).

## Depth of field

```rust
let dof_pass = dof(
    &scene_pass.texture(),
    scene_pass.view_z_node("depth"),
    focus_distance, // uniform( 500 )
    focal_length,   // uniform( 200 )
    bokeh_scale,    // uniform( 10 )
);
render_pipeline.output_node = Some(dof_pass.node());
```

`DepthOfFieldNode` owns six targets and draws nine quads per frame, run from
the first draw that samples `dof_pass.node()`, as TRAA's resolve is. It needs
nothing from the caller beyond the call. `docs/nodes.md` §66 has the passes
and the four graph pieces it brought: `outputStruct()`, red targets,
`uniformArray( Vector2[] )`, and a Gaussian through the CoC texture's uv
matrix.

**There is no rung for it**, for TRAA's reason: three lists
`webgpu_postprocessing_dof` in its e2e exception list. All seven distinct quad
shaders are gated against three's dump instead (`dof_*` in
`tests/nodes_display_wgsl.rs`), and the page is in the native viewer
(`viewer postprocessing_dof`).

`webgpu_postprocessing_dof_basic` is graded, but it does not use this node.
Its depth of field is a `boxBlur` of the pass, mixed in by
`smoothstep( min, max, | viewZ - focus.z | )`.

## Selection outlines (`webgpu_postprocessing_outline`)

`outline()` takes the scene and camera itself, because it renders them
again:

```rust
let outline_pass = outline(
    scene.clone(),
    camera.clone(),
    OutlineParams {
        selected_objects: vec![],
        edge_thickness: edge_thickness_node,
        edge_glow: edge_glow_node,
        ..OutlineParams::default()
    },
);
let outline_color = outline_pass
    .visible_edge()
    .mul(visible_edge_color)
    .add(outline_pass.hidden_edge().mul(hidden_edge_color))
    .mul(edge_strength);
// The page also pulses `outline_color` with `osc_sine` when
// `pulsePeriod > 0`.
render_pipeline.output_node = Some(outline_color.add(scene_pass.node()));
// later, from a raycast:
outline_pass.set_selected_objects(vec![hit.object.clone()]);
```

Each frame with a selection, the node renders the scene twice. The first
render draws everything not selected, for depth. The second draws only the
selection, testing it against that depth. Then come seven quads, ending in
a composite whose red channel is the visible edge and whose green channel
is the hidden edge. With nothing selected it draws nothing.

The two scene renders need three's `setRenderObjectFunction()`, which the
port does not have. The renderer has a crate-private hook in its place,
`Renderer.outline_selection`, set only for the length of those two renders.
`docs/nodes.md` §72 has the details.

The rung grades the page as three's harness sees it, at 15 pixels, the
same as three's own frame. The pointer never moves there, so nothing is
selected. The selected passes are gated on their shaders against three's
dump, and on `tests/outline_frames.rs`.

## Colour grading with a 3D LUT (`webgpu_postprocessing_3dlut`)

```rust
let lut = LutCubeLoader::new().load(dir.join("Bourbon 64.CUBE"))?;
let lut_pass = lut_3d(
    render_output(scene_pass.node(), renderer.tone_mapping),
    &texture_3d_sampled(&lut.texture_3d),
    f64::from(lut.size),
    intensity_node,
);
render_pipeline.output_color_transform = false;
render_pipeline.output_node = Some(lut_pass.node());
```

`LutCubeLoader`, `Lut3dlLoader` and `LutImageLoader` are the three loaders
the page uses. Each is checked byte for byte against three's own loader.
`texture_3d_sampled` is `texture3D( texture )` with no level. The table is
fixed when the node is built, so to change table, build a new `Lut3DNode`
and set it as the pipeline's output. Three assigns `lutNode.value` instead.
See `docs/nodes.md` §73.
## A scene pass drawn as a PS1 would (`webgpu_postprocessing_retro`)

`retro_pass` is a scene pass at a quarter of the canvas, nearest-filtered,
that draws every classic material with snapped vertices and level-0 textures.
The CRT functions then work on its texture:

```rust
let retro = retro_pass(
    scene.clone(),
    camera.clone(),
    RetroPassOptions::default().affine_distortion(affine_distortion),
);

let mut output = retro.node();
output = replace_default_uv(barrel_uv(curvature.clone(), uv()), output);
output = color_bleeding(output, bleeding.add(distorted_delta));
output = bayer_dither(output, color_depth_steps.clone());
output = posterize(output, color_depth_steps);
output = vignette(output, vignette_intensity, float(0.6), uv());
output = scanlines(output, intensity, screen_size().y().mul(density), speed, uv());
render_pipeline.output_node = Some(output);
```

**The pass swaps the materials.** Three's `RetroPassNode` installs a
render-object function for the length of its own render. The port's
`PassNode` can hold one too (`RenderObjectFunction`, crate-private), and the
renderer asks it once per draw, the background's included. A material with
no node slots set (one `GltfLoader` made, say) is drawn with the retro vertex,
colour and context nodes. A node material is drawn as itself, which is what
three's property copy amounts to. `docs/nodes.md` §79 has the details.

**`replace_default_uv` reaches only taps built later.** It puts `getUV` in
the builder context. The retro pass's texture reads it at build time, so it
is distorted. A tap that already has its uv, `pass( … )`'s for instance,
keeps it. `color_bleeding` makes an `rtt()` of its input, so the barrel
distortion is rendered once into that target and the three bleed taps read
the result.

**The resolution scale.** `PassNode::set_resolution_scale( 0.25 )` makes the
target `floor( size · 0.25 )`, at least one texel. It is on every
`PassNode`, not just the retro one.

`set_filter_textures( true )` keeps mipmaps on the next frame. Three's page
follows it with `retro.dispose()` to drop its material cache. The port
derives the material per draw and has no cache to drop.

**There is no graded rung.** three.js itself misses its own reference
screenshot for this page on this machine (1503 of 100 000 pixels against a
0.1% limit), and the port scores the same 1503. So the e2e rung exists but is
ignored. The page's two post-processing shaders are gated against three's
dump in `tests/nodes_display_wgsl.rs`. `tests/retro_frames.rs` checks the
pass on the GPU:

- the target is a quarter of the canvas;
- the frame is made of 4×4 blocks;
- textures are level 0, and filtered with `set_filter_textures( true )`;
- affine mapping moves the texture;
- the sky's `normalWorld` is the back-side one.

`docs/webgpu_postprocessing_retro-progress.md` has the scores. The example
is in the native viewer (`viewer postprocessing_retro`).

`FilmNode`, `Sepia.js` and `BleachBypass.js` are ported as `film`, `sepia`
and `bleach`. No three page uses them, so they are gated against a dump page
of the repo's own (`docs/nodes.md` §80).

## The display nodes of #144

`src/nodes/display/` now also has these ports of
`examples/jsm/tsl/display/`:

- `GaussianBlurNode`;
- `SobelOperatorNode`, `DotScreenNode`, `RGBShiftNode` and `TransitionNode`;
- `hashBlur` and `boxBlur`;
- `AfterImageNode` and `PixelationPassNode`.

`tests/nodes_display_wgsl.rs` gates each against three's dump of a page that
uses it. `webgpu_procedural_texture`, `webgpu_postprocessing_sobel` and
`webgpu_postprocessing_transition` are the graded rungs, and
`webgpu_postprocessing_dof_basic` grades `boxBlur`.

The nodes follow the shapes above:

- The single-pass nodes are functions that return a node.
- `GaussianBlurNode` and `AfterImageNode` own their targets and quads, as
  `BloomNode` does. Their `render()` is `updateBefore()`, still fired by the
  example: #162 moved `PassNode`, `RttNode` and `BloomNode` onto the
  renderer's update phases and left these two for later.
- `PixelationPassNode` wraps a `PassNode` rather than subclassing one. The
  wrapped pass renders nearest-filtered at `floor( drawingBuffer / pixelSize )`,
  through `PassNode`'s new size divisor, with an `{ output, normal }` MRT.
  `pass( scene, camera )` takes any `RenderCamera` because that page's camera
  is orthographic.

Divergences, each noted where it lives:

- A node that three hands a `TextureNode` takes a `&Texture`. The example
  makes the `convertToTexture()` RTT itself, as `webgpu_postprocessing_ca`
  does.
- `DotScreenNode` reads `screenSize` from the viewport size, the uniform
  three's dump binds (`render.nodeUniform1`). It does not add a setter.
- `TransitionNode`'s mix texture is fixed when the node is built. Three
  swaps `mixTextureNode.value` per frame.
- `AfterImageNode` keeps last frame's output with the render target's
  previous-texture swap from `webgpu_postprocessing_difference`. It does not
  copy.
- `hashBlur` over `viewportSharedTexture()` (`webgpu_backdrop_area`) passes
  the viewport texture tap to `hash_blur_with`, and its WGSL gate compares
  three's loop exactly. The texture and the copy behind it are in
  `docs/nodes.md` §61.

## Light shafts and lens flares (`webgpu_postprocessing_godrays`, `webgpu_postprocessing_lensflare`)

`godrays`, `bilateral_blur`, `depth_aware_blend` and `lensflare` are the next
display nodes. Like `TraaNode`, each one that owns a target registers its own
update-before with the renderer, so the pipeline runs it and the example does
not:

```rust
let godrays_pass = godrays(&scene_pass_depth, camera.clone(), &point_light);
let blur_pass = bilateral_blur(&godrays_pass.texture(), None, 4, 0.1);
render_pipeline.output_node = Some(depth_aware_blend(
    &scene_pass_color,
    &blur_pass.texture(),
    &scene_pass_depth,
    &camera,
    options,
));
```

Three things are new here:

- **The pass's depth is read by an effect.** `godrays` reconstructs world
  positions from `scene_pass.depth_texture()`. It runs the pass's
  update-before first, so the depth it marches is this frame's.
- **An effect reads a shadow map.** `godrays` samples the point light's cube
  shadow through `LightShadow::point_depth_texture()`. The renderer draws the
  shadow into that same texture.
- **A hand-fired node sizes itself from its input.** The lens-flare page
  still calls `blur_pass.render()` itself, as `GaussianBlurNode` requires.
  `render()` now runs the input's update-before first, through
  `Renderer::update_texture_source`. So the first frame's blur is not sized
  from a 1×1 `rtt()`.

`docs/nodes.md` §74 and §75 have the shaders, the gates and what is not
ported.