threers 0.0.7

Drop-in three.js replacement for Rust and WebAssembly (wgpu) — THREE.* API, scene graph, PBR, post-fx, mesh BVH, CSG, an OpenSCAD front end with a watertight exact-CSG kernel, headless render, and native media codecs
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
//! Drop the alpha channel on the GPU, before the frame is ever read back.
//!
//! A rendered frame is RGBA because that is what a colour attachment is. A
//! video frame is not: every encoder here wants three bytes a pixel, so the
//! fourth is carried across the PCIe/unified-memory readback, handed to a video
//! encoder and thrown away. At 8K that is 33 MB a frame of pure waste on the
//! way out, and the same again on the way in to swscale.
//!
//! Doing the pack on the CPU instead is worse than doing nothing, which is not
//! obvious until it is measured. One pass over 33 Mpx copying three bytes at a
//! time vectorises badly, and threaded across the cores it saturates the memory
//! bandwidth the render loop needs for its own readback: an 8K frame went from
//! 37.7 ms in output to 236.5, and readback from 3.4 ms to 36.8 — 232 ms a
//! frame spent to save the encoder 150.
//!
//! # Why four pixels per invocation
//!
//! WGSL storage buffers are addressed in `u32`s, so writing three bytes per
//! pixel would mean read-modify-write across word boundaries, and neighbouring
//! invocations would collide on the shared word. Four pixels is the smallest
//! group whose packed form — 12 bytes — is a whole number of words. So each
//! invocation reads 4 texels and writes exactly 3 words that nobody else
//! touches: no atomics, no barriers, no overlap.
//!
//! The tail is handled by clamping reads to the last pixel rather than by a
//! branch: a frame whose pixel count is not a multiple of four writes a few
//! bytes of padding past the end, which `read` trims off.

/// A compute pass that packs an RGBA texture into tightly-packed RGB bytes.
pub struct RgbPack {
    /// Kept so the reprojection matrices can be refreshed each frame; they
    /// change every frame and a pack built once would blur along stale ones.
    ubo: wgpu::Buffer,
    pipeline: wgpu::ComputePipeline,
    bind_group: wgpu::BindGroup,
    /// The packed bytes, as a storage buffer the readback copies from.
    buffer: wgpu::Buffer,
    width: u32,
    height: u32,
    /// Bytes actually meaningful: `width * height * 3`.
    len: usize,
    groups_x: u32,
    groups_y: u32,
}

const WORKGROUP: u32 = 64;

/// Vignette and grain, as a pair, because they are the two things that say
/// "photograph" rather than "render" and neither is part of the scene.
///
/// Zero on both is bit-for-bit the frame without them -- the shader branches
/// out entirely -- so this is free to leave in the pipeline and off by default.
#[derive(Clone, Copy, Debug, Default)]
pub struct FilmGrade {
    /// 0 none, 1 a full cos-fourth falloff. 0.2-0.4 is a lens; 1.0 is a look.
    pub vignette: f32,
    /// Peak grain amplitude in the mid-tones, in output units. 0.02 is 35 mm.
    pub grain: f32,
    /// Frame number, so the grain moves. Anything that changes per frame.
    pub seed: f32,
}

impl RgbPack {
    /// Build the pass for `src`, or `None` if its format cannot be sampled as
    /// plain 8-bit colour — the HDR path has to stay on the float readback.
    pub fn new(device: &wgpu::Device, src: &wgpu::Texture) -> Option<Self> {
        Self::with_bloom(device, src, None, 0.0)
    }

    /// As [`new`](Self::new), but adds `bloom` (a lower-resolution linear-light
    /// texture) scaled by `strength` before packing.
    ///
    /// Compositing HERE rather than in a pass of its own is what keeps the
    /// frame from being touched twice: this shader already reads every pixel on
    /// its way to the encoder, so the add is free beyond the sample. With
    /// `strength` at zero the output is bit-for-bit what it was without bloom,
    /// which is what lets the byte-exactness test keep meaning something.
    pub fn with_bloom(
        device: &wgpu::Device,
        src: &wgpu::Texture,
        bloom: Option<&wgpu::TextureView>,
        strength: f32,
    ) -> Option<Self> {
        Self::with_post(device, src, bloom, strength, None)
    }

