sgl-3d 0.4.2

Caller-driven 3D rendering for SGL games, native and in the browser (WebGPU)
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
//! Transparent: blended receivers as the surface, the volume layers, the
//! transmission copy, blended, transmissive and additive surfaces, mist and
//! distortion.
pub(crate) mod effects;
pub(crate) mod heat;
pub(crate) mod mist;
pub(crate) mod transmission;
pub(crate) mod volumes;

use crate::shading::bind::{self, BindingTier, BlendedTrace};
use crate::view::cached_group::CachedGroup;
use crate::view::frame::FrameContext;
use crate::view::pipelines::GeometryPass;
use crate::view::targets::{SharedTargets, attachment};

/// The beauty a transparent draw composes onto.
pub(crate) enum Beauty<'a> {
    /// The reflections' incident radiance, before they trace it, so
    /// reflections show the draws.
    Incident(&'a wgpu::TextureView),
    /// The shared composite, after reflections are composed, with what the
    /// screen-space method returned while one ran, which receivers that are
    /// the surface compose into their traced lobe. While FSR2 runs, these
    /// draws also write its reactive and transparency and composition
    /// masks, which are cleared here and, while the scene holds an opaque
    /// surface whose shading moves, marked by it first.
    Composite {
        reflections: Option<&'a wgpu::TextureView>,
    },
}

/// Transparent: the receiver pass (`encode_receivers`), which draws the
/// blended receivers of screen-space reflections as the surface; the volume
/// layers (`encode_volumes`), while volume paths are in effect, of the
/// blended materials whose shader reads its volume path, which both blended
/// draws read; then blended surfaces, transmissive ones among them, back to
/// front, and additive glow and ground mist, drawn (`encode`) into the
/// reflections' incident radiance while they trace it and onto the
/// composite, each fogged from the frame's fog volume where it lies, then
/// heat distortion (`encode_heat`). On a device of the Extended binding tier, in a frame
/// whose blended list holds a transmissive material, the draw onto the
/// composite first copies it with its mips (`transmission`), which the
/// transmissive surfaces sample; elsewhere, and in the draw into the
/// incident radiance, they blend the light behind them through. While FSR2 runs and the scene
/// holds an opaque or masked material whose shading moves where its
/// geometry stands still (`Material::surface_moves`: its normal layers), the
/// draw onto the composite first marks those surfaces in FSR2's
/// transparency and composition mask, at the opaque depth, as AMD's FSR
/// sample marks its animated textures after its lighting and before its
/// translucency (`samples/fsrapi/config/fsrapiconfig.json`, its render
/// modules' order; SDK 1.1.4, MIT, see LICENSE-amd-fidelityfx.txt).
///
/// Reads: the camera's blended draw list with its lit group 0 and the
/// geometry pipelines, the camera's opaque draw list (its sets whose
/// material's surface moves, while FSR2 runs), its unlit group 0 (with the
/// fog volume), the opaque depth (copied into the surface depth, and tested
/// by every draw but the receiver pass, never written), the surface depth
/// and the screen-space method's result (receivers that are the surface),
/// the scene's transient geometry (glow, heat and mist), the beauty it draws
/// onto (the composite copied for transmission), its volume layers (the
/// blended draws, and the second exit layer's pass the exit layer).
/// Writes: the surface depth, the receiver layer and the G-buffer's motion
/// (the receiver pass); its volume layers (copies of the opaque depth with
/// the volumes' faces drawn over them); its transmission copy; that beauty
/// in place; FSR2's masks while FSR2 runs; the completed scene in place
/// (heat) through its own snapshot of it.
/// Blended surfaces write no other depth, motion or G-buffer.
/// Honours: the receiver pass and volume paths (the effective
/// configuration's), atmosphere (mist), heat distortion, FSR2 (its masks),
/// the effects and atmosphere diagnostics layers.
/// Timing groups: `receivers`, `volume layers`, `FSR2 composition` (the
/// moving opaque surfaces' mask), `transmission copy`, `blended` (blended
/// surfaces, both draws), `transparent` (glow and mist, both draws), `heat
/// distortion`.
/// History: none; the receiver pass rebuilds the surface, the volume layers
/// are drawn from the frame's geometry and the copy is made again every
/// frame they run.
pub(crate) struct Transparent {
    effects: effects::Effects,
    mist: mist::Mist,
    heat: heat::Heat,
    /// The depth soft glow reads.
    depth_group: wgpu::BindGroup,
    /// No screen-space result, which the blended draws bind while none
    /// composes, and no transmission copy, which they bind on the Extended
    /// binding tier while none holds the frame: 1×1, zero.
    no_reflections: wgpu::TextureView,
    /// The blended group 3 of the draw into the incident radiance, which
    /// composes nothing, and of the draw onto the composite.
    blended: [BlendedGroup; 2],
    /// The copy of the composed frame transmissive surfaces sample.
    transmission: transmission::Transmission,
    /// The volume layers a game's shader measures its volume path from.
    volumes: volumes::Volumes,
    /// The device's binding tier, which binds the copy on `Extended`.
    tier: BindingTier,
}

