665bfac0b339
prefetch.rs
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<i64>, cached: &[i64], max: i64) -> (i64, i64) {
let ahead: Vec<i64> = (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<i64> {
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<i64> = (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<i64> {
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<i64> {
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<f64> {
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<i64> = (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);
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.