sgl-3d 0.2.0

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
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
//! Views and what they see. The main camera, each directional shadow
//! cascade, each local-light shadow face and each probe-capture face is a
//! `View` with its own `ViewUniform`; its draw list holds its culled,
//! LOD-selected draws: GPU-built for the camera's opaque and masked surfaces
//! and the cascades (`draw_list::gpu`), CPU-built and instanced for the rest
//! (`DrawList`); `Clusters` the scene lights and decals that reach each part
//! of it, and `GeometryPipelines` the pipelines they draw with. `cascades` fits the directional shadow's cascades, and
//! `frame_uniform` builds the frame data every view of a frame shares,
//! including the cascades.
//!
//! The types stages share, which the renderer owns and lends them, are
//! here too: the frame's context (`frame`), the effective configuration
//! (`effective`), the sizes and shared targets (`targets`), group 0
//! (`bindings`), DiligentFX's post-effect context (`post_fx`), the bind
//! group cache stages keep for their own passes (`cached_group`), and a
//! tracing stage's programs for each path its rays take (`trace_paths`).
pub(crate) mod bindings;
pub(crate) mod cached_group;
pub(crate) mod cascades;
pub(crate) mod clusters;
pub(crate) mod culling;
pub(crate) mod draw_list;
pub(crate) mod effective;
pub(crate) mod frame;
pub(crate) mod history;
pub(crate) mod lod;
pub(crate) mod pipelines;
pub(crate) mod population;
pub(crate) mod post_fx;
pub(crate) mod reflection_camera;
pub(crate) mod targets;
pub(crate) mod trace_paths;

use crate::FrameInput;
use crate::content::irradiance_volume::IrradianceVolume;
use crate::content::lighting::{Backdrop, DirectionalLight, DirectionalShadow};
use crate::scene::dynamic_gi::ProbePlacement;
use crate::scene::static_lighting::StaticLighting;
use crate::shading::uniforms::{
    DIRECTIONAL_LIGHT_SHADOW, DirectionalLightUniform, FRAME_BACKDROP_COLOR, FRAME_BAKED_LIGHTING,
    FRAME_DYNAMIC_GI, FRAME_FOG, FRAME_HARDWARE_SHADOW_FILTER, FRAME_IRRADIANCE_ATLAS,
    FRAME_IRRADIANCE_VOLUME, FRAME_TEMPORAL_SHADOW_FILTER, FrameUniform, ShadowCascadeUniform,
    VIEW_PROBE_CAPTURE, ViewUniform,
};
use bytemuck::Zeroable;
use cascades::{Cascades, MAX_SHADOW_CASCADES};
use effective::ShadowFilter;
use glam::camera;
use glam::{Mat4, Vec3};

/// The near plane of local-light shadow faces, in metres.
pub(crate) const LOCAL_SHADOW_NEAR: f32 = 0.02;
/// Each local-light shadow cube face's direction and up, in face order.
const LOCAL_SHADOW_FACES: [(Vec3, Vec3); 6] = [
    (Vec3::X, Vec3::NEG_Y),
    (Vec3::NEG_X, Vec3::NEG_Y),
    (Vec3::Y, Vec3::Z),
    (Vec3::NEG_Y, Vec3::NEG_Z),
    (Vec3::Z, Vec3::NEG_Y),
    (Vec3::NEG_Z, Vec3::NEG_Y),
];
/// Each probe-capture face's direction and up, in cube-face order.
const PROBE_FACES: [(Vec3, Vec3); 6] = [
    (Vec3::X, Vec3::Y),
    (Vec3::NEG_X, Vec3::Y),
    (Vec3::Y, Vec3::Z),
    (Vec3::NEG_Y, Vec3::NEG_Z),
    (Vec3::NEG_Z, Vec3::Y),
    (Vec3::Z, Vec3::Y),
];

fn flag(on: bool, flag: u32) -> u32 {
    if on { flag } else { 0 }
}

/// The radius at unit distance of a disc spanning `angular_diameter`
/// radians, clamped to 0..=Ï€/2 (NaN as 0).
fn disc_radius(angular_diameter: f32) -> f32 {
    let angle = if angular_diameter.is_nan() {
        0.
    } else {
        angular_diameter.clamp(0., std::f32::consts::FRAC_PI_2)
    };
    (angle * 0.5).tan()
}

/// Directional light `index` of `input`, unless it is absent or off.
fn directional_light(input: &FrameInput, index: usize) -> Option<DirectionalLight> {
    input.directional_lights[index].filter(DirectionalLight::is_on)
}

