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
//! 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, its visibility mask, 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,
/// This frame's visibility mask (`FrameInput::visibility_mask`), which
/// `finish` commits.
pub visibility_mask: u32,
/// Whether it differs from the last submitted frame's: material groups
/// appeared or departed without moving, which rearms TAA's rejection
/// across the view. False after a reset, which restarts every history.
pub visibility_changed: bool,
}
/// 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,
/// The last submitted frame's visibility mask.
visibility_mask: u32,
}
impl CameraHistory {
/// The history of a frame seen by `camera` at `elapsed_seconds` with the
/// scene's origin at `origin` and `visibility_mask` enabling its material
/// groups, restarted when `reset`. Nothing changes until `finish`, so an
/// abandoned frame translates nothing twice and a mask change it saw is
/// seen again by the next.
pub fn begin(
&self,
camera: CameraFrame,
reset: bool,
origin: DVec3,
elapsed_seconds: f64,
visibility_mask: u32,
) -> 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
},
visibility_mask,
visibility_changed: previous.is_some() && visibility_mask != self.visibility_mask,
}
}
/// 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;
self.visibility_mask = frame.visibility_mask;
}
}
#[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., 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., 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., 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., 0);
if let Some(last) = last {
assert_eq!(frame.frames, u32::wrapping_add(last, 1));
}
last = Some(frame.frames);
history.finish(frame);
}
}
// Plausible defects: a mask change never reported (the old image of a
// hidden group fades out over many frames at TAA's relaxed rejection),
// the comparison value committed when a frame is rendered rather than
// submitted (an abandoned frame or a frame rendered again loses the
// change), the change reported on every later frame (stabilization
// never returns), or a change in the high bits ignored although
// `Material::enabled` tests every bit. The oracle is the architecture's
// rule (Frame item 10) that appearances and departures rearm the view
// until a submitted frame; the expected values follow from the masks
// each frame passes, compared by hand.
#[wasm_bindgen_test(unsupported = test)]
fn a_changed_visibility_mask_is_reported_until_a_frame_is_finished() {
let camera = CameraFrame {
view: Mat4::IDENTITY,
projection: crate::perspective(1.1, 1.5, 0.1),
jitter: [0.; 2],
};
let mut history = CameraHistory::default();
let frame = |history: &mut CameraHistory, reset: bool, mask: u32, finish: bool| {
let frame = history.begin(camera, reset, DVec3::ZERO, 0., mask);
if finish {
history.finish(frame);
}
frame.visibility_changed
};
assert!(
!frame(&mut history, true, 0b11, true),
"the first frame restarts history: nothing to compare"
);
assert!(!frame(&mut history, false, 0b11, true), "an unchanged mask");
assert!(frame(&mut history, false, 0b01, false), "group 2 departs");
assert!(
frame(&mut history, false, 0b01, false),
"the abandoned frame did not consume the change"
);
assert!(
frame(&mut history, false, 0b01, true),
"nor did a frame rendered twice"
);
assert!(
!frame(&mut history, false, 0b01, true),
"the change was submitted"
);
assert!(
frame(&mut history, false, 0b01 | 1 << 30, true),
"a high group appears"
);
assert!(
!frame(&mut history, true, 0b11, true),
"a reset restarts history, which needs no signal"
);
assert!(
!frame(&mut history, false, 0b11, true),
"the reset frame committed its mask"
);
assert!(
frame(&mut history, false, 0b01, false),
"group 2 departs in a frame that is abandoned"
);
assert!(
!frame(&mut history, false, 0b11, true),
"a mask changed back before any frame was finished changed nothing"
);
}
#[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:?}"
);
}
}
}