    /// As [`with_bloom`](Self::with_bloom), plus an ambient-occlusion factor
    /// multiplied into the frame. Both are composited in this one pass because
    /// it already reads every pixel; adding either as its own pass over the
    /// picture would cost more than the effects do.
    pub fn with_post(
        device: &wgpu::Device,
        src: &wgpu::Texture,
        bloom: Option<&wgpu::TextureView>,
        strength: f32,
        ao: Option<&wgpu::TextureView>,
    ) -> Option<Self> {
        Self::with_post_mb(
            device, src, bloom, strength, ao, None, [0.0; 16], [0.0; 16], 0.0, None,
        )
    }

    /// As [`with_post_mb`](Self::with_post_mb), plus the film grade.
    ///
    /// Vignette and grain belong in THIS pass and not on the CPU, for the same
    /// reason the masthead does: the frame is read back straight from the buffer
    /// the GPU wrote it to, so touching it afterwards costs a full copy of every
    /// frame. Here they are two lines in a shader that already reads every pixel.
    ///
    /// Both go on BEFORE the overlay, so the masthead and the captions stay
    /// clean -- they are graphics laid on the picture, and a vignette across a
    /// logo strip reads as a mistake.
    #[allow(clippy::too_many_arguments)]
    pub fn with_post_film(
        device: &wgpu::Device,
        src: &wgpu::Texture,
        bloom: Option<&wgpu::TextureView>,
        strength: f32,
        ao: Option<&wgpu::TextureView>,
        depth: Option<&wgpu::Texture>,
        inv_vp: [f32; 16],
        prev_vp: [f32; 16],
        shutter: f32,
        overlay: Option<&wgpu::Texture>,
        film: FilmGrade,
    ) -> Option<Self> {
        Self::build(
            device, src, bloom, strength, ao, depth, inv_vp, prev_vp, shutter, overlay, film,
        )
    }

    /// As [`with_post`](Self::with_post), plus camera motion blur.
    ///
    /// `depth` with the two matrices gives each pixel a velocity: reconstruct
    /// where it is, ask where it WAS through the previous camera, and the screen
    /// distance between the two is how far it travelled during the frame.
    /// `shutter` scales that — 0.5 is a 180-degree shutter, the film default,
    /// because a real shutter is open for half the frame interval and not all
    /// of it.
    ///
    /// Camera motion only. Object motion needs per-object velocities, which
    /// means a velocity buffer this renderer does not write; the arm swinging
    /// against a still camera will not blur. For this film the dominant motion
    /// IS the camera, so that is most of the benefit for none of the plumbing.
    #[allow(clippy::too_many_arguments)]
    pub fn with_post_mb(
        device: &wgpu::Device,
        src: &wgpu::Texture,
        bloom: Option<&wgpu::TextureView>,
        strength: f32,
        ao: Option<&wgpu::TextureView>,
        depth: Option<&wgpu::Texture>,
        inv_vp: [f32; 16],
        prev_vp: [f32; 16],
        shutter: f32,
        overlay: Option<&wgpu::Texture>,
    ) -> Option<Self> {
        Self::build(
            device, src, bloom, strength, ao, depth, inv_vp, prev_vp, shutter, overlay,
            FilmGrade::default(),
        )
    }