/// The directional light that casts the frame's shadow, by its index in
/// `FrameInput::directional_lights`, with its shadow: the first light that
/// is on and has one.
pub(crate) fn directional_shadow(input: &FrameInput) -> Option<(usize, DirectionalShadow)> {
    (0..input.directional_lights.len()).find_map(|index| {
        directional_light(input, index)?
            .shadow
            .map(|shadow| (index, shadow))
    })
}

/// The directional shadow of one frame's views: the light that casts it and
/// its cascades, the camera's filter, and the frames since history
/// restarted, which turn the temporal filter's noise.
#[derive(Clone, Copy, Debug, Default)]
pub(crate) struct FrameShadow {
    pub light: Option<usize>,
    pub cascades: Cascades,
    pub filter: ShadowFilter,
    pub frame_count: u32,
}

impl FrameShadow {
    /// The shadow `input`'s camera sees in cascades of `map_size` texels.
    /// Its surfaces take every shadow, local lights' too, with `filter`,
    /// whether or not a directional light casts one.
    pub fn camera(
        input: &FrameInput,
        map_size: u32,
        filter: ShadowFilter,
        frame_count: u32,
        origin: glam::DVec3,
    ) -> Self {
        let camera = input.camera;
        let (light, cascades) = Self::fit(input, |direction, shadow| {
            Cascades::camera(
                camera.view,
                camera.projection,
                direction,
                shadow,
                map_size,
                origin,
            )
        })
        .map_or((None, Cascades::default()), |(light, cascades)| {
            (Some(light), cascades)
        });
        Self {
            light,
            cascades,
            filter,
            frame_count,
        }
    }

    /// The shadow of `input`'s light for a probe capture at `center`, in
    /// cascades of `map_size` texels, in the render frame of the scene's
    /// `origin`.
    pub fn capture(input: &FrameInput, center: Vec3, map_size: u32, origin: glam::DVec3) -> Self {
        Self::fit(input, |direction, shadow| {
            Cascades::capture(center, direction, shadow, map_size, origin)
        })
        .map_or_else(Self::default, |(light, cascades)| Self {
            light: Some(light),
            cascades,
            ..Self::default()
        })
    }

    /// The casting light's index and its cascades, fit by `fit` from its
    /// direction and shadow.
    fn fit(
        input: &FrameInput,
        fit: impl FnOnce(Vec3, &DirectionalShadow) -> Cascades,
    ) -> Option<(usize, Cascades)> {
        let (light, shadow) = directional_shadow(input)?;
        let direction = input.directional_lights[light]?.direction;
        Some((light, fit(direction, &shadow)))
    }
}

