Skip to main content

sgl_3d/renderer/
view.rs

1//! One camera's frame: its targets and sizes, its stages with their state,
2//! group 0's bindings, and every history kept in screen space or fit to its
3//! camera, which `frame::render_view` renders after the frame's shared
4//! scene work (`shared::Shared`).
5use super::Renderer;
6use super::effective;
7use super::shared::Shared;
8use crate::settings::{Antialiasing, RenderPreset, Settings};
9use crate::stages::shadows::local::LocalShadowStats;
10use crate::stages::{
11    antialiasing, cull::Cull, exposure::Exposure, fog::VolumetricFog, motion_blur::MotionBlur,
12    opaque::Opaque, post::Post, reflections::Reflections, shadows::Shadows,
13    shadows::contact::ContactShadowStage, shadows::traced::TracedShadows, sky::Sky,
14    transparent::Transparent,
15};
16use crate::view::FrameViews;
17use crate::view::bindings::FrameBindings;
18use crate::view::draw_list::GeometryStats;
19use crate::view::draw_list::readback::StatisticsReadback;
20use crate::view::effective::Effective;
21use crate::view::history::{CameraFrame, CameraHistory, HistoryFrame};
22use crate::view::post_fx::PostFx;
23use crate::view::targets::{SharedTargets, Sizes};
24use crate::{FrameInput, Scene};
25use std::sync::Arc;
26use std::sync::atomic::{AtomicBool, Ordering};
27
28/// One view's part of a frame ([`Renderer::render`]): the view, its
29/// camera and frame values, its settings and the texture it renders into,
30/// a view of its output format and size (offscreen or a surface's). Scene
31/// work is timed with the primary view's `timing`.
32pub struct ViewFrame<'a> {
33    pub view: &'a mut View,
34    pub input: &'a FrameInput,
35    pub settings: &'a Settings,
36    pub output: &'a wgpu::TextureView,
37    pub timing: Option<&'a crate::timing::GpuTiming>,
38}
39
40/// Why a view could not be created.
41#[derive(Debug)]
42pub enum ViewError {
43    /// SMAA's lookup textures did not decode.
44    LookupTextures(image::ImageError),
45    /// The surface requires an unsupported transfer or format/colour-space pair.
46    UnsupportedSurfaceOutput {
47        format: wgpu::TextureFormat,
48        color_space: wgpu::SurfaceColorSpace,
49    },
50}
51
52impl std::fmt::Display for ViewError {
53    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
54        match self {
55            Self::LookupTextures(error) => write!(f, "SMAA lookup textures: {error}"),
56            Self::UnsupportedSurfaceOutput {
57                format,
58                color_space,
59            } => {
60                write!(
61                    f,
62                    "unsupported SGL3D surface output: {format:?} in {color_space:?}"
63                )
64            }
65        }
66    }
67}
68
69impl std::error::Error for ViewError {
70    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
71        match self {
72            Self::LookupTextures(error) => Some(error),
73            Self::UnsupportedSurfaceOutput { .. } => None,
74        }
75    }
76}
77
78/// One camera's frame of a scene: its targets and sizes, its stages with
79/// their state, group 0's bindings, and every history kept in screen space
80/// or fit to its camera. A game creates one for each image of the scene it
81/// draws (a window, each half of a split screen, an inset, a rear view, an
82/// editor's viewports), sizes it with [`View::resize`], lists it in
83/// [`Renderer::render`] and drops it when it is done, which releases
84/// everything it held. Its history continues only from its scene's last
85/// finished frame, so a view that a finished frame of its scene did not
86/// render restarts, as on a cut.
87// The stages of more than 2 KB are boxed: a debug build copies a `View`
88// several times on the stack as it is built and moved, in the game's code
89// too, and the debug WASM stack is 1 MB (#839).
90pub struct View {
91    pub(crate) output_encodes_srgb: bool,
92    pub(crate) sizes: Sizes,
93    /// A change of preset restarts history even if the pixel sizes agree.
94    preset: RenderPreset,
95    pub(crate) targets: SharedTargets,
96    pub(crate) views: Box<FrameViews>,
97    pub(crate) bindings: FrameBindings,
98    /// DiligentFX's post-effect context, while TAA or Crystal SSR runs.
99    pub(crate) post_fx: Option<Box<PostFx>>,
100    pub(crate) cull: Cull,
101    /// The procedural sky's tables, while its frames name one.
102    pub(crate) sky: Sky,
103    /// The camera's geometry statistics, read back without blocking.
104    pub(crate) statistics: StatisticsReadback,
105    pub(crate) shadows: Shadows,
106    pub(crate) traced_shadows: Box<TracedShadows>,
107    pub(crate) contact_shadows: Box<ContactShadowStage>,
108    pub(crate) fog: VolumetricFog,
109    pub(crate) opaque: Opaque,
110    pub(crate) reflections: Box<Reflections>,
111    pub(crate) transparent: Transparent,
112    pub(crate) exposure: Exposure,
113    pub(crate) antialiasing: antialiasing::Antialiasing,
114    pub(crate) motion_blur: MotionBlur,
115    pub(crate) post: Box<Post>,
116    pub(crate) history: CameraHistory,
117    /// History restarts: the targets changed since the last finished frame
118    /// was rendered, or the view's last render was a reset that was not
119    /// finished. A reset holds until a frame is finished.
120    pub(crate) pending_reset: bool,
121    /// Counts target changes, so `settle` keeps a reset requested after the
122    /// frame it commits was rendered.
123    pub(crate) targets_generation: u64,
124    /// The scene frame attempt of the view's last finished frame.
125    pub(crate) finished: Option<u64>,
126    /// The last rendered frame, which `settle` commits or drops.
127    pub(crate) rendered: Option<Pending>,
128    /// The identity of the renderer that created the view (`Renderer::id`).
129    pub(crate) renderer: u64,
130    /// The numerical frame probe, once a frame asked for it.
131    #[cfg(feature = "diagnostics")]
132    pub(crate) probe: Option<crate::stages::frame_probe::FrameProbe>,
133    /// Which target completed the last rendered frame's scene
134    /// (`DiagnosticTarget::Antialiased`).
135    #[cfg(any(test, feature = "diagnostics"))]
136    pub(crate) completed: Option<crate::view::frame::Completed>,
137}
138
139/// A rendered frame the view has not settled: the scene frame attempt it
140/// was part of, the flag `Renderer::finish_frame` sets when that attempt is
141/// finished, its history and the targets generation it rendered with.
142pub(crate) struct Pending {
143    pub attempt: u64,
144    pub finished: Arc<AtomicBool>,
145    pub history: HistoryFrame,
146    pub generation: u64,
147}
148
149impl View {
150    /// A view of `renderer`'s scenes rendering into a composition texture
151    /// at `output_size` physical pixels at `device_scale`, with its stages
152    /// built for the frame `settings` describe. Float textures hold
153    /// display-referred linear sRGB on both platforms. An sRGB attachment
154    /// performs its transfer; other unorm outputs receive sRGB-encoded
155    /// colour. Use [`Self::new_surface`] for direct presentation.
156    pub fn new(
157        renderer: &Renderer,
158        device: &wgpu::Device,
159        queue: &wgpu::Queue,
160        output_format: wgpu::TextureFormat,
161        output_size: [u32; 2],
162        device_scale: f32,
163        settings: &Settings,
164    ) -> Result<Self, ViewError> {
165        Self::with_output(
166            renderer,
167            (device, queue),
168            crate::stages::post::Output::texture(output_format),
169            output_size,
170            device_scale,
171            settings,
172        )
173    }
174
175    /// A view of `renderer`'s scenes rendering directly to a surface
176    /// configured with `config`. Its format and colour space determine the
177    /// display transfer, including browser float canvases. Supports Auto,
178    /// sRGB, extended sRGB and extended linear sRGB. Pass
179    /// `surface.get_capabilities(&adapter)` from the configured surface so
180    /// native Auto float output follows its actual linear/sRGB capability.
181    /// Recreate the view when the surface format or colour space changes.
182    pub fn new_surface(
183        renderer: &Renderer,
184        device: &wgpu::Device,
185        queue: &wgpu::Queue,
186        config: &wgpu::SurfaceConfiguration,
187        capabilities: &wgpu::SurfaceCapabilities,
188        device_scale: f32,
189        settings: &Settings,
190    ) -> Result<Self, ViewError> {
191        let output = crate::stages::post::Output::surface(
192            config,
193            capabilities,
194            device.adapter_info().backend,
195        )
196        .ok_or(ViewError::UnsupportedSurfaceOutput {
197            format: config.format,
198            color_space: config.color_space,
199        })?;
200        Self::with_output(
201            renderer,
202            (device, queue),
203            output,
204            [config.width, config.height],
205            device_scale,
206            settings,
207        )
208    }
209
210    fn with_output(
211        renderer: &Renderer,
212        (device, queue): (&wgpu::Device, &wgpu::Queue),
213        output: crate::stages::post::Output,
214        output_size: [u32; 2],
215        device_scale: f32,
216        settings: &Settings,
217    ) -> Result<Self, ViewError> {
218        let shared = &renderer.shared;
219        let scene = effective::scene_size(
220            output_size,
221            settings.preset,
222            settings.scene_resolution,
223            device_scale,
224        );
225        let sizing = effective::sizing(settings);
226        let mut antialiasing = antialiasing::Antialiasing::default();
227        let (render, _) = antialiasing.resize(device, scene, sizing.fsr);
228        let sizes = Sizes {
229            render,
230            scene,
231            output: output_size,
232        };
233        let layouts = &shared.layouts;
234        let views = Box::new(FrameViews::new(device));
235        let shadows = Shadows::new(device, settings.shadow_quality);
236        let fog = VolumetricFog::new(device);
237        let bindings = FrameBindings::new(
238            device,
239            layouts,
240            &views,
241            shadows.maps(),
242            fog.volume(),
243            shared
244                .dynamic_gi
245                .as_ref()
246                .map(crate::stages::dynamic_gi::DynamicGi::probes),
247        );
248        let targets = SharedTargets::new(device, render, false);
249        let cull = Cull::new(device);
250        let exposure = Exposure::new(device);
251        let first_frame = effective::first_frame(
252            settings,
253            shared.device(antialiasing.fsr_running(), cull.occlusion_supported()),
254        );
255        Ok(Self {
256            output_encodes_srgb: output.encodes_srgb,
257            opaque: Opaque::new(
258                device,
259                &bindings.unlit,
260                [
261                    &bindings.shadow_mask,
262                    &bindings.contact_shadow,
263                    &bindings.screen_indirect,
264                    &bindings.shadow_mask_screen_indirect,
265                    &bindings.contact_shadow_screen_indirect,
266                ],
267            ),
268            traced_shadows: Box::new(TracedShadows::new(device, &bindings.lit, &bindings.scene)),
269            contact_shadows: Box::new(ContactShadowStage::new(device)),
270            reflections: Box::new(Reflections::new(device, queue, render, &first_frame)),
271            transparent: Transparent::new(
272                device,
273                &bindings.blended,
274                exposure.view(),
275                bindings.lit.tier,
276            ),
277            exposure,
278            antialiasing,
279            motion_blur: MotionBlur::new(device, first_frame.motion_blur.is_some()),
280            post: Box::new(
281                Post::new(
282                    device,
283                    queue,
284                    output,
285                    sizes,
286                    first_frame.bloom,
287                    (first_frame.antialiasing == Antialiasing::Smaa && first_frame.smaa)
288                        .then_some(settings.smaa_quality),
289                )
290                .map_err(ViewError::LookupTextures)?,
291            ),
292            cull,
293            sky: Sky::default(),
294            statistics: StatisticsReadback::default(),
295            sizes,
296            preset: settings.preset,
297            targets,
298            views,
299            bindings,
300            post_fx: None,
301            shadows,
302            fog,
303            history: CameraHistory::default(),
304            pending_reset: false,
305            targets_generation: 0,
306            finished: None,
307            rendered: None,
308            renderer: renderer.id,
309            #[cfg(feature = "diagnostics")]
310            probe: None,
311            #[cfg(any(test, feature = "diagnostics"))]
312            completed: None,
313        })
314    }
315
316    /// Sizes the targets for an output of `output_size` physical pixels at
317    /// `device_scale` and the size-affecting settings, and starts or stops
318    /// FSR. Cheap when nothing changed, so a game calls it every frame;
319    /// when the targets change, the view's history restarts.
320    pub fn resize(
321        &mut self,
322        device: &wgpu::Device,
323        output_size: [u32; 2],
324        device_scale: f32,
325        settings: &Settings,
326    ) {
327        self.settle(false);
328        let scene = effective::scene_size(
329            output_size,
330            settings.preset,
331            settings.scene_resolution,
332            device_scale,
333        );
334        let sizing = effective::sizing(settings);
335        let (render, restarted) = self.antialiasing.resize(device, scene, sizing.fsr);
336        if restarted {
337            self.pending_reset = true;
338            self.targets_generation = self.targets_generation.wrapping_add(1);
339            self.post.forget_inputs();
340            self.motion_blur.forget_inputs();
341            self.antialiasing.forget_inputs();
342        }
343        let sizes = Sizes {
344            render,
345            scene,
346            output: output_size,
347        };
348        if self.sizes == sizes && self.preset == settings.preset {
349            return;
350        }
351        self.targets = SharedTargets::new(device, render, self.targets.surface.is_some());
352        self.exposure.forget_inputs();
353        self.motion_blur.forget_inputs();
354        self.antialiasing.forget_inputs();
355        self.post.resize(device, sizes, sizing.bloom_targets);
356        self.transparent.resize(device, &self.targets);
357        self.reflections.resize(device, render);
358        self.sizes = sizes;
359        self.preset = settings.preset;
360        self.pending_reset = true;
361        self.targets_generation = self.targets_generation.wrapping_add(1);
362    }
363
364    /// Whether shaders must write sRGB-encoded values into this view's
365    /// output. Use the same transfer for UI composed directly over the
366    /// scene; false means linear values (including hardware sRGB attachment
367    /// encoding).
368    pub fn output_encodes_srgb(&self) -> bool {
369        self.output_encodes_srgb
370    }
371
372    /// The antialiasing that runs for `settings`: their choice resolved for
373    /// the preset, with TAA where FSR is chosen but not running (see
374    /// `fsr_error`, or awaiting `resize`). The saved choice is unchanged.
375    pub fn antialiasing_in_effect(&self, settings: &Settings) -> Antialiasing {
376        effective::antialiasing(settings, self.antialiasing.fsr_running())
377    }
378
379    /// Why the FSR version selected at the last `resize` is unavailable.
380    /// Failures are retained independently for FSR2 and FSR3.
381    pub fn fsr_error(&self) -> Option<&str> {
382        self.antialiasing.error()
383    }
384
385    /// The size every pass up to antialiasing renders at: the scene size,
386    /// or FSR's render size while it upscales.
387    pub fn render_size(&self) -> [u32; 2] {
388        self.sizes.render
389    }
390
391    /// The size motion blur, bloom, SMAA and tone mapping run at
392    /// (`SceneResolution`).
393    pub fn scene_size(&self) -> [u32; 2] {
394        self.sizes.scene
395    }
396
397    /// The camera's submitted geometry in the most recent completed frame:
398    /// its opaque and masked surfaces counted on the GPU and read back
399    /// without blocking, the map requested once the frame was finished,
400    /// with its blended surfaces' counts from the same frame. None until a
401    /// frame's readback has arrived, which takes a few frames.
402    pub fn geometry_stats(&mut self, device: &wgpu::Device) -> Option<GeometryStats> {
403        self.settle(false);
404        self.statistics.poll(device);
405        self.statistics.latest()
406    }
407
408    /// The last rendered frame's local-light shadows: how many casting
409    /// lights in the camera's view have a shadow, how many the atlas had no
410    /// room for, and what the frame drew.
411    pub fn local_shadow_stats(&self) -> LocalShadowStats {
412        self.shadows.local.stats()
413    }
414
415    /// Whether `Settings::occlusion_culling` runs for `settings`: it is on,
416    /// the device binds the depth pyramid's six storage textures a stage
417    /// (`graphics_device::limits` requests the adapter's) and, with the
418    /// `diagnostics` feature, the culling layer is on. Otherwise the camera
419    /// culls by frustum alone. The saved choice is unchanged.
420    pub fn occlusion_culling_in_effect(&self, settings: &Settings) -> bool {
421        settings.occlusion_culling
422            && self.cull.occlusion_supported()
423            && !settings.diagnostics_in_effect().disable.culling
424    }
425
426    /// Begins the view's frame of `scene` seen as `input` with `settings`:
427    /// settles its last render, begins its history (which restarts for a
428    /// camera cut, a resize, an unfinished reset, and a frame that does not
429    /// follow its own last finished frame), and resolves its effective
430    /// configuration, holding the surface's targets from a scene's first
431    /// receiver on and the temporal masks while a writer can mark them.
432    pub(super) fn begin(
433        &mut self,
434        device: &wgpu::Device,
435        shared: &Shared,
436        scene: &Scene,
437        input: &FrameInput,
438        settings: &Settings,
439    ) -> (HistoryFrame, Effective) {
440        self.settle(true);
441        let history = self.begin_history(scene, input);
442        if scene.materials.holds_receivers() {
443            self.targets.hold_surface(device);
444        }
445        let effective = effective::resolve(
446            settings,
447            input,
448            effective::SceneContent::of(scene),
449            shared.device(
450                self.antialiasing.fsr_running(),
451                self.cull.occlusion_supported(),
452            ),
453        );
454        self.targets
455            .set_temporal_masks(device, effective.temporal_masks);
456        (history, effective)
457    }
458
459    /// The history of a frame of `scene` seen by `input`'s camera, in the
460    /// render frame of the scene's origin. It continues only from the
461    /// scene's last finished frame, when that frame rendered this view, and
462    /// not while a reset is pending (a resize, or a reset rendered and not
463    /// finished).
464    pub(crate) fn begin_history(&self, scene: &Scene, input: &FrameInput) -> HistoryFrame {
465        let reset = input.camera_cut
466            || self.pending_reset
467            || self.finished.is_none()
468            || self.finished != scene.last_finished();
469        let camera = CameraFrame {
470            view: input.camera.view,
471            projection: input.camera.projection,
472            jitter: [0.; 2],
473        };
474        let mut frame = self.history.begin(
475            camera,
476            reset,
477            scene.origin(),
478            input.elapsed_seconds,
479            input.visibility_mask,
480        );
481        self.history
482            .set_backdrop(&mut frame, crate::view::backdrop_yaw(input));
483        frame
484    }
485
486    /// Settles the last render, if one is pending, and the view renders
487    /// `again` or it was finished (`Renderer::finish_frame` set its
488    /// attempt's flag, whichever frames came after it). A finished render
489    /// commits its camera history, its reset, its local shadow cache,
490    /// culling pyramid, exposure, statistics and probe readback; an
491    /// unfinished reset holds, so the next render resets too (a cut that
492    /// was never shown has not happened yet). Then every stage that keeps
493    /// what describes its GPU history as the last finished frame left it
494    /// (`view::history::Kept`) settles it: exactly once per render, at the
495    /// start of the view's first `&mut self` method after its frame was
496    /// finished, or as unfinished when it renders again first. A method
497    /// called between `render` and `finish_frame` leaves the render
498    /// pending. The History contract's "What a frame commits".
499    pub(crate) fn settle(&mut self, again: bool) {
500        let Some(pending) = &self.rendered else {
501            return;
502        };
503        let finished = pending.finished.load(Ordering::Acquire);
504        if !finished && !again {
505            return;
506        }
507        let Some(Pending {
508            attempt,
509            history,
510            generation,
511            ..
512        }) = self.rendered.take()
513        else {
514            return;
515        };
516        if !finished && !history.valid {
517            self.pending_reset = true;
518        }
519        if finished {
520            self.history.finish(history);
521            // A resize after the render still restarts the next frame.
522            if generation == self.targets_generation {
523                self.pending_reset = false;
524            }
525            self.finished = Some(attempt);
526            self.shadows.local.finish_frame();
527            self.cull.finish_frame();
528            self.exposure.finish_frame();
529            self.statistics.submitted();
530            #[cfg(feature = "diagnostics")]
531            if let Some(probe) = &mut self.probe {
532                probe.submitted();
533            }
534        }
535        if let Some(post_fx) = &mut self.post_fx {
536            post_fx.settle(finished);
537        }
538        self.antialiasing.settle(finished);
539        self.sky.settle(finished);
540        self.reflections.settle(finished);
541        self.opaque.settle(finished);
542        self.traced_shadows.settle(finished);
543    }
544}