use super::{EffectcraftApp, FrameKey, FrameWindow, ItemId, PlaybackPass, frames}; /// Seconds without a project change before paused prefetch resumes (see /// [`EffectcraftApp::editing`]). const EDIT_QUIET: f64 = 0.3; /// Longest a preview with sound holds its first frame, once that frame is cached, waiting for the /// frames ahead (seconds, #947). A frame ahead that never gets cached mustn't hold it for ever: /// the sound starts from the first frame anyway, and the preview goes on as a stalled one does. const STARTUP_WAIT: f64 = 2.0; /// Longest a preview with sound holds its first frame in all (seconds, #947). The first frame /// itself can take a while (a heavy comp, a busy machine), and [`STARTUP_WAIT`] counts only from /// when it is cached; but one that never gets cached (larger than the RAM preview, which the size /// estimate can't always tell) mustn't hold it for ever. The preview then goes on as a stalled /// one does: its sound starts once the frames are cached. const STARTUP_LIMIT: f64 = 10.0; /// How many frames from the first a preview with sound waits for before it starts (#947): the /// prefetch's `ahead`, but no more than its `window` requests from the current frame (offsets /// `0..window`), and no more than fit in the RAM preview `budget` (90 %, as for the prefetch) at /// `frame_bytes`, the size frames really render at; at least the current frame, which the viewer /// always requests. Waiting for a frame that is never requested, or that can't stay cached with /// the others, would hold the first frame for ever. fn startup_frames(ahead: i64, window: i64, budget: usize, frame_bytes: usize) -> i64 { let fit = (budget as f64 * 0.9 / frame_bytes.max(1) as f64) as i64; ahead.min(window).min(fit).max(1) } /// Whether frame `f` comes after the current frame `cur` and before the sound's frame `target` in /// play order. A looping preview whose sound is at a lower frame than the picture has wrapped /// to the loop's start, so the frames up to the end and then from the start count; otherwise /// (and always without a loop) only the frames strictly between them do. fn between_picture_and_sound(cur: i64, f: i64, target: i64, looping: bool) -> bool { if target >= cur || !looping { cur < f && f < target } else { f > cur || f < target } } /// How long the pace takes to follow the rate frames arrive at (seconds, the time constant of /// its smoothing): short enough to follow a change, long enough to play through a batch of /// frames finishing together. const PACE_TAU: f64 = 0.5; /// The rate a preview plays at when frames arrive slower than its frame rate: proportional to /// the cached frames ahead (`lead` of `target`), so it settles where the clock takes frames as /// fast as they arrive and the lead stays put; smoothed over [`PACE_TAU`] (`dt` seconds since /// the last pass). Never above the frame rate, never under an eighth of it (slower reads as /// stopped: the clock holds instead). No frame ahead: the previous pace, the clock holds anyway. fn pace_for(prev: f64, lead: i64, target: i64, fps: f64, dt: f64) -> f64 { if lead <= 0 || target <= 0 || fps <= 0.0 { return prev; } let raw = (fps * lead as f64 / target as f64).clamp(fps / 8.0, fps); let k = 1.0 - (-dt.max(0.0) / PACE_TAU).exp(); prev + (raw - prev) * k } /// How many frames after the current one the pace measures its lead over: twice the prefetch /// depth `ahead`, but only frames the RAM preview can keep cached together with the current one. /// `prefetch_playback` requests offsets `0..fit_ahead` from the current frame (the current frame /// and `fit_ahead - 1` after it), so a lead counted over more frames than that could never fill: /// a preview that renders every frame at once would still be slowed down to a fraction of its /// frame rate. 0 when not even one frame after the current one is prefetched: the pace can't /// measure anything, and the clock runs in real time (holding on frames that aren't cached). fn pace_horizon(ahead: i64, fit_ahead: i64) -> i64 { (ahead * 2).max(1).min(fit_ahead - 1).max(0) } /// Cached frames (`cached`, sorted) among the next `max` frames `after(1..=max)` plays, and how /// many frames it plays (`after` is `None` past the end). Counted, not the consecutive run: one /// late frame (a GPU warm-up frame, a heavy one) with frames cached beyond it holds the clock /// for a moment when it gets there, rather than slowing the whole preview to a crawl. fn lead_of(after: impl Fn(i64) -> Option, cached: &[i64], max: i64) -> (i64, i64) { let ahead: Vec = (1..=max).map_while(after).collect(); (ahead.iter().filter(|f| cached.binary_search(f).is_ok()).count() as i64, ahead.len() as i64) } impl PlaybackPass<'_> { /// The frame `k` played frames after `from` (wrapping as the preview loops), `None` once a /// preview that doesn't loop has reached its end. fn frame_after(&self, from: i64, k: i64) -> Option { match self.plan { Some(p) => p.frame_after(from, k), None => { let FrameWindow { first: wa, last: wb } = self.window; let f = from + k; if f <= wb { Some(f) } else if self.looping { Some(wa + (f - wa).rem_euclid((wb - wa + 1).max(1))) } else { None } } } } } impl EffectcraftApp { /// RAM preview: advance at the preview's frame rate when frames are cached; otherwise hold /// and keep rendering ahead (the green cache bar fills, then playback runs in real time). pub(super) fn advance_playback(&mut self, ctx: &egui::Context, scale: f64, now: f64, input_active: bool, cid: ItemId) { let Some(c) = self.session.project.comp_arc(cid) else { return }; let fr = c.frame_rate; let plan = self.playback.plan.filter(|_| self.playback.playing); let (wa, wb) = match plan { Some(p) => (p.start, p.end), None => (fr.frame_at(c.work_area.0), fr.frame_at(c.work_area.1 - c.frame_duration())), }; let looping = plan.is_none_or(|p| p.looping); let video = plan.is_none_or(|p| p.video); // Prefetch ahead. let cur = fr.frame_at(self.session.time()); // While the sound drives a video preview, frames are rendered and kept ahead of what it // plays rather than of the picture, which drops frames behind it when rendering can't // keep up (#2473). let lead = if video { self.sound_frame(fr, wa, wb, plan.map_or(1, |p| p.step)).unwrap_or(cur) } else { cur }; let ahead = self.prefetch_ahead(ctx, now); let queued = self.frames.inflight(); let series = self.frame_series(cid, scale); // The preview's position orders prefetch and eviction (#595). let playhead = plan.filter(|p| p.video).map(|p| frames::Playhead { series, cur: lead, start: p.start, end: p.end, step: p.step, looping: p.looping }); self.frames.set_playhead(playhead); let pass = PlaybackPass { ctx, comp: &c, cid, scale, now, frame_rate: fr, series, plan, window: FrameWindow { first: wa, last: wb }, cur, video, looping, ahead, queued, }; if self.cache_preview(&pass) { return; } let step = plan.map_or(1, |p| p.step); let fit_ahead = self.frames_that_fit(&c, scale) - 1; self.prefetch_playback(&PlaybackPass { cur: lead, ..pass }, fit_ahead); self.wake_silent_preview(); self.pump_meters(ctx, now); if !self.playback.playing { self.cache_when_idle(ctx, &c, &series, now, input_active, (wa, wb)); return; } let fit = self.frames_that_fit(&c, scale); if self.hold_first_frame(&pass, fit) { return; } self.start_held_audio(&pass, fit); if self.advance_audio_clock(&pass, step) { return; } self.advance_frame_clock(&pass, step, fit_ahead); } /// While paused (scrubbing, editing) the viewer's frame comes first: prefetch only a few /// frames, only once it is done, and not while edits keep coming (a layer dragged in the /// viewer): those frames would be stale at the next step and would hold the CPU and GPU /// the next viewer frame needs. fn prefetch_ahead(&mut self, ctx: &egui::Context, now: f64) -> i64 { if self.playback.playing { (self.frames_parallelism() * 2).max(4) as i64 } else if self.frames.urgent_pending() { 0 } else if let Some(wait) = self.editing(now) { ctx.request_repaint_after(std::time::Duration::from_secs_f64(wait)); 0 } else { // Keep workers available for a newly edited viewer frame. Running obsolete // background renders cannot be preempted by the priority queue. self.frames_parallelism().saturating_sub(1).min(2) as i64 } } /// Cache Before Playback: the range in play order, then start the clock. A range larger than /// the RAM preview budget is cut to the frames that fit (caching more would evict the first /// ones and never finish). Returns true when this pass handled the preview. fn cache_preview(&mut self, pass: &PlaybackPass<'_>) -> bool { let PlaybackPass { ctx, comp, cid, scale, now, frame_rate: fr, series, plan, ahead, mut queued, .. } = *pass; if !self.playback.caching { return false; } let Some(p) = plan else { return false }; let mut all = true; let n = (p.end - p.start) / p.step + 1; let fit = self.frames_that_fit(comp, scale); if n > fit { let mut cut = p; (cut.start, cut.end) = (p.first, (p.first + (fit - 1) * p.step).min(p.end)); self.playback.plan = Some(cut); self.toast = Some((format!("Preview cut to {fit} of {n} frames: no more fit in the RAM preview (Settings ▸ Memory & CPU)"), now)); ctx.request_repaint(); return true; } let order: Vec = (0..n).filter_map(|k| p.frame_after(p.first, k)).collect(); for f in order { if self.frames.is_cached(&FrameKey { frame: f, ..series }) { continue; } all = false; if queued < ahead as usize { self.request_frame(cid, f, scale); queued += 1; } } self.playback.waiting = !all; if all { self.playback.caching = false; self.playback.start_wall = now; self.playback.start_frame = p.first; self.session.set_time(fr.tick_of(p.first)); self.start_audio(fr.tick_of(p.first)); } ctx.request_repaint(); true } /// Never further ahead than the RAM preview holds: those frames would evict the ones the /// preview shows first, or be evicted before it gets there (#595). The window starts at the /// first uncached frame ahead: after a loop or a restart the frames just ahead are cached, /// and a window from the playhead left the workers idle until it came near the end of the /// cached run. It stays ahead × 3 frames wide: workers spread over the whole preview render /// frames with different layers at once (on the GPU, an atlas each: #1812). fn prefetch_playback(&self, pass: &PlaybackPass<'_>, fit_ahead: i64) { let PlaybackPass { cid, scale, plan, cur, ahead, series, mut queued, video, .. } = *pass; let FrameWindow { first: wa, last: wb } = pass.window; let frame = |k: i64| match plan { Some(p) => p.frame_after(cur, k), None => { let f = cur + k; Some(if f > wb { wa + (f - wb - 1).rem_euclid((wb - wa + 1).max(1)) } else { f }) } }; let cached = self.frames.cached_frames(&series); let uncached = |f: i64| cached.binary_search(&f).is_err(); let first = match plan.filter(|_| self.playback.playing) { Some(p) => (0..fit_ahead.min((p.end - p.start) / p.step.max(1) + 1)) .map_while(|k| frame(k).map(|f| (k, f))) .find(|&(_, f)| uncached(f)) .map_or(0, |(k, _)| k), None => 0, }; for k in first..(first + ahead * 3).min(fit_ahead) { if queued >= ahead as usize || !video { break; } let Some(f) = frame(k) else { break }; if uncached(f) { self.request_frame(cid, f, scale); queued += 1; } } } /// Advance the audio or scrub output and feed its latest peaks to the level meter; an idle scrub is closed after /// one second. With no source but an active meter, drive the meter to silence and request a repaint. fn pump_meters(&mut self, ctx: &egui::Context, now: f64) { if let Some(a) = &mut self.audio { // An edit while playing (mute, unmute, solo, levels): the sound follows it (#2104). if a.project().is_some_and(|p| !std::sync::Arc::ptr_eq(&p, &self.session.project)) { a.follow_project(self.session.project.clone()); } a.pump(); self.meter.update(a.feed.take_peaks(), now); } else if let Some(s) = &mut self.scrub { // Scrubbing: the meters follow the snippets; an idle second closes the output. s.pump(); self.meter.update(s.feed.take_peaks(), now); if now - s.last_used > 1.0 { self.scrub = None; } ctx.request_repaint_after(std::time::Duration::from_millis(50)); } else if self.meter.active() { self.meter.update([0.0; 2], now); ctx.request_repaint(); } } /// Starting a preview with sound: hold the first frame until the frames ahead are cached, then /// start the sound from that same frame (see `Playback::starting`). Without an output device /// the picture plays on its own clock from it. How many frames ahead: only ones /// `prefetch_playback` requests and that fit in the RAM preview at the size they really render /// (an Extended Viewer frame is larger than the comp), so the wait always ends. Returns true /// while it holds the first frame. fn hold_first_frame(&mut self, pass: &PlaybackPass<'_>, fit: i64) -> bool { let PlaybackPass { ctx, comp, scale, now, plan, series, cur, ahead, frame_rate: fr, .. } = *pass; if !self.playback.starting { return false; } let Some(p) = plan else { return false }; self.playback.start_wall = now; self.playback.start_frame = cur; // `prefetch_playback` requests every uncached frame of offsets 0..window from here. let window = (ahead * 3).min(fit - 1); let need = self.frames.get(&FrameKey { frame: cur, ..series }).map(|img| startup_frames(ahead, window, self.frames.budget(), img.bytes())); if need.is_some() && self.playback.first_cached.is_none() { self.playback.first_cached = Some(now); } // Don't wait for frames the RAM preview can't hold (not even one frame fits), for the // frames ahead longer than STARTUP_WAIT once the first is in, nor longer than // STARTUP_LIMIT in all (a frame that never gets cached). let give_up = (self.frames.budget() as f64) < self.frame_bytes(comp, scale) || self.playback.first_cached.is_some_and(|t| now - t >= STARTUP_WAIT) || now - self.playback.starting_since >= STARTUP_LIMIT; if !give_up && !need.is_some_and(|n| self.cached_ahead(&p, &series, cur, n)) { self.playback.waiting = true; ctx.request_repaint(); return true; } self.playback.starting = false; self.playback.waiting = false; // Not on a frame that isn't cached: the picture couldn't show where the sound starts. The // preview goes on silently, and the sound starts once frames are cached. if need.is_some() { self.playback.audio_held = false; self.start_audio(fr.tick_of(cur)); } false } /// A silent preview whose project was edited so that it has sound now (a layer unmuted while /// playing, #2104): video previews wait for cached frames; audio-only previews start from /// their moving audio frame, not the stationary timeline. Checked once per project edit. fn wake_silent_preview(&mut self) { let pb = &self.playback; if self.audio.is_some() || !pb.playing || pb.caching || pb.starting || pb.audio_held { return; } if pb.silent_project.as_ref().is_some_and(|p| std::sync::Arc::ptr_eq(p, &self.session.project)) { return; } self.playback.silent_project = Some(self.session.project.clone()); if !self.audio_plays() { return; } if self.playback.plan.is_some_and(|p| p.video) { self.playback.audio_held = true; } else if let Some(c) = self.session.active_comp() { let frame = self.playback.audio_frame.unwrap_or(self.playback.start_frame); self.start_audio(c.frame_rate.tick_of(frame)); } } /// Held sound starts once the frames ahead are cached (see `Playback::audio_held`): the /// prefetch's `ahead` when the silent preview keeps real time, else the rest of the preview. fn start_held_audio(&mut self, pass: &PlaybackPass<'_>, fit: i64) { let PlaybackPass { now, plan, series, cur, ahead, frame_rate: fr, .. } = *pass; if !self.playback.audio_held { return; } let Some(p) = plan else { return }; // No more than the prefetch requests: offsets below `fit - 1` (`advance_playback`). let need = ahead.min(fit - 1).max(1); if (self.playback.keeps_up(now) && self.cached_ahead(&p, &series, cur, need)) || self.cached_ahead(&p, &series, cur, fit) { self.playback.audio_held = false; self.playback.start_wall = now; self.playback.start_frame = cur; self.start_audio(fr.tick_of(cur)); } } /// Audio clock drives playback: show the frame under the audible sample. Returns true when /// the audio path handled this pass (including stopping at the end). fn advance_audio_clock(&mut self, pass: &PlaybackPass<'_>, step: i64) -> bool { let PlaybackPass { ctx, now, series, video, frame_rate: fr, cur, .. } = *pass; let FrameWindow { first: wa, last: wb } = pass.window; let Some(a) = &self.audio else { return false }; if a.finished() { if video { self.session.set_time(fr.tick_of(wb)); } else { self.playback.audio_frame = Some(wb); } self.stop(); return true; } let snap = |f: i64| wa + (f - wa).div_euclid(step) * step; let target = snap(fr.frame_at(a.clock_time()).clamp(wa, wb)); if !video { self.playback.audio_frame = Some(target); } else if self.frames.is_cached(&FrameKey { frame: target, ..series }) { self.playback.waiting = false; if target != cur { self.session.set_time(fr.tick_of(target)); self.playback.frame_shown(now); } } else { // Rendering can't keep up: the sound plays on and the picture drops frames, showing // the latest one rendered up to the sound, while `advance_playback` renders ahead of // the sound (#2473). Stopping the sound instead and starting it again once frames were // cached chopped it into bursts that played as distortion (#3260). self.playback.waiting = true; if let Some(f) = self.latest_cached_before(pass, target).filter(|&f| f != cur) { self.session.set_time(fr.tick_of(f)); self.playback.frame_shown(now); } // Dropping frames: a lower resolution may keep up (the rate shown says so). self.step_down(now, pass.scale); } ctx.request_repaint(); true } /// The frame under the audible sample while the sound drives the preview, kept in the /// preview's range and on its frame step; `None` without sound. fn sound_frame(&self, fr: effectcraft_engine::time::FrameRate, wa: i64, wb: i64, step: i64) -> Option { let a = self.audio.as_ref()?; let step = step.max(1); Some(wa + (fr.frame_at(a.clock_time()).clamp(wa, wb) - wa).div_euclid(step) * step) } /// The last cached frame after the current one and before `target`, in play order: what a /// preview behind its sound shows (`None` when no such frame is cached). The walk stops at /// the first frame that isn't before the sound's, which it can step over without meeting /// (a picture off the plan's frame step) or never reach (a sound behind the picture). fn latest_cached_before(&self, pass: &PlaybackPass<'_>, target: i64) -> Option { let PlaybackPass { plan, series, cur, window, looping, .. } = *pass; let cached = self.frames.cached_frames(&series); let mut best = None; for k in 1..=(window.last - window.first + 1).max(1) { let Some(f) = plan.map_or(Some(cur + k), |p| p.frame_after(cur, k)) else { break }; if !between_picture_and_sound(cur, f, target, looping) { break; } if cached.binary_search(&f).is_ok() { best = Some(f); } } best } /// The wall clock advances the preview when no audio device drives it, and shows the target /// frame (or holds when it is not cached yet). While frames arrive slower than the frame /// rate it runs at their pace ([`pace_for`]): every frame shows, evenly, as After Effects /// plays a preview it hasn't cached yet; real time again once the frames ahead are cached. fn advance_frame_clock(&mut self, pass: &PlaybackPass<'_>, step: i64, fit_ahead: i64) { let PlaybackPass { ctx, now, plan, video, frame_rate: fr, cur, series, .. } = *pass; let FrameWindow { last: wb, .. } = pass.window; // The plan carries the rate the preview was started with (and `play_with` copies it to // `Playback::fps`). Deriving the frame from the plan keeps a logic-only tick correct even // when a host/test supplies only the plan; a stale duplicate cannot hold playback open. let fps = plan.map_or(self.playback.fps, |p| p.fps); let dt = self.playback.paced_at.map_or(0.0, |t| (now - t).max(0.0)); self.playback.paced_at = Some(now); if video { // The lead counts out of twice the prefetch depth: the prefetch keeps that many // frames coming (or the frames left before the end), so a full lead means rendering // keeps up. No more than the RAM preview holds ([`pace_horizon`]). let horizon = pace_horizon(pass.ahead, fit_ahead); let prev = if self.playback.pace > 0.0 { self.playback.pace } else { fps }; let pace = if horizon > 0 { let (lead, target) = self.cached_lead(pass, horizon); pace_for(prev, lead, target, fps, dt) } else { fps }; self.playback.pace = pace; if pace < fps * 0.8 { self.step_down(now, pass.scale); } if pace < fps * 0.98 { self.advance_paced(pass, pace, dt); return; } if self.playback.pace_acc.take().is_some() { // Back to real time from here. self.playback.start_wall = now; self.playback.start_frame = cur; } } let elapsed = now - self.playback.start_wall; let n = ((elapsed * fps) / step as f64).floor() as i64; let target = pass.frame_after(self.playback.start_frame, n); let Some(target) = target else { if video { self.session.set_time(fr.tick_of(wb)); } else { self.playback.audio_frame = Some(wb); } self.stop(); return; }; if !video { // Audio-only preview without an audio device: the clock runs, the time stays. self.playback.audio_frame = Some(target); ctx.request_repaint(); return; } if self.frames.is_cached(&FrameKey { frame: target, ..series }) { self.playback.waiting = false; if target != cur { self.session.set_time(fr.tick_of(target)); self.playback.frame_shown(now); } } else { // Not cached yet: hold the clock at the current frame (cache first, then play). self.playback.waiting = true; self.step_down(now, pass.scale); let next = pass.frame_after(cur, 1).unwrap_or(cur); if self.frames.is_cached(&FrameKey { frame: next, ..series }) { self.session.set_time(fr.tick_of(next)); } self.playback.start_wall = now; self.playback.start_frame = fr.frame_at(self.session.time()); } ctx.request_repaint(); } /// The paced clock: it owes `pace` played frames a second (plus what the last passes left /// over) and shows them one by one as far as they are cached; on a frame that isn't it holds /// (owing one frame, so that frame shows the moment it arrives), and at the end of a preview /// that doesn't loop it stops. fn advance_paced(&mut self, pass: &PlaybackPass<'_>, pace: f64, dt: f64) { let PlaybackPass { ctx, now, frame_rate: fr, cur, series, .. } = *pass; let step = pass.plan.map_or(1, |p| p.step).max(1) as f64; let mut owed = self.playback.pace_acc.unwrap_or(0.0) + dt * pace / step; let mut f = cur; while owed >= 1.0 { match pass.frame_after(f, 1) { Some(n) if self.frames.is_cached(&FrameKey { frame: n, ..series }) => { f = n; owed -= 1.0; } Some(_) => { owed = 1.0; break; } None => { self.session.set_time(fr.tick_of(pass.window.last)); self.stop(); return; } } } self.playback.waiting = owed >= 1.0; if f != cur { self.session.set_time(fr.tick_of(f)); self.playback.frame_shown(now); } self.playback.pace_acc = Some(owed); ctx.request_repaint(); } /// Cached frames among the next `max` in play order, and how many of those there are (fewer /// near the end of a preview that doesn't loop: its cached tail is a full lead). See /// [`lead_of`]. fn cached_lead(&self, pass: &PlaybackPass<'_>, max: i64) -> (i64, i64) { lead_of(|k| pass.frame_after(pass.cur, k), &self.frames.cached_frames(&pass.series), max) } /// Settings ▸ Previews ▸ Lower Resolution When Playback Can't Keep Up: a preview at /// Resolution Auto plays under 80 % of its frame rate (its pace, or stalled on a frame that /// isn't cached) two seconds after it started or last stepped down (the first frames at a /// new scale, and the GPU's warm-up frames, take a moment), so it plays on at half `scale`, /// no lower than the Adaptive Resolution Limit. An explicit Resolution is kept. // ponytail: it never steps back up during a play, and frames cached at the higher scale aren't // shown once it stepped down; add both if loops over a partly cached comp need them. fn step_down(&mut self, now: f64, scale: f64) { let pb = &self.playback; let since = pb.adaptive.map_or(pb.starting_since, |(_, t)| t); let step = pb.plan.map_or(1, |p| p.step).max(1) as f64; let lower = scale * 0.5; if !self.session.prefs.previews.adaptive_playback || pb.res.is_some() || !self.viewer_res().is_auto() || now - since < 2.0 // (a rate from before a stall: nothing shown for a second isn't keeping up) || (pb.shown_at.back().is_some_and(|t| now - t <= 1.0) && pb.achieved_fps().is_some_and(|f| f * step >= pb.fps * 0.8)) || lower < self.session.prefs.adaptive_limit() - 1e-9 { return; } self.playback.adaptive = Some((lower, now)); self.playback.shown_at.clear(); } /// While the project keeps changing (an edit within [`EDIT_QUIET`] seconds), how long until /// it counts as settled. fn editing(&mut self, now: f64) -> Option { if self.last_edit.1 != self.session.revision { self.last_edit = (now, self.session.revision); } let left = EDIT_QUIET - (now - self.last_edit.0); (left > 0.0).then_some(left) } /// Composition ▸ Preview ▸ Cache Frames When Idle: after a second without input or edits, /// render the work area's frames (from the current time on, then from its start) in the /// background, a few at a time, until it is cached or the RAM preview budget is full. fn cache_when_idle( &mut self, ctx: &egui::Context, comp: &effectcraft_engine::project::Comp, series: &FrameKey, now: f64, input_active: bool, (wa, wb): (i64, i64), ) { let active = input_active; if active || self.last_activity.1 != self.session.revision { self.last_activity = (now, self.session.revision); } if !self.ui.cache_when_idle || self.frames.urgent_pending() { return; } let quiet = now - self.last_activity.0; if quiet < 1.0 { ctx.request_repaint_after(std::time::Duration::from_secs_f64(1.0 - quiet)); return; } // Frames an edit kept in RAM are on disk under the comp's previous content only. // Again soon while frames wait to be written (a refused write is retried then). #[cfg(not(target_arch = "wasm32"))] if self.frames.persist_missing(&self.render_source(), series, &self.frame_opts(ItemId(series.comp), series.scale as f64 / 1000.0)) { ctx.request_repaint_after(std::time::Duration::from_millis(500)); } // An empty work area has nothing to cache. let n = wb - wa + 1; if n < 1 { return; } let cur = comp.frame_rate.frame_at(self.session.time()).clamp(wa, wb); // The viewer's exact factor (1/3, not the key's 0.333): it shows these frames. let scale = frames::render_scale(series.scale, comp.resolution.factor()); let fit = self.frames_that_fit(comp, scale).min(n); // One thread each (`Frames::request_background`), so every frame thread takes one. let slots = self.frames_parallelism().max(1); let mut queued = self.frames.inflight(); let mut pending = false; for k in 0..fit { let f = wa + (cur - wa + k).rem_euclid(n); if self.frames.is_cached(&FrameKey { frame: f, ..*series }) { continue; } pending = true; if queued >= slots { break; } self.request_frame_background(ItemId(series.comp), f, scale); queued += 1; } if pending { ctx.request_repaint_after(std::time::Duration::from_millis(100)); } } /// How many viewer frames of `comp` at `scale` the RAM preview budget holds (90 % of it, /// at least one). /// The frames of `plan` from `cur` to its end, or as many as fit in the RAM preview, are /// cached: sound can play from `cur` in real time. fn cached_ahead(&self, plan: &effectcraft_engine::preview::PreviewPlan, series: &FrameKey, cur: i64, fit: i64) -> bool { let cached = self.frames.cached_frames(series); (0..fit).map_while(|k| plan.frame_after(cur, k)).take_while(|f| *f >= cur).all(|f| cached.binary_search(&f).is_ok()) } fn frames_that_fit(&self, comp: &effectcraft_engine::project::Comp, scale: f64) -> i64 { ((self.frames.budget() as f64 * 0.9 / self.frame_bytes(comp, scale)) as i64).max(1) } /// Bytes of one comp-sized viewer frame at `scale` (Extended Viewer frames are larger; 32 bpc /// frames are half floats, twice the bytes of 8-bit ones). fn frame_bytes(&self, comp: &effectcraft_engine::project::Comp, scale: f64) -> f64 { let side = |n: u32| (n as f64 * scale).ceil().max(1.0); side(comp.width) * side(comp.height) * frames::frame_pixel_bytes(&self.session.project.settings) as f64 } /// Frames rendered at once by a preview or idle caching: the lanes (in the browser the frame /// workers; without them frames render one at a time on the UI thread, `Frames::pump`). fn frames_parallelism(&self) -> usize { self.frames.lanes() } } #[cfg(test)] mod pace_tests { use super::{lead_of, pace_for, pace_horizon}; /// The lead is measured over no more frames than the RAM preview keeps ahead of the current /// one, so a full cache plays in real time. (It counted out of twice the prefetch depth: with /// room for 4 frames, at most 2 after the current one were ever cached, and a preview that /// rendered at once played at a quarter of its frame rate.) #[test] fn the_pace_horizon_fits_in_the_ram_preview() { // A roomy budget: twice the prefetch depth. assert_eq!(pace_horizon(6, 400), 12); // Room for 4 frames: the prefetch requests offsets 0..3, so 2 after the current one. assert_eq!(pace_horizon(6, 3), 2); let (lead, target) = lead_of(|k| Some(10 + k), &[10, 11, 12], pace_horizon(6, 3)); assert!((pace_for(30.0, lead, target, 30.0, 10.0) - 30.0).abs() < 1e-6, "a full cache plays in real time"); // Room for the current frame only (or nothing): no lead to measure. assert_eq!(pace_horizon(6, 1), 0); assert_eq!(pace_horizon(6, 0), 0); // No prefetch depth: still the next frame. assert_eq!(pace_horizon(0, 400), 1); } /// The pace follows the cached lead: real time with a full lead, a third of it with a third, /// never under an eighth, unchanged with nothing ahead, and smoothed over time. #[test] fn pace_follows_the_cached_lead() { // Settled (a long dt): proportional to the lead. assert!((pace_for(30.0, 12, 12, 30.0, 10.0) - 30.0).abs() < 1e-6); assert!((pace_for(30.0, 4, 12, 30.0, 10.0) - 10.0).abs() < 1e-6); assert!((pace_for(30.0, 1, 100, 30.0, 10.0) - 3.75).abs() < 1e-6, "never under an eighth"); assert_eq!(pace_for(17.0, 0, 12, 30.0, 10.0), 17.0, "no frame ahead: unchanged"); // Smoothing: after one time constant it has gone 63 % of the way. let p = pace_for(30.0, 4, 12, 30.0, 0.5); assert!((p - (30.0 - 20.0 * (1.0 - (-1.0f64).exp()))).abs() < 1e-6); assert_eq!(pace_for(30.0, 4, 12, 30.0, 0.0), 30.0, "no time passed: unchanged"); assert!(pace_for(10.0, 12, 12, 30.0, 0.5) > 10.0, "and up again as the lead fills"); } /// Near the end of a preview that doesn't loop, the lead counts out of the frames left: a /// cached tail plays in real time. (It counted out of the full depth, and a cached preview /// slowed down over its last frames, a short one for its whole length.) #[test] fn a_cached_end_is_a_full_lead() { let cached: Vec = (0..=20).collect(); let to_20 = |cur: i64| move |k: i64| Some(cur + k).filter(|f| *f <= 20); assert_eq!(lead_of(to_20(5), &cached, 12), (12, 12)); assert_eq!(lead_of(to_20(16), &cached, 12), (4, 4)); assert_eq!(lead_of(to_20(20), &cached, 12), (0, 0)); let (lead, target) = lead_of(to_20(16), &cached, 12); assert!((pace_for(30.0, lead, target, 30.0, 10.0) - 30.0).abs() < 1e-6); // Frames left uncached still count against it. assert_eq!(lead_of(to_20(16), &[17, 19], 12), (2, 4)); // Looping: the walk wraps, always `max` frames. assert_eq!(lead_of(|k| Some((18 + k) % 21), &cached, 12), (12, 12)); } } #[cfg(test)] mod startup_tests { use super::{between_picture_and_sound, startup_frames}; /// The frames a preview behind its sound may show are only those before the sound's frame in /// play order, so the picture is never ahead of the sound (#2473). #[test] fn a_dropped_frame_preview_never_shows_past_the_sound() { // Sound ahead of the picture: only the frames between them. assert!(between_picture_and_sound(10, 12, 14, false)); assert!(!between_picture_and_sound(10, 14, 14, false), "not the sound's own frame"); assert!(!between_picture_and_sound(10, 15, 14, true), "nor one past it, stepped over off the grid"); assert!(!between_picture_and_sound(10, 10, 14, true), "nor the current frame"); // A looping preview whose sound wrapped to the start: the end of the loop, then its start. assert!(between_picture_and_sound(90, 95, 3, true)); assert!(between_picture_and_sound(90, 1, 3, true)); assert!(!between_picture_and_sound(90, 3, 3, true)); assert!(!between_picture_and_sound(90, 50, 3, true), "the wrapped walk stops before reaching the picture again"); // Without a loop, a sound behind the picture allows nothing ahead of it. assert!(!between_picture_and_sound(90, 95, 3, false)); assert!(!between_picture_and_sound(90, 1, 3, false)); // The sound on the picture's frame: nothing. assert!(!between_picture_and_sound(10, 11, 10, true)); } /// The frames a preview with sound waits for are always requested and fit together (#947). #[test] fn startup_waits_only_for_frames_it_requests_and_can_keep() { // A 64×36 frame: 9216 bytes. A 46 080-byte budget fits 4 of them (90 %); the prefetch // window then requests offsets 0..3, so the start needs those 3, not 4 it never asks for. let frame = 64 * 36 * 4; let fit = 4; let window = (32i64 * 3).min(fit - 1); assert_eq!(startup_frames(32, window, 46_080, frame), 3); // A roomy budget: the prefetch's `ahead` frames. assert_eq!(startup_frames(8, 24, 100_000_000, frame), 8); // Extended Viewer: a 160×120 comp renders 320×248 frames. 952 320 bytes fit 11 comp-sized // frames but only 2 real ones (90 %): wait for 2, not 4. assert_eq!(startup_frames(4, 11, 952_320, 320 * 248 * 4), 2); // Nothing fits, or no window: still the current frame, never 0. assert_eq!(startup_frames(8, 0, 0, frame), 1); // A zero frame size counts as 1 byte: no division by zero. assert_eq!(startup_frames(8, 24, 10, 0), 8); } }