/// The frame data of `input` for a scene with `baked` diffuse lighting and
/// `irradiance_volume`, which lights the frame with baked lighting, with the
/// directional `shadow`; `fog` is whether the frame's volumetric fog ran, so
/// draws fog from its volume, and `dynamic_gi` the dynamic GI volume whose
/// probes group 0 binds, which then lights the frame.
pub(crate) fn frame_uniform(
    input: &FrameInput,
    (baked, irradiance_volume): (&StaticLighting, Option<IrradianceVolume>),
    shadow: &FrameShadow,
    fog: bool,
    dynamic_gi: Option<&ProbePlacement>,
) -> FrameUniform {
    let irradiance_volume = irradiance_volume.filter(|_| input.baked_lighting);
    let cascades = shadow.cascades.as_slice();
    let directional_lights = std::array::from_fn(|index| {
        directional_light(input, index).map_or(DirectionalLightUniform::zeroed(), |light| {
            DirectionalLightUniform {
                direction_to_light: (-light.direction).to_array(),
                flags: flag(shadow.light == Some(index), DIRECTIONAL_LIGHT_SHADOW),
                color: light.color,
                illuminance: light.illuminance,
                // As `is_on` takes a light it cannot shine for none, a fog
                // energy the fog cannot scale by leaves it out of the fog.
                fog_energy: if light.fog_energy.is_finite() && light.fog_energy > 0. {
                    light.fog_energy
                } else {
                    0.
                },
                // A shadow opacity the blend cannot take draws no shadow.
                shadow_opacity: if light.shadow_opacity.is_finite() {
                    light.shadow_opacity.clamp(0., 1.)
                } else {
                    0.
                },
                disc_radius: disc_radius(light.angular_diameter),
                padding: 0.,
            }
        })
    });
    let shadow_cascades: [ShadowCascadeUniform; MAX_SHADOW_CASCADES] =
        std::array::from_fn(|index| {
            cascades
                .get(index)
                .map_or(ShadowCascadeUniform::zeroed(), |cascade| {
                    ShadowCascadeUniform {
                        clip_from_world: cascade.clip_from_world.to_cols_array_2d(),
                        texel_size: cascade.texel_size,
                        far_bound: cascade.far_bound,
                        padding: [0.; 2],
                    }
                })
        });
    let (backdrop_color, backdrop_yaw, backdrop_brightness) = match input.backdrop {
        Backdrop::Environment { yaw, brightness } => ([0.; 3], yaw, brightness),
        Backdrop::Color(color) => (color, 0., 0.),
    };
    let hemisphere = input.hemisphere_light;
    let mist = input.mist;
    FrameUniform {
        directional_lights,
        shadow_cascades,
        hemisphere_sky_color: hemisphere.sky_color,
        hemisphere_intensity: hemisphere.intensity,
        hemisphere_ground_color: hemisphere.ground_color,
        diffuse_environment_yaw: input.diffuse_environment.yaw,
        backdrop_color,
        diffuse_environment_intensity: input.diffuse_environment.intensity,
        mist_thin_color: mist.thin_color,
        mist_opacity: mist.opacity,
        mist_dense_color: mist.dense_color,
        backdrop_yaw,
        mist_size: [mist.width, mist.height],
        mist_drift: mist.drift,
        backdrop_brightness,
        fog_inverse_length: input.fog.length.recip(),
        fog_inverse_detail_spread: crate::shading::fog::DETAIL_SPREAD.recip(),
        reflection_yaw: input.reflection_environment.yaw,
        reflection_intensity: input.reflection_environment.intensity,
        elapsed_seconds: input.elapsed_seconds as f32,
        fixed_irradiance_scale: baked.atlas_scale,
        visibility_mask: input.visibility_mask,
        lightmap_chart: baked.lightmap_chart,
        flags: flag(fog, FRAME_FOG)
            | flag(input.baked_lighting, FRAME_BAKED_LIGHTING)
            | flag(baked.atlas_installed, FRAME_IRRADIANCE_ATLAS)
            | flag(
                matches!(input.backdrop, Backdrop::Color(_)),
                FRAME_BACKDROP_COLOR,
            )
            | flag(
                shadow.filter == ShadowFilter::Temporal,
                FRAME_TEMPORAL_SHADOW_FILTER,
            )
            | flag(
                shadow.filter == ShadowFilter::Hardware,
                FRAME_HARDWARE_SHADOW_FILTER,
            )
            | flag(dynamic_gi.is_some(), FRAME_DYNAMIC_GI)
            | flag(irradiance_volume.is_some(), FRAME_IRRADIANCE_VOLUME),
        shadow_cascade_count: cascades.len() as u32,
        frame_count: shadow.frame_count,
        animation_phase: crate::shading::material::animation_phase(input.elapsed_seconds),
        dynamic_gi_origin: dynamic_gi
            .map_or([0.; 3], |placement| placement.volume.origin.to_array()),
        padding_origin: 0.,
        dynamic_gi_spacing: dynamic_gi
            .map_or([0.; 3], |placement| placement.volume.spacing.to_array()),
        padding_spacing: 0.,
        dynamic_gi_probes: dynamic_gi.map_or([0; 3], |placement| placement.volume.probes),
        padding_probes: 0,
        dynamic_gi_scroll: dynamic_gi.map_or([0; 3], |placement| placement.scroll),
        padding_scroll: 0,
        irradiance_volume_origin: irradiance_volume
            .map_or([0.; 3], |volume| volume.origin.to_array()),
        padding_volume_origin: 0.,
        irradiance_volume_cell_size: irradiance_volume
            .map_or([0.; 3], |volume| volume.cell_size.to_array()),
        padding_cell_size: 0.,
        irradiance_volume_cells: irradiance_volume.map_or([0; 3], |volume| volume.cells),
        padding_cells: 0,
    }
}

/// The jitter antialiasing applies to a view's raster projection: an NDC
/// offset, and the texture mip bias that goes with it.
#[derive(Clone, Copy, Debug)]
pub(crate) struct Jitter {
    pub ndc: [f32; 2],
    pub mip_bias: f32,
}