    #[allow(clippy::too_many_arguments)]
    fn build(
        device: &wgpu::Device,
        src: &wgpu::Texture,
        bloom: Option<&wgpu::TextureView>,
        strength: f32,
        ao: Option<&wgpu::TextureView>,
        depth: Option<&wgpu::Texture>,
        inv_vp: [f32; 16],
        prev_vp: [f32; 16],
        shutter: f32,
        // An RGBA overlay drawn over the top of the frame, anchored at the top
        // left — a masthead, a lower third, anything the caller composites.
        //
        // It belongs HERE and not on the CPU. Compositing it into the frame
        // after readback means the frame has to be WRITABLE, which means it has
        // to be copied out of the buffer the GPU wrote it to — 99.5 MB a frame
        // at 8K, purely so a strip across the top can be blended in. Done here
        // the frame is never touched by the CPU at all.
        overlay: Option<&wgpu::Texture>,
        film: FilmGrade,
    ) -> Option<Self> {
        // WebGL2 has no compute stage. wgpu signals that by zeroing the compute
        // limits rather than by refusing the device, so without this check the
        // pipeline is never created and the pass quietly does nothing — a frame
        // that looks almost right, at a full frame rate. Every public
        // constructor funnels through here, so this one guard covers them all.
        if !crate::renderer::caps::supports_compute(device) {
            return None;
        }
        let (width, height) = (src.width(), src.height());
        // textureLoad on a non-filterable float view is the cheapest way in and
        // needs no sampler. Formats outside this set are not what the video
        // path produces.
        let bgra = match src.format() {
            wgpu::TextureFormat::Bgra8Unorm | wgpu::TextureFormat::Bgra8UnormSrgb => true,
            wgpu::TextureFormat::Rgba8Unorm | wgpu::TextureFormat::Rgba8UnormSrgb => false,
            _ => return None,
        };

        let px = width as usize * height as usize;
        let len = px * 3;
        // Round up to whole 4-pixel groups so the last invocation's three words
        // land inside the allocation.
        let words = px.div_ceil(4) * 3;
        let buffer = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("threers rgb pack"),
            size: (words * 4) as u64,
            usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
            mapped_at_creation: false,
        });

        // An sRGB view would decode on load and undo the very encoding the file
        // is supposed to carry, so read the texture as UNORM and pass the bytes
        // through untouched.
        let view_format = if bgra {
            wgpu::TextureFormat::Bgra8Unorm
        } else {
            wgpu::TextureFormat::Rgba8Unorm
        };
        let view = src.create_view(&wgpu::TextureViewDescriptor {
            label: Some("threers rgb pack src"),
            format: Some(view_format),
            ..Default::default()
        });

        let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("threers rgb pack"),
            source: wgpu::ShaderSource::Wgsl(SHADER.into()),
        });
        let layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("threers rgb pack layout"),
            entries: &[
                wgpu::BindGroupLayoutEntry {
                    binding: 0,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Texture {
                        sample_type: wgpu::TextureSampleType::Float { filterable: false },
                        view_dimension: wgpu::TextureViewDimension::D2,
                        multisampled: false,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 1,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Storage { read_only: false },
                        has_dynamic_offset: false,
                        min_binding_size: None,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 2,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Uniform,
                        has_dynamic_offset: false,
                        min_binding_size: None,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 3,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Texture {
                        sample_type: wgpu::TextureSampleType::Float { filterable: false },
                        view_dimension: wgpu::TextureViewDimension::D2,
                        multisampled: false,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 4,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Texture {
                        sample_type: wgpu::TextureSampleType::Float { filterable: false },
                        view_dimension: wgpu::TextureViewDimension::D2,
                        multisampled: false,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 5,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Texture {
                        sample_type: wgpu::TextureSampleType::Depth,
                        view_dimension: wgpu::TextureViewDimension::D2,
                        multisampled: false,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 6,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Texture {
                        sample_type: wgpu::TextureSampleType::Float { filterable: false },
                        view_dimension: wgpu::TextureViewDimension::D2,
                        multisampled: false,
                    },
                    count: None,
                },
            ],
        });
        // A dispatch dimension caps at 65535 workgroups, and 8K needs 129600 of
        // them, so the grid is 2D and the shader rebuilds the linear index from
        // both axes. `stride` is how many quads one row of the grid covers.
        let quads = px.div_ceil(4) as u32;
        let total_groups = quads.div_ceil(WORKGROUP);
        let groups_x = total_groups.clamp(1, 32768);
        let groups_y = total_groups.div_ceil(groups_x);
        let stride = groups_x * WORKGROUP;
        // width, pixel count, BGRA flag, and the grid stride in quads.
        let params = [width, px as u32, u32::from(bgra), stride];
        let mb_on = depth.is_some() && shutter > 0.0;
        let (ov_w, ov_h) = overlay.map(|t| (t.width(), t.height())).unwrap_or((0, 0));
        let fparams = [
            strength,
            if bloom.is_some() { 1.0f32 } else { 0.0 },
            if ao.is_some() { 1.0f32 } else { 0.0 },
            if mb_on { shutter } else { 0.0 },
        ];
        let ubo = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("threers rgb pack params"),
            size: 208,
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: true,
        });
        {
            let mut m = ubo.slice(..).get_mapped_range_mut().expect("buffer range is mapped");
            m.slice(..16).copy_from_slice(bytemuck::cast_slice(&params));
            m.slice(16..32).copy_from_slice(bytemuck::cast_slice(&fparams));
            m.slice(32..96).copy_from_slice(bytemuck::cast_slice(&inv_vp));
            m.slice(96..160).copy_from_slice(bytemuck::cast_slice(&prev_vp));
            m.slice(160..168).copy_from_slice(bytemuck::cast_slice(&[ov_w, ov_h]));
            m.slice(168..176).copy_from_slice(bytemuck::cast_slice(&[film.vignette, film.grain]));
            m.slice(176..192)
                .copy_from_slice(bytemuck::cast_slice(&[film.seed, 0.0f32, 0.0f32, 0.0f32]));
            // Depth of field is set per frame, like the reprojection: focus
            // moves and the camera's clip range can too.
            m.slice(192..208)
                .copy_from_slice(bytemuck::cast_slice(&[0.0f32, 0.0, 0.0, 0.0]));
        }
        ubo.unmap();

        // A 1x1 stand-in when there is no bloom: the binding must be filled
        // either way, and a branch in the shader on a uniform is cheaper than
        // two pipelines.
        let dummy = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("threers rgb pack no-bloom"),
            size: wgpu::Extent3d {
                width: 1,
                height: 1,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rgba16Float,
            usage: wgpu::TextureUsages::TEXTURE_BINDING,
            view_formats: &[],
        });
        let dummy_view = dummy.create_view(&Default::default());
        let bloom_view = bloom.unwrap_or(&dummy_view);
        let ao_dummy = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("threers rgb pack no-ao"),
            size: wgpu::Extent3d {
                width: 1,
                height: 1,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::R32Float,
            usage: wgpu::TextureUsages::TEXTURE_BINDING,
            view_formats: &[],
        });
        let ao_dummy_view = ao_dummy.create_view(&Default::default());
        let ao_view = ao.unwrap_or(&ao_dummy_view);
        let depth_dummy = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("threers rgb pack no-depth"),
            size: wgpu::Extent3d {
                width: 1,
                height: 1,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Depth32Float,
            usage: wgpu::TextureUsages::TEXTURE_BINDING,
            view_formats: &[],
        });
        let ov_dummy = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("threers rgb pack no-overlay"),
            size: wgpu::Extent3d {
                width: 1,
                height: 1,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rgba8Unorm,
            usage: wgpu::TextureUsages::TEXTURE_BINDING,
            view_formats: &[],
        });
        let ov_view = match overlay {
            Some(t) => t.create_view(&Default::default()),
            None => ov_dummy.create_view(&Default::default()),
        };
        let depth_view = match depth.filter(|d| d.sample_count() == 1) {
            Some(d) => d.create_view(&wgpu::TextureViewDescriptor {
                label: Some("threers rgb pack depth"),
                aspect: wgpu::TextureAspect::DepthOnly,
                ..Default::default()
            }),
            None => depth_dummy.create_view(&Default::default()),
        };

        let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("threers rgb pack bind group"),
            layout: &layout,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: buffer.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 2,
                    resource: ubo.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 3,
                    resource: wgpu::BindingResource::TextureView(bloom_view),
                },
                wgpu::BindGroupEntry {
                    binding: 4,
                    resource: wgpu::BindingResource::TextureView(ao_view),
                },
                wgpu::BindGroupEntry {
                    binding: 5,
                    resource: wgpu::BindingResource::TextureView(&depth_view),
                },
                wgpu::BindGroupEntry {
                    binding: 6,
                    resource: wgpu::BindingResource::TextureView(&ov_view),
                },
            ],
        });
        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("threers rgb pack pipeline layout"),
            bind_group_layouts: &[Some(&layout)],
            immediate_size: 0,
        });
        let pipeline = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
            label: Some("threers rgb pack pipeline"),
            layout: Some(&pipeline_layout),
            module: &shader,
            entry_point: Some("main"),
            compilation_options: Default::default(),
            cache: None,
        });

        Some(Self {
            ubo,
            pipeline,
            bind_group,
            buffer,
            width,
            height,
            len,
            groups_x,
            groups_y,
        })
    }

    /// Refresh the reprojection for this frame. Must be called before
    /// [`pack`](Self::pack) on every frame motion blur is wanted on: the
    /// matrices are per-frame, and stale ones smear along last frame's motion.
    pub fn set_reprojection(&self, queue: &wgpu::Queue, inv_vp: [f32; 16], prev_vp: [f32; 16]) {
        queue.write_buffer(&self.ubo, 32, bytemuck::cast_slice(&inv_vp));
        queue.write_buffer(&self.ubo, 96, bytemuck::cast_slice(&prev_vp));
    }

    /// Focus distance, the range either side of it that stays sharp, the blur
    /// radius in pixels at full defocus, and the camera's clip planes.
    ///
    /// `near`/`far` MUST be the ones the frame was drawn with — the depth
    /// linearisation is wrong otherwise, and wrong silently, in the same way
    /// [`Ssao`](crate::renderer::ssao) is. A radius of zero turns it off.
    pub fn set_dof(&self, queue: &wgpu::Queue, focus: f32, range: f32, radius: f32, near: f32, far: f32) {
        queue.write_buffer(
            &self.ubo,
            180,
            bytemuck::cast_slice(&[focus, range, radius, near, far]),
        );
    }

    /// Read the depth as reversed — what
    /// [`Renderer::set_reversed_z`](crate::Renderer::set_reversed_z) draws.
    pub fn set_reversed_depth(&self, queue: &wgpu::Queue, on: bool) {
        queue.write_buffer(&self.ubo, 200, bytemuck::bytes_of(&if on { 1.0f32 } else { 0.0 }));
    }

    /// Advance the grain seed. Cheap: eight bytes into a buffer that is already
    /// written every frame, and no pipeline rebuild -- which is the whole reason
    /// the seed is a uniform and not baked in at construction.
    pub fn set_grain_seed(&self, queue: &wgpu::Queue, seed: f32) {
        queue.write_buffer(&self.ubo, 176, bytemuck::cast_slice(&[seed]));
    }

    /// Record the pack. Must run after the frame is drawn and before the copy.
    pub fn pack(&self, encoder: &mut wgpu::CommandEncoder) {
        let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
            label: Some("threers rgb pack pass"),
            timestamp_writes: None,
        });
        pass.set_pipeline(&self.pipeline);
        pass.set_bind_group(0, &self.bind_group, &[]);
        pass.dispatch_workgroups(self.groups_x, self.groups_y, 1);
    }

    pub fn buffer(&self) -> &wgpu::Buffer {
        &self.buffer
    }

    /// Meaningful byte count — `width * height * 3`, without the group padding.
    pub fn len(&self) -> usize {
        self.len
    }

    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    pub fn size(&self) -> (u32, u32) {
        (self.width, self.height)
    }
}