/// A blended draw's group 3 (`shading::bind::blended`), kept while it binds
/// the same method result and surface depth, and its `BlendedTrace`
/// uniform, written when the values change.
struct BlendedGroup {
    group: CachedGroup,
    trace: wgpu::Buffer,
    written: Option<BlendedTrace>,
}

impl Transparent {
    /// The stage over `unlit` group 0 for its effects and mist and `blended`
    /// group 3 (`shading::bind::blended`) of the device's binding `tier` for
    /// its blended draws.
    pub fn new(
        device: &wgpu::Device,
        unlit: &wgpu::BindGroupLayout,
        blended: &wgpu::BindGroupLayout,
        targets: &SharedTargets,
        tier: BindingTier,
    ) -> Self {
        let effects = effects::Effects::new(device, unlit);
        let group = |label| BlendedGroup {
            group: CachedGroup::new(blended.clone()),
            trace: crate::counters::buffer(
                device,
                &wgpu::BufferDescriptor {
                    label: Some(label),
                    size: size_of::<BlendedTrace>() as u64,
                    usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
                    mapped_at_creation: false,
                },
            ),
            written: None,
        };
        Self {
            depth_group: effects.depth_group(device, &targets.depth),
            effects,
            mist: mist::Mist::new(device, unlit),
            heat: heat::Heat::new(device),
            no_reflections: crate::view::targets::target(
                device,
                "no screen-space reflections",
                [1, 1],
                crate::shading::gbuffer::COLOR,
            ),
            blended: [
                group("blended incident trace"),
                group("blended composite trace"),
            ],
            transmission: transmission::Transmission::new(device),
            volumes: volumes::Volumes::new(device, blended),
            tier,
        }
    }