/// One view: the view data it renders and culls with. Each kind of view has
/// its constructor.
#[derive(Clone, Copy)]
pub(crate) struct View {
    pub uniform: ViewUniform,
}

impl View {
    /// The main camera, with the view data its frame uploaded.
    pub fn camera(uniform: ViewUniform) -> Self {
        Self { uniform }
    }

    /// Face `face` (0..6) of a static specular probe captured at `center`.
    /// Faces use right-handed views stored as a cube mirrored in world Z, so
    /// scene winding is unchanged; lookups flip Z back.
    pub fn probe_face(center: Vec3, face: u8) -> Self {
        let (direction, up) = PROBE_FACES[usize::from(face)];
        let projection = crate::perspective(std::f32::consts::FRAC_PI_2, 1., 0.1);
        let view = camera::rh::view::look_at_mat4(center, center + direction, up);
        let view_projection = projection * view;
        Self {
            uniform: ViewUniform {
                view: view.to_cols_array_2d(),
                projection: projection.to_cols_array_2d(),
                view_projection: view_projection.to_cols_array_2d(),
                inverse_view_projection: view_projection.inverse().to_cols_array_2d(),
                stable_view_projection: view_projection.to_cols_array_2d(),
                previous_view_projection: view_projection.to_cols_array_2d(),
                eye: center.to_array(),
                mip_bias: 0.,
                jitter: [0.; 2],
                viewport: [0.; 2],
                flags: VIEW_PROBE_CAPTURE,
                padding: [0; 3],
            },
        }
    }

    /// A directional shadow cascade with reversed-Z orthographic
    /// `clip_from_world`: an identity view with the cascade's matrix as the
    /// projection.
    pub fn shadow_cascade(clip_from_world: Mat4) -> Self {
        let clip = clip_from_world.to_cols_array_2d();
        Self {
            uniform: ViewUniform {
                view: Mat4::IDENTITY.to_cols_array_2d(),
                projection: clip,
                view_projection: clip,
                ..ViewUniform::zeroed()
            },
        }
    }

    /// Face `face` (0..6) of the local-light shadow cube of a light at
    /// `position`, reaching `range` metres: a right-handed 90° view along
    /// the face's axis, reversed-Z out to the range.
    pub fn local_shadow_face(face: u8, position: Vec3, range: f32) -> Self {
        let (direction, up) = LOCAL_SHADOW_FACES[usize::from(face)];
        Self::local_shadow(position, direction, up, std::f32::consts::FRAC_PI_2, range)
    }

    /// The local-light shadow face of a spot light at `position` shining
    /// along unit `direction`, its cone `outer_angle` wide and reaching
    /// `range` metres: a view along its direction covering the cone, as
    /// Bevy's and Godot's spot shadows are, reversed-Z out to the range.
    pub fn spot_shadow(position: Vec3, direction: Vec3, outer_angle: f32, range: f32) -> Self {
        let up = if direction.y.abs() < 0.9 {
            Vec3::Y
        } else {
            Vec3::X
        };
        Self::local_shadow(position, direction, up, 2. * outer_angle, range)
    }

    fn local_shadow(position: Vec3, direction: Vec3, up: Vec3, fov: f32, range: f32) -> Self {
        let projection = camera::rh::proj::directx::perspective(fov, 1., range, LOCAL_SHADOW_NEAR);
        let view = camera::rh::view::look_to_mat4(position, direction, up);
        Self {
            uniform: ViewUniform {
                view: view.to_cols_array_2d(),
                projection: projection.to_cols_array_2d(),
                view_projection: (projection * view).to_cols_array_2d(),
                eye: position.to_array(),
                ..ViewUniform::zeroed()
            },
        }
    }

    pub fn view_projection(&self) -> Mat4 {
        Mat4::from_cols_array_2d(&self.uniform.view_projection)
    }

    /// The clip volume an object at `pose` is rasterized against, with the
    /// view's jitter.
    pub fn frustum(&self, pose: Mat4) -> culling::Frustum {
        culling::Frustum::new(
            Mat4::from_cols_array_2d(&self.uniform.view),
            Mat4::from_cols_array_2d(&self.uniform.projection),
            pose,
            self.uniform.jitter,
        )
    }
}