const SHADER: &str = r#"
struct Params {
    width    : u32,
    count    : u32,
    bgra     : u32,
    stride   : u32,
    strength : f32,
    has_bloom: f32,
    has_ao   : f32,
    shutter  : f32,
    inv_vp   : mat4x4<f32>,
    prev_vp  : mat4x4<f32>,
    ov_w     : u32,
    ov_h     : u32,
    vig      : f32,
    grain    : f32,
    seed     : f32,
    dof_focus: f32,
    dof_range: f32,
    dof_rad  : f32,
    dof_near : f32,
    dof_far  : f32,
    // 1 when the depth is reversed.
    reversed : f32,
    fpad2    : f32,
};

@group(0) @binding(0) var src : texture_2d<f32>;
@group(0) @binding(1) var<storage, read_write> dst : array<u32>;
@group(0) @binding(2) var<uniform> p : Params;
@group(0) @binding(3) var bloom : texture_2d<f32>;
@group(0) @binding(4) var ao    : texture_2d<f32>;
@group(0) @binding(5) var mb_depth : texture_depth_2d;
@group(0) @binding(6) var overlay : texture_2d<f32>;

// sRGB transfer, both ways. Bloom is gathered and blurred in linear light
// because that is the only space where "how much light is here" is additive;
// the stored frame is sRGB-encoded, so it has to be decoded before the add and
// re-encoded after. Adding encoded values instead brightens midtones far more
// than highlights, which is the opposite of what a bloom should do.
fn to_linear(c : f32) -> f32 {
    if (c <= 0.04045) { return c / 12.92; }
    return pow((c + 0.055) / 1.055, 2.4);
}
fn to_srgb(c : f32) -> f32 {
    if (c <= 0.0031308) { return c * 12.92; }
    return 1.055 * pow(c, 1.0 / 2.4) - 0.055;
}
fn lin3(c : vec3<f32>) -> vec3<f32> {
    return vec3<f32>(to_linear(c.r), to_linear(c.g), to_linear(c.b));
}
fn srgb3(c : vec3<f32>) -> vec3<f32> {
    return vec3<f32>(to_srgb(c.r), to_srgb(c.g), to_srgb(c.b));
}

