diff --git a/Cargo.lock b/Cargo.lock index ba347f1a7..4f047a9a1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1554,6 +1554,7 @@ dependencies = [ "image", "kurbo", "log", + "memory-stats", "rayon", "same-file", "serde", @@ -3948,6 +3949,16 @@ dependencies = [ "autocfg", ] +[[package]] +name = "memory-stats" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c73f5c649995a115e1a0220b35e4df0a1294500477f97a91d0660fb5abeb574a" +dependencies = [ + "libc", + "windows-sys 0.52.0", +] + [[package]] name = "minicov" version = "0.3.8" diff --git a/Cargo.toml b/Cargo.toml index abb2256c2..302a05a84 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -59,6 +59,8 @@ thiserror = "2" serde = { version = "1", features = ["derive", "rc"] } serde_json = { version = "1", features = ["float_roundtrip"] } log = "0.4" +# The process's own memory use for the memory accountant (#3301; MIT OR Apache-2.0). +memory-stats = "1.2" # All date/time conversion goes through chrono (no hand-rolled calendar code beyond the 400-year range extension; AGENTS.md). chrono = { version = "0.4.45", default-features = false, features = ["std"] } rayon = "1" diff --git a/crates/engine/Cargo.toml b/crates/engine/Cargo.toml index aa5956ebe..cd85c858d 100644 --- a/crates/engine/Cargo.toml +++ b/crates/engine/Cargo.toml @@ -43,6 +43,7 @@ exr = { workspace = true } # Native file identity and SAM 2 inference; browsers keep the built-in engines. [target.'cfg(not(target_arch = "wasm32"))'.dependencies] +memory-stats = { workspace = true } same-file = { workspace = true } tempfile = { workspace = true } effectcraft-sam2 = { workspace = true } diff --git a/crates/engine/src/settings/prefs.rs b/crates/engine/src/settings/prefs.rs index 4743f5292..1f855f8ed 100644 --- a/crates/engine/src/settings/prefs.rs +++ b/crates/engine/src/settings/prefs.rs @@ -28,8 +28,8 @@ pub use choices::{APPEARANCE_MODES, DARK_THEMES, LANGUAGES, LIGHT_THEMES, THEMES pub use dialog::{Item, Kind, Page, pages, pages_json, todo_keys}; pub use document::{migrate, page_id, section_key}; pub use queries::{ - CacheCaps, FALLBACK_MEMORY_BUDGET, MEMORY_HEADROOM_PERCENT, MIN_MEMORY_BUDGET, MemoryBudget, WEB_LAYER_CACHE, WEB_MEDIA_CACHE, WEB_MEMORY_BUDGET, - WEB_PREVIEW_CACHE, mask_color, + CacheCaps, FALLBACK_MEMORY_BUDGET, MEMORY_HEADROOM_PERCENT, MIN_MEMORY_BUDGET, MemoryBudget, PROCESS_PURGE_PERCENT, WEB_LAYER_CACHE, WEB_MEDIA_CACHE, + WEB_MEMORY_BUDGET, WEB_PREVIEW_CACHE, mask_color, }; pub use recent::{MAX_RECENT_SCRIPTS, RecentScript}; pub use sections::{ diff --git a/crates/engine/src/settings/prefs/queries.rs b/crates/engine/src/settings/prefs/queries.rs index e48518906..c15d48269 100644 --- a/crates/engine/src/settings/prefs/queries.rs +++ b/crates/engine/src/settings/prefs/queries.rs @@ -29,6 +29,17 @@ impl Prefs { } } + /// The limits on the process's measured memory (bytes): above the first the caches give way + /// by what it is over, above the second also the frames a playing preview shows next + /// ([`PROCESS_PURGE_PERCENT`] of the installed RAM left after the reserve, and all of it). + /// `None` while the installed RAM is unknown. + pub fn process_limits(&self, mem: Option) -> Option<(u64, u64)> { + let total = mem.map(|m| m.total).filter(|t| *t > 0)?; + let room = total.saturating_sub(u64::from(self.memory.ram_reserved_gb) << 30).max(MIN_MEMORY_BUDGET); + let purge = u64::try_from(u128::from(room) * u128::from(PROCESS_PURGE_PERCENT) / 100).unwrap_or(room); + Some((purge, room)) + } + /// The memory EffectCraft's caches share (Settings ▸ Memory & CPU): the layer cache, the /// footage frames, the decoded OpenEXR planes and the RAM preview frames together, kept within /// it by the memory accountant (`effectcraft_render::memory::Accountant`), which decides @@ -161,6 +172,12 @@ pub const WEB_LAYER_CACHE: u64 = 512 << 20; /// The most the footage frame cache holds in the browser (see [`WEB_LAYER_CACHE`]). pub const WEB_MEDIA_CACHE: u64 = 256 << 20; +/// Above this part (percent) of the installed RAM left after **RAM Reserved for Other +/// Applications**, the process's measured memory makes the caches give way even within their +/// budget ([`Prefs::process_limits`]): above the caches' budget plus most of the room left for +/// the app's own working memory. +pub const PROCESS_PURGE_PERCENT: u64 = 95; + /// The part (percent) of the installed RAM left after **RAM Reserved for Other Applications** /// that EffectCraft's caches share ([`Prefs::memory_budget`]). The rest is headroom for /// EffectCraft's own working memory (decoders, render buffers, undo, GPU staging, the interface), diff --git a/crates/engine/src/settings/prefs/sections.rs b/crates/engine/src/settings/prefs/sections.rs index cb1d1bfb4..7a00b4915 100644 --- a/crates/engine/src/settings/prefs/sections.rs +++ b/crates/engine/src/settings/prefs/sections.rs @@ -93,7 +93,8 @@ page!(Previews { /// Largest downsampling while playing back: `1/2`, `1/4`, `1/8`. adaptive_resolution_limit: String = "1/8".into(), show_internal_wireframes: bool = false, - cache_frames_when_idle: bool = false, + /// Cache Frames When Idle: on by default (#3321); a saved `false` stays off. + cache_frames_when_idle: bool = true, fast_previews: bool = false, /// `faster` or `moreAccurate`. zoom_quality: String = "moreAccurate".into(), diff --git a/crates/engine/src/settings/session_settings.rs b/crates/engine/src/settings/session_settings.rs index bf4acbde3..cc25f35ea 100644 --- a/crates/engine/src/settings/session_settings.rs +++ b/crates/engine/src/settings/session_settings.rs @@ -122,6 +122,13 @@ impl Session { let layers: std::sync::Arc = self.layer_cache.clone(); accountant.register(&layers); accountant.set_budget(b.bytes); + // The process's measured memory as well (#3301: memory nobody accounts for, such as GPU + // staging, effect buffers and the allocator's fragmentation): over the purge limit the + // caches give way by what it is over, over the hard limit also the frames a playing + // preview shows next. + if let Some((purge_at, hard_at)) = self.prefs.process_limits(self.sys_memory) { + accountant.set_process_memory(crate::sysinfo::process_memory, purge_at, hard_at); + } } /// The memory the caches share for the last memory reading ([`Prefs::memory_budget`]), kept @@ -150,6 +157,9 @@ impl Session { self.sys_memory = reading.or(self.sys_memory); self.memory_low = self.sys_memory.is_some_and(|m| m.still_low(self.memory_low)); let after = self.memory_budget(); + // (the process's memory is checked with each balance; a reading now and then also + // when the caches don't grow) + effectcraft_render::memory::Accountant::global().balance(); if after != before { self.apply_cache_budgets(); // Frontends re-apply their preview cache budget. diff --git a/crates/engine/src/system/sysinfo.rs b/crates/engine/src/system/sysinfo.rs index b86fbbce0..8c594b214 100644 --- a/crates/engine/src/system/sysinfo.rs +++ b/crates/engine/src/system/sysinfo.rs @@ -152,6 +152,20 @@ pub fn parse_freebsd_sysctl(text: &str) -> Option { Some(SysMemory { total, available: free.saturating_mul(page).min(total) }) } +/// The physical memory this process uses now (its resident set, the working set on Windows), in +/// bytes; `None` where it can't be read (the browser). Cheap: the memory accountant reads it +/// with each balance (at most every 250 ms). +pub fn process_memory() -> Option { + #[cfg(not(target_arch = "wasm32"))] + { + memory_stats::memory_stats().and_then(|m| u64::try_from(m.physical_mem).ok()) + } + #[cfg(target_arch = "wasm32")] + { + None + } +} + /// Total and available physical memory, when the system reports them. pub fn memory() -> Option { #[cfg(target_os = "linux")] diff --git a/crates/engine/src/tests/m145.rs b/crates/engine/src/tests/m145.rs index 2bd32deb1..08ed81a3c 100644 --- a/crates/engine/src/tests/m145.rs +++ b/crates/engine/src/tests/m145.rs @@ -263,6 +263,17 @@ fn a_low_memory_episode_toasts_once_and_reapplies_the_budget() { assert_eq!(toasts(&mut s), 1); } +/// #3321: Cache Frames When Idle is on by default; a saved "off" stays off. +#[test] +fn cache_frames_when_idle_is_on_by_default() { + use crate::prefs::Prefs; + assert!(Prefs::default().previews.cache_frames_when_idle); + assert!(Prefs::from_json(r#"{"version": 5, "previews": {"fastPreviews": true}}"#).previews.cache_frames_when_idle, "not saved: on"); + let off = Prefs::from_json(r#"{"version": 5, "previews": {"cacheFramesWhenIdle": false}}"#); + assert!(!off.previews.cache_frames_when_idle, "saved off: off"); + assert!(!Prefs::from_json(&off.to_json()).previews.cache_frames_when_idle, "and after the next save"); +} + /// #3298: settings saved with the three cache budgets (version 4, or a later file that still /// has them) keep RAM Reserved for Other Applications and lose the budgets: they are not kept /// as unknown keys and written back. diff --git a/crates/media/src/exr_planes.rs b/crates/media/src/exr_planes.rs index 94b9cd0d0..3e294c30b 100644 --- a/crates/media/src/exr_planes.rs +++ b/crates/media/src/exr_planes.rs @@ -724,7 +724,7 @@ impl PlaneStore { let e = st.entries.get(Self::oldest_droppable(&st, None, false)?)?; let cost_us = if e.cost_us > 0 { e.cost_us } else { effectcraft_render::memory::default_cost(e.bytes, effectcraft_render::memory::DEFAULT_PLANE_US_PER_MB) }; - Some(effectcraft_render::memory::Candidate { used: e.used, bytes: e.bytes, cost_us }) + Some(effectcraft_render::memory::Candidate { used: e.used, bytes: e.bytes, cost_us, protected: false }) } /// Drop [`PlaneStore::oldest_candidate`]; the bytes freed. @@ -959,12 +959,15 @@ fn decode(path: &str, source: &ExrSource, flight: &Arc, base: Option = missing.iter().zip(&kept).filter(|(_, k)| k.is_none()).map(|(id, _)| *id).collect(); let from_disk = to_read.is_empty(); + // (what reading the planes took: their cost, against reading them back from the disk cache) + let read_from = effectcraft_render::memory::tick(); let (read, stats) = if to_read.is_empty() { (Ok(vec![]), Default::default()) } else { let request = ReadRequest { max_bytes: cap_of(path), ..ReadRequest::full(to_read.clone()) }; read_planes(&mut *opened.reader, &index, &request) }; + let read_took = effectcraft_render::memory::tick().saturating_sub(read_from); #[cfg(test)] DECODES.lock().unwrap_or_else(PoisonError::into_inner).push((path.to_string(), DecodeRecord { channels: names.clone(), stats: stats.clone(), from_disk })); #[cfg(not(test))] @@ -1024,7 +1027,12 @@ fn decode(path: &str, source: &ExrSource, flight: &Arc, base: Option())).fold(0, usize::saturating_add); + let took_us = read_took; + if d.pays_off(bytes, took_us) { + d.put_planes(w as u32, h as u32, planes, &entry, since); + } } } Ok(batch) diff --git a/crates/media/src/exr_planes/tests.rs b/crates/media/src/exr_planes/tests.rs index 8141fcde3..7b2c95bfc 100644 --- a/crates/media/src/exr_planes/tests.rs +++ b/crates/media/src/exr_planes/tests.rs @@ -957,6 +957,8 @@ fn decoded_planes_are_kept_on_disk_and_read_back_exactly() { let file = dir.join("crypto_0001.exr"); std::fs::write(&file, multipart()).unwrap(); let dc = DiskCache::open(dir.join("cache"), 1 << 30).unwrap(); + // (every decode is written, however quick: not decided by this machine's speed) + dc.set_read_us_per_mb(0); // (only this test's files use it) use_disk_for(&dir.to_string_lossy()); set_disk_cache(Some(&dc)); diff --git a/crates/media/src/localize.rs b/crates/media/src/localize.rs index 6f25b56e1..bef0d2f72 100644 --- a/crates/media/src/localize.rs +++ b/crates/media/src/localize.rs @@ -188,9 +188,11 @@ impl Drop for Adopting { } } -/// The copies `folder` holds from an earlier session, by source; temporaries and copies without -/// a record are deleted (only the localizer's own files: other files in the folder are left -/// alone, and those of `busy`, the copy being made now). Runs without the localizer's lock. +/// The copies `folder` holds from an earlier session, by source; temporaries, records without +/// their copy and copies without a record are deleted (a copy renamed into place whose record +/// was never written, #3301 review: nothing else would ever delete it, and the size limit +/// didn't count it). Only the localizer's own files: other files in the folder are left alone, +/// and those of `busy`, the copy being made now. Runs without the localizer's lock. fn adopt(folder: &Path, busy: Option<&str>) -> Vec<(PathBuf, Copy)> { #[cfg(test)] { @@ -202,6 +204,7 @@ fn adopt(folder: &Path, busy: Option<&str>) -> Vec<(PathBuf, Copy)> { let mut found = vec![]; let Ok(dir) = std::fs::read_dir(folder) else { return found }; let mut records = vec![]; + let mut copies = vec![]; for e in dir.flatten() { let name = e.file_name().to_string_lossy().to_string(); if !ours(&name) || busy.is_some_and(|b| name.starts_with(b)) { @@ -211,8 +214,14 @@ fn adopt(folder: &Path, busy: Option<&str>) -> Vec<(PathBuf, Copy)> { let _ = std::fs::remove_file(e.path()); } else if name.ends_with(".src") { records.push(e.path()); + } else if e.file_type().is_ok_and(|t| t.is_file()) { + copies.push(e.path()); } } + let recorded: std::collections::HashSet = records.iter().map(|r| r.with_extension("")).collect(); + for copy in copies.iter().filter(|c| !recorded.contains(*c)) { + let _ = std::fs::remove_file(copy); + } for rec in records { let local = rec.with_extension(""); let parsed = std::fs::read_to_string(&rec).ok().and_then(|t| parse_record(&t)); @@ -461,8 +470,11 @@ fn worker() { } } -/// Copy `original` into `folder`: under a temporary name, then renamed when complete, with its -/// record beside it; its modification time set to the source's. The copy, its size and the +/// Copy `original` into `folder`: under a temporary name; then an earlier copy of it removed, +/// its record written beside the final name, and the temporary renamed when complete (a crash +/// in between leaves a record without its copy or a temporary, both deleted when the folder is +/// adopted; never a copy without a record, nor old bytes beside a new record); its +/// modification time set to the source's. The copy, its size and the /// source's identity, or `None` (larger than `room`, unreadable, or changed while it was /// copied). #[cfg(not(target_arch = "wasm32"))] @@ -495,8 +507,17 @@ fn copy_file(original: &Path, folder: &Path, room: u64) -> Option<(PathBuf, u64, let after = std::fs::metadata(original).ok().map(|m| FileStamp::of_metadata(&m)); let text = record(original, &before, meta.len()); match (copied, text) { - (Ok(n), Some(text)) if n == meta.len() && after.as_ref() == Some(&before) && std::fs::rename(&tmp, &local).is_ok() => { - if std::fs::write(record_path(&local), text).is_err() { + (Ok(n), Some(text)) if n == meta.len() && after.as_ref() == Some(&before) => { + // An earlier copy of the source goes first (its record too): a new record must never + // sit beside old bytes. One that can't be deleted (open elsewhere) stays, with its + // own record, and this copy is given up. + if local.exists() && std::fs::remove_file(&local).is_err() { + let _ = std::fs::remove_file(&tmp); + return None; + } + let _ = std::fs::remove_file(record_path(&local)); + if std::fs::write(record_path(&local), text).is_err() || std::fs::rename(&tmp, &local).is_err() { + let _ = std::fs::remove_file(&tmp); remove_copy(&local); return None; } @@ -688,4 +709,32 @@ mod tests { assert_eq!((s.files, s.bytes), (1, 1500), "copied once, counted once: {s:?}"); let _ = std::fs::remove_dir_all(&root); } + + /// #3301 review: a copy renamed into place whose record was never written (a crash in + /// between) is deleted when the folder is adopted: nothing else would delete it, and the + /// size limit didn't count it. Other files in the folder and the copy being made stay. + #[test] + fn a_copy_without_its_record_is_deleted_when_adopted() { + let _serial = TEST_SERIAL.lock().unwrap_or_else(PoisonError::into_inner); + let folder = std::env::temp_dir().join(format!("ec-3301-orphan-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&folder); + std::fs::create_dir_all(&folder).unwrap(); + let orphan = folder.join("0123456789abcdef_plate.exr"); + let busy = folder.join("fedcba9876543210_busy.exr"); + let other = folder.join("notes.txt"); + for f in [&orphan, &busy, &other] { + std::fs::write(f, b"pixels").unwrap(); + } + // A crash between writing a copy's record and renaming its temporary into place: both go. + let mid = folder.join("abcdef0123456789_mid.exr"); + let (mid_rec, mid_part) = (record_path(&mid), folder.join("abcdef0123456789_mid.exr.part")); + std::fs::write(&mid_rec, "/share/mid.exr\n6\n-\n6\n").unwrap(); + std::fs::write(&mid_part, b"pixels").unwrap(); + assert!(adopt(&folder, Some("fedcba9876543210_busy")).is_empty()); + assert!(!mid_rec.exists() && !mid_part.exists(), "a record without its copy and a temporary go"); + assert!(!orphan.exists(), "the copy without a record went"); + assert!(busy.exists(), "the copy being made stays"); + assert!(other.exists(), "not the localizer's: left alone"); + let _ = std::fs::remove_dir_all(&folder); + } } diff --git a/crates/media/src/pool.rs b/crates/media/src/pool.rs index 534ee8232..006adba1c 100644 --- a/crates/media/src/pool.rs +++ b/crates/media/src/pool.rs @@ -412,6 +412,40 @@ enum Waited { No, } +/// At most this many movie/audio files are kept open ([`Sources`]): the least recently used one +/// nobody is using is closed beyond it (it opens again when asked for; a project that cycles +/// through more files than this opens them again each time). +/// Still images and image sequences keep no file open (an OpenEXR file is opened for one decode). +const MAX_OPEN_SOURCES: usize = 256; + +/// The opened movie/audio sources by path, with when each was last asked for. +#[derive(Default)] +struct Sources { + map: HashMap, (SourceSlot, u64)>, + clock: u64, +} + +impl Sources { + /// The slot of `path` (new when there is none), as just used; the least recently used slot + /// beyond [`MAX_OPEN_SOURCES`] is dropped. + fn slot(&mut self, path: &Arc) -> SourceSlot { + self.clock = self.clock.wrapping_add(1); + let clock = self.clock; + let slot = { + let e = self.map.entry(path.clone()).or_insert_with(|| (SourceSlot::default(), clock)); + e.1 = clock; + e.0.clone() + }; + // (only a slot nobody is using or opening: an open in progress isn't started twice) + if self.map.len() > MAX_OPEN_SOURCES + && let Some(oldest) = self.map.iter().filter(|(_, (s, _))| Arc::strong_count(s) == 1).min_by_key(|(_, (_, used))| *used).map(|(p, _)| p.clone()) + { + self.map.remove(&oldest); + } + slot + } +} + /// A movie/audio source by path ([`Opened`]), opened by the first caller while the others wait /// for it (`None`: failed to open; not retried until `forget`), with the file's identity as /// opened. @@ -448,8 +482,8 @@ fn channel_order(src: &SharedSource, header: Option<&[u8]>, file: Option<&dyn fi type GifSlot = Arc, String>, ReadFile)>>; struct Inner { - /// Opened movie/audio sources by path. - sources: Mutex, SourceSlot>>, + /// Opened movie/audio sources by path, at most [`MAX_OPEN_SOURCES`]. + sources: Mutex, /// Files opened into `sources` (see [`PoolStats::opened`]). opened: AtomicU64, /// In-memory files registered with `add_bytes` (web builds, tests). @@ -717,13 +751,13 @@ impl MediaPool { /// Drop every cached frame and decoder. pub fn clear(&self) { self.clear_frames(); - lock(&self.inner.sources).clear(); + lock(&self.inner.sources).map.clear(); lock(&self.inner.problems).clear(); } /// Forget a file (after it changed on disk, or to retry a file that failed to open). pub fn forget(&self, path: &str) { - lock(&self.inner.sources).remove(path); + lock(&self.inner.sources).map.remove(path); lock(&self.inner.models).remove(path); lock(&self.inner.gifs).remove(path); lock(&self.inner.problems).remove(path); @@ -1027,7 +1061,7 @@ impl Inner { /// each decoded a long FLAC in full at once (#408). /// Each call notes the file as read (see [`crate::reads`]), with its identity as opened. fn opened(&self, path: &Arc) -> Option { - let slot = lock(&self.sources).entry(path.clone()).or_default().clone(); + let slot = lock(&self.sources).slot(path); let (opened, file) = slot.get_or_init(|| self.open(path)); reads::note(file.clone()); opened.clone() @@ -1578,8 +1612,9 @@ impl effectcraft_render::memory::MemoryHolder for Inner { fn oldest(&self) -> Option { use effectcraft_render::memory::Candidate; let c = lock(&self.cache); - let frame = c.lru.oldest().and_then(|(k, _)| c.lru.map.get(k)).map(|e| Candidate { used: e.used, bytes: e.bytes, cost_us: e.cost_us }); - let still = c.recent.front().map(|r| Candidate { used: r.used, bytes: r.bytes.max(1), cost_us: 0 }); + let frame = + c.lru.oldest().and_then(|(k, _)| c.lru.map.get(k)).map(|e| Candidate { used: e.used, bytes: e.bytes, cost_us: e.cost_us, protected: false }); + let still = c.recent.front().map(|r| Candidate { used: r.used, bytes: r.bytes.max(1), cost_us: 0, protected: false }); match (frame, still) { (Some(f), Some(s)) => Some(if s.used < f.used { s } else { f }), (f, s) => f.or(s), @@ -2427,4 +2462,22 @@ mod tests { assert!(c.stale("/b.exr", at), "older than the remembered paths: stale"); assert!(!c.stale("/b.exr", c.generation)); } + + /// #3301: open movie/audio files are capped: beyond [`MAX_OPEN_SOURCES`] the least recently + /// asked for is closed (a project of thousands of clips kept every one open). + #[test] + fn open_sources_are_capped_least_recently_used_first() { + let mut s = Sources::default(); + let path = |i: usize| -> Arc { format!("/clips/{i}.mov").into() }; + let first = s.slot(&path(0)); + for i in 1..MAX_OPEN_SOURCES + 40 { + s.slot(&path(i)); + // (the first clip is asked for again and again: it stays) + s.slot(&path(0)); + } + assert_eq!(s.map.len(), MAX_OPEN_SOURCES); + assert!(s.map.contains_key(&path(0)), "used lately: kept"); + assert!(!s.map.contains_key(&path(1)), "the least recently used went"); + assert!(Arc::ptr_eq(&first, &s.slot(&path(0))), "a kept slot is the same slot"); + } } diff --git a/crates/project/src/layer.rs b/crates/project/src/layer.rs index b13c1d980..fd1f0c347 100644 --- a/crates/project/src/layer.rs +++ b/crates/project/src/layer.rs @@ -222,6 +222,102 @@ const READS_OTHER_FRAMES: &[&str] = &[ "ec.paint.paint", ]; +/// Does the effect group `g` read its own parameters at times its frame doesn't show, past the +/// comp's shutter (`EffectHost::params_at`, `param_at`)? Write-on lays a dab at every Brush +/// Spacing from the layer's start with the Brush Position of its time, Radio Waves keeps the +/// parameters each wave was born with for its lifespan, and Transform samples past the comp's +/// shutter with its own Shutter Angle (up to 720°) or on a stretched layer (`unit_stretch` +/// false: it samples in layer time). A key change of theirs then reaches frames far from the key. The time effects and simulations ([`reads_other_frames`]) +/// read them too, and reach every frame anyway. +// ponytail: hand-kept list of the effects that call `params_at`/`param_at` beyond the comp's +// shutter; a new one must be added here. +fn reads_own_params_elsewhen(g: &PropGroup, unit_stretch: bool) -> bool { + let GroupKind::Effect { effect } = &g.kind else { return false }; + match effect.as_str() { + "ec.generate.writeon" | "ec.generate.radiowaves" => true, + // (the comp's shutter at 100% stretch is within `Comp::shutter_margin`) + "ec.distort.transform" => !unit_stretch || !g.get("useCompositionShutterAngle").is_some_and(|p| p.keys.is_empty() && p.value.as_bool()), + _ => false, + } +} + +/// `a` and `b` have the same header: every field but the children. +fn same_head(a: &PropGroup, b: &PropGroup) -> bool { + // Every field (no `..`: a new field must be considered here). + let PropGroup { uid, match_id, name, kind, enabled, label, children: _ } = a; + *uid == b.uid && *match_id == b.match_id && *name == b.name && *kind == b.kind && *enabled == b.enabled && *label == b.label +} + +/// Groups nested deeper than this in a layer's property tree count as changed everywhere. +const MAX_PROP_DEPTH: usize = 64; + +/// Where a group sits in a layer's property tree, for its audio-only children ([`audio_only`]). +#[derive(Clone, Copy, PartialEq)] +enum Level { + Root, + /// The root's Effects group. + Effects, + Inner, +} + +/// The pairs of properties that differ between `a` and `b` (groups at `level` of two layers' +/// trees, `depth` deep), when all else is the same: the same headers, children and kinds, and +/// every difference a property whose value at a time reaches only the frames around that time. +/// `None` for any other difference: one in a header, a group added, removed or reordered, or a +/// property that is read at other times (inside an effect that reads its own parameters +/// elsewhen, [`reads_own_params_elsewhen`]; in the Essential Properties; in the audio something +/// draws). Audio-only nodes count only when `heard`, as in [`same_picture_props`]. `unit_stretch`: +/// the layer plays at 100%, so layer time and comp time advance alike. +fn changed_props<'a>( + a: &'a PropGroup, + b: &'a PropGroup, + level: Level, + heard: bool, + unit_stretch: bool, + depth: usize, + out: &mut Vec<(&'a Property, &'a Property)>, +) -> Option<()> { + if depth > MAX_PROP_DEPTH || !same_head(a, b) { + return None; + } + let audio = |n: &Node| match level { + Level::Root => audio_only(n, true), + Level::Effects => audio_only(n, false), + Level::Inner => false, + }; + let mut x = a.children.iter().filter(|n| heard || !audio(n)); + let mut y = b.children.iter().filter(|n| heard || !audio(n)); + loop { + let (m, n) = match (x.next(), y.next()) { + (None, None) => return Some(()), + (Some(m), Some(n)) => (m, n), + _ => return None, + }; + if m == n { + continue; + } + // Waveform and spectrum effects draw a stretch of the audio they hear; audio effects + // (delay, reverb) carry it on. + if audio(m) || audio(n) { + return None; + } + match (m, n) { + (Node::Group(g), Node::Group(h)) => { + // (the Essential Properties override the nested comp's controls, which reach its + // layers by paths this walk doesn't follow: time effects and motion blur there, + // mirrored masters; conservatively, their whole span) + if matches!(g.kind, GroupKind::Essential { .. }) || reads_own_params_elsewhen(g, unit_stretch) || reads_own_params_elsewhen(h, unit_stretch) { + return None; + } + let level = if level == Level::Root && g.match_id == "effects" { Level::Effects } else { Level::Inner }; + changed_props(g, h, level, heard, unit_stretch, depth.saturating_add(1), out)?; + } + (Node::Prop(p), Node::Prop(q)) => out.push((p, q)), + _ => return None, + } + } +} + impl Switches { /// These switches with Audio, Lock and Shy at their defaults. pub fn pixels(&self) -> Switches { @@ -246,11 +342,6 @@ fn audio_only(n: &Node, root: bool) -> bool { /// `a` and `b` are equal but for their audio-only nodes ([`audio_only`]: the root's Audio group, /// the effects in its Effects group that are audio effects). fn same_picture_props(a: &PropGroup, b: &PropGroup) -> bool { - fn head(a: &PropGroup, b: &PropGroup) -> bool { - // Every field (no `..`: a new field must be considered here). - let PropGroup { uid, match_id, name, kind, enabled, label, children: _ } = a; - *uid == b.uid && *match_id == b.match_id && *name == b.name && *kind == b.kind && *enabled == b.enabled && *label == b.label - } fn children(a: &PropGroup, b: &PropGroup, root: bool) -> bool { let mut x = a.children.iter().filter(|n| !audio_only(n, root)); let mut y = b.children.iter().filter(|n| !audio_only(n, root)); @@ -258,7 +349,7 @@ fn same_picture_props(a: &PropGroup, b: &PropGroup) -> bool { match (x.next(), y.next()) { (None, None) => return true, (Some(Node::Group(g)), Some(Node::Group(h))) if root && g.match_id == "effects" && h.match_id == "effects" => { - if !(head(g, h) && children(g, h, false)) { + if !(same_head(g, h) && children(g, h, false)) { return false; } } @@ -267,7 +358,7 @@ fn same_picture_props(a: &PropGroup, b: &PropGroup) -> bool { } } } - head(a, b) && children(a, b, true) + same_head(a, b) && children(a, b, true) } /// `g` (a layer's property tree) without its audio-only nodes ([`same_picture_props`]). @@ -343,16 +434,20 @@ impl Layer { } /// The comp-time spans where `self` draws differently than `o` when the two differ only in - /// the keyframes of Transform properties (a key's value, ease or interpolation moved in the - /// Timeline or Graph Editor): from two keys before the first changed key to two after the - /// last (auto-Bezier and continuous tangents reach the neighbouring segments), to the - /// layer's in or out point past the first or last key (values hold there). `None` for any - /// other difference, a static value, an expression on the layer (it can read the keyed - /// property at other times), roving or muted keys, a time remap or a time effect (it reads other - /// times): those reach the layer's whole span. + /// the keyframes of their properties (a key's value, ease or interpolation moved in the + /// Timeline or Graph Editor), anywhere in the property tree: Transform, effects, masks, shape + /// contents, text animators, layer styles… Per changed property, from two keys before the + /// first changed key to two after the last (auto-Bezier and continuous tangents reach the + /// neighbouring segments), to the layer's in or out point past the first or last key (values + /// hold there). A keyed value at a time comes from the keys around it, whatever its kind (a + /// path, a gradient, Source Text's hold keys, an orientation). `None` for any other + /// difference: the tree's structure (a group or effect added, removed or reordered, a + /// group's header), a static value, an expression on the layer (it can read the keyed + /// property at other times), roving or muted keys, a time remap or a time effect (it reads + /// other times), a property read at other times (an effect reading its own parameters + /// elsewhen, the Essential Properties, audio something draws, see [`changed_props`]; Position + /// under Auto-Orient Along Path; a model's animation clip): those reach the layer's whole span. pub fn keyframe_spans(&self, o: &Layer, with_markers: bool, heard: bool) -> Option> { - let transform = |l: &Layer| l.props.group("transform").cloned(); - let (t1, t0) = (transform(self)?, transform(o)?); let reads_time = |l: &Layer| { l.props.get("timeRemap").is_some() || l.props.group("effects").is_some_and(|e| { @@ -367,22 +462,35 @@ impl Layer { if reads_time(self) || reads_time(o) || has_expr(self) || has_expr(o) { return None; } - // Everything but the Transform group draws the same. - let rest = |l: &Layer| { + // Everything but the property tree's contents draws the same. + let shell = |l: &Layer| { let mut l = l.clone(); - l.props.children.retain(|n| !matches!(n, Node::Group(g) if g.match_id == "transform")); + l.props.children.clear(); l }; - let head = |g: &PropGroup| PropGroup { children: vec![], ..g.clone() }; - if !rest(self).same_pixels_with(&rest(o), with_markers, heard) || head(&t1) != head(&t0) || t1.children.len() != t0.children.len() { + if !shell(self).same_pixels_with(&shell(o), with_markers, heard) { return None; } + // Properties read at other times by the renderer: Position under Auto-Orient Along Path + // (where the layer holds still it keeps the direction of the last motion, any distance + // back) and a model's animation clip (it plays from the key that chose it). + fn at<'a>(l: &'a Layer, group: &str, m: &str) -> Option<&'a Property> { + l.props.sub(group).and_then(|g| g.get(m)) + } + let along = self.auto_orient == AutoOrient::AlongPath || o.auto_orient == AutoOrient::AlongPath; + if (along && ["position", "positionX", "positionY", "positionZ"].iter().any(|m| at(self, "transform", m) != at(o, "transform", m))) + || at(self, "geometryOptions", "animation") != at(o, "geometryOptions", "animation") + { + return None; + } + let unit_stretch = (self.effective_stretch() - 100.0).abs() < 1e-9; + let mut pairs = Vec::new(); + changed_props(&self.props, &o.props, Level::Root, heard, unit_stretch, 0, &mut pairs)?; + // (a reversed layer plays its first keys last) + let reversed = self.effective_stretch() < 0.0; + let (early, late) = if reversed { (self.out_point, self.in_point) } else { (self.in_point, self.out_point) }; let mut spans = Vec::new(); - for (n1, n0) in t1.children.iter().zip(&t0.children) { - if n1 == n0 { - continue; - } - let (Node::Prop(p1), Node::Prop(p0)) = (n1, n0) else { return None }; + for (p1, p0) in pairs { let bare = |p: &Property| Property { keys: vec![], value: Value::Scalar(0.0), ..p.clone() }; // (muted keys are skipped: the keys around an edit that play can be any distance away) if bare(p1) != bare(p0) || p1.keys.is_empty() || p0.keys.is_empty() || p1.keys.iter().chain(&p0.keys).any(|k| k.roving || k.muted) { @@ -405,7 +513,7 @@ impl Layer { let ahead = if upto >= keys.len() { None } else { keys.get(upto.saturating_add(1).min(keys.len().saturating_sub(1))) }; hi = hi.zip(ahead).map(|(a, k)| a.max(k.time)); } - let (x, y) = (lo.map_or(self.in_point, |t| self.comp_time(t)), hi.map_or(self.out_point, |t| self.comp_time(t))); + let (x, y) = (lo.map_or(early, |t| self.comp_time(t)), hi.map_or(late, |t| self.comp_time(t))); let (x, y) = (x.min(y).max(self.in_point), x.max(y).min(self.out_point)); if x <= y { spans.push((x, y)); diff --git a/crates/project/src/tests.rs b/crates/project/src/tests.rs index d040c8f0b..ad652b182 100644 --- a/crates/project/src/tests.rs +++ b/crates/project/src/tests.rs @@ -523,3 +523,275 @@ fn an_item_inside_a_non_folder_moves_to_the_top_level_when_a_project_is_opened() // Nothing to repair in a sound project. assert!(Project::from_json_repaired(&q.to_json()).expect("opens").1.is_empty()); } + +/// #3324: a layer of [`project_with_layer`] with `add` applied and three keys (at 1, 2 and 3 s) +/// with `values` on the property at `path`, and that layer with the middle key's value `mid`. +fn middle_key_edit(add: impl FnOnce(&mut Ids, &mut crate::Layer), path: &str, values: [Value; 3], mid: Value) -> (crate::Layer, crate::Layer) { + let (mut p, cid) = project_with_layer(); + let mut l = p.comp(cid).unwrap().layers[0].clone(); + add(&mut Ids(&mut p.next_id), &mut l); + l.props.prop_mut(path).unwrap_or_else(|| panic!("{path}")).keys = + values.into_iter().zip([1.0, 2.0, 3.0]).map(|(v, s)| Keyframe::new(Tick::from_seconds_f64(s), v)).collect(); + let mut edited = l.clone(); + edited.props.prop_mut(path).unwrap().keys[1].value = mid; + (l, edited) +} + +/// The span of a middle-key edit: from the first key to the last (1 to 3 s). +fn first_to_last_key() -> Option> { + Some(vec![(Tick::from_seconds_f64(1.0), Tick::from_seconds_f64(3.0))]) +} + +/// An effect instance as `effects::instantiate` builds it: `params` under its group, or under a +/// `master` group (Exposure's `master/exposure`). +fn effect(ids: &mut Ids, id: &str, params: Vec) -> crate::PropGroup { + let mut fx = ids.group(id, id); + fx.kind = crate::GroupKind::Effect { effect: id.into() }; + for p in params { + fx.children.push(p.into()); + } + fx +} + +fn exposure(ids: &mut Ids) -> crate::PropGroup { + let master = ids.group("master", "Master").with(ids.prop("exposure", "Exposure", Value::Scalar(0.0))); + let mut fx = effect(ids, "ec.color.exposure", vec![]); + fx.children.push(master.into()); + fx +} + +fn add_effect(l: &mut crate::Layer, fx: crate::PropGroup) { + l.props.sub_mut("effects").unwrap().children.push(fx.into()); +} + +fn scalars(v: [f64; 3]) -> [Value; 3] { + v.map(Value::Scalar) +} + +/// A key edit on an effect parameter (inside the effect's Master group) keeps the frames +/// outside its keys, as a Transform key edit does (#3324). +#[test] +fn an_effect_key_edit_reaches_only_its_keys() { + let (a, b) = middle_key_edit(|ids, l| add_effect(l, exposure(ids)), "effects/#1/master/exposure", scalars([0.0, 1.0, 0.0]), Value::Scalar(2.0)); + assert_eq!(b.keyframe_spans(&a, true, false), first_to_last_key()); + assert_eq!(a.keyframe_spans(&b, true, false), first_to_last_key()); +} + +/// A key edit on a mask's path (a shape value) keeps the frames outside its keys (#3324). +#[test] +fn a_mask_path_key_edit_reaches_only_its_keys() { + let path = |w: f64| Value::Path(ShapePath::rect([0.0, 0.0], w, 10.0)); + let (a, b) = middle_key_edit( + |ids, l| { + let m = build::mask(ids, "Mask 1", ShapePath::rect([0.0, 0.0], 10.0, 10.0), MaskMode::Add, [255, 0, 0]); + l.props.sub_mut("masks").unwrap().children.push(m.into()); + }, + "masks/mask#1/path", + [path(10.0), path(20.0), path(10.0)], + path(40.0), + ); + assert_eq!(b.keyframe_spans(&a, true, false), first_to_last_key()); +} + +/// A key edit on a shape's path inside a shape group keeps the frames outside its keys (#3324). +#[test] +fn a_shape_path_key_edit_reaches_only_its_keys() { + let path = |w: f64| Value::Path(ShapePath::ellipse([0.0, 0.0], w, 10.0)); + let (a, b) = middle_key_edit( + |ids, l| { + let shape = build::shape_path(ids, ShapePath::ellipse([0.0, 0.0], 10.0, 10.0)); + let fill = build::shape_fill(ids, [1.0, 0.0, 0.0, 1.0]); + let group = build::shape_group(ids, "Group 1", vec![shape, fill]); + l.props.children.push(build::contents(ids).with(group).into()); + }, + "contents/group#1/contents/path#1/path", + [path(10.0), path(20.0), path(10.0)], + path(40.0), + ); + assert_eq!(b.keyframe_spans(&a, true, false), first_to_last_key()); +} + +/// A key edit on a text animator's property keeps the frames outside its keys, and so does one +/// on Source Text (hold keys) (#3324). +#[test] +fn text_key_edits_reach_only_their_keys() { + let text = |ids: &mut Ids, l: &mut crate::Layer| { + let mut t = build::text(ids, effectcraft_keyframe::TextDoc::plain("Hello")); + let opacity = build::text_anim_prop(ids, "opacity").unwrap(); + let animator = build::text_animator(ids, "Animator 1", vec![opacity]); + t.sub_mut("animators").unwrap().children.push(animator.into()); + l.props.children.push(t.into()); + }; + let (a, b) = middle_key_edit(text, "text/animators/animator#1/properties/opacity", scalars([100.0, 0.0, 100.0]), Value::Scalar(50.0)); + assert_eq!(b.keyframe_spans(&a, true, false), first_to_last_key()); + let doc = |s: &str| Value::Text(Box::new(effectcraft_keyframe::TextDoc::plain(s))); + let (a, b) = middle_key_edit(text, "text/sourceText", [doc("a"), doc("b"), doc("c")], doc("B")); + assert_eq!(b.keyframe_spans(&a, true, false), first_to_last_key()); +} + +/// An expression anywhere on the layer can read the keyed property at other times: an effect key +/// edit then reaches the layer's whole span (#3324). +#[test] +fn an_expression_elsewhere_on_the_layer_keeps_the_whole_span() { + let (a, b) = middle_key_edit( + |ids, l| { + add_effect(l, exposure(ids)); + l.props.prop_mut("transform/rotation").unwrap().expr = Some(crate::Expression { text: "time * 10".into(), enabled: true }); + }, + "effects/#1/master/exposure", + scalars([0.0, 1.0, 0.0]), + Value::Scalar(2.0), + ); + assert_eq!(b.keyframe_spans(&a, true, false), None); +} + +/// A change of the tree's structure reaches the layer's whole span: an effect added (even beside +/// a key edit), and a group header (an effect switched off) (#3324). +#[test] +fn an_effect_added_or_switched_off_keeps_the_whole_span() { + let (a, b) = middle_key_edit(|ids, l| add_effect(l, exposure(ids)), "effects/#1/master/exposure", scalars([0.0, 1.0, 0.0]), Value::Scalar(2.0)); + let mut added = a.clone(); + add_effect(&mut added, effect(&mut Ids(&mut 10_000), "ec.channel.invert", vec![])); + assert_eq!(added.keyframe_spans(&a, true, false), None); + let mut both = b.clone(); + add_effect(&mut both, effect(&mut Ids(&mut 10_000), "ec.channel.invert", vec![])); + assert_eq!(both.keyframe_spans(&a, true, false), None); + let mut off = b.clone(); + off.props.group_mut("effects/#1").unwrap().enabled = false; + assert_eq!(off.keyframe_spans(&a, true, false), None); +} + +/// Effects that read their own parameters at other times (Write-on's dabs since the layer's +/// start, Radio Waves' birth values, Transform's own shutter) reach the layer's whole span with a +/// key edit of theirs, not with one of another effect on the layer (#3324). +#[test] +fn effects_reading_their_parameters_elsewhen_keep_the_whole_span() { + let v2 = |x: f64| Value::Vec2([x, 0.0]); + let write_on = |ids: &mut Ids| { + let p = ids.prop("brushPosition", "Brush Position", v2(0.0)); + effect(ids, "ec.generate.writeon", vec![p]) + }; + let (a, b) = middle_key_edit(|ids, l| add_effect(l, write_on(ids)), "effects/#1/brushPosition", [v2(0.0), v2(5.0), v2(0.0)], v2(9.0)); + assert_eq!(b.keyframe_spans(&a, true, false), None); + let radio = |ids: &mut Ids| { + let p = ids.prop("producePoint", "Producer Point", v2(0.0)); + effect(ids, "ec.generate.radiowaves", vec![p]) + }; + let (a, b) = middle_key_edit(|ids, l| add_effect(l, radio(ids)), "effects/#1/producePoint", [v2(0.0), v2(5.0), v2(0.0)], v2(9.0)); + assert_eq!(b.keyframe_spans(&a, true, false), None); + // Transform: its own Shutter Angle reaches past the comp's shutter, the comp's doesn't unless + // the layer is stretched (Transform samples its shutter in layer time). + for (comp_shutter, stretch, want) in [(false, 100.0, None), (true, 100.0, first_to_last_key()), (true, 200.0, None)] { + let transform = |ids: &mut Ids, l: &mut crate::Layer| { + let shutter = ids.prop("useCompositionShutterAngle", "Use Composition's Shutter Angle", Value::Bool(comp_shutter)); + let rotation = ids.prop("rotation", "Rotation", Value::Scalar(0.0)); + add_effect(l, effect(ids, "ec.distort.transform", vec![shutter, rotation])); + l.stretch = stretch; + }; + let (a, b) = middle_key_edit(transform, "effects/#1/rotation", scalars([0.0, 10.0, 0.0]), Value::Scalar(20.0)); + let want = want.map(|_| vec![(a.comp_time(Tick::from_seconds_f64(1.0)), a.comp_time(Tick::from_seconds_f64(3.0)))]); + assert_eq!(b.keyframe_spans(&a, true, false), want, "comp shutter {comp_shutter}, stretch {stretch}"); + } + // Another effect's key edit beside a Write-on. + let (a, b) = middle_key_edit( + |ids, l| { + add_effect(l, write_on(ids)); + add_effect(l, exposure(ids)); + }, + "effects/#2/master/exposure", + scalars([0.0, 1.0, 0.0]), + Value::Scalar(2.0), + ); + assert_eq!(b.keyframe_spans(&a, true, false), first_to_last_key()); +} + +/// The Essential Properties feed a nested comp, and audio something draws (a waveform reads a +/// stretch of it): a key edit there reaches the layer's whole span. Audio nothing draws doesn't +/// count at all (#3324). +#[test] +fn essential_properties_and_heard_audio_keep_the_whole_span() { + let (a, b) = middle_key_edit( + |ids, l| { + let mut g = ids.group("essentialProperties", "Essential Properties").with(ids.prop("control1", "Size", Value::Scalar(0.0))); + g.kind = crate::GroupKind::Essential { overridden: vec![] }; + l.props.children.push(g.into()); + }, + "essentialProperties/control1", + scalars([0.0, 1.0, 0.0]), + Value::Scalar(2.0), + ); + assert_eq!(b.keyframe_spans(&a, true, false), None); + let (a, b) = middle_key_edit( + |ids, l| l.props.children.push(build::audio(ids).into()), + "audio/levels", + [Value::Vec2([0.0; 2]), Value::Vec2([-6.0; 2]), Value::Vec2([0.0; 2])], + Value::Vec2([-12.0; 2]), + ); + assert_eq!(b.keyframe_spans(&a, true, true), None, "heard"); + assert_eq!(b.keyframe_spans(&a, true, false), Some(vec![]), "not heard: the picture is the same"); +} + +/// A property tree nested deeper than the walk goes counts as changed everywhere (#3324). +#[test] +fn a_deeply_nested_key_edit_keeps_the_whole_span() { + // 100 groups around a property keyed at 1, 2 and 3 s with `mid` in the middle (the same uids + // each time). + let deep = |mid: f64| { + let mut n = 50_000; + let ids = &mut Ids(&mut n); + let mut x = ids.prop("x", "X", Value::Scalar(0.0)); + x.keys = [0.0, mid, 0.0].into_iter().zip([1.0, 2.0, 3.0]).map(|(v, s)| Keyframe::new(Tick::from_seconds_f64(s), Value::Scalar(v))).collect(); + let mut g = ids.group("g", "G").with(x); + for _ in 0..100 { + g = ids.group("g", "G").with(g); + } + g + }; + let (p, cid) = project_with_layer(); + let (mut a, mut b) = (p.comp(cid).unwrap().layers[0].clone(), p.comp(cid).unwrap().layers[0].clone()); + a.props.children.push(deep(1.0).into()); + b.props.children.push(deep(2.0).into()); + assert_eq!(b.keyframe_spans(&a, true, false), None); + // (a Transform key edit beside the same deep tree keeps its span) + let (a, b) = middle_key_edit(|_, l| l.props.children.push(deep(1.0).into()), "transform/opacity", scalars([100.0, 0.0, 100.0]), Value::Scalar(50.0)); + assert_eq!(b.keyframe_spans(&a, true, false), first_to_last_key()); +} + +/// On a reversed layer (negative stretch) the first keys play last: an edit of the first key +/// reaches from the next keys' time to the out point, not from the in point (#3324). +#[test] +fn a_first_key_edit_on_a_reversed_layer_reaches_the_out_point() { + // (a layer from 0 to 10 s reversed: start 10 s, so layer time t shows at 10 - t) + let reversed = |_: &mut Ids, l: &mut crate::Layer| (l.stretch, l.start_time) = (-100.0, Tick::from_seconds_f64(10.0)); + let (a, _) = middle_key_edit(reversed, "transform/opacity", scalars([100.0, 0.0, 100.0]), Value::Scalar(0.0)); + let mut b = a.clone(); + b.props.prop_mut("transform/opacity").unwrap().keys[0].value = Value::Scalar(50.0); + let spans = b.keyframe_spans(&a, true, false).unwrap(); + let (s, e) = spans[0]; + assert_eq!(spans.len(), 1); + // Keys at layer 1, 2, 3 s show at 9, 8, 7 s; the first key's edit reaches 7 s (its second key + // after) through the out point. + assert_eq!((s, e), (Tick::from_seconds_f64(7.0), a.out_point), "{spans:?}"); +} + +/// The renderer reads some properties at other times: Position under Auto-Orient Along Path (a +/// still layer keeps its last direction of travel) and a model's animation clip (it plays from the +/// key that chose it). Their key edits reach the layer's whole span (#3324). +#[test] +fn properties_the_renderer_reads_elsewhen_keep_the_whole_span() { + let v3 = |x: f64| Value::Vec3([x, 0.0, 0.0]); + let (a, b) = middle_key_edit(|_, l| l.auto_orient = crate::AutoOrient::AlongPath, "transform/position", [v3(0.0), v3(5.0), v3(9.0)], v3(2.0)); + assert_eq!(b.keyframe_spans(&a, true, false), None); + let (a, b) = middle_key_edit(|_, _| {}, "transform/position", [v3(0.0), v3(5.0), v3(9.0)], v3(2.0)); + assert_eq!(b.keyframe_spans(&a, true, false), first_to_last_key(), "without Auto-Orient"); + let (a, b) = middle_key_edit( + |ids, l| { + let g = ids.group("geometryOptions", "Geometry Options").with(ids.prop("animation", "Animation", Value::Enum(0))); + l.props.children.push(g.into()); + }, + "geometryOptions/animation", + [Value::Enum(0), Value::Enum(1), Value::Enum(1)], + Value::Enum(0), + ); + assert_eq!(b.keyframe_spans(&a, true, false), None); +} diff --git a/crates/render/src/cache.rs b/crates/render/src/cache.rs index 2248326ed..1fcb62e1d 100644 --- a/crates/render/src/cache.rs +++ b/crates/render/src/cache.rs @@ -1046,7 +1046,7 @@ impl crate::memory::MemoryHolder for LayerCache { fn oldest(&self) -> Option { let g = self.inner.lock().ok()?; let e = g.map.get(&g.oldest_key()?)?; - Some(crate::memory::Candidate { used: e.used, bytes: e.bytes, cost_us: e.cost_us }) + Some(crate::memory::Candidate { used: e.used, bytes: e.bytes, cost_us: e.cost_us, protected: false }) } fn drop_oldest(&self) -> usize { let Ok(mut g) = self.inner.lock() else { return 0 }; diff --git a/crates/render/src/disk_cache.rs b/crates/render/src/disk_cache.rs index 4c7817280..097ab53e3 100644 --- a/crates/render/src/disk_cache.rs +++ b/crates/render/src/disk_cache.rs @@ -53,6 +53,11 @@ const MAGIC: &[u8; 4] = b"ECDC"; /// Pending layer and matte writes before new ones are dropped. #[cfg(not(target_arch = "wasm32"))] const QUEUE_LIMIT: usize = 64; +/// What reading a megabyte of a disk cache entry back is assumed to take until reads are +/// measured, in microseconds: 10 ms (100 MB/s, a slow disk or a network share), so a quick frame +/// is not written on a guess ([`DiskCache::pays_off`]). +pub const DEFAULT_READ_US_PER_MB: u64 = 10_000; + /// Pending frame bytes before new frames are dropped. Frames have their own lane, written /// before layer buffers: a burst of large layer writes used to fill the shared queue and drop /// frames, so a fully cached comp came back with gaps in its blue bar. @@ -524,6 +529,9 @@ pub struct DiskCache { queue: Arc<(Mutex, Condvar)>, /// Layer buffers that took less than this to render are not written (ms). min_layer_ms: AtomicU64, + /// What reading a megabyte of an entry takes, in microseconds ([`DiskCache::pays_off`]): + /// [`DEFAULT_READ_US_PER_MB`] until reads are measured, then their running average. + read_us_per_mb: AtomicU64, /// Files whose entries are being deleted ([`DiskCache::drop_files`]), each with the number /// of drops of it pending: until then an entry made of one is a miss. dropping: Mutex, u32>>, @@ -636,6 +644,7 @@ impl DiskCache { Condvar::new(), )), min_layer_ms: AtomicU64::new(30), + read_us_per_mb: AtomicU64::new(DEFAULT_READ_US_PER_MB), dropping: Mutex::new(HashMap::new()), #[cfg(test)] head_bytes: AtomicU64::new(0), @@ -771,6 +780,38 @@ impl DiskCache { self.min_layer_ms.load(Ordering::Relaxed) } + /// What reading `bytes` of an entry back is expected to take, in microseconds (the measured + /// read rate, [`DiskCache::note_read`]). + pub fn read_us(&self, bytes: usize) -> u64 { + let rate = u128::from(self.read_us_per_mb.load(Ordering::Relaxed)); + u64::try_from(u128::try_from(bytes).unwrap_or(u128::MAX).saturating_mul(rate) >> 20).unwrap_or(u64::MAX) + } + + /// Set the read rate assumed until reads are measured (microseconds per MB; tests that need + /// every write give 0: everything pays off). + pub fn set_read_us_per_mb(&self, us: u64) { + self.read_us_per_mb.store(us, Ordering::Relaxed); + } + + /// Whether a frame or plane set of `bytes` that took `make_us` microseconds to make is worth + /// a disk write: only when making it again costs more than reading it back (#3301). A RAM + /// eviction keeps the disk copy either way. + pub fn pays_off(&self, bytes: usize, make_us: u64) -> bool { + let read = self.read_us(bytes); + read == 0 || make_us > read + } + + /// Note a read of `bytes` that took `took_us` (reads of under 64 KB are too short to time): + /// the read rate becomes a running average (7/8 the old rate, 1/8 this read's). + fn note_read(&self, bytes: usize, took_us: u64) { + if bytes < 64 << 10 { + return; + } + let rate = u64::try_from(u128::from(took_us).saturating_mul(1 << 20) / u128::try_from(bytes).unwrap_or(1).max(1)).unwrap_or(u64::MAX); + let old = self.read_us_per_mb.load(Ordering::Relaxed); + self.read_us_per_mb.store(old.saturating_mul(7).saturating_add(rate) / 8, Ordering::Relaxed); + } + pub fn contains(&self, kind: Kind, key: u128) -> bool { self.index.lock().is_ok_and(|g| g.contains(kind, key)) } @@ -851,8 +892,12 @@ impl DiskCache { return None; } let path = self.path(kind, key); + let t0 = web_time::Instant::now(); let data = std::fs::read(&path).ok(); let ok = data.as_deref().and_then(|d| Some((*d.get(5)?, verify(d, kind)?.to_vec()))); + if let Some((_, payload)) = &ok { + self.note_read(payload.len(), u64::try_from(t0.elapsed().as_micros()).unwrap_or(u64::MAX)); + } if ok.is_none() { // Gone (another process evicted it) or damaged: forget it. if data.is_some() { @@ -1553,7 +1598,7 @@ impl crate::memory::MemoryHolder for DiskCache { fn oldest(&self) -> Option { let q = self.queue.0.lock().ok()?; let (_, bytes) = q.newest_unique()?; - Some(crate::memory::Candidate { used: 0, bytes, cost_us: 0 }) + Some(crate::memory::Candidate { used: 0, bytes, cost_us: 0, protected: false }) } fn drop_oldest(&self) -> usize { let Ok(mut q) = self.queue.0.lock() else { return 0 }; @@ -2940,4 +2985,29 @@ mod tests { assert!(!dc.made_of_dropped(&files, &dc.drops_now()), "read after the drop: used"); let _ = std::fs::remove_dir_all(&dir); } + + /// #3301: a frame or plane set is written only when making it again costs more than + /// reading it back: a cheap one is not written, an expensive one is; the read rate follows + /// the reads measured. + #[test] + fn only_items_dearer_to_make_than_to_read_are_written() { + let dir = tmpdir("pays-off"); + let dc = DiskCache::open(&dir, 1 << 30).unwrap(); + let eight_mb = 8 << 20; + // Until a read is measured: 10 ms per MB, 80 ms for 8 MB. + assert_eq!(dc.read_us(eight_mb), 8 * DEFAULT_READ_US_PER_MB); + assert!(!dc.pays_off(eight_mb, 1_000), "rendered in 1 ms: not written"); + assert!(dc.pays_off(eight_mb, 200_000), "rendered in 200 ms: written"); + // Reads measured at 1 ms per MB: a 20 ms frame of 8 MB is now worth writing. + assert!(!dc.pays_off(eight_mb, 20_000)); + for _ in 0..40 { + dc.note_read(1 << 20, 1_000); + } + assert!(dc.pays_off(eight_mb, 20_000), "{}", dc.read_us(eight_mb)); + // Tiny reads are not timed. + dc.note_read(100, 1_000_000); + assert!(dc.pays_off(eight_mb, 20_000)); + drop(dc); + let _ = std::fs::remove_dir_all(&dir); + } } diff --git a/crates/render/src/memory.rs b/crates/render/src/memory.rs index 9e2ef1dc5..7859be071 100644 --- a/crates/render/src/memory.rs +++ b/crates/render/src/memory.rs @@ -8,7 +8,8 @@ //! //! An item's value is what it would cost to make again per byte ([`Candidate::cost_us`], the //! measured render or decode time where known, else a typical one: [`DEFAULT_LAYER_US_PER_MB`] -//! and its neighbours), decayed by the time since it was last used ([`HALF_LIFE_US`]): +//! and its neighbours), decayed slowly by the time since it was last used (by the logarithm of +//! the seconds unused, so a costly frame unused for minutes still outlives a cheap one): //! [`value`]. A copy of data another cache holds (a queued disk write) costs nothing to make //! again. Each holder offers the item it would drop next (its least recently used one, //! [`MemoryHolder::oldest`]); the accountant drops the least valuable of those, asks that holder @@ -28,10 +29,6 @@ use std::sync::{Arc, Mutex, MutexGuard, PoisonError, TryLockError, Weak}; /// The share of the budget the accountant frees down to once it is over (hysteresis). pub const TRIM_TO: f64 = 0.9; -/// An item unused this long is worth half as much as one just used ([`value`]), a quarter at -/// three times this, and so on (`1 / (1 + age / HALF_LIFE_US)`). -pub const HALF_LIFE_US: u64 = 30_000_000; - /// While a holder thrashes, its items are worth this many times more ([`value`]). pub const THRASH_BOOST: f64 = 4.0; @@ -79,7 +76,7 @@ const GROWTH_PART: usize = 16; const THRASH_FOR: std::time::Duration = std::time::Duration::from_secs(10); /// The item a holder would drop next ([`MemoryHolder::oldest`]). -#[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] pub struct Candidate { /// When it was last used ([`tick`]). pub used: u64, @@ -87,15 +84,53 @@ pub struct Candidate { pub bytes: usize, /// What making it again costs, in microseconds (0: a copy of data another cache holds). pub cost_us: u64, + /// About to be used: a frame a playing RAM preview shows next. Kept over the budget by up to + /// [`preview_overage`] while other items can go instead, never past the hard limit. + pub protected: bool, } -/// What an item is worth keeping at `now` ([`tick`]): its cost to make again per byte, halved -/// after [`HALF_LIFE_US`] unused, [`THRASH_BOOST`] times more while its holder thrashes. +impl Candidate { + /// An item that is not [`Candidate::protected`]. + pub fn new(used: u64, bytes: usize, cost_us: u64) -> Candidate { + Candidate { used, bytes, cost_us, protected: false } + } +} + +/// How far protected items (frames a playing preview shows next) may keep the caches over a +/// budget of `budget` bytes while other items can go instead: a tenth of it, at most 1 GB. +pub fn preview_overage(budget: usize) -> usize { + (budget / 10).min(1 << 30) +} + +/// How often the process's memory is read at most ([`Accountant::set_process_memory`]), in +/// [`tick`]'s units (microseconds). +const PROCESS_READ_EVERY: u64 = 250_000; + +/// The process's memory as the accountant watches it ([`Accountant::set_process_memory`]). +struct ProcessWatch { + /// Reads the memory the process uses now, in bytes (`None`: unknown). + read: Option Option>, + /// Above this the caches are trimmed by what is over, even when they are within their + /// budget (memory nobody accounts for: GPU staging, effect buffers, the allocator's + /// fragmentation)… + purge_at: u64, + /// …and above this also the protected items go ([`Candidate::protected`]). + hard_at: u64, + /// When it was last read ([`tick`]'s units). + read_at: Option, + /// What the caches freed for it since it was last under its purge limit: freed memory often + /// stays in the reading (the allocator keeps it), so it counts as freed; the caches give way + /// again only for memory that grew beyond that, and are never emptied for one reading. + credited: u64, +} + +/// What an item is worth keeping at `now` ([`tick`]): its cost to make again per byte, divided +/// by `ln(seconds unused + 1) + 1` (a slow decay: about a fifth after a minute unused, a +/// seventh after ten), [`THRASH_BOOST`] times more while its holder thrashes. pub fn value(c: &Candidate, now: u64, thrashing: bool) -> f64 { let per_byte = c.cost_us as f64 / c.bytes.max(1) as f64; - let age = now.saturating_sub(c.used) as f64; - let half = HALF_LIFE_US as f64; - let v = per_byte * half / (half + age); + let age_s = now.saturating_sub(c.used) as f64 / 1e6; + let v = per_byte / ((age_s + 1.0).ln() + 1.0); if thrashing { v * THRASH_BOOST } else { v } } @@ -140,6 +175,8 @@ pub struct Accountant { requested: AtomicBool, /// The clock items' ages are measured with ([`tick`]; tests give their own). clock: fn() -> u64, + /// The process's memory, read and checked by each balance. + process: Mutex, } impl Default for Accountant { @@ -164,16 +201,60 @@ impl Accountant { balancing: Mutex::new(None), requested: AtomicBool::new(false), clock, + process: Mutex::new(ProcessWatch { read: None, purge_at: u64::MAX, hard_at: u64::MAX, read_at: None, credited: 0 }), } } + /// Watch the process's memory with `read` (the bytes it uses now): a balance (at most every + /// 250 ms) trims the caches by what it is over `purge_at`, even while they are within their + /// budget, and above `hard_at` also the frames a playing preview shows next. + pub fn set_process_memory(&self, read: fn() -> Option, purge_at: u64, hard_at: u64) { + { + let mut p = self.process.lock().unwrap_or_else(PoisonError::into_inner); + p.read = Some(read); + p.purge_at = purge_at; + p.hard_at = hard_at.max(purge_at); + } + self.balance(); + } + + /// What a balance at `now` must free beyond the budget for the process's memory, and whether + /// it is past the hard limit (a reading at most every [`PROCESS_READ_EVERY`]). What the caches + /// already freed for it counts as freed ([`ProcessWatch::credited`]). + fn process_excess(&self, now: u64) -> (u64, bool) { + let mut p = self.process.lock().unwrap_or_else(PoisonError::into_inner); + let Some(read) = p.read else { return (0, false) }; + if p.read_at.is_some_and(|at| now.saturating_sub(at) < PROCESS_READ_EVERY) { + return (0, false); + } + p.read_at = Some(now); + let Some(used) = read() else { return (0, false) }; + if used <= p.purge_at { + p.credited = 0; + return (0, false); + } + let used = used.saturating_sub(p.credited); + // (down to the trim line under the purge limit, as for the budget) + let line = (p.purge_at as f64 * TRIM_TO) as u64; + (used.saturating_sub(line), used > p.hard_at) + } + + /// The caches freed `bytes` for the process's memory. + fn credit(&self, bytes: usize) { + let mut p = self.process.lock().unwrap_or_else(PoisonError::into_inner); + p.credited = p.credited.saturating_add(u64::try_from(bytes).unwrap_or(u64::MAX)); + } + /// The process's accountant. pub fn global() -> &'static Accountant { static GLOBAL: Accountant = Accountant::new(usize::MAX); &GLOBAL } - /// Set the common budget and free down to it at once. + /// Set the common budget and free down to it: right away when no balance is running; when + /// one is (on another thread, or this one further up the stack), that balance runs again + /// with the new budget once its pass ends, so this may return before the caches are within + /// it ([`Accountant::balance`]). pub fn set_budget(&self, bytes: usize) { self.budget.store(bytes, Ordering::Relaxed); self.balance(); @@ -279,27 +360,44 @@ impl Accountant { } /// One pass of [`Accountant::balance`] with the budget in force now. + /// + /// Over the budget the caches are freed down to [`TRIM_TO`] of it; with the process's memory + /// over its purge limit ([`Accountant::set_process_memory`]) also by what that is over. + /// Protected items ([`Candidate::protected`]) go last, and only while the caches are more than + /// [`preview_overage`] over the target (or the process is past its hard limit). fn balance_once(&self) { let budget = self.budget(); if budget == usize::MAX { return; } self.grown.store(0, Ordering::Relaxed); + let now = (self.clock)(); + let (excess, hard) = self.process_excess(now); let holders = self.alive(); let mut total: usize = holders.iter().map(|(h, _)| h.bytes()).fold(0, usize::saturating_add); - if total <= budget { + let excess = usize::try_from(excess).unwrap_or(usize::MAX); + if total <= budget && excess == 0 { return; } - let target = (budget as f64 * TRIM_TO) as usize; - let now = (self.clock)(); + let held = total; + let trimmed = if total > budget { (budget as f64 * TRIM_TO) as usize } else { total }; + // (the caches can free at most what they hold) + let target = trimmed.min(total.saturating_sub(excess.min(total))); + let overage = if hard { 0 } else { preview_overage(budget) }; // Each holder's next item (`None`: it has nothing more it may drop). let mut next: Vec> = holders.iter().map(|(h, _)| h.oldest()).collect(); while total > target { + // (protected items only once nothing else can go, or past the overage) + let any_unprotected = next.iter().flatten().any(|c| !c.protected); + let protected_ok = !any_unprotected && total > target.saturating_add(overage); let pick = next .iter() .enumerate() .filter_map(|(i, c)| { let c = (*c)?; + if c.protected && !protected_ok { + return None; + } let thrashing = holders.get(i).is_some_and(|(_, t)| *t); Some((i, value(&c, now, thrashing), c.used)) }) @@ -313,6 +411,11 @@ impl Accountant { total = total.saturating_sub(freed); self.freed.fetch_add(freed, Ordering::Relaxed); } + if excess > 0 { + // (what went beyond the budget's own trim was freed for the process's memory) + let for_budget = held.saturating_sub(trimmed.max(target)); + self.credit(held.saturating_sub(total).saturating_sub(for_budget).min(excess)); + } } } @@ -329,7 +432,7 @@ mod tests { impl Fake { fn new(name: &'static str, items: &[(u64, usize, u64)]) -> Arc { - let items = items.iter().map(|&(used, bytes, cost_us)| Candidate { used, bytes, cost_us }).collect(); + let items = items.iter().map(|&(used, bytes, cost_us)| Candidate::new(used, bytes, cost_us)).collect(); Arc::new(Fake { name, items: Mutex::new(items), refills: Mutex::new(0) }) } fn held(&self) -> usize { @@ -339,7 +442,7 @@ mod tests { self.items.lock().unwrap().len() } fn push(&self, used: u64, bytes: usize, cost_us: u64) { - self.items.lock().unwrap().push_back(Candidate { used, bytes, cost_us }); + self.items.lock().unwrap().push_back(Candidate::new(used, bytes, cost_us)); } } @@ -406,10 +509,16 @@ mod tests { /// one unused for long enough goes before a costlier one used just now. #[test] fn value_falls_with_time_unused() { - let c = |used, cost_us| Candidate { used, bytes: 100, cost_us }; + let c = |used, cost_us| Candidate::new(used, 100, cost_us); assert!(value(&c(0, 1000), at_100s(), false) < value(&c(99 * S, 1000), at_100s(), false)); - let half = value(&c(at_100s() - HALF_LIFE_US, 1000), at_100s(), false); - assert!((half - 5.0).abs() < 1e-9, "{half}"); + let fresh = value(&c(at_100s(), 1000), at_100s(), false); + assert!((fresh - 10.0).abs() < 1e-9, "{fresh}"); + let a_second = value(&c(at_100s() - S, 1000), at_100s(), false); + assert!((a_second - 10.0 / (2f64.ln() + 1.0)).abs() < 1e-9, "{a_second}"); + // #3301: the decay is slow: unused for ten minutes, an item keeps more than a tenth of its + // value (it kept under a twentieth when it halved every 30 s). + let ten_minutes = value(&c(0, 1000), 600 * S, false); + assert!(ten_minutes > fresh / 10.0, "{ten_minutes}"); assert!(value(&c(0, 2000), at_100s(), false) < value(&c(at_100s(), 1000), at_100s(), false)); assert_eq!(value(&c(at_100s(), 0), at_100s(), false), 0.0, "a copy is worth nothing"); assert_eq!(value(&c(0, 1000), at_100s(), true), THRASH_BOOST * value(&c(0, 1000), at_100s(), false)); @@ -632,4 +741,94 @@ mod tests { acc.note_growth(1); assert!(frames.held() <= 900, "{}", frames.held()); } + + static PROCESS_NOW: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + static PROCESS_CLOCK: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(100_000_000); + fn process_now() -> Option { + Some(PROCESS_NOW.load(Ordering::SeqCst)) + } + fn process_clock() -> u64 { + PROCESS_CLOCK.load(Ordering::SeqCst) + } + /// (the process-memory tests share the statics above: one at a time) + static PROCESS_SERIAL: Mutex<()> = Mutex::new(()); + + /// #3301: memory nobody accounts for (GPU staging, effect buffers, fragmentation): with the + /// caches within their budget but the process over its purge limit, the caches give way by + /// what it is over, least valuable first; a reading that stays high (freed memory not shown + /// yet) doesn't empty them; over the hard limit the protected items go too. + #[test] + fn the_process_memory_over_its_limit_trims_the_caches() { + let _serial = PROCESS_SERIAL.lock().unwrap_or_else(PoisonError::into_inner); + let frames = Fake::new("frames", &[]); + for i in 0..10 { + frames.push(i * S, 100, 1_000); + } + let acc = Accountant::with_clock(10_000, process_clock); + let held: Arc = frames.clone(); + acc.register(&held); + // Under its purge limit (2000): nothing goes. + PROCESS_NOW.store(1_500, Ordering::SeqCst); + acc.set_process_memory(process_now, 2_000, 3_000); + assert_eq!(frames.held(), 1000, "within the budget and the limit"); + // 2500 measured, down to the trim line under the limit (1800): 700 go. + PROCESS_CLOCK.fetch_add(PROCESS_READ_EVERY, Ordering::SeqCst); + PROCESS_NOW.store(2_500, Ordering::SeqCst); + acc.balance(); + assert_eq!(frames.held(), 300, "the caches gave way for the process"); + // The reading stays high (the memory not handed back yet), for a minute: what was freed + // counts, the caches are not drained. + for _ in 0..240 { + PROCESS_CLOCK.fetch_add(PROCESS_READ_EVERY, Ordering::SeqCst); + acc.balance(); + } + assert_eq!(frames.held(), 300, "the same reading doesn't drain the caches"); + // Read at most every 250 ms: a higher reading within that waits. + PROCESS_NOW.store(2_600, Ordering::SeqCst); + acc.balance(); + assert_eq!(frames.held(), 300); + // 100 more than last time: the caches give way by that. + PROCESS_CLOCK.fetch_add(PROCESS_READ_EVERY, Ordering::SeqCst); + acc.balance(); + assert_eq!(frames.held(), 200, "grown by 100: 100 more go"); + // Under the limit again, then over: counted afresh. + PROCESS_CLOCK.fetch_add(PROCESS_READ_EVERY, Ordering::SeqCst); + PROCESS_NOW.store(1_000, Ordering::SeqCst); + acc.balance(); + PROCESS_CLOCK.fetch_add(PROCESS_READ_EVERY, Ordering::SeqCst); + PROCESS_NOW.store(2_050, Ordering::SeqCst); + acc.balance(); + // (250 over the trim line, with nothing counted as freed: the 200 held go) + assert_eq!(frames.held(), 0, "counted afresh"); + } + + /// #3301: frames a playing preview shows next (protected) keep the caches over the budget by + /// at most a tenth of it while other items can go instead, and go once nothing else can or + /// past that overage; past the process's hard limit no overage is allowed. + #[test] + fn protected_items_go_last_and_only_a_bounded_way_over() { + let _serial = PROCESS_SERIAL.lock().unwrap_or_else(PoisonError::into_inner); + let preview = Fake::new("preview", &[]); + for i in 0..4 { + preview.items.lock().unwrap().push_back(Candidate { used: i * S, bytes: 100, cost_us: 1, protected: true }); + } + let footage = Fake::new("footage", &[(99 * S, 300, 1_000_000)]); + let acc = Accountant::with_clock(usize::MAX, process_clock); + let held: Vec> = vec![holder(&preview), holder(&footage)]; + for h in &held { + acc.register(h); + } + // 700 held, budget 500 (target 450, overage 50): the footage goes though worth more. + acc.set_budget(500); + assert_eq!((preview.held(), footage.held()), (400, 0)); + // Budget 300 (target 270, overage 30): nothing else left, the preview frames go down to + // the overage over the target. + acc.set_budget(300); + assert_eq!(preview.held(), 300, "over the target by at most the overage"); + // Past the process's hard limit: no overage. + PROCESS_CLOCK.fetch_add(PROCESS_READ_EVERY, Ordering::SeqCst); + PROCESS_NOW.store(10_000, Ordering::SeqCst); + acc.set_process_memory(process_now, 1_000, 2_000); + assert!(preview.held() <= 200, "{}", preview.held()); + } } diff --git a/crates/ui-egui/src/frames.rs b/crates/ui-egui/src/frames.rs index 0a633afa8..725385fff 100644 --- a/crates/ui-egui/src/frames.rs +++ b/crates/ui-egui/src/frames.rs @@ -378,19 +378,21 @@ impl effectcraft_engine::render::memory::MemoryHolder for PreviewMemory { self.0.lock().map(|c| c.bytes.saturating_sub(c.gpu_bytes)).unwrap_or(0) } // (only frames in RAM: dropping a GPU frame frees no RAM, and loses a viewer frame) - /// A frame a playing preview shows next counts as just used: it is about to be (#3298 - /// review: one rendered from cached layers costs little, and older footage outlived it, so - /// the preview played into live renders). A frame costs at least a typical render - /// ([`effectcraft_engine::render::memory::DEFAULT_PREVIEW_US_PER_MB`]): a quick one still stands for a whole comp. + /// A frame a playing preview shows next is protected: the accountant lets it keep the caches + /// over the budget by a bounded amount while other items can go instead (#3301: one rendered + /// from cached layers costs little, and older footage outlived it, so the preview played into + /// live renders). A frame costs at least a typical render + /// ([`effectcraft_engine::render::memory::DEFAULT_PREVIEW_US_PER_MB`]): a quick one still + /// stands for a whole comp. fn oldest(&self) -> Option { + use effectcraft_engine::render::memory::{Candidate, DEFAULT_PREVIEW_US_PER_MB, default_cost}; let c = self.0.lock().ok()?; let k = c.order.get(c.cpu_victim()?)?; let f = c.map.get(k)?; let bytes = f.img.bytes(); - let ahead = c.playhead.as_ref().is_some_and(|p| p.ahead(k).is_some()); - let used = if ahead { effectcraft_engine::render::memory::tick() } else { f.used }; - let cost_us = f.cost_us.max(effectcraft_engine::render::memory::default_cost(bytes, effectcraft_engine::render::memory::DEFAULT_PREVIEW_US_PER_MB)); - Some(effectcraft_engine::render::memory::Candidate { used, bytes, cost_us }) + let protected = c.playhead.as_ref().is_some_and(|p| p.ahead(k).is_some()); + let cost_us = f.cost_us.max(default_cost(bytes, DEFAULT_PREVIEW_US_PER_MB)); + Some(Candidate { used: f.used, bytes, cost_us, protected }) } fn drop_oldest(&self) -> usize { let Ok(mut c) = self.0.lock() else { return 0 }; @@ -1171,6 +1173,10 @@ impl Frames { // (only with the generation its render started at, for this cache: a frame // made of a file Reload Footage dropped since holds the pixels from before) let since = c.since.as_ref().and_then(|s| s.for_cache(&dc)).filter(|s| !dc.dropped_since(files, *s))?; + // (only a frame that costs more to render again than to read back, #3301) + if !dc.pays_off(c.img.bytes(), c.cost_us) { + return None; + } let dk = disk_cache::frame_key(content, k.frame, k.scale, k.view ^ oh); let tries = written.1.get(&dk).copied().unwrap_or(0); (tries < 2 && !dc.contains(disk_cache::Kind::Frame, dk) && !dc.frame_pending(dk) && queued.insert(dk)) @@ -1763,8 +1769,11 @@ impl Worker { // and compression. Persistence still runs on this worker, using the same snapshot. let since = disk.as_ref().map(|(dc, _, since)| DiskSince::of(dc, *since)); self.finish(&job, ci.clone(), Some(files.clone()), since, t0); + let took_us = u64::try_from(t0.elapsed().as_micros()).unwrap_or(u64::MAX); if !disk_hit && let Some((dc, k, since)) = &disk + // (only a frame that costs more to render again than to read back, #3301) + && dc.pays_off(ci.bytes(), took_us) && put_disk_frame(dc, *k, &ci, &files, self.virtual_id.as_deref(), *since) && let Some(ctx) = &self.ctx { diff --git a/crates/ui-egui/src/frames/tests.rs b/crates/ui-egui/src/frames/tests.rs index 22013fa5d..5898cb5ba 100644 --- a/crates/ui-egui/src/frames/tests.rs +++ b/crates/ui-egui/src/frames/tests.rs @@ -2233,6 +2233,56 @@ fn a_keyframe_edit_reaches_only_the_keys_around_it() { } } +/// A key edit of an effect parameter re-renders only around the keys it changed, as a Transform +/// key edit does (#3324): Exposure keyed at frames 30, 60 and 90, its middle key changed. Write-on +/// reads its Brush Position at every earlier time (a dab per Brush Spacing since the layer's +/// start), so its middle key edit reaches every frame after it. Every frame kept renders as +/// before. +#[test] +fn an_effect_key_edit_reaches_only_the_frames_that_read_it() { + use effectcraft_engine::Session; + use effectcraft_engine::project::{LayerId, Value}; + use effectcraft_engine::render::render_frame; + use serde_json::{Value as Json, json}; + let v2 = |x: f64, y: f64| (json!([x, y]), Value::Vec2([x, y])); + let edits = [ + ("Exposure", "master/exposure", [json!(0.0), json!(1.0), json!(0.0)], Value::Scalar(3.0)), + ("Write-on", "brushPosition", [v2(2.0, 2.0).0, v2(14.0, 14.0).0, v2(2.0, 14.0).0], v2(14.0, 2.0).1), + ]; + for (effect, param, values, mid) in edits { + let mut s = Session::default(); + let cid = + ItemId(s.execute("comp.new", json!({"name": "A", "width": 16, "height": 16, "duration": 4, "frameRate": 30})).unwrap()["comp"].as_u64().unwrap()); + let l = s.execute("layer.newSolid", json!({"color": "#808080", "width": 16, "height": 16})).unwrap()["layer"].as_u64().unwrap(); + s.execute("effect.apply", json!({"layers": [l], "effect": effect})).unwrap(); + let path = format!("effects/#1/{param}"); + let fr = s.project.comp(cid).unwrap().frame_rate; + for (f, v) in [30, 60, 90].into_iter().zip(values) { + let add: Json = json!({"layer": l, "path": path, "time": fr.tick_of(f).seconds(), "value": v}); + s.execute("prop.addKey", add).unwrap(); + } + let p0 = s.project.clone(); + let f = Frames::default(); + let k = |content: u64, frame: i64| FrameKey { content, comp: cid.0, ..key(0, frame, 0) }; + let id0 = f.content_of(&p0, 1, cid); + (0..120).for_each(|i| insert(&f, k(id0, i))); + let mut p1 = p0.clone(); + Arc::make_mut(&mut p1).comp_mut(cid).unwrap().layer_mut(LayerId(l)).unwrap().props.prop_mut(&path).unwrap().keys[1].value = mid; + let kept = f.cached_frames(&k(f.content_of(&p1, 2, cid), 0)); + let same = |i: i64| render_frame(&p0, cid, fr.tick_of(i), 1.0).data == render_frame(&p1, cid, fr.tick_of(i), 1.0).data; + assert!(!same(60), "{effect}: the edit shows"); + assert!(![45, 60, 75].iter().any(|i| kept.contains(i)), "{effect}: {kept:?}"); + if effect == "Exposure" { + assert!((0..=27).chain(93..120).all(|i| kept.contains(&i)), "{effect}: the frames outside the keys stay: {kept:?}"); + } else { + assert!(!same(110) && !kept.contains(&110), "{effect}: the stroke drawn by frame 110 passes the edited key: {kept:?}"); + } + for i in kept { + assert!(same(i), "{effect}: kept frame {i} renders differently after the edit"); + } + } +} + /// Music's Audio Levels keep every frame, in RAM and on disk, while the project's expressions /// can't read audio (a wiggle); an expression naming the music's Audio Levels re-renders its layer. #[test] @@ -2719,6 +2769,8 @@ mod frame_files { fn session(p: &Arc, dir: &Path) -> Session { let disk = DiskCache::open(dir.join("cache"), 1 << 30).unwrap(); + // (every frame is written, however quick to render: not decided by this machine's speed) + disk.set_read_us_per_mb(0); let hook_calls = Arc::new(AtomicUsize::new(0)); let mut frames = Frames::default(); let calls = hook_calls.clone(); @@ -3000,9 +3052,9 @@ fn the_accountant_trims_only_frames_in_ram() { assert_eq!(memory.bytes(), 16); } -/// #3298 review: preview frames compete with the other caches by value. A frame a playing -/// preview shows next counts as just used, and a frame rendered quickly (from cached layers) -/// still costs a typical render: an old, cheap footage frame goes before it. +/// #3301: frames a playing preview shows next are protected: other caches give way first, even +/// for items worth more, until the caches are more than the bounded overage over; past it the +/// preview frames go too. A frame rendered quickly still costs a typical render. #[test] fn preview_frames_ahead_of_the_playhead_outlive_old_footage() { use effectcraft_engine::render::memory::{self, Accountant, Candidate, MemoryHolder}; @@ -3027,26 +3079,26 @@ fn preview_frames_ahead_of_the_playhead_outlive_old_footage() { let mut c = frames.cache.lock().unwrap(); for i in 10..12 { c.insert_took(key(1, i, 0), img(), None, None, Some(std::time::Duration::from_micros(100))); - // (as old as the footage frame below) - c.map.get_mut(&key(1, i, 0)).unwrap().used = 0; } } let preview: Arc = Arc::new(PreviewMemory(frames.cache.clone())); - // Stopped: the oldest frame is offered as it is, with at least a typical render's cost. + // Stopped: the oldest frame is offered unprotected, with at least a typical render's cost. let offered = preview.oldest().unwrap(); - assert_eq!(offered.used, 0); + assert!(!offered.protected); assert_eq!(offered.cost_us, memory::default_cost(16, memory::DEFAULT_PREVIEW_US_PER_MB)); - // Playing from frame 10: the frames ahead count as just used. + // Playing from frame 10: the frames ahead are protected. frames.set_playhead(Some(playhead(10, false))); - let before = memory::tick(); - assert!(preview.oldest().unwrap().used >= before); - // An old footage frame that cost less per byte goes first. - let footage = Arc::new(Footage(Mutex::new(vec![Candidate { used: 0, bytes: 16, cost_us: 6_000 }]))); + assert!(preview.oldest().unwrap().protected); + // A footage frame worth far more per byte, used just now, still goes first. + let footage = Arc::new(Footage(Mutex::new(vec![Candidate::new(memory::tick(), 16, 1_000_000)]))); let footage_holder: Arc = footage.clone(); - let acc = Accountant::new(40); + let acc = Accountant::new(1000); acc.register(&preview); acc.register(&footage_holder); - acc.balance(); + acc.set_budget(40); assert_eq!(footage.bytes(), 0, "the footage frame went"); - assert_eq!(preview.bytes(), 32, "the preview frames stay"); + assert_eq!(preview.bytes(), 32, "the preview frames stay, a bounded way over"); + // Far over the budget, past the overage: the preview frames go too. + acc.set_budget(10); + assert!(preview.bytes() < 32, "{}", preview.bytes()); } diff --git a/crates/ui-egui/src/state.rs b/crates/ui-egui/src/state.rs index 60a30e97e..922594292 100644 --- a/crates/ui-egui/src/state.rs +++ b/crates/ui-egui/src/state.rs @@ -806,7 +806,8 @@ impl Default for UiState { home_learn: false, home_templates: false, align_to_selection: false, - cache_when_idle: false, + // (the setting's default, #3321; the settings set it when they load) + cache_when_idle: true, tracker_source: None, layer_panel: None, layer_view: None, diff --git a/docs/preferences.md b/docs/preferences.md index 16c11bd2e..c5a3f4cdb 100644 --- a/docs/preferences.md +++ b/docs/preferences.md @@ -53,9 +53,11 @@ Commands (CLI, MCP, control channel): - `composition.showRenderingProgress`: Show Rendering Progress in Info Panel and Flowchart - `previews.adaptiveResolutionLimit`: Adaptive Resolution Limit (the lowest resolution Fast Previews ▸ Adaptive Resolution drops to while you drag; a playing preview keeps the viewer's resolution) -- `previews.cacheFramesWhenIdle`: Cache Frames When Idle (Composition ▸ Preview): after a second - without input or edits, the viewer renders the work area into the RAM preview in the - background, from the current time on, until it is cached or the budget is full +- `previews.cacheFramesWhenIdle`: Cache Frames When Idle (Composition ▸ Preview), on by default: + after a second without input or edits, the viewer renders the work area into the RAM preview + in the background, from the current time on, until it is cached or the budget is full. Any + input, edit, playback or a frame the viewer waits for stops it at once (it starts again after + the next quiet second). A saved setting of off stays off - `previews.fastPreviews`: Fast Previews (Draft 3D, Faster Effects) - `appearance.appearanceMode`: Appearance Mode (`auto` / `dark` / `light`). `auto` (Sync with System) follows the operating system's light or dark appearance while the app runs: on Linux the desktop app reads the XDG desktop portal (`org.freedesktop.appearance` `color-scheme`) once and then listens for its `SettingChanged` signal on a worker thread, repainting only when the value changes (nothing polls); `gsettings` runs at most once at start-up, by absolute path, when the portal gives no answer. Elsewhere it uses what the window system reports. With no answer it shows the dark theme. New installs stay `dark`; Sync with System is opt-in. The Tools bar's appearance button (a monitor, sun or moon) cycles Sync with System, Light and Dark (`view.theme.toggle`, Next Appearance Mode). - `appearance.darkTheme`: Dark Theme (`dark` / `darker`), shown in dark appearance @@ -171,10 +173,22 @@ Commands (CLI, MCP, control channel): hold more than the budget together, the memory accountant frees the least valuable data first, whichever cache holds it, down to 90 % of the budget. An item's value is what it would cost to make again (its measured render or decode time; when not measured, a typical 4 ms per MB for a - layer, 8 ms for a preview frame, 2 ms for footage frames and planes) per byte, halved after - 30 s unused, a quarter after 90 s, and so on; a copy of data another cache holds (a queued disk write) is worth - nothing, and a cache that had to make again what it let go of shortly before is protected for - a while. In the browser the layer cache also stays within 512 MB and the footage frames within + layer, 8 ms for a preview frame, 2 ms for footage frames and planes) per byte, divided by + `ln(seconds unused + 1) + 1`: a slow decay (about a fifth after a minute unused, a seventh after + ten), so a costly frame unused for minutes still outlives a cheap one; a copy of data another + cache holds (a queued disk write) is worth nothing, and a cache that had to make again what it + let go of shortly before is protected for a while. The frames a playing RAM preview shows next + go last: they may keep the caches over the budget by a tenth of it (at most 1 GB) while other + items can go instead. Besides the bytes the caches count, the process's measured memory is + watched (its resident size, read with each balance and at most every 250 ms): above 95 % of the + installed RAM left after the reserve the caches give way by what it is over even within their + budget (memory nobody counts: GPU staging, effect buffers, the allocator's fragmentation), at + most once per reading unless it grows; above all of it also the preview frames that would + play next. A frame or plane set is written to the disk cache only when making it again costs + more than reading it back (the measured read rate, 10 ms per MB until reads are measured); a + RAM eviction keeps the disk copy, and the disk cache drops its oldest entries first. At most + 256 movie and audio files are kept open, the least recently used closed beyond that (image + sequences, OpenEXR included, keep no file open between decodes). In the browser the layer cache also stays within 512 MB and the footage frames within 256 MB (see [web.md](web.md)). The Memory & CPU page shows what EffectCraft may use, of the installed RAM. Settings saved before this (version 4 and earlier) had Layer Cache, Footage Frame Cache and Preview (RAM) Cache budgets (`memory.layerCacheMb`, `memory.mediaCacheMb`,