/// One GPU-built view of a frame: its view data, the uniform buffer group 0
/// binds it from, and its draw list, with the CPU time its list took to
/// build (preparing it, and encoding its cull) and its passes since took to
/// record its draws, in milliseconds (diagnostics; zero without them).
pub(crate) struct ViewSlot {
    pub view: View,
    pub buffer: wgpu::Buffer,
    pub list: draw_list::gpu::GpuList,
    #[cfg_attr(not(feature = "diagnostics"), allow(dead_code))]
    build_ms: std::cell::Cell<f64>,
    encode_ms: std::cell::Cell<f64>,
}

impl ViewSlot {
    fn new(device: &wgpu::Device, label: &str) -> Self {
        let view = View {
            uniform: ViewUniform::zeroed(),
        };
        Self {
            buffer: crate::scene::buffer(
                device,
                label,
                bytemuck::bytes_of(&view.uniform),
                wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
            ),
            view,
            list: draw_list::gpu::GpuList::new(device),
            build_ms: std::cell::Cell::new(0.),
            encode_ms: std::cell::Cell::new(0.),
        }
    }

    /// After its list was prepared from `started`: the frame's build and
    /// recording start.
    pub fn built(&mut self, started: crate::counters::Moment) {
        self.build_ms.set(started.elapsed_ms());
        self.encode_ms.set(0.);
    }

    /// Adds the time since `started` to its list's build: the cull stage
    /// took it as it began encoding the list's cull.
    pub fn culled_since(&self, started: crate::counters::Moment) {
        self.build_ms
            .set(self.build_ms.get() + started.elapsed_ms());
    }

    /// Adds the time since `started` to its draws' recording: the caller
    /// took it at the start of a pass that draws its list and calls this
    /// once the pass has ended.
    pub fn recorded_since(&self, started: crate::counters::Moment) {
        self.encode_ms
            .set(self.encode_ms.get() + started.elapsed_ms());
    }

    /// The CPU time its list's last build took and its passes took to
    /// record its draws since.
    #[cfg(feature = "diagnostics")]
    pub fn cpu_ms(&self) -> crate::diagnostics::ViewTime {
        crate::diagnostics::ViewTime {
            build_ms: self.build_ms.get(),
            encode_ms: self.encode_ms.get(),
        }
    }

    /// Sets this slot's view and uploads its uniform.
    pub fn set(&mut self, queue: &wgpu::Queue, view: View) {
        self.view = view;
        crate::counters::write_buffer(queue, &self.buffer, 0, bytemuck::bytes_of(&view.uniform));
    }
}

/// The views of one frame and what each sees, built once per frame by the
/// prepare stage and read by every later stage: the camera and its
/// clusters, the light and decal lists of world-space ray hits and of the
/// dynamic GI probe rays' hits, the directional shadow's cascades and the
/// draw instances of every CPU-built list the frame draws.
pub(crate) struct FrameViews {
    pub camera: ViewSlot,
    /// The camera's blended surfaces, back to front; `camera.list` holds
    /// its opaque and masked ones.
    pub blended: draw_list::DrawList,
    /// The scene lights and decals that reach each of the camera's
    /// clusters.
    pub clusters: clusters::Clusters,
    /// The scene lights and decals world-space ray hits shade with.
    pub ray_lists: clusters::Clusters,
    /// The scene lights and decals the dynamic GI probe rays' hits shade
    /// with.
    pub volume_lists: clusters::Clusters,
    /// Each directional shadow cascade, nearest first; the frame uses the
    /// first `cascade_count`.
    pub cascades: [ViewSlot; MAX_SHADOW_CASCADES],
    pub cascade_count: usize,
    /// The camera as reflections and DiligentFX see it: its view and its
    /// projection with the frame's jitter.
    pub reflection_camera: reflection_camera::Camera,
    /// Every CPU-built draw list's instances this frame: the blended
    /// list's and the local-light shadow faces'.
    pub instances: draw_list::DrawInstances,
}

impl FrameViews {
    pub fn new(device: &wgpu::Device) -> Self {
        Self {
            camera: ViewSlot::new(device, "camera view"),
            blended: draw_list::DrawList::default(),
            clusters: clusters::Clusters::new(device, "camera clusters"),
            ray_lists: clusters::Clusters::new(device, "ray hit lights and decals"),
            volume_lists: clusters::Clusters::new(device, "dynamic GI probe hit lights and decals"),
            cascades: std::array::from_fn(|_| ViewSlot::new(device, "directional shadow cascade")),
            cascade_count: 0,
            reflection_camera: reflection_camera::Camera::new(Mat4::IDENTITY, Mat4::IDENTITY),
            instances: draw_list::DrawInstances::default(),
        }
    }
}