// --- Depth of field --------------------------------------------------------
//
// One gather at full resolution rather than the usual half-res chain. That
// costs more samples for the same quality and is worth it here: the pack is a
// single compute pass that already holds the frame and the depth, so this adds
// no targets, no passes and no state, and a headless still is not paying for it
// sixty times a second.
const DOF_TAPS : i32 = 96;
//
// How far this pixel is from the focus plane, as a fraction of full blur.
// Anything at the far plane — the background, which has no geometry in it — is
// taken as fully defocused, which is what a lens does with a distant backdrop
// and is the whole reason a subject separates from it.
// The depth as standard depth: `1 - d` when the renderer reversed it.
fn pack_depth(xy : vec2<i32>) -> f32 {
    let d = textureLoad(mb_depth, xy, 0);
    return select(d, 1.0 - d, p.reversed > 0.5);
}

fn coc_at(xy : vec2<i32>) -> f32 {
    let d = pack_depth(xy);
    if (d >= 1.0) { return 1.0; }
    let z = (p.dof_near * p.dof_far) / (p.dof_far - d * (p.dof_far - p.dof_near));
    return clamp(abs(z - p.dof_focus) / max(p.dof_range, 1e-4), 0.0, 1.0);
}

// A golden-angle spiral inside this pixel's circle of confusion, gathered in
// linear light.
//
// The weight is the part that matters. A sample only contributes if *its own*
// circle is wide enough to reach this pixel, so a sharp foreground does not
// smear over a blurred background behind it — which is the artefact that makes
// a naive depth-weighted blur read as a mistake rather than as a lens.
fn dof(xy : vec2<u32>, dim : vec2<u32>, centre : vec3<f32>) -> vec3<f32> {
    let coc = coc_at(vec2<i32>(xy));
    let radius = coc * p.dof_rad;
    if (radius < 0.75) { return centre; }
    // Interleaved gradient noise: a per-pixel rotation hides the tap pattern,
    // which at this few samples is otherwise a visible rosette.
    let n = fract(52.9829189 * fract(dot(vec2<f32>(xy), vec2<f32>(0.06711056, 0.00583715))));
    let a0 = n * 6.2831853;
    var dir = vec2<f32>(cos(a0), sin(a0));
    let golden = mat2x2<f32>(-0.7373688, 0.6754903, -0.6754903, -0.7373688);
    var acc = lin3(centre);
    var wsum = 1.0;
    let hi = vec2<i32>(dim) - vec2<i32>(1, 1);
    // The tap count has to grow with the area being gathered or the disc is
    // undersampled and the "blur" is speckle: at a 14-pixel radius, 24 taps sit
    // about three pixels apart. `DOF_TAPS` is the ceiling and the spacing rule
    // picks how many of them are used, so a small blur stays cheap.
    let want = i32(clamp(3.14159 * radius * radius / 2.2, 8.0, f32(DOF_TAPS)));
    for (var i = 0; i < DOF_TAPS; i = i + 1) {
        if (i >= want) { break; }
        let r = sqrt((f32(i) + 0.5) / f32(want));
        dir = golden * dir;
        let off = dir * (r * radius);
        let sp = vec2<f32>(xy) + off;
        let cl = clamp(vec2<i32>(floor(sp)), vec2<i32>(0, 0), hi);
        let sc = coc_at(cl);
        // Does this sample's own circle actually reach this pixel? Compared in
        // pixels rather than in the parametric radius, which is the same test
        // everywhere except near the centre of the kernel — and near the centre
        // the parametric form says yes to everything, so a sharp foreground
        // bled a one-pixel halo into the blurred background behind it.
        let w = smoothstep(length(off) - 0.5, length(off) + 0.5, sc * p.dof_rad);
        let s = textureLoad(src, cl, 0);
        let rgb = select(s.rgb, s.bgr, p.bgra != 0u);
        acc = acc + lin3(rgb) * w;
        wsum = wsum + w;
    }
    return srgb3(acc / wsum);
}