    /// The Receivers step: when the effective configuration runs it and the
    /// camera's blended list holds receivers, copies the opaque depth into
    /// the surface depth and draws the list's receiver batches over it with
    /// the frame's jittered view, tested strictly nearer and written: each
    /// receiver's traced lobe into the receiver layer and its unjittered
    /// motion into the G-buffer's. Returns whether it drew, after which the
    /// surface is the surface targets'.
    pub fn encode_receivers(&self, ctx: &mut FrameContext<'_>) -> bool {
        let targets: &SharedTargets = ctx.targets;
        let Some(surface) = &targets.surface else {
            return false;
        };
        if !ctx.effective.receivers || !ctx.views.blended.holds_receivers(ctx.scene) {
            return false;
        }
        ctx.encoder.copy_texture_to_texture(
            targets.depth.texture().as_image_copy(),
            surface.depth.texture().as_image_copy(),
            targets.depth.texture().size(),
        );
        let mut pass = ctx.encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
            label: Some("blended receivers"),
            color_attachments: &[
                attachment(&surface.receivers),
                loaded(attachment(&targets.motion), true),
            ],
            depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
                view: &surface.depth,
                depth_ops: Some(wgpu::Operations {
                    load: wgpu::LoadOp::Load,
                    store: wgpu::StoreOp::Store,
                }),
                stencil_ops: None,
            }),
            timestamp_writes: ctx.timing.and_then(|t| t.render_pass("receivers")),
            ..Default::default()
        });
        pass.set_bind_group(0, ctx.bindings.camera_lit(), &[]);
        ctx.views.blended.draw(
            ctx.scene,
            ctx.pipelines,
            &ctx.views.instances,
            &mut pass,
            GeometryPass::Receivers,
        );
        true
    }

    /// The Receivers and volume layers step's second part, after the
    /// receivers: when the effective
    /// configuration has volume paths and the camera's blended list holds a
    /// material whose shader reads its volume path, copies the opaque depth
    /// into each volume layer and draws those materials' batches over it
    /// (`volumes`), which this frame's blended draws then bind; otherwise
    /// they bind the opaque depth in their place. Returns whether it drew.
    /// Without volume paths it frees the layers, and the blended groups
    /// that bound them let go of them.
    pub fn encode_volumes(&mut self, ctx: &mut FrameContext<'_>) -> bool {
        if !ctx.effective.volume_paths {
            if self.volumes.release() {
                for blended in &mut self.blended {
                    blended.group.forget();
                }
            }
            return false;
        }
        self.volumes.encode(ctx, &self.no_reflections)
    }

    /// Rebinds the depth the glow reads.
    pub fn resize(&mut self, device: &wgpu::Device, targets: &SharedTargets) {
        self.depth_group = self.effects.depth_group(device, &targets.depth);
    }

    /// Blended surfaces, glow and mist onto `beauty`.
    pub fn encode(&mut self, ctx: &mut FrameContext<'_>, beauty: Beauty<'_>) {
        let targets: &SharedTargets = ctx.targets;
        // The draw's slot in `blended`, and the method's result it composes.
        let (beauty, fsr2_masks, (trace, reflections)) = match beauty {
            Beauty::Incident(view) => (view, None, (0, None)),
            Beauty::Composite { reflections } => (
                &targets.composite,
                ctx.effective.fsr2.then_some(&targets.fsr2_masks),
                (1, reflections),
            ),
        };
        // The first pass that writes FSR2's masks clears them: the moving
        // opaque surfaces' while the scene holds one, else the blended
        // surfaces', else the additive effects'.
        let moving = fsr2_masks.filter(|_| ctx.scene.materials.holds_moving_surfaces());
        if let Some(masks) = moving {
            Self::encode_composition(ctx, masks);
        }
        let blended = !ctx.views.blended.is_empty();
        if blended {
            // The copy of the composed frame, before anything is drawn onto
            // it, where a transmissive surface shows.
            let copy = (trace == 1
                && self.tier == BindingTier::Extended
                && ctx.views.blended.holds_transmissive(ctx.scene))
            .then(|| {
                self.transmission
                    .encode(ctx.device, ctx.encoder, &targets.composite, ctx.timing)
                    .clone()
            });
            let group = Self::blended_group(
                ctx,
                &mut self.blended[trace],
                &self.no_reflections,
                (reflections, copy.as_ref(), self.volumes.held()),
                self.tier,
            );
            Self::encode_blended(ctx, beauty, fsr2_masks, moving.is_some(), group);
        }
        let cleared = moving.is_some() || blended;
        let draw = ctx.effective.effects;
        if draw || (fsr2_masks.is_some() && !cleared) {
            let mut color = attachment(beauty).unwrap();
            color.ops.load = wgpu::LoadOp::Load;
            let mut attachments = vec![Some(color)];
            attachments.extend(
                fsr2_masks
                    .into_iter()
                    .flatten()
                    .map(|mask| loaded(attachment(mask), cleared)),
            );
            let mut pass = ctx.encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                label: Some("additive effects"),
                color_attachments: &attachments,
                depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
                    view: &targets.depth,
                    depth_ops: None,
                    stencil_ops: None,
                }),
                timestamp_writes: ctx.timing.and_then(|t| t.render_pass("transparent")),
                ..Default::default()
            });
            if draw {
                self.effects.draw(
                    &mut pass,
                    ctx.bindings.camera_unlit(),
                    &self.depth_group,
                    &ctx.scene.transient,
                    fsr2_masks.is_some(),
                );
            }
        }
        if ctx.effective.atmosphere {
            self.mist.encode(
                ctx.encoder,
                ctx.bindings.camera_unlit(),
                &ctx.scene.transient,
                beauty,
                &targets.depth,
                fsr2_masks,
                ctx.timing,
                "transparent",
            );
        }
    }

    /// A blended draw's group 3 `blended`: the screen-space method's
    /// `reflections` with its cutoff and fade where the draw composes them,
    /// else `no_reflections` and no trace, and the frame's surface depth;
    /// on a device of `tier` `Extended`, the transmission `copy` where it
    /// holds the frame, else `no_reflections` in its place, the opaque
    /// depth, and the volume layers where they hold the frame (`volumes`),
    /// else the opaque depth in their place.
    fn blended_group<'a>(
        ctx: &FrameContext<'_>,
        blended: &'a mut BlendedGroup,
        no_reflections: &wgpu::TextureView,
        (reflections, copy, volumes): (
            Option<&wgpu::TextureView>,
            Option<&wgpu::TextureView>,
            Option<&volumes::Layers>,
        ),
        tier: BindingTier,
    ) -> &'a wgpu::BindGroup {
        let traced = ctx.effective.screen_space.zip(reflections);
        let mut values = traced.map_or_else(BlendedTrace::default, |(ssr, _)| BlendedTrace {
            cutoff: ssr.cutoff,
            fade: ssr.fade,
            ..BlendedTrace::default()
        });
        values.transmission = u32::from(copy.is_some());
        values.volumes = u32::from(volumes.is_some());
        if blended.written != Some(values) {
            crate::counters::write_buffer(
                ctx.queue,
                &blended.trace,
                0,
                bytemuck::bytes_of(&values),
            );
            blended.written = Some(values);
        }
        let reflections = traced.map_or(no_reflections, |(_, view)| view);
        let texture = wgpu::BindingResource::TextureView;
        let mut entries = vec![
            (bind::blended::REFLECTIONS, texture(reflections)),
            (bind::blended::SURFACE_DEPTH, texture(ctx.surface.depth)),
            (bind::blended::TRACE, blended.trace.as_entire_binding()),
        ];
        if bind::blended::tier(bind::blended::TRANSMISSION) <= tier {
            entries.push((
                bind::blended::TRANSMISSION,
                texture(copy.unwrap_or(no_reflections)),
            ));
        }
        // The opaque depth, which the draws test read-only, as the glow
        // samples it: a game's shader's scene depth (shader_scene_depth.wgsl).
        if bind::blended::tier(bind::blended::SCENE_DEPTH) <= tier {
            entries.push((bind::blended::SCENE_DEPTH, texture(&ctx.targets.depth)));
        }
        // The volume layers a game's shader measures its path from
        // (shader_scene_depth.wgsl's scene_volume_path).
        if bind::blended::tier(bind::blended::VOLUME_ENTRY) <= tier {
            let layer = |held: fn(&volumes::Layers) -> &wgpu::TextureView| {
                texture(volumes.map_or(&ctx.targets.depth, held))
            };
            entries.extend([
                (bind::blended::VOLUME_ENTRY, layer(|layers| &layers.entry)),
                (bind::blended::VOLUME_EXIT, layer(|layers| &layers.exit)),
                (
                    bind::blended::VOLUME_SECOND_EXIT,
                    layer(|layers| &layers.second_exit),
                ),
            ]);
        }
        blended
            .group
            .get(ctx.device, "blended reflections", &entries)
    }

    /// FSR2's `masks`, cleared, with the camera's opaque and masked
    /// surfaces whose material's shading moves (`Material::surface_moves`)
    /// marked in its transparency and composition mask, drawn at the
    /// opaque depth, which they test for equality without writing it.
    fn encode_composition(ctx: &mut FrameContext<'_>, masks: &[wgpu::TextureView; 2]) {
        let attachments = masks.each_ref().map(attachment);
        let started = crate::counters::Moment::now();
        let mut pass = ctx.encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
            label: Some("FSR2 composition of moving surfaces"),
            color_attachments: &attachments,
            depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
                view: &ctx.targets.depth,
                depth_ops: None,
                stencil_ops: None,
            }),
            timestamp_writes: ctx.timing.and_then(|t| t.render_pass("FSR2 composition")),
            ..Default::default()
        });
        pass.set_bind_group(0, ctx.bindings.camera_lit(), &[]);
        let scene = ctx.scene;
        ctx.views.camera.list.draw_materials(
            scene,
            ctx.pipelines,
            &mut pass,
            GeometryPass::Fsr2Composition,
            &|material| scene.drawn_material(material).surface_moves(),
        );
        drop(pass);
        ctx.views.camera.recorded_since(started);
    }

    /// The camera's blended surfaces onto `beauty`, back to front, tested
    /// against the opaque depth without writing it, with their group 3
    /// `group`, and, with `fsr2_masks`, onto FSR2's masks, which this pass
    /// clears unless they were `cleared`.
    fn encode_blended(
        ctx: &mut FrameContext<'_>,
        beauty: &wgpu::TextureView,
        fsr2_masks: Option<&[wgpu::TextureView; 2]>,
        cleared: bool,
        group: &wgpu::BindGroup,
    ) {
        let color = loaded(attachment(beauty), true);
        let mut attachments = vec![color];
        attachments.extend(
            fsr2_masks
                .into_iter()
                .flatten()
                .map(|mask| loaded(attachment(mask), cleared)),
        );
        let mut pass = ctx.encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
            label: Some("blended surfaces"),
            color_attachments: &attachments,
            depth_stencil_attachment: Some(wgpu::RenderPassDepthStencilAttachment {
                view: &ctx.targets.depth,
                depth_ops: None,
                stencil_ops: None,
            }),
            timestamp_writes: ctx.timing.and_then(|t| t.render_pass("blended")),
            ..Default::default()
        });
        pass.set_bind_group(0, ctx.bindings.camera_lit(), &[]);
        pass.set_bind_group(3, group, &[]);
        let kind = GeometryPass::Blended {
            fsr2_masks: fsr2_masks.is_some(),
        };
        ctx.views.blended.draw(
            ctx.scene,
            ctx.pipelines,
            &ctx.views.instances,
            &mut pass,
            kind,
        );
    }

    /// Heat distortion of the completed scene `color` in place.
    pub fn encode_heat(&mut self, ctx: &mut FrameContext<'_>, color: &wgpu::TextureView) {
        self.heat.encode(
            ctx.device,
            ctx.queue,
            ctx.encoder,
            &ctx.scene.transient,
            &ctx.values.view.view_projection,
            ctx.sizes.scene,
            color,
            &ctx.targets.depth,
            ctx.timing,
        );
    }
}

#[cfg(all(test, not(target_arch = "wasm32")))]
mod blended_tests;
#[cfg(all(test, not(target_arch = "wasm32")))]
mod composition_tests;
#[cfg(all(test, not(target_arch = "wasm32")))]
mod effects_tests;
#[cfg(all(test, not(target_arch = "wasm32")))]
mod receiver_tests;
#[cfg(all(test, not(target_arch = "wasm32")))]
mod transmission_tests;

/// `target`, keeping what it holds when `load`.
fn loaded(
    mut target: Option<wgpu::RenderPassColorAttachment<'_>>,
    load: bool,
) -> Option<wgpu::RenderPassColorAttachment<'_>> {
    if load {
        target.as_mut().unwrap().ops.load = wgpu::LoadOp::Load;
    }
    target
}