sgl-3d 0.4.2

Caller-driven 3D rendering for SGL games, native and in the browser (WebGPU)
Documentation
//! The camera's history: the last submitted frame's unjittered view and
//! projection, with the jitter antialiasing applied to that frame, its time
//! (`FrameInput::elapsed_seconds`), at which a material's vertex function
//! evaluates the motion it writes, and the frames since the last reset. The renderer owns it; a frame commits to it
//! only when the caller finishes that frame. It is kept in the render frame
//! of the scene's origin it was committed at, and a frame whose scene moved
//! its origin since sees it translated into its own (the architecture's
//! History contract).
use glam::{DMat4, DVec3, Mat4, Vec3};

/// One frame's camera: its unjittered view and projection, and the jitter
/// (NDC) antialiasing applied to its projection, zero without one.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) struct CameraFrame {
    pub view: Mat4,
    pub projection: Mat4,
    pub jitter: [f32; 2],
}

impl CameraFrame {
    /// Its projection as it rasterized, the jitter applied: the projection
    /// prepare draws the frame with.
    pub fn jittered_projection(&self) -> Mat4 {
        Mat4::from_translation(Vec3::new(self.jitter[0], self.jitter[1], 0.)) * self.projection
    }

    /// Its view-projection as it rasterized.
    pub fn jittered_view_projection(&self) -> Mat4 {
        self.jittered_projection() * self.view
    }

    /// The same camera in a render frame whose origin lies `by` from this
    /// one's: positions there are this frame's less `by`. The view is
    /// composed with the translation in double precision and rounded once.
    fn translated(self, by: DVec3) -> Self {
        if by == DVec3::ZERO {
            return self;
        }
        Self {
            view: (self.view.as_dmat4() * DMat4::from_translation(by)).as_mat4(),
            ..self
        }
    }
}

/// One frame's view of the camera history.
#[derive(Clone, Copy)]
pub(crate) struct HistoryFrame {
    /// This frame's unjittered view-projection.
    pub stable: Mat4,
    /// The previous frame's unjittered view-projection (this frame's after a reset).
    pub previous: Mat4,
    /// The last submitted frame's camera in this frame's render frame; none
    /// after a reset.
    pub previous_camera: Option<CameraFrame>,
    /// False after a reset: history from earlier frames must not be reused.
    pub valid: bool,
    /// Frames since the last reset.
    pub frames: u32,
    /// This frame's camera, which `finish` commits; its jitter is set once
    /// antialiasing chose it.
    pub camera: CameraFrame,
    /// The scene's render origin this frame (`Scene::origin`).
    pub origin: DVec3,
    /// This frame's time, which `finish` commits, and the last submitted
    /// frame's; this frame's after a reset.
    pub elapsed_seconds: f64,
    pub previous_elapsed_seconds: f64,
}

/// A stage's temporal history: its frame count since it last restarted (0
/// restarts it), and the half of each history pair the frame writes, the
/// other holding the last frame's. The half alternates every frame the
/// stage runs, apart from the count, so the count skipping 0 as it wraps
/// never writes one half twice in a row.
#[derive(Clone, Copy, Default)]
pub(crate) struct StageHistory {
    pub count: u32,
    pub current: usize,
}

impl StageHistory {
    pub fn advance(&mut self) {
        self.count = self.count.wrapping_add(1).max(1);
        self.current = 1 - self.current;
    }
}

#[derive(Default)]
pub(crate) struct CameraHistory {
    previous: Option<CameraFrame>,
    frames: u32,
    /// The render origin `previous` is expressed in.
    origin: DVec3,
    /// The last submitted frame's time.
    elapsed_seconds: f64,
}

impl CameraHistory {
    /// The history of a frame seen by `camera` at `elapsed_seconds` with the
    /// scene's origin at `origin`, restarted when `reset`. Nothing changes
    /// until `finish`, so an abandoned frame translates nothing twice.
    pub fn begin(
        &self,
        camera: CameraFrame,
        reset: bool,
        origin: DVec3,
        elapsed_seconds: f64,
    ) -> HistoryFrame {
        let (previous, frames) = if reset {
            (None, 0)
        } else {
            (
                self.previous
                    .map(|previous| previous.translated(origin - self.origin)),
                self.frames,
            )
        };
        let stable = camera.projection * camera.view;
        HistoryFrame {
            stable,
            previous: previous.map_or(stable, |previous| previous.projection * previous.view),
            previous_camera: previous,
            valid: previous.is_some(),
            frames,
            camera,
            origin,
            elapsed_seconds,
            previous_elapsed_seconds: if previous.is_some() {
                self.elapsed_seconds
            } else {
                elapsed_seconds
            },
        }
    }