// Where this pixel was a frame ago, in UV. Reconstruct its world position from
// depth and look it up through the previous camera; the gap between the two is
// the distance it swept while the shutter was open.
fn velocity(xy : vec2<u32>, dim : vec2<u32>) -> vec2<f32> {
    let d = pack_depth(vec2<i32>(xy));
    if (d >= 1.0) { return vec2<f32>(0.0); }
    let uv = (vec2<f32>(xy) + 0.5) / vec2<f32>(dim);
    let ndc = vec4<f32>(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, d, 1.0);
    let wh = p.inv_vp * ndc;
    let world = wh.xyz / wh.w;
    let pc = p.prev_vp * vec4<f32>(world, 1.0);
    if (pc.w <= 0.0) { return vec2<f32>(0.0); }
    let prev_uv = (pc.xy / pc.w) * vec2<f32>(0.5, -0.5) + vec2<f32>(0.5, 0.5);
    return (uv - prev_uv) * p.shutter;
}

fn texel(i : u32) -> vec3<u32> {
    // Clamp rather than branch: the tail of the last group re-reads the final
    // pixel, and the bytes it writes are past `len` and trimmed on the way out.
    let j = min(i, p.count - 1u);
    let xy = vec2<u32>(j % p.width, j / p.width);
    let c = textureLoad(src, vec2<i32>(xy), 0);
    var rgb = select(c.rgb, c.bgr, p.bgra != 0u);
    if (p.dof_rad > 0.0) {
        rgb = dof(xy, textureDimensions(src), rgb);
    }
    if (p.shutter > 0.0) {
        let dim = textureDimensions(src);
        let v = velocity(xy, dim);
        // Below a pixel of travel there is nothing to smear, and sampling
        // anyway would just soften a still frame.
        let px = length(v * vec2<f32>(dim));
        if (px > 1.0) {
            // 32 TAPS, AND A DITHERED PHASE.
            //
            // At 12 the tap COUNT was capped but the tap SPACING was not, so a
            // 120-pixel sweep sampled 12 points ten pixels apart: not a blur,
            // twelve discrete copies. On a big smooth bright subject -- Earth's
            // limb, the Moon's disc -- those copies read as a ladder of edges,
            // which is the "lines when we move fast" this has been showing.
            // Point sources are worse still: a star becomes twelve stars.
            //
            // Raising the cap alone only moves the threshold. What removes the
            // banding is breaking the phase per pixel, so neighbouring pixels
            // sample at different offsets along the streak and the residual
            // undersampling turns into noise instead of a fixed pattern -- and
            // noise at this amplitude is indistinguishable from the blur it is
            // standing in for.
            // TAPS ARE PRICED, NOT MAXED. min(px, 32) sampled one tap per
            // pixel of streak, so any sweep over 32 px paid the full 32 -- and
            // at 8K almost every moving pixel does. Measured on the deck film
            // at 854x480 that put motion blur at 43% of frame time; the cost
            // scales with pixels x taps, so at 8K it dominates.
            //
            // One tap per pixel was only ever needed because the taps landed on
            // a fixed ladder. With the phase dithered per pixel the residual is
            // noise, and noise at one tap per THREE pixels is indistinguishable
            // from the blur it stands in for -- neighbouring pixels fill each
            // other's gaps. So price the taps off the streak and cap at 24:
            //
            //     px  12 ->  6 taps  (was 12)
            //     px  30 -> 12 taps  (was 30)
            //     px 300 -> 24 taps  (was 32)
            let n = clamp(u32(px / 3.0 + 2.0), 4u, 24u);
            var jh = xy.x * 1973u + xy.y * 9277u + u32(p.seed) * 26699u;
            jh = jh ^ (jh >> 15u);
            jh = jh * 2246822519u;
            let jit = f32((jh ^ (jh >> 13u)) & 0xffffu) / 65536.0;
            var acc = rgb;
            var w = 1.0;
            for (var k = 1u; k <= n; k = k + 1u) {
                // (k - jit) not k: the offset is per pixel, so the taps of
                // adjacent pixels interleave instead of landing on the same
                // ladder. jit is in [0,1), so t stays in (0, 1].
                let t = (f32(k) - jit) / f32(n);
                let s = vec2<f32>(xy) - v * vec2<f32>(dim) * t;
                let sc = clamp(vec2<i32>(s), vec2<i32>(0), vec2<i32>(dim) - 1);
                let sm = textureLoad(src, sc, 0);
                acc = acc + select(sm.rgb, sm.bgr, p.bgra != 0u);
                w = w + 1.0;
            }
            rgb = acc / w;
        }
    }
    if (p.has_ao > 0.5) {
        // Occlusion multiplies LIGHT, so it belongs in linear space like the
        // bloom add. Applied to the encoded value it would crush shadows and
        // barely touch highlights.
        let ad = textureDimensions(ao);
        let au = vec2<u32>(min(xy.x * ad.x / max(p.width, 1u), ad.x - 1u),
                           min(xy.y * ad.y / max(textureDimensions(src).y, 1u), ad.y - 1u));
        let k = textureLoad(ao, vec2<i32>(au), 0).r;
        let lin = vec3<f32>(to_linear(rgb.r), to_linear(rgb.g), to_linear(rgb.b)) * k;
        rgb = vec3<f32>(to_srgb(lin.r), to_srgb(lin.g), to_srgb(lin.b));
    }
    if (p.has_bloom > 0.5) {
        // Nearest-tap upsample from the quarter-resolution bloom. It is a blur;
        // there is nothing in it that a bilinear fetch would preserve.
        let bd = textureDimensions(bloom);
        let uv = vec2<u32>(
            min(xy.x * bd.x / max(p.width, 1u), bd.x - 1u),
            min(xy.y * bd.y / max(textureDimensions(src).y, 1u), bd.y - 1u));
        let add = textureLoad(bloom, vec2<i32>(uv), 0).rgb * p.strength;
        let lin = vec3<f32>(to_linear(rgb.r), to_linear(rgb.g), to_linear(rgb.b)) + add;
        rgb = vec3<f32>(to_srgb(lin.r), to_srgb(lin.g), to_srgb(lin.b));
    }
    // THE FILM GRADE, before the overlay for the reason given on with_post_film.
    if (p.vig > 0.0 || p.grain > 0.0) {
        let dim = vec2<f32>(textureDimensions(src));
        if (p.vig > 0.0) {
            // cos-fourth falloff -- the one a real lens has. Normalised so the
            // centre is untouched and only the corners lose light. Vignetting
            // is lost LIGHT, so it multiplies in linear like the AO term.
            let q = (vec2<f32>(xy) + 0.5) / dim * 2.0 - 1.0;
            let f = 1.0 / (1.0 + dot(q, q) * 0.5);
            let k = mix(1.0, f * f, p.vig);
            let lin = vec3<f32>(to_linear(rgb.r), to_linear(rgb.g), to_linear(rgb.b)) * k;
            rgb = vec3<f32>(to_srgb(lin.r), to_srgb(lin.g), to_srgb(lin.b));
        }
        if (p.grain > 0.0) {
            // Hashed on the pixel AND the frame, so it moves: static grain is
            // dirt on the lens, not grain. Weighted to the mid-tones, because
            // film has almost none in the toe or the shoulder and an even
            // sprinkle over black reads as sensor noise.
            var hsh = xy.x * 374761393u + xy.y * 668265263u
                    + u32(p.seed) * 1274126177u;
            hsh = hsh ^ (hsh >> 13u);
            hsh = hsh * 1274126177u;
            let n = f32((hsh ^ (hsh >> 16u)) & 0xffffu) / 65535.0 - 0.5;
            let l = dot(rgb, vec3<f32>(0.299, 0.587, 0.114));
            rgb = clamp(rgb + n * p.grain * (4.0 * l * (1.0 - l)),
                        vec3<f32>(0.0), vec3<f32>(1.0));
        }
    }
    // The overlay goes on LAST, over bloom and everything else: it is graphics
    // laid on the picture, not part of the scene, so nothing should bloom it or
    // blur it. Straight alpha, in the frame's own encoding.
    if (p.ov_w > 0u && xy.y < p.ov_h && xy.x < p.ov_w) {
        let o = textureLoad(overlay, vec2<i32>(vec2<u32>(xy.x, xy.y)), 0);
        rgb = mix(rgb, o.rgb, o.a);
    }
    // Otherwise the attachment is already in the encoding the file will carry,
    // so round the stored value and do not touch its transfer function.
    return vec3<u32>(clamp(rgb * 255.0 + 0.5, vec3<f32>(0.0), vec3<f32>(255.0)));
}

@compute @workgroup_size(64)
fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
    let quad = gid.x + gid.y * p.stride;
    let first = quad * 4u;
    if (first >= p.count) { return; }

    let a = texel(first);
    let b = texel(first + 1u);
    let c = texel(first + 2u);
    let d = texel(first + 3u);

    // 4 pixels -> 12 bytes -> exactly 3 words, little-endian, no neighbour
    // shares a word with us.
    let o = quad * 3u;
    dst[o]      = a.x | (a.y << 8u) | (a.z << 16u) | (b.x << 24u);
    dst[o + 1u] = b.y | (b.z << 8u) | (c.x << 16u) | (c.y << 24u);
    dst[o + 2u] = c.z | (d.x << 8u) | (d.y << 16u) | (d.z << 24u);
}
"#;