    /// Commits `frame`, which the caller submitted.
    pub fn finish(&mut self, frame: HistoryFrame) {
        self.previous = Some(frame.camera);
        self.frames = frame.frames.wrapping_add(1);
        self.origin = frame.origin;
        self.elapsed_seconds = frame.elapsed_seconds;
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use glam::Vec4;
    use wasm_bindgen_test::wasm_bindgen_test;

    // Plausible defects: the previous camera kept in the old render frame,
    // translated the wrong way, translated again by a frame that was not
    // finished, or left untranslated by a reset. The oracle is the world:
    // a point the game expresses in the new frame (less the move) projects
    // through the translated previous camera where the same point projected
    // through the previous camera before the move.
    #[wasm_bindgen_test(unsupported = test)]
    fn a_moved_origin_reprojects_the_same_world_point() {
        let projection = crate::perspective(1.1, 1.5, 0.1);
        let eye = Vec3::new(5003.25, 12.5, -7020.75);
        let camera = |eye: Vec3| CameraFrame {
            view: glam::camera::rh::view::look_at_mat4(
                eye,
                eye + Vec3::new(1., -0.2, -1.),
                Vec3::Y,
            ),
            projection,
            jitter: [0.25, -0.5],
        };
        let mut history = CameraHistory::default();
        let first = history.begin(camera(eye), false, DVec3::ZERO, 0.);
        history.finish(first);
        let moved = Vec3::new(5000., 0., -7000.);
        let point = Vec3::new(5010.5, 11., -7031.);
        let before = first.camera.jittered_view_projection() * point.extend(1.);
        // An abandoned frame after the move, then the frame that finishes.
        for _ in 0..2 {
            let frame = history.begin(camera(eye - moved), false, moved.as_dvec3(), 0.);
            let previous = frame.previous_camera.expect("history continues");
            let after = previous.jittered_view_projection() * (point - moved).extend(1.);
            let ndc = |clip: Vec4| clip.truncate() / clip.w;
            assert!(
                (ndc(before) - ndc(after)).abs().max_element() < 1e-4,
                "{:?} became {:?}",
                ndc(before),
                ndc(after)
            );
            assert_eq!(previous.jitter, first.camera.jitter);
        }
        let reset = history.begin(camera(eye - moved), true, moved.as_dvec3(), 0.);
        assert!(reset.previous_camera.is_none() && !reset.valid);
    }

    // Plausible defect: the frame count stops at its cap, so every later
    // frame looks like a gap and TAA, SSR, fog and the traced stages restart
    // their history each frame. The oracle is the stages' continuity rule:
    // a frame continues the last when its count is the last's plus one,
    // wrapping.
    #[wasm_bindgen_test(unsupported = test)]
    fn consecutive_frames_continue_across_the_frame_count_s_wrap() {
        let camera = CameraFrame {
            view: Mat4::IDENTITY,
            projection: crate::perspective(1.1, 1.5, 0.1),
            jitter: [0.; 2],
        };
        let mut history = CameraHistory {
            frames: u32::MAX - 1,
            ..CameraHistory::default()
        };
        let mut last = None;
        for _ in 0..4 {
            let frame = history.begin(camera, false, DVec3::ZERO, 0.);
            if let Some(last) = last {
                assert_eq!(frame.frames, u32::wrapping_add(last, 1));
            }
            last = Some(frame.frames);
            history.finish(frame);
        }
    }

    #[wasm_bindgen_test(unsupported = test)]
    fn the_history_halves_alternate_across_the_frame_count_s_wrap() {
        let mut frame = StageHistory {
            count: u32::MAX - 2,
            current: 1,
        };
        let mut written = vec![frame.current];
        for _ in 0..6 {
            frame.advance();
            assert_ne!(frame.count, 0, "only a restart sets the count to 0");
            written.push(frame.current);
        }
        for pair in written.windows(2) {
            assert_ne!(
                pair[0], pair[1],
                "consecutive frames wrote one half: {written:?}"
            );
        }